Lima

Enhanced supply chain security with gomodjail

Mon, 01 Jan 0001 00:00:00 +0000

gomodjail is an experimental library sandbox for Go modules.

gomodjail imposes syscall restrictions on a specific set of Go modules, so as to mitigate their potential vulnerabilities and supply chain attack vectors. A restricted module is hindered to access files and execute commands.

gomodjail can be enabled for nerdctl by using the nerdctl.gomodjail binary.

lima nerdctl.gomodjail ...

For the gomodjail policy applied to nerdctl.gomodjail, see https://github.com/containerd/nerdctl/blob/main/go.mod.

Linux

Mon, 01 Jan 0001 00:00:00 +0000

Linux is the default guest operating system.

QEMU

Mon, 01 Jan 0001 00:00:00 +0000

“qemu” option makes use of QEMU to run guest operating system.

“qemu” is the default driver for Linux hosts.

Recommended QEMU version:

v8.2.1 or later (macOS)
v6.2.0 or later (Linux)

On a Windows host, “qemu” needs ssh, scp, and ssh-keygen; the OpenSSH client that Windows installs by default provides all three. Mounts must use reverse-sshfs, because QEMU for Windows has no 9p support. Pinning sftpDriver: openssh-sftp-server also requires sftp-server.exe, which comes from the optional OpenSSH Server feature.

VM driver plugins

Mon, 01 Jan 0001 00:00:00 +0000

See Virtual Machine Drivers.

Accelerating rootless networking with bypass4netns

Mon, 01 Jan 0001 00:00:00 +0000

bypass4netns is an experimental accelerator for rootless networking.

On macOS hosts, it is highly recommended to use the vzNAT networking in conjunction to reduce the overhead of Lima’s user-mode networking:

limactl start --network vzNAT

To enable bypass4netns, the daemon process (bypass4netnsd) has to be installed in the VM as follows:

lima containerd-rootless-setuptool.sh install-bypass4netnsd

Then run a container with an annotation nerdctl/bypass4netns=true:

# 192.168.64.1 is the IP address of the "bridge100" interface on the macOS host
lima nerdctl run --annotation nerdctl/bypass4netns=true alpine \
 sh -euc 'apk add iperf3 && iperf3 -c 192.168.64.1'

Benchmark result:

CLI plugins

Mon, 01 Jan 0001 00:00:00 +0000

Warning Support for CLI plugins is experimental

⚡ Requirement	Lima >= 2.0

Lima supports a plugin-like command aliasing system similar to git, kubectl, and docker. When you run a limactl command that doesn’t exist, Lima will automatically look for an external program named limactl-<command> in your system’s PATH and additional directories.

Plugin Discovery

Lima discovers plugins by scanning for executables named limactl-<plugin-name> in the following locations:

Directory containing the limactl binary (including symlink support)
All directories in your $PATH environment variable
<PREFIX>/libexec/lima - For plugins installed by package managers or distribution packages

Plugin discovery respects symlinks, ensuring that even if limactl is installed via Homebrew and points to a symlink, all plugins are correctly discovered.

macOS

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.1, macOS (same or newer than the guest OS), ARM

Running macOS guests is experimentally supported since Lima v2.1.

limactl start template:macos

To specify the macOS version explicitly:

limactl start template:macos-27

limactl start template:homebrew-macos

The user password is randomly generated and stored in the ~/password file in the VM. Consider changing it after the first login.

VZ

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 0.14, macOS >= 13.0

“vz” option makes use of native virtualization support provided by macOS Virtualization.Framework.

“vz” has been the default driver for macOS hosts since Lima v1.0.

An example configuration (no need to be specified manually):

limactl start --vm-type=vz

vmType: "vz"

base:
- template:_images/ubuntu
- template:_default/mounts

Windows

Mon, 01 Jan 0001 00:00:00 +0000

⚡ 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.

autostart

Mon, 01 Jan 0001 00:00:00 +0000

limactl autostart

Manage automatic startup of Lima instances

Options

 -h, --help help for autostart

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

autostart disable

Mon, 01 Jan 0001 00:00:00 +0000

limactl autostart disable

Unregister an instance from automatic startup

limactl autostart disable INSTANCE [flags]

Options

 -h, --help help for disable

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

autostart enable

Mon, 01 Jan 0001 00:00:00 +0000

limactl autostart enable

limactl autostart enable INSTANCE [flags]

Options

 --condition string When to start the instance: "login" (user session) or "boot" (system boot, macOS only) (default "login")
 -h, --help help for enable
 --keep-alive Restart the instance automatically if the host agent exits unexpectedly (default true)
 --user string macOS username to run the instance as when --condition=boot (default: $USER)

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

clone

Mon, 01 Jan 0001 00:00:00 +0000

limactl clone

Clone an instance of Lima

Synopsis

Clone an instance of Lima.

Not to be confused with ’limactl copy’ (’limactl cp’).

limactl clone OLDINST NEWINST [flags]

Options

 --block-device strings [limactl edit] Host block devices to attach (macOS VZ), e.g. /dev/disk4; requires a protected helper and 'limactl sudoers --block-device' setup
 --cpus int [limactl edit] Number of CPUs
 --disk float32 [limactl edit] Disk size in GiB
 --dns ipSlice [limactl edit] Specify custom DNS (disable host resolver) (default [])
 -h, --help help for clone
 --memory float32 [limactl edit] Memory in GiB
 --mount strings [limactl edit] Directories to mount, suffix ':w' for writable (Do not specify directories that overlap with the existing mounts)
 --mount-inotify [limactl edit] Enable inotify for mounts
 --mount-none [limactl edit] Remove all mounts
 --mount-only strings [limactl edit] Similar to --mount, but overrides the existing mounts
 --mount-type string [limactl edit] Mount type (reverse-sshfs, 9p, virtiofs)
 --mount-writable [limactl edit] Make all mounts writable
 --nested-virt [limactl edit] Enable nested virtualization
 --network strings [limactl edit] Additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
 --param stringArray [limactl edit] Set a template parameter, e.g. name=value. Can be passed multiple times.
 --rosetta [limactl edit] Enable Rosetta (for vz instances)
 --set stringArray [limactl edit] Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --shell string [limactl edit] User login shell in the guest (e.g. /bin/bash, /bin/zsh)
 --ssh-port uint16 [limactl edit] SSH port (0 for random)
 --start Start the instance after cloning
 --video [limactl edit] Enable video output (has negative performance impact for QEMU)
 --vm-type string [limactl edit] Virtual machine type

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

completion

Mon, 01 Jan 0001 00:00:00 +0000

limactl completion

Generate the autocompletion script for the specified shell

Synopsis

Generate the autocompletion script for limactl for the specified shell.
See each sub-command’s help for details on how to use the generated script.

Options

 -h, --help help for completion

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

completion bash

Mon, 01 Jan 0001 00:00:00 +0000

limactl completion bash

Generate the autocompletion script for bash

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(limactl completion bash)

To load completions for every new session, execute once:

Linux:

limactl completion bash > /etc/bash_completion.d/limactl

macOS:

limactl completion bash > $(brew --prefix)/etc/bash_completion.d/limactl

You will need to start a new shell for this setup to take effect.

completion fish

Mon, 01 Jan 0001 00:00:00 +0000

limactl completion fish

Generate the autocompletion script for fish

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

limactl completion fish | source

To load completions for every new session, execute once:

limactl completion fish > ~/.config/fish/completions/limactl.fish

You will need to start a new shell for this setup to take effect.

limactl completion fish [flags]

Options

 -h, --help help for fish
 --no-descriptions disable completion descriptions

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

completion powershell

Mon, 01 Jan 0001 00:00:00 +0000

limactl completion powershell

Generate the autocompletion script for powershell

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

limactl completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

limactl completion powershell [flags]

Options

 -h, --help help for powershell
 --no-descriptions disable completion descriptions

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

completion zsh

Mon, 01 Jan 0001 00:00:00 +0000

limactl completion zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(limactl completion zsh)

To load completions for every new session, execute once:

copy

Mon, 01 Jan 0001 00:00:00 +0000

limactl copy

Copy files between host and guest

Synopsis

Copy files between host and guest

Prefix guest filenames with the instance name and a colon.

Backends:
auto - Automatically selects the best available backend (rsync preferred, falls back to scp)
rsync - Uses rsync for faster transfers with resume capability (requires rsync on both host and guest)
scp - Uses scp for reliable transfers (always available)

Not to be confused with ’limactl clone’.

create

Mon, 01 Jan 0001 00:00:00 +0000

limactl create

Create an instance of Lima

limactl create FILE.yaml|URL [flags]

Examples


 To create an instance "default" from the default Ubuntu template:
 $ limactl create

 To create an instance "default" from a template "docker":
 $ limactl create --name=default template:docker

 To create an instance "default" with modified parameters:
 $ limactl create --cpus=2 --memory=2

 To create an instance "default" with yq expressions:
 $ limactl create --set='.cpus = 2 | .memory = "2GiB"'
 Note: Some yq operators are restricted. See 'limactl help yq-restrictions'.

 To create an instance "default" with a template parameter:
 $ limactl create --name=default --param containerdSnapshotter=false template:docker

 To see the template list:
 $ limactl create --list-templates

 To create an instance "default" from a local file:
 $ limactl create --name=default /usr/local/share/lima/templates/fedora.yaml

 To create an instance "default" from a remote URL (use carefully, with a trustable source):
 $ limactl create --name=default https://raw.githubusercontent.com/lima-vm/lima/master/templates/alpine.yaml

 To create an instance "local" from a template passed to stdin (--name parameter is required):
 $ cat template.yaml | limactl create --name=local -

Options

 --arch string Machine architecture (x86_64, aarch64, riscv64, armv7l, s390x, ppc64le)
 --arch-variant string Architecture variant (e.g. "v3" for x86-64-v3)
 --audio-device string Audio device backend (e.g., 'pa', 'coreaudio', 'none')
 --audio-interface string Audio virtual hardware interface ('hda' or 'virtio')
 --audio-microphone Attach an audio input stream as well as playback (vz only)
 --block-device strings Host block devices to attach (macOS VZ), e.g. /dev/disk4; requires a protected helper and 'limactl sudoers --block-device' setup
 --containerd string containerd mode (user, system, user+system, none)
 --cpus int Number of CPUs
 --disk float32 Disk size in GiB
 --dns ipSlice Specify custom DNS (disable host resolver) (default [])
 -h, --help help for create
 --image-variant string Image variant
 --list-drivers List available drivers and exit
 --list-templates List available templates and exit
 --memory float32 Memory in GiB
 --mount strings Directories to mount, suffix ':w' for writable (Do not specify directories that overlap with the existing mounts)
 --mount-inotify Enable inotify for mounts
 --mount-none Remove all mounts
 --mount-only strings Similar to --mount, but overrides the existing mounts
 --mount-type string Mount type (reverse-sshfs, 9p, virtiofs)
 --mount-writable Make all mounts writable
 --name string Override the instance name
 --nested-virt Enable nested virtualization
 --network strings Additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
 --param stringArray Set a template parameter, e.g. name=value. Can be passed multiple times.
 --plain Plain mode. Disables mounts, port forwarding, containerd, etc.
 --port-forward stringArray Port forwards (host:guest), e.g., '8080:80' or '9090:9090,static=true' for static port-forwards
 --rosetta Enable Rosetta (for vz instances)
 --set stringArray Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --shell string User login shell in the guest (e.g. /bin/bash, /bin/zsh)
 --ssh-port uint16 SSH port (0 for random)
 --video Enable video output (has negative performance impact for QEMU)
 --vm-type string Virtual machine type

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

delete

Mon, 01 Jan 0001 00:00:00 +0000

limactl delete

Delete an instance of Lima

limactl delete INSTANCE [INSTANCE, ...] [flags]

Options

 -f, --force Forcibly kill the processes
 -h, --help help for delete

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk

Lima disk management

Examples

 Create a disk:
 $ limactl disk create DISK --size SIZE [--format qcow2]

 List existing disks:
 $ limactl disk ls

 Delete a disk:
 $ limactl disk delete DISK

 Resize a disk:
 $ limactl disk resize DISK --size SIZE

Options

 -h, --help help for disk

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk create

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk create

Create a Lima disk

limactl disk create DISK [flags]

Examples


To create a new disk:
$ limactl disk create DISK --size SIZE [--format qcow2]

Options

 --format string Specify the disk format (default "qcow2")
 -h, --help help for create
 --size string Configure the disk size

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk delete

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk delete

Delete one or more Lima disks

limactl disk delete DISK [DISK, ...] [flags]

Examples


To delete a disk:
$ limactl disk delete DISK

To delete multiple disks:
$ limactl disk delete DISK1 DISK2 ...

Options

 -f, --force Force delete
 -h, --help help for delete

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk import

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk import

Import an existing disk to Lima

limactl disk import DISK FILE [flags]

Examples


Import a disk:
$ limactl disk import DISK DISKPATH

Options

 -h, --help help for import

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk list

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk list

List existing Lima disks

limactl disk list [flags]

Examples


To list existing disks:
$ limactl disk list

Options

 -h, --help help for list
 --json JSONify output

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk resize

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk resize

Resize existing Lima disk

limactl disk resize DISK [flags]

Examples


Resize a disk:
$ limactl disk resize DISK --size SIZE

Options

 -h, --help help for resize
 --size string Disk size

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

disk unlock

Mon, 01 Jan 0001 00:00:00 +0000

limactl disk unlock

Unlock one or more Lima disks

limactl disk unlock DISK [DISK, ...] [flags]

Examples


Emergency recovery! If an instance is force stopped, it may leave a disk locked while not actually using it.

To unlock a disk:
$ limactl disk unlock DISK

To unlock multiple disks:
$ limactl disk unlock DISK1 DISK2 ...

Options

 -h, --help help for unlock

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

edit

Mon, 01 Jan 0001 00:00:00 +0000

limactl edit

Edit an instance of Lima or a template

limactl edit INSTANCE|FILE.yaml [flags]

Options

 --block-device strings Host block devices to attach (macOS VZ), e.g. /dev/disk4; requires a protected helper and 'limactl sudoers --block-device' setup
 --cpus int Number of CPUs
 --disk float32 Disk size in GiB
 --dns ipSlice Specify custom DNS (disable host resolver) (default [])
 -h, --help help for edit
 --memory float32 Memory in GiB
 --mount strings Directories to mount, suffix ':w' for writable (Do not specify directories that overlap with the existing mounts)
 --mount-inotify Enable inotify for mounts
 --mount-none Remove all mounts
 --mount-only strings Similar to --mount, but overrides the existing mounts
 --mount-type string Mount type (reverse-sshfs, 9p, virtiofs)
 --mount-writable Make all mounts writable
 --nested-virt Enable nested virtualization
 --network strings Additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
 --param stringArray Set a template parameter, e.g. name=value. Can be passed multiple times.
 --rosetta Enable Rosetta (for vz instances)
 --set stringArray Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --shell string User login shell in the guest (e.g. /bin/bash, /bin/zsh)
 --ssh-port uint16 SSH port (0 for random)
 --start Start the instance after editing
 --video Enable video output (has negative performance impact for QEMU)
 --vm-type string Virtual machine type

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

Accelerating start-up time with eStargz

Mon, 01 Jan 0001 00:00:00 +0000

eStargz is an OCI-compatible container image format that reduces start-up latency using lazy-pulling technique.

The support for eStargz is available by default in Lima.

The timings below were measured on an Apple M5 Max (macOS, VZ-backend Lima, default template) pulling the native arm64 images. Numbers are a median of three cold runs (image removed with nerdctl rmi between each run).

Without eStargz:

$ time lima nerdctl run ghcr.io/stargz-containers/python:3.13-org python3 -c 'print("hi")'
hi

real	0m14.031s
user	0m0.017s
sys	0m0.018s

With eStargz:

factory-reset

Mon, 01 Jan 0001 00:00:00 +0000

limactl factory-reset

Factory reset an instance of Lima

limactl factory-reset INSTANCE [flags]

Options

 -h, --help help for factory-reset

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

FreeBSD

Mon, 01 Jan 0001 00:00:00 +0000

⚡ 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).

info

Mon, 01 Jan 0001 00:00:00 +0000

limactl info

Show diagnostic information

limactl info [flags]

Options

 -h, --help help for info
 --yq string Apply yq expression to output (default ".")

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

limactl

Mon, 01 Jan 0001 00:00:00 +0000

limactl

Lima: Linux virtual machines

limactl [flags]

Examples

 Start the default instance:
 $ limactl start

 Open a shell:
 $ lima

 Run a container:
 $ lima nerdctl run -d --name nginx -p 8080:80 nginx:alpine

 Stop the default instance:
 $ limactl stop

 See also template YAMLs: /usr/local/share/lima/templates

Options

 --debug Debug mode
 -h, --help help for limactl
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

list

Mon, 01 Jan 0001 00:00:00 +0000

limactl list

List instances of Lima

Synopsis

List instances of Lima.

The output can be presented in one of several formats, using the --format flag.

--format json - Output in JSON format
--format yaml - Output in YAML format
--format table - Output in table format
--format ‘{{ }}’ - If the format begins and ends with ‘{{ }}’, then it is used as a go template.

Filtering instances:
--filter EXPR - Filter instances using yq expression (this is equivalent to --yq ‘select(EXPR)’)
Can be specified multiple times (combined with AND logic) and it works with all output formats.
Examples:
--filter ‘.status == “Running”’
--filter ‘.vmType == “vz”’
--filter ‘.status == “Running”’ --filter ‘.vmType == “vz”’ (Same as AND)

network

Mon, 01 Jan 0001 00:00:00 +0000

limactl network

Lima network management

Examples

 List all networks:
 $ limactl network list

 Create a network:
 $ limactl network create foo --gateway 192.168.42.1/24

 Connect VM instances to the newly created network:
 $ limactl create --network lima:foo --name vm1
 $ limactl create --network lima:foo --name vm2

 Delete a network:
 $ limactl network delete --force foo

Options

 -h, --help help for network

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

network create

Mon, 01 Jan 0001 00:00:00 +0000

limactl network create

Create a Lima network

limactl network create NETWORK [flags]

Examples

 Create a network:
 $ limactl network create foo --gateway 192.168.42.1/24

 Connect VM instances to the newly created network:
 $ limactl create --network lima:foo --name vm1
 $ limactl create --network lima:foo --name vm2

Options

 --gateway string gateway, e.g., "192.168.42.1/24"
 -h, --help help for create
 --interface string interface for bridged mode
 --mode string mode (default "user-v2")

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

network delete

Mon, 01 Jan 0001 00:00:00 +0000

limactl network delete

Delete one or more Lima networks

limactl network delete NETWORK [NETWORK, ...] [flags]

Examples

 Delete a network:
 $ limactl network delete --force foo

 Delete multiple networks:
 $ limactl network delete --force foo bar

Options

 -f, --force Force delete (currently always required)
 -h, --help help for delete

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

network list

Mon, 01 Jan 0001 00:00:00 +0000

limactl network list

List networks

limactl network list [flags]

Examples

 List all networks:
 $ limactl network list

 List networks in JSON format:
 $ limactl network list --json

Options

 -h, --help help for list
 --json JSONify output

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

protect

Mon, 01 Jan 0001 00:00:00 +0000

limactl protect

Protect an instance to prohibit accidental removal

Synopsis

Protect an instance to prohibit accidental removal via the ’limactl delete’ command.
The instance is not being protected against removal via ‘/bin/rm’, Finder, etc.

limactl protect INSTANCE [INSTANCE, ...] [flags]

Options

 -h, --help help for protect

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

prune

Mon, 01 Jan 0001 00:00:00 +0000

limactl prune

Prune garbage objects

limactl prune [flags]

Options

 -h, --help help for prune
 --keep-referred Keep objects that are referred by some instances or templates

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

rename

Mon, 01 Jan 0001 00:00:00 +0000

limactl rename

Rename an instance of Lima

limactl rename OLDINST NEWINST [flags]

Options

 --block-device strings [limactl edit] Host block devices to attach (macOS VZ), e.g. /dev/disk4; requires a protected helper and 'limactl sudoers --block-device' setup
 --cpus int [limactl edit] Number of CPUs
 --disk float32 [limactl edit] Disk size in GiB
 --dns ipSlice [limactl edit] Specify custom DNS (disable host resolver) (default [])
 -h, --help help for rename
 --memory float32 [limactl edit] Memory in GiB
 --mount strings [limactl edit] Directories to mount, suffix ':w' for writable (Do not specify directories that overlap with the existing mounts)
 --mount-inotify [limactl edit] Enable inotify for mounts
 --mount-none [limactl edit] Remove all mounts
 --mount-only strings [limactl edit] Similar to --mount, but overrides the existing mounts
 --mount-type string [limactl edit] Mount type (reverse-sshfs, 9p, virtiofs)
 --mount-writable [limactl edit] Make all mounts writable
 --nested-virt [limactl edit] Enable nested virtualization
 --network strings [limactl edit] Additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
 --param stringArray [limactl edit] Set a template parameter, e.g. name=value. Can be passed multiple times.
 --rosetta [limactl edit] Enable Rosetta (for vz instances)
 --set stringArray [limactl edit] Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --shell string [limactl edit] User login shell in the guest (e.g. /bin/bash, /bin/zsh)
 --ssh-port uint16 [limactl edit] SSH port (0 for random)
 --start Start the instance after renaming
 --video [limactl edit] Enable video output (has negative performance impact for QEMU)
 --vm-type string [limactl edit] Virtual machine type

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

restart

Mon, 01 Jan 0001 00:00:00 +0000

limactl restart

Restart a running instance

limactl restart INSTANCE [flags]

Options

 --block-device strings Host block devices to attach (macOS VZ), e.g. /dev/disk4; requires a protected helper and 'limactl sudoers --block-device' setup
 --cpus int Number of CPUs
 --disk float32 Disk size in GiB
 --dns ipSlice Specify custom DNS (disable host resolver) (default [])
 -f, --force Force stop and restart the instance
 -h, --help help for restart
 --memory float32 Memory in GiB
 --mount strings Directories to mount, suffix ':w' for writable (Do not specify directories that overlap with the existing mounts)
 --mount-inotify Enable inotify for mounts
 --mount-none Remove all mounts
 --mount-only strings Similar to --mount, but overrides the existing mounts
 --mount-type string Mount type (reverse-sshfs, 9p, virtiofs)
 --mount-writable Make all mounts writable
 --nested-virt Enable nested virtualization
 --network strings Additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
 --param stringArray Set a template parameter, e.g. name=value. Can be passed multiple times.
 --progress Show provision script progress by tailing cloud-init logs
 --rosetta Enable Rosetta (for vz instances)
 --set stringArray Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --shell string User login shell in the guest (e.g. /bin/bash, /bin/zsh)
 --ssh-port uint16 SSH port (0 for random)
 --video Enable video output (has negative performance impact for QEMU)
 --vm-type string Virtual machine type

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

screenshot

Mon, 01 Jan 0001 00:00:00 +0000

limactl screenshot

Capture a screenshot of the VM display

limactl screenshot INSTANCE [flags]

Options

 -h, --help help for screenshot
 -o, --output string Output path; extension must be .png or .bmp (default: INSTANCE-screenshot.png)

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

shell

Mon, 01 Jan 0001 00:00:00 +0000

limactl shell

Execute shell in Lima

Synopsis

Execute shell in Lima

lima command is provided as an alias for limactl shell $LIMA_INSTANCE. $LIMA_INSTANCE defaults to “default”.

By default, the first ‘ssh’ executable found in the host’s PATH is used to connect to the Lima instance.
A custom ssh alias can be used instead by setting the $SSH environment variable.

Environment Variables:
--preserve-env: Propagates host environment variables to the guest instance.
Use LIMA_SHELLENV_BLOCK to specify variables to block (prefix with + to extend the default blocklist).
Use LIMA_SHELLENV_ALLOW to exempt specific variables from the blocklist.

show-ssh

Mon, 01 Jan 0001 00:00:00 +0000

limactl show-ssh

Show the SSH command line (DEPRECATED; use ssh -F instead)

Synopsis

Show the SSH command line (DEPRECATED)

WARNING: ’limactl show-ssh’ is deprecated.
Instead, use ‘ssh -F ~/.lima/default/ssh.config lima-default’ .

limactl show-ssh [flags] INSTANCE

Examples


 "cmd" format (default): Full SSH command line
 $ limactl show-ssh --format=cmd default
 ssh -o IdentityFile="/Users/example/.lima/_config/user" -o User=example -o Hostname=127.0.0.1 -o Port=60022 lima-default

 "args" format: Similar to the cmd format but omits "ssh" and the destination address
 $ limactl show-ssh --format=args default
 -o IdentityFile="/Users/example/.lima/_config/user" -o User=example -o Hostname=127.0.0.1 -o Port=60022

 "options" format: SSH option key value pairs
 $ limactl show-ssh --format=options default
 IdentityFile="/Users/example/.lima/_config/user"
 User=example
 Hostname=127.0.0.1
 Port=60022

 "config" format: ~/.ssh/config format
 $ limactl show-ssh --format=config default
 Host lima-default
 IdentityFile "/Users/example/.lima/_config/user "
 User example
 Hostname 127.0.0.1
 Port 60022

 To show the config file path:
 $ limactl ls --format='{{.SSHConfigFile}}' default
 /Users/example/.lima/default/ssh.config

Options

 -f, --format string Format: cmd, args, options, config (default "cmd")
 -h, --help help for show-ssh

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

snapshot

Mon, 01 Jan 0001 00:00:00 +0000

limactl snapshot

Manage instance snapshots

Examples

 List all snapshots of an instance:
 $ limactl snapshot list default

 Create a snapshot:
 $ limactl snapshot create default --tag snap1

 Apply (restore) a snapshot:
 $ limactl snapshot apply default --id 1

 Delete a snapshot:
 $ limactl snapshot delete default --id 1

Options

 -h, --help help for snapshot

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

snapshot apply

Mon, 01 Jan 0001 00:00:00 +0000

limactl snapshot apply

Apply (load) a snapshot

limactl snapshot apply INSTANCE [flags]

Examples

 Apply (restore) a snapshot:
 $ limactl snapshot apply default --id 1

Options

 -h, --help help for apply
 --id string ID of the snapshot
 --tag string Name of the snapshot

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

snapshot create

Mon, 01 Jan 0001 00:00:00 +0000

limactl snapshot create

Create (save) a snapshot

limactl snapshot create INSTANCE [flags]

Examples

 Create a snapshot of an instance:
 $ limactl snapshot create default --tag snap1

Options

 -h, --help help for create
 --tag string Name of the snapshot

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

snapshot delete

Mon, 01 Jan 0001 00:00:00 +0000

limactl snapshot delete

Delete (del) a snapshot

limactl snapshot delete INSTANCE [flags]

Examples

 Delete a snapshot:
 $ limactl snapshot delete default --id 1

Options

 -h, --help help for delete
 --id string ID of the snapshot
 --tag string Name of the snapshot

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

snapshot list

Mon, 01 Jan 0001 00:00:00 +0000

limactl snapshot list

List existing snapshots

limactl snapshot list INSTANCE [flags]

Examples

 List all snapshots of an instance:
 $ limactl snapshot list default

 List only snapshot tags:
 $ limactl snapshot list default --quiet

 List snapshots in JSON format:
 $ limactl snapshot list default --json

Options

 -h, --help help for list
 --json JSONify output
 -q, --quiet Only show tags

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

SSH

Mon, 01 Jan 0001 00:00:00 +0000

Instead of the limactl shell command, SSH can be used too:

$ limactl ls --format='{{.SSHConfigFile}}' default
/Users/example/.lima/default/ssh.config

$ ssh -F /Users/example/.lima/default/ssh.config lima-default

This is useful for interoperability with other software that expects the SSH connectivity.

Using SSH without additional options

Add the following line to your ~/.ssh/config:

Include ~/.lima/*/ssh.config

Then you can connect directly without specifying -F:

ssh lima-default

This configuration is notably useful for the Remote Development mode of Visual Studio Code.

start

Mon, 01 Jan 0001 00:00:00 +0000

limactl start

Start an instance of Lima

limactl start NAME|FILE.yaml|URL [flags]

Examples


 To create an instance "default" (if not created yet) from the default Ubuntu template, and start it:
 $ limactl start

 To create an instance "default" from a template "docker", and start it:
 $ limactl start --name=default template:docker

Options

 --arch string [limactl create] Machine architecture (x86_64, aarch64, riscv64, armv7l, s390x, ppc64le)
 --arch-variant string [limactl create] Architecture variant (e.g. "v3" for x86-64-v3)
 --audio-device string [limactl create] Audio device backend (e.g., 'pa', 'coreaudio', 'none')
 --audio-interface string [limactl create] Audio virtual hardware interface ('hda' or 'virtio')
 --audio-microphone [limactl create] Attach an audio input stream as well as playback (vz only)
 --block-device strings [limactl create] Host block devices to attach (macOS VZ), e.g. /dev/disk4; requires a protected helper and 'limactl sudoers --block-device' setup
 --containerd string [limactl create] containerd mode (user, system, user+system, none)
 --cpus int [limactl create] Number of CPUs
 --disk float32 [limactl create] Disk size in GiB
 --dns ipSlice [limactl create] Specify custom DNS (disable host resolver) (default [])
 --foreground Run the hostagent in the foreground
 -h, --help help for start
 --image-variant string [limactl create] Image variant
 --list-drivers [limactl create] List available drivers and exit
 --list-templates [limactl create] List available templates and exit
 --memory float32 [limactl create] Memory in GiB
 --mount strings [limactl create] Directories to mount, suffix ':w' for writable (Do not specify directories that overlap with the existing mounts)
 --mount-inotify [limactl create] Enable inotify for mounts
 --mount-none [limactl create] Remove all mounts
 --mount-only strings [limactl create] Similar to --mount, but overrides the existing mounts
 --mount-type string [limactl create] Mount type (reverse-sshfs, 9p, virtiofs)
 --mount-writable [limactl create] Make all mounts writable
 --name string [limactl create] Override the instance name
 --nested-virt [limactl create] Enable nested virtualization
 --network strings [limactl create] Additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
 --param stringArray [limactl create] Set a template parameter, e.g. name=value. Can be passed multiple times.
 --plain [limactl create] Plain mode. Disables mounts, port forwarding, containerd, etc.
 --port-forward stringArray [limactl create] Port forwards (host:guest), e.g., '8080:80' or '9090:9090,static=true' for static port-forwards
 --progress Show provision script progress by tailing cloud-init logs
 --rosetta [limactl create] Enable Rosetta (for vz instances)
 --set stringArray [limactl create] Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --shell string [limactl create] User login shell in the guest (e.g. /bin/bash, /bin/zsh)
 --ssh-port uint16 [limactl create] SSH port (0 for random)
 --timeout duration Duration to wait for the instance to be running before timing out (default 10m0s)
 --video [limactl create] Enable video output (has negative performance impact for QEMU)
 --vm-type string [limactl create] Virtual machine type

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

stop

Mon, 01 Jan 0001 00:00:00 +0000

limactl stop

Stop an instance

limactl stop INSTANCE [INSTANCE, ...] [flags]

Options

 -f, --force Force stop the instance
 -h, --help help for stop

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

sudoers

Mon, 01 Jan 0001 00:00:00 +0000

limactl sudoers

Generate the content of the /etc/sudoers.d/lima file

Synopsis

Generate the content of the /etc/sudoers.d/lima file for the host helpers that require privilege escalation:
vmnet.framework support (socket_vmnet) on macOS, or the shared/host/bridged networks (Linux bridges with dnsmasq) on Linux.
On macOS, use --block-device=/dev/rdiskN to also emit opt-in
host block-device helper entries for the listed devices and current user.
Block devices require a root-owned helper and ancestor directories; user-writable
installations need additional setup: https://lima-vm.io/docs/config/disk/#sudoers-setup
--block-device on start/edit selects devices; it does not install sudoers grants.
The content is written to stdout, NOT to the file.
This command must not run as the root user.
On macOS, see https://lima-vm.io/docs/config/network/managed/macos/#socket_vmnet for the usage.

template

Mon, 01 Jan 0001 00:00:00 +0000

limactl template

Lima template management (EXPERIMENTAL)

Options

 -h, --help help for template

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

template copy

Mon, 01 Jan 0001 00:00:00 +0000

limactl template copy

Copy template

Synopsis

Copy a template via locator to a local file or stdout (default)

limactl template copy [OPTIONS] TEMPLATE [DEST] [flags]

Examples

 Template locators are local files, file://, https://, or template: URLs

 # Copy default template to STDOUT
 limactl template copy template:default -

 # Copy template from web location to local file and embed all external references
 # (this does not embed template: references)
 limactl template copy --embed https://example.com/lima.yaml mighty-machine.yaml

Options

 --embed Embed external dependencies into template
 --embed-all Embed all dependencies into template
 --fill Fill defaults
 -h, --help help for copy
 --param stringArray Set a template parameter, e.g. name=value. Can be passed multiple times.
 --set stringArray Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.
 --verbatim Don't make locators absolute

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

template url

Mon, 01 Jan 0001 00:00:00 +0000

limactl template url

Transform custom template URLs to regular file or https URLs

limactl template url CUSTOM_URL [flags]

Options

 -h, --help help for url

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

template validate

Mon, 01 Jan 0001 00:00:00 +0000

limactl template validate

Validate YAML templates

limactl template validate TEMPLATE [TEMPLATE, ...] [flags]

Options

 --fill Fill defaults
 -h, --help help for validate
 --param stringArray Set a template parameter, e.g. name=value. Can be passed multiple times.
 --set stringArray Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

template yq

Mon, 01 Jan 0001 00:00:00 +0000

limactl template yq

Query template expressions

Synopsis

Use the builtin YQ evaluator to extract information from a template. External references are embedded and default values are filled in before the YQ expression is evaluated.

Example: limactl template yq template:default ‘.images[].location’

The example command is equivalent to using an external yq command like this: limactl template copy –fill template:default - | yq ‘.images[].location’

limactl template yq TEMPLATE EXPR [flags]

Options

 -h, --help help for yq

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

tunnel

Mon, 01 Jan 0001 00:00:00 +0000

limactl tunnel

Create a tunnel for Lima

Synopsis

Create a tunnel for Lima

Create a SOCKS tunnel so that the host can join the guest network.

limactl tunnel [flags] INSTANCE

Options

 -h, --help help for tunnel
 --socks-port int SOCKS port, defaults to a random port
 --type string Tunnel type, currently only "socks" is implemented (default "socks")

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

unprotect

Mon, 01 Jan 0001 00:00:00 +0000

limactl unprotect

Unprotect an instance

limactl unprotect INSTANCE [INSTANCE, ...] [flags]

Options

 -h, --help help for unprotect

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

URL handler plugins

Mon, 01 Jan 0001 00:00:00 +0000

Warning Support for URL handler plugins is experimental

⚡ Requirement	Lima >= 2.0

Lima’s template locator supports custom URL schemes through plugins. A plugin named limactl-url-<scheme> handles URLs that begin with <scheme>:. This lets you create short, memorable template locators for your own workflows.

How it works

When Lima encounters a URL with an unrecognized scheme (e.g. dev:webapp), it:

Searches for an executable named limactl-url-dev using the standard plugin discovery mechanism
Calls the plugin with the part after the colon as its sole argument (in this case, webapp)
Reads the plugin’s stdout, which must be either a URL (with any supported scheme) or a local file path

The plugin’s output can itself use a custom scheme. Lima resolves the chain until it reaches a final https: URL or local file path. It detects and rejects redirect loops.

validate

Mon, 01 Jan 0001 00:00:00 +0000

limactl validate

Validate YAML templates

limactl validate TEMPLATE [TEMPLATE, ...] [flags]

Options

 --fill Fill defaults
 -h, --help help for validate
 --param stringArray Set a template parameter, e.g. name=value. Can be passed multiple times.
 --set stringArray Modify the template inplace, using yq syntax. Can be passed multiple times. See 'limactl help yq-restrictions' for limitations.

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

watch

Mon, 01 Jan 0001 00:00:00 +0000

limactl watch

Watch events from instances

Synopsis

Watch events from Lima instances.

Events include status changes (starting, running, stopping), port forwarding
events, and other instance lifecycle events.

If no instance is specified, events from all instances are watched,
including newly created instances.

The command will continue watching until interrupted (Ctrl+C).

limactl watch [INSTANCE]... [flags]

Examples

 # Watch events from all instances:
 $ limactl watch

 # Watch events from a specific instance:
 $ limactl watch default

 # Include historical events:
 $ limactl watch --history default

 # Show verbose output (host agent logs, etc.):
 $ limactl watch --verbose

 # Watch events in JSON format (for scripting):
 $ limactl watch --json default

Options

 -h, --help help for watch
 --history Include historical events from before watch started
 --json Output events as newline-delimited JSON
 --verbose Show verbose output

Options inherited from parent commands

 --debug Debug mode
 --log-format string Set the logging format [text, json] (default "text")
 --log-level string Set the logging level [trace, debug, info, warn, error]
 --tty Enable TUI interactions such as opening an editor. Defaults to true when stdout is a terminal. Set to false for automation.
 -y, --yes Alias of --tty=false

WSL2

Mon, 01 Jan 0001 00:00:00 +0000

Warning “wsl2” mode is experimental

⚡ Requirement	Lima >= 0.18 + (Windows >= 10 Build 19041 OR Windows 11)

“wsl2” option makes use of native virtualization support provided by Windows’ wsl.exe (more info).

An example configuration:

limactl start --vm-type=wsl2 --mount-type=wsl2 --containerd=system

# Example to run Fedora using vmType: wsl2
vmType: wsl2
images:
# Source: https://github.com/runfinch/finch-core/blob/main/rootfs/Dockerfile
- location: "https://deps.runfinch.com/common/x86-64/finch-rootfs-production-amd64-1771357941.tar.gz"
 arch: "x86_64"
 digest: "sha256:423d1a0f1cabeaea6801995c90ed896dccc091180068626430f19fd87853fdf3"
mountType: wsl2
containerd:
 system: true
 user: false

Automatic Startup

Mon, 01 Jan 0001 00:00:00 +0000

⚡ 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.

Krunkit

Mon, 01 Jan 0001 00:00:00 +0000

Warning “krunkit” is experimental

⚡ Requirement	Lima >= 2.0, macOS >= 14 (Sonoma+), Apple Silicon (arm64)

Krunkit runs super‑light VMs on macOS/ARM64 with a focus on GPU access. It builds on libkrun, a library that embeds a VMM so apps can launch processes in a hardware‑isolated VM (HVF on macOS, KVM on Linux). The standout feature is GPU support in the guest via Mesa’s Venus Vulkan driver (venus), enabling Vulkan workloads inside the VM. See the project: containers/krunkit.

AI agents

Mon, 01 Jan 0001 00:00:00 +0000

Lima is useful for running AI agents inside a VM, so as to prevent agents from directly reading, writing, or executing the host files.

For running AI agents, it is highly recommended to only mount your project directory (current directory) into the VM:

limactl start --mount-only .:w

Drop :w for read-only mode.

HCS

Mon, 01 Jan 0001 00:00:00 +0000

Warning “hcs” mode is experimental

⚡ Requirement	Lima >= 2.3 + (Windows >= Windows 11)

“hcs” option makes use of native virtualization support provided by Windows’ Host Compute System (HCS) API (more info).

An example configuration:

limactl start --vm-type=hcs --plain --dns 8.8.8.8

# Example to run Ubuntu using vmType: hcs
vmType: hcs
images:
- location: "https://cloud-images.ubuntu.com/releases/resolute/release-20260720/ubuntu-26.04-server-cloudimg-amd64.img"
 arch: "x86_64"
 digest: "sha256:117816726abbdefc5ef3e38902e81a76f1c76c3610e709999d0885f9d5d9b477"
plain: true
dns:
- 8.8.8.8

Visual Studio Code

Mon, 01 Jan 0001 00:00:00 +0000

Securing Visual Studio Code with Lima

Lima helps securing the development environment by running it inside a VM. Notably, this prevents AI agents, such as GitHub Copilot in VS Code, from directly executing untrusted commands on the host.

Start a Lima instance. If you use GitHub Copilot, consider disabling mounts by passing the --mount-none flag to prevent Copilot from accessing host files:

limactl start --mount-none

Add the following line to ~/.ssh/config:

Include ~/.lima/*/ssh.config

Open the Remote Explorer in the Visual Studio Code sidebar and select lima-<INSTANCE> from the SSH remote list.

Deprecated features

Mon, 01 Jan 0001 00:00:00 +0000

The following features are deprecated:

limactl show-ssh command: deprecated in v0.18.0 (Use ssh -F ~/.lima/default/ssh.config lima-default instead)
Ansible provisioning mode: deprecated in Lima v1.1.0 (Use ansible-playbook playbook.yaml after the start instead)
limactl --yes flag: deprecated in Lima v2.0.0 (Use limactl (clone|rename|edit|shell) --start instead)
Environment variable LIMA_SSH_OVER_VSOCK: deprecated in Lima v2.0.2 (Use the YAML property .ssh.overVsock)
YAML property cpuType: deprecated in Lima v2.0.0 (Use vmOpts.qemu.cpuType instead)
YAML property rosetta: deprecated in Lima v2.0.0 (Use vmOpts.vz.rosetta instead)
limactl start-at-login command: deprecated in Lima v2.2.0 (Use limactl autostart instead, which also adds support for starting instances at system boot via --condition=boot)

Removed features

YAML property network: deprecated in Lima v0.7.0 and removed in Lima v0.14.0, in favor of networks
YAML property useHostResolver: deprecated in Lima v0.8.1 and removed in Lima v0.14.0,in favor of hostResolver.enabled
VDE support, including VNL and vde_vmnet: deprecated in Lima v0.12.0 and removed in Lima v0.22.0, in favor of socket_vmnet
CentOS 7 guest support: deprecated in Lima v0.9.2 and removed in Lima v0.23.0, in favor of CentOS Stream, AlmaLinux, and Rocky Linux.

Undeprecated features

Loading non-strict YAMLs (i.e., YAMLs with unknown properties): once deprecated in Lima v0.12.0, but undeprecated in Lima v1.0.4

Experimental features

Mon, 01 Jan 0001 00:00:00 +0000

The following features are experimental and subject to change:

mountType: virtiofs on Linux
networks: [{lima: ...}] on Linux (shared, host, and bridged)
vmType: wsl2 and relevant configurations (mountType: wsl2)
arch: riscv64, armv7l, s390x, and ppc64le
video.display: vnc and relevant configuration (video.vnc.display)
audio.device, audio.interface, and audio.microphone
mountInotify: true
tpm: true
user.passwordlessSudo: false (See Sudo)
External drivers: building and using drivers as separate executables (see Virtual Machine Drivers)
vmType: krunkit
vmType:hcs
github URL scheme: referencing templates on GitHub with github: URLs
macOS guests
FreeBSD guests
Windows guests

The following commands are experimental and subject to change:

GitHub Actions

Mon, 01 Jan 0001 00:00:00 +0000

Running Lima on GitHub Actions

On GitHub Actions, Lima is useful for:

Running commands on non-Ubuntu operating systems (e.g., Fedora for testing SELinux)
Emulating multiple hosts

While these tasks can be partially accomplished with containers like Docker, those containers still rely on the Ubuntu host’s kernel and cannot utilize features missing in Ubuntu, such as SELinux.

In contrast, Lima runs virtual machines that do not depend on the Ubuntu host’s kernel.

Governance

Mon, 01 Jan 0001 00:00:00 +0000

Code of Conduct

Lima follows the CNCF Code of Conduct.

Maintainership

Lima is governed by Maintainers who are elected from active contributors.

As a Cloud Native Computing Foundation project, Lima will keep its vendor-neutrality.

Roles

Maintainers consist of two roles:

Committer (Full maintainership): Committers have full write accesses to repos under https://github.com/lima-vm. Committers’ commits should still be made via GitHub pull requests (except for urgent security fixes), and should not be pushed directly. Committers must enable 2FA for their GitHub accounts. Committers are also recognized as Maintainers in https://github.com/cncf/foundation/blob/main/project-maintainers-.project.csv.

Internal data structure

Mon, 01 Jan 0001 00:00:00 +0000

Lima home directory (`${LIMA_HOME}`)

Defaults to ~/.lima.

Note that we intentionally avoid using ~/Library/Application Support/Lima on macOS.

We use ~/.lima so that we can have enough space for the length of the socket path, which must be less than 104 characters on macOS.

Unix: The directory can not be located on an NFS file system, it needs to be local.

_block-device-<disk>.lock files coordinate host block-device use across VZ instances. Raw/block aliases and partitions share the whole-disk lock. The files remain after the VM stops so another VM cannot lock a different inode for the same disk.

Managed networks (macOS)

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	macOS

VMNet assigns a “real” IP address that is reachable from the host.

On Linux hosts, the same shared, host and bridged networks are provided by lima-privileged-net instead.

For VZ instances, the vzNAT network is easier to set up, as it needs neither socket_vmnet nor the sudoers file.

To connect to a socket_vmnet daemon that is not controlled by Lima, see Unmanaged networks.

socket_vmnet

Managed (192.168.105.0/24)

socket_vmnet can be used for adding another guest IP that is accessible from the host and other guests, without depending on vz. It must be installed according to the instruction provided on https://github.com/lima-vm/socket_vmnet.

Virtual Machine Drivers

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.0

Lima supports two types of drivers: internal and external. This architecture allows for extensibility and platform-specific implementations. Drivers are unware whether they are internal or external.

💡 See also: VM Types for user configuration of different virtualization backends.

Internal vs External Drivers

Internal Drivers are compiled directly into the limactl binary and are registered automatically at startup by passing the driver object into registry.Register() function and importing the package in the main limactl code using Go’s blank import _. For example:

Antigravity

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.0

This page describes how to use Lima as a sandbox for Google Antigravity CLI, the successor to Gemini CLI.

Prerequisite

In addition to Antigravity CLI and Lima, make sure that limactl mcp plugin is installed:

$ limactl mcp -v
limactl-mcp version 2.0.0-alpha.1

The limactl mcp plugin is bundled in Lima since v2.0, however, it may not be installed depending on the method of the installation.

Configuration

Run the default Lima instance, with a mount of your project directory:

limactl start --mount-only "$(pwd):w" default

Drop the :w suffix if you do not want to allow writing to the mounted directory.

Breaking changes

Mon, 01 Jan 0001 00:00:00 +0000

v2.3.0

The experimental _LIMA_WINDOWS_EXTRA_PATH environment variable was removed. It prepended directories to limactl.exe’s own PATH on Windows hosts, leaving the calling shell’s PATH untouched. Put them on PATH instead.
The SnapshotManager.ListSnapshots() method now returns structured snapshot metadata instead of raw text. ApplySnapshot() and DeleteSnapshot() now identify snapshots by ID instead of tag. External drivers must update their snapshot implementations and regenerate their protobuf bindings.

v2.2.0

The default socket_vmnet group in networks.yaml was changed from everyone to admin. A non-admin user must set group to a group they belong to (e.g. staff).
The default VM driver on Windows hosts was changed from wsl2 to qemu, as wsl2 is not compatible with most templates.
External driver transport was reworked:
- The Driver.FillConfig() method was removed; its logic was merged into Driver.Configure(), which now returns (*ConfiguredDriver, error).
- The external driver gRPC server socket moved from the OS temp directory (/tmp/lima-driver-<name>-<pid>.sock) to the instance directory (~/.lima/<instance>/lima-driver-<name>.sock).
- External driver authors must update their drivers to match the new driver.Driver interface.

v2.0.0

/tmp/lima is no longer mounted by default.
SSH port is no longer hard-coded to 60022 for the “default” instance.
Port forwarding with sudo nerdctl run -p no longer works with nerdctl prior to v2.1.6.
The default of guestIPMustBeZero was changed from false to true when guestIP is 0.0.0.0.

v1.1.0

The lima-additional-guestagent package was split from the main lima package.

v1.0.0

The default VM type was changed from qemu to vz on macOS hosts with the support for vz.
The default mount type was changed from reverse-sshfs to virtiofs for vz, 9p for qemu.
socket_vmnet binary has to be strictly owned by root.
The default value of ssh.loadDotSSHPubKeys was changed from true to false.
Several templates were removed or renamed.

v0.22.0

Support for vde_vmnet was dropped in favor of socket_vmnet.

v0.3.0

limactl start no longer starts a VM in the foreground.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Reporting issues

Bugs and feature requests can be submitted via https://github.com/lima-vm/lima/issues.

For asking questions, use GitHub Discussions or Slack (#lima).

For reporting vulnerabilities, see https://github.com/lima-vm/.github/blob/main/SECURITY.md.

Contributing code

Getting Involved

We welcome new contributors! Here are some ways to get started and engage with the Lima community:

Introduce Yourself

Join our community communication channels (Slack, GitHub Discussions, Zoom meetings) and say hello! Let us know your interests and how you’d like to help. Also share how your organization is involved with Lima.

Learn Where Work Is Needed

Check the Lima Roadmap, related issues, and discussions to see ongoing and planned work.
Read through the documentation to understand the project’s goals and architecture.

Find Open Issues

Browse GitHub Issues labeled as good first issue for tasks that are great for new contributors.
If you’re unsure where to start, ask in the community channels or open a new discussion.

We’re glad to have you here, your contributions make Lima better!

GitHub template URLs

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.0

Lima provides a special github: URL scheme to reference templates from a GitHub repo, as an alternative to using the https: scheme with a “raw” URL.

For example the templates/fedora.yaml template in the lima-vm/lima repo could be referenced as

https://raw.githubusercontent.com/lima-vm/lima/refs/heads/master/templates/fedora.yaml

Using the github: scheme this becomes:

github:lima-vm/lima/templates/fedora

⚠️ Note: github: URLs are experimental and the exact semantics may change in future releases.

General rules

File extension:

A github: URL without file extension will automatically get a .yaml suffix. So the Fedora URL above is the same as

Intel-on-ARM and ARM-on-Intel

Mon, 01 Jan 0001 00:00:00 +0000

Lima supports several modes for running Intel-on-ARM and ARM-on-Intel:

Slow mode: Intel VM on ARM Host / ARM VM on Intel Host

⚡ Requirement	QEMU, lima-additional-guestagents

Lima can run a VM with a foreign architecture, using QEMU.

For port forwarding, the lima-additional-guestagents package has to be installed on the host.

An example configuration:

limactl start --vm-type=qemu --arch=x86_64 --plain

See the YAML tab for the explanation of the corresponding CLI flags.

Managed networks (Linux)

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.3, Linux

Warning

This feature is experimental and subject to change.

On Linux hosts, the shared, host and bridged networks defined in $LIMA_HOME/_config/networks.yaml assign a “real” IP address that is reachable from the host, in the same way socket_vmnet does on macOS.

They are managed by lima-privileged-net, a privileged helper that ships with Lima and is installed to <PREFIX>/libexec/lima/privileged/lima-privileged-net. It creates a Linux bridge per network and attaches one tap device per instance.

BATS Style Guide

Mon, 01 Jan 0001 00:00:00 +0000

Lima uses BATS with the bats-support, bats-assert, and bats-file helper libraries.

All tests run with errexit enabled (via BATS_RUN_ERREXIT=1 in helpers/load.bash), so any failing command aborts the test immediately.

When to use `run`

Use run only when you need to capture output or assert a non-zero exit code. Do not use it just to check that a command succeeds.

Command should succeed, output does not matter

Call the command directly. errexit handles the failure case.

Default user-mode network

Mon, 01 Jan 0001 00:00:00 +0000

By default Lima only enables the user-mode networking aka “slirp”.

The subnet is hard-coded to 192.168.5.0/24. Use user-v2 network to customize the subnet.

Guest IP (192.168.5.15)

The guest IP address is set to 192.168.5.15.

This IP address is not accessible from the host by design.

Use vzNAT or managed networks to allow accessing the guest IP from the host and other guests.

Host IP (192.168.5.2)

The loopback addresses of the host is 192.168.5.2 and is accessible from the guest as host.lima.internal.

Git tips

Mon, 01 Jan 0001 00:00:00 +0000

Squashing Commits

To combine multiple commits into one (recommended unless your PR covers multiple topics):

# Adjust the number based on how many commits you want to squash
git rebase -i HEAD~3

In the interactive editor that appears:

Keep the first commit as pick
Change subsequent commits from pick to fixup (short formf). You may also choose squash (s), however, fixup is recommended to keep the commit message clean.
Save and close the editor to proceed

Example:

Source Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installing from Source

If you prefer to build Lima from source, follow these steps:

Prerequisites

Ensure you have the following dependencies installed:

git
go
make

Build and Install

Run the following commands:

git clone https://github.com/lima-vm/lima
cd lima
make
sudo make install

Note: sudo make install is required unless you have write permissions for /usr/local. Otherwise, installation may fail.

Alternative Installation (Without Sudo)

If you prefer installing Lima in your home directory, configure the PREFIX and PATH as follows:

Port Forwarding

Mon, 01 Jan 0001 00:00:00 +0000

Lima supports automatic port-forwarding of localhost ports from guest to host.

See also: In plain mode, dynamic port forwarding is disabled and only rules with static: true are forwarded.

Port forwarding types

Lima supports two port forwarders: SSH and GRPC.

The default port forwarder is shown in the following table.

Version	Default
v0.1.0	SSH
v1.0.0	GRPC
v1.0.1	SSH
v1.1.0	GRPC

The default was once changed to GRPC in Lima v1.0, but it was reverted to SSH in v1.0.1 due to stability reasons. The default was further reverted to GRPC in Lima v1.1, as the stability issues were resolved.

user-v2 network

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 0.16.0

user-v2 network provides a user-mode networking similar to the default user-mode network and also provides support for vm -> vm communication.

To enable this network mode, define a network with mode: user-v2 in networks.yaml

By default, the below network configuration is already applied (Since v0.18).

...
networks:
 user-v2:
 mode: user-v2
 gateway: 192.168.104.1
 netmask: 255.255.255.0
...

Instances can then reference these networks from their lima.yaml file:

vzNAT network

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 0.14, macOS >= 13.0

vzNAT assigns a “real” IP address that is reachable from the host.

Compared to managed networks, the “vzNAT” network:

does not need the socket_vmnet binary and the sudoers file.
has a significant advantage in the throughput. See the benchmark result.

For VZ instances, the “vzNAT” network can be configured as follows:

limactl start --vm-type=vz --network=vzNAT

networks:
- vzNAT: true

Unmanaged networks (socket_vmnet)

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	macOS

Lima can also connect to “unmanaged” networks addressed by “socket”. This means that the daemons will not be controlled by Lima, but must be started before the instance. The interface type (host, shared, or bridged) is configured in socket_vmnet and not in lima.

See Managed networks (macOS) for how to install socket_vmnet.

networks:
 - socket: "/var/run/socket_vmnet"

Sudo

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.2

By default, the guest user has passwordless sudo (NOPASSWD:ALL).

Warning user.passwordlessSudo: false is experimental. The default user.passwordlessSudo: true is not experimental.

The password is only generated once, on first boot. If you manually change the password and remove ~/password, it will not be regenerated on subsequent boots, the file is purely informational for the initial login.

user:
 passwordlessSudo: false

Caveats

Requires plain: true on non-macOS guests (GHSA-2j9v-p4xj-cjw2): the guest agent’s Unix socket tunneling is disabled until it can safely refuse privileged socket tunneling with passwordless sudo off.
Only applies to cloud-init provisioned guests (QEMU/vz). Setting user.passwordlessSudo: false on WSL2 (Windows) guests returns a validation error, as WSL2 does not support this configuration as of now.
The guest user is already a member of the adm and systemd-journal groups, which grants passive read access to /var/log/* and the full system journal independent of sudo.
param still relies on sudo internally (param.env is read via sudo cat inside the guest), so it may not work as expected when user.passwordlessSudo: false is set. A warning is printed in this case.
macOS: not configurable. Password-required sudo is always on (except /sbin/shutdown -h now), matching the built-in macOS guest behavior. Setting user.passwordlessSudo: true on a macOS guest returns a validation error.

Filesystem mounts

Mon, 01 Jan 0001 00:00:00 +0000

Lima supports several methods for mounting the host filesystem into the guest.

See also: In plain mode, all filesystem mounts are disabled.

The default mount type is shown in the following table:

Lima Version	Default
< 0.10	reverse-sshfs + Builtin SFTP server
>= 0.10	reverse-sshfs + OpenSSH SFTP server
>= 0.17	reverse-sshfs + OpenSSH SFTP server for QEMU, virtiofs for VZ
>= 1.0	9p for QEMU (on non-Windows), virtiofs for VZ

Mount types

reverse-sshfs

The “reverse-sshfs” mount type exposes the host filesystem by running an SFTP server on the host. While the host works as an SFTP server, the host does not open any TCP port, as the host initiates an SSH connection into the guest and let the guest connect to the SFTP server via the stdin.

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Instead of using a static text file, Lima uses the roadmap label on GitHub issues to designate features or bug fixes that we plan to implement.

Issues are tagged with the roadmap label when at least one maintainer or contributor has declared intent to work on or help with the implementation.

There are no commitments or timelines attached to the label, and the label may be removed again from an abandoned issue at any time.

Plain mode

Mon, 01 Jan 0001 00:00:00 +0000

Plain mode makes the VM instance as close as possible to a physical host by disabling Lima’s convenience features such as filesystem mounts, dynamic port forwarding, and the built-in containerd.

It is useful when you want to provision the guest with plain old ssh and rsync, without relying on Lima-specific integrations. See the GitHub Actions example for a typical use case.

Enabling plain mode

plain: true

limactl start --plain

Plain mode is disabled (false) by default.

Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

Environment Variables

This page documents the environment variables used in Lima.

`LIMA_HOME`

Description: Specifies the Lima home directory.
Default: ~/.lima
Usage:
```
export LIMA_HOME=~/.lima-custom
lima
```

`LIMA_INSTANCE`

Description: Specifies the name of the Lima instance to use.
Default: default

Usage:

export LIMA_INSTANCE=my-instance
lima uname -a

`LIMA_SHELL`

Description: Specifies the shell interpreter to use inside the Lima instance.
Default: User’s shell configured inside the instance
Usage:
```
export LIMA_SHELL=/bin/bash
lima
```

`LIMA_TEMPLATES_PATH`

Description: Specifies the directories used to resolve template: URLs.
Default: $LIMA_HOME/_templates:/usr/local/share/lima/templates

Usage:

export LIMA_TEMPLATES_PATH="$HOME/.config/lima/templates:/usr/local/share/lima/templates"
limactl create --name my-vm template:my-distro

`LIMA_WORKDIR`

Description: Specifies the initial working directory inside the Lima instance.
Default: Current directory from the host

Usage:

export LIMA_WORKDIR=/home/user/project
lima

`LIMA_SHELLENV_ALLOW`

Description: Specifies a comma-separated list of environment variable patterns to exempt from the block list when propagating environment variables to the Lima instance with --preserve-env. Variables matching the allow list pass through even if they also match the block list. Variables that match neither list pass through as well. This feature only applies to Lima v2.0.0 or later.
Default: unset (when using --preserve-env, all variables are propagated except those matching the block list patterns)

Usage:

# Pass FPATH and XAUTHORITY even though they are on the default block list
export LIMA_SHELLENV_ALLOW="FPATH,XAUTHORITY,CUSTOM_*"
limactl shell --preserve-env default

# To propagate ONLY specific variables, block everything else first
export LIMA_SHELLENV_BLOCK="*"
export LIMA_SHELLENV_ALLOW="GITHUB_TOKEN,MY_*"
limactl shell --preserve-env default

Behavior:
- Without --preserve-env: No environment variables are propagated (regardless of this setting)
- With --preserve-env and LIMA_SHELLENV_ALLOW unset: All variables are propagated except those in the block list
- With --preserve-env and LIMA_SHELLENV_ALLOW set: Variables matching the allow list are propagated even if they also match the block list. Variables matching neither list are still propagated. Only variables that match the block list without a corresponding allow list match are blocked.
Note: Patterns support * wildcards anywhere in the pattern (e.g., CUSTOM_* matches CUSTOM_VAR; *TOKEN* matches GITHUB_TOKEN).

`LIMA_SHELLENV_BLOCK`

Description: Specifies a comma-separated list of environment variable patterns to block when propagating environment variables to the Lima instance with --preserve-env. Can either replace the default block list or extend it by prefixing with +. This feature only applies to Lima v2.0.0 or later.

GPU acceleration

Mon, 01 Jan 0001 00:00:00 +0000

Lima VM supports GPU acceleration for the following VM types:

krunkit.

Note

“Lima” in this web site refers to the Lima VM project.

The Lima VM project is unrelated to the Lima driver project (driver for ARM Mali GPUs), which appears as “Lima” in the documentations of Mesa 3D, etc.

Subprojects

Mon, 01 Jan 0001 00:00:00 +0000

Some portions of Lima are useful for other projects too and split out to separate repos:

https://github.com/lima-vm/socket_vmnet: vmnet.framework support for unmodified rootless QEMU
https://github.com/lima-vm/lima-actions: run Lima on GitHub Actions
https://github.com/lima-vm/go-qcow2reader: qcow2 reader for Go
https://github.com/lima-vm/sshocker: ssh + reverse sshfs + port forwarder, in Docker-like CLI (predecessor of Lima)
https://github.com/lima-vm/alpine-lima: Create an alpine based image for lima

See also https://github.com/lima-vm for other subprojects.

The maintainership of the subprojects corresponds to the maintainership of Lima itself.

MCP tools

Mon, 01 Jan 0001 00:00:00 +0000

Lima implements the “MCP Sandbox Interface” (tentative name): https://pkg.go.dev/github.com/lima-vm/lima/v2/pkg/mcp/msi

MCP Sandbox Interface defines MCP (Model Context Protocol) tools that can be used for reading, writing, and executing local files with an appropriate sandboxing technology, such as Lima.

The sandboxing technology can be more secure and/or efficient than the default tools provided by an AI agent.

MCP Sandbox Interface was inspired by Google Gemini CLI’s built-in tools.

`glob`

Description

Finds files matching specific glob patterns (e.g., src/**/*.ts, *.md)

Colima (third-party project)

Mon, 01 Jan 0001 00:00:00 +0000

“How does Lima relate to Colima?”

Colima is a third-party project that wraps Lima to provide an alternative user experience for launching containers.

The key difference is that Colima launches Docker by default, while Lima launches containerd by default.

Container	Lima	Colima
containerd	`limactl start`	`colima start --runtime=containerd`
Docker	`limactl start template:docker`	`colima start`
Podman	`limactl start template:podman`	-
Kubernetes (k3s)	`limactl start template:k3s`	`colima start --kubernetes`
Kubernetes (kubeadm)	`limactl start template:k8s`	-

The colima CLI is similar to the limactl CLI, but there are subtle differences:

Disks

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to manage Lima disks: standalone raw/qcow2 block devices that persist independently of any instance.

Additional Disks (limactl disk)

Lima disks can be shared across instances and survive instance deletion.

Listing disks

limactl disk list
# or the short alias:
limactl disk ls

Creating a disk

limactl disk create NAME --size SIZE [--format qcow2|raw]

The supported formats are qcow2 (default) and raw.

Example – create a 20 GiB disk named data:

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

Lima

Enhanced supply chain security with gomodjail

Linux

See also

QEMU

VM driver plugins

Accelerating rootless networking with bypass4netns

CLI plugins

Plugin Discovery

macOS

VZ

Windows

autostart

limactl autostart

Options

Options inherited from parent commands

SEE ALSO

autostart disable

limactl autostart disable

Options

Options inherited from parent commands

SEE ALSO

autostart enable

limactl autostart enable

Options

Options inherited from parent commands

SEE ALSO

clone

limactl clone

Synopsis

Options

Options inherited from parent commands

SEE ALSO

completion

limactl completion

Synopsis

Options

Options inherited from parent commands

SEE ALSO

completion bash

limactl completion bash

Synopsis

Linux:

macOS:

completion fish

limactl completion fish

Synopsis

Options

Options inherited from parent commands

SEE ALSO

completion powershell

limactl completion powershell

Synopsis

Options

Options inherited from parent commands

SEE ALSO

completion zsh

limactl completion zsh

Synopsis

copy

limactl copy

Synopsis

create

limactl create

Examples

Options

Options inherited from parent commands

SEE ALSO

delete

limactl delete

Options

Options inherited from parent commands

SEE ALSO

disk

limactl disk

Examples

Options

Options inherited from parent commands

SEE ALSO

disk create