Run limactl start <INSTANCE> to create and start the first instance.
The <INSTANCE> name defaults to “default”.
$ limactl start
? Creating an instance "default" [Use arrows to move, type to filter]
> Proceed with the current configuration
Open an editor to review or modify the current configuration
Choose another template (docker, podman, archlinux, fedora, ...)
Exit
...
INFO[0029] READY. Run `lima` to open the shell.
Choose Proceed with the current configuration, and wait until “READY” to be printed on the host terminal.
For automation, --tty=false flag can be used for disabling the interactive user interface.
Customization
To create an instance “default” from a template “docker”:
For the “default” instance, this command can be shortened as lima <COMMAND>.
lima uname -a
The lima command also accepts the instance name as the environment variable $LIMA_INSTANCE.
Home directory
The host home directory is mounted as read-only on the following path by default:
/Users/${USER} (on macOS hosts)
/home/${USER} (on other hosts)
To make the host mount writable, run limactl start with --mount-writable.
To disable the mount, limactl start with --mount-none or --plain.
The guest home directory exists independently on the following path:
/Users/${USER}.guest (on macOS guests)
/home/${USER}.guest (on other guests, since Lima v2.1)
/home/${USER}.linux (prior to Lima v2.1)
Shell completion
To enable bash completion, add source <(limactl completion bash) to ~/.bash_profile.
To enable zsh completion, see limactl completion zsh --help
User shell
The default login shell inside the guest can be overridden via the user.shell
field in the instance YAML, or with --shell on limactl create / limactl edit.
The shell must already exist in the guest image.
On an existing instance, chsh inside the guest can be used to change the login shell.
To launch a different shell for a single session, use limactl shell --shell=SHELL.
1 - SSH
Instead of the limactl shell command, SSH can be used too:
limactl list --format '{{ .SSHLocalPort }}' default
See also .lima/default/ssh.config.
2 - Automatic Startup
⚡ Requirement
Lima >= 2.2
Lima instances can be registered to start automatically using limactl autostart.
Two conditions are supported: login (start when the user logs in) and boot
(start at system boot, before any user session). This replaces the older
limactl start-at-login command, which is deprecated as of Lima v2.2.
Starting instances automatically
Use limactl autostart enable to register a Lima instance to start automatically.
Use limactl autostart disable to remove the registration.
On macOS this installs a LaunchAgent in ~/Library/LaunchAgents/. On Linux it
installs a systemd user service. The instance starts in the background on the
next login and on subsequent logins.
At system boot, without a user session (macOS only)
For headless macOS servers where no user session is expected, use
--condition=boot. This installs a system LaunchDaemon that starts the instance
at boot, before any user logs in.
The --user flag specifies which macOS user the instance runs as (default:
$USER). The plist is installed to
/Library/LaunchDaemons/io.lima-vm.daemon.<instance>.plist.
Keep-alive behavior
By default (--keep-alive=true), launchd will automatically restart the Lima
host agent if it exits unexpectedly. To disable this:
This applies to both --condition=login (macOS LaunchAgent) and
--condition=boot (macOS LaunchDaemon). On Linux, the flag sets the systemd unit’s
Restart= directive: on-failure when enabled (the default), or no when disabled.
Unclean shutdown recovery
A host agent that dies without stopping the VM — because launchd’s shutdown timeout expired,
or after a crash, a kill -9, or a power loss — can leave an instance in one of two broken
states, in which limactl start refuses to start it. Neither is a sign of misconfiguration.
Orphaned VM driver — a driver that runs as its own process, such as qemu, is still
running with no host agent attached. The same state is reported when a PID file left on
disk names a PID that an unrelated process has since been given.
Stale host agent socket — ha.pid names a live PID, but nothing is listening on
ha.sock, because that PID now belongs to an unrelated process.
Lima detects and recovers from both states automatically on the next limactl start:
For an orphaned driver, limactl start force-stops the driver process and starts cleanly.
For a stale socket, limactl start removes the stale ha.pid and ha.sock files (without
signaling the unrelated process) and starts cleanly. A driver that runs the VM inside the
host agent process, such as vz, records the same PID, so its PID file is removed as well;
a driver running as its own process is left untouched and handled as an orphaned driver.
No manual intervention is required. To clear either state by hand — for example on an
instance left behind by an older version of Lima — use:
Password-less sudo is disabled, except for /sbin/shutdown -h now (see Sudo — this is not currently configurable on macOS)
Several features are not implemented yet. See Caveats below.
Advanced topics
Suppressing first-login setup screens
⚡ Requirement
Lima >= 2.3, macOS >= 13.0
By default, macOS shows a series of setup wizard screens (Setup Assistant /
mini-buddy) on the first GUI login. For automated or headless-style macOS VMs
this is inconvenient. Set osOpts.Darwin.suppressFirstLoginSetup to have Lima
pre-populate the relevant preference plists during provisioning, before any GUI
session starts, so the setup screens are skipped automatically:
osOpts:Darwin:suppressFirstLoginSetup:true
This writes com.apple.SetupAssistant.plist into the guest user’s home
directory and pre-configures com.apple.SoftwareUpdate system preferences so
that the “Update Mac Automatically” dialog is also suppressed. The preferences
are written as root (via the Lima guest agent) before first login, so macOS
reads them as the authoritative initial state and does not reset them.
Default: unset — setup screens are shown as normal.
Custom plist
The built-in com.apple.SetupAssistant.plist template is shown below. At VM
creation time, <build> is replaced with the output of sw_vers -buildVersion
and <version> with sw_vers -productVersion from inside the guest. The
version stamps are what macOS checks to decide whether setup is already
complete — without them macOS resets MiniBuddyLaunchReason to 13 on first
GUI login.
When suppressFirstLoginSetupPlist is supplied, it is used verbatim — no
<build>/<version> substitution is performed. Copy and adapt the built-in
template above, then supply the actual build and version strings for your
target OS release if needed.
Caveats
No support for turning off the video display.
No support for automatic port forwarding.
Use ssh -L to manually set up port forwarding, or,
use the vzNAT network to access the guest by its IP.
No support for installing custom caCerts
Plain mode
containerd and automatic port forwarding are not available on macOS guests regardless
of the mode, so plain mode additionally disables only the
host directory mounts.
3.3 - Windows
⚡ Requirement
Lima >= 2.2, QEMU, swtpm
Running Windows guests is experimentally supported since Lima v2.2.
limactl start template:windows
limactl start template:windows-2025
The user password is randomly generated and stored in the %USERPROFILE%\password.txt file in the VM.
Consider changing it after the first login.
By default, Windows 11 enables Trusted Platform Module (TPM) emulation because of the hardware requirement. However, you can turn it off (in that case, lima bypasses the hardware check). In order to use TPM emulation, you need to install swtpm on your host computer.
For Windows server 2025, TPM emulation is disabled by default. However, there are some benefits if you enable TPM emulation. For example, you can install BitLocker disk encryption on your VM.
Difference from Linux guests
Several features are not implemented yet. See Caveats below.
Caveats
For Windows 11 guest, you need to download the installer ISO manually from here
QEMU is the only VM driver that supports Windows guests
provision feature is limited support (no boot, yq modes, and data and dependency modes have limitations)
Only plain mode is supported (no file mount, no dynamic port-forwarding)
Booting Windows 11 may occasionally fail. If it fails, please delete the instance and try it again from scratch.
3.4 - FreeBSD
⚡ Requirement
Lima >= 2.1
Running FreeBSD guests is experimentally supported since Lima v2.1.
limactl start template:freebsd-15
limactl start template:experimental/freebsd-16
Prerequisites:
QEMU
xorriso (on non-macOS hosts)
Difference from Linux guests
Several features are not implemented yet. See Caveats below.
Caveats
No support for automatic port forwarding. Use ssh -L to manually set up port forwarding.
No support for installing custom caCerts
And more
FreeBSD prior to 15.1
No support for mounting host directories.
Use limactl cp or limactl shell --sync to share files with the host.
Plain mode
The guest agent, containerd, and automatic port forwarding are not available on
FreeBSD guests regardless of the mode, so plain mode
additionally disables only the host directory mounts (on FreeBSD 15.1 and later).