This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Lima: Linux Machines

Lima launches Linux virtual machines with automatic file sharing and port forwarding (similar to WSL2).

✅ Automatic file sharing

✅ Automatic port forwarding

✅ Built-in support for containerd (Other container engines can be used too)

✅ Intel on Intel

ARM on Intel

✅ ARM on ARM

Intel on ARM

✅ Various guest Linux distributions: AlmaLinux, Alpine, Arch Linux, Debian, Fedora, openSUSE, Oracle Linux, Rocky, Ubuntu (default), …

Related project: sshocker (ssh with file sharing and port forwarding)

This project is unrelated to The Lima driver project (driver for ARM Mali GPUs).

Motivation

The original goal of Lima was to promote containerd including nerdctl (contaiNERD ctl) to Mac users, but Lima can be used for non-container applications as well. Lima also supports non-macOS hosts (Linux, NetBSD, etc.).

1 - Installation

NOTE Lima is not regularly tested on ARM Mac (due to lack of CI).

Prerequisite:

  • QEMU 7.0 or later (Required, only if QEMU driver is used)
brew install lima

Homebrew formula is available here. Supports macOS and Linux.

sudo port install lima

Port: https://ports.macports.org/port/lima/

Download the binary archive of Lima from https://github.com/lima-vm/lima/releases, and extract it under /usr/local (or somewhere else).

brew install jq
VERSION=$(curl -fsSL https://api.github.com/repos/lima-vm/lima/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/lima-vm/lima/releases/download/${VERSION}/lima-${VERSION:1}-$(uname -s)-$(uname -m).tar.gz" | tar Cxzvm /usr/local

The source code can be found at https://github.com/lima-vm/lima.git

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

To change the build configuration, run make config or make menuconfig.

This requires kconfig tools installed, it is also possible to edit .config. The default configuration can be found in the file config.mk (make syntax).

Kconfig tools

The tools are available as either “kconfig-frontends” or “kbuild-standalone”. There is one conf for the text, and one mconf for the menu interface.

A python implementation is available at https://pypi.org/project/kconfiglib. It can be installed with pip install --user kconfiglib, including guiconfig.

2 - Usage

Starting a Linux instance

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”:

limactl create --name=default template://docker
limactl start default

See also the command reference:

Executing Linux commands

Run limactl shell <INSTANCE> <COMMAND> to launch <COMMAND> on the VM:

limactl shell default uname -a

See also the command reference:

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.

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

Shell completion

  • To enable bash completion, add source <(limactl completion bash) to ~/.bash_profile.
  • To enable zsh completion, see limactl completion zsh --help

3 - Examples

Running Linux commands

lima sudo apt-get install -y neofetch
lima neofetch

Accessing host files

By default, the VM has read-only accesses to /Users/<USERNAME> and read-write accesses to /tmp/lima.

To allow writing to /Users/<USERNAME>:

limactl edit --mount-writable --mount-type=virtiofs

Specifying --mount-type=virtiofs is not necessary here, but it is highly recommended for the best performance and stability.

Running containers

nerdctl.lima run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
limactl start template://docker
export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
limactl start template://k8s
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
kubectl apply -f ...

Advanced configuration

limactl start \
  --name=default \
  --cpus=4 \
  --memory=8 \
  --vm-type=vz \
  --rosetta \
  --mount-type=virtiofs \
  --mount-writable \
  --network=vzNAT \
  template://fedora
  • --name=default: Set the instance name to “default”
  • --cpus=4: Set the number of the CPUs to 4
  • --memory=8: Set the amount of the memory to 8 GiB
  • --vm-type=vz: Use Apple’s Virtualization.framework (vz) to enable Rosetta, virtiofs, and vzNAT
  • --rosetta: Allow running Intel (AMD) binaries on ARM
  • --mount-type=virtiofs: Use virtiofs for better performance
  • --mount-writable: Make the home mount (/Users/<USERNAME>) writable
  • --network=vzNAT: Make the VM reachable from the host by its IP address
  • template://fedora: Use Fedora

4 - Templates

Run limactl start template://fedora to create a Lima instance named "fedora".

To open a shell, run limactl shell fedora bash or LIMA_INSTANCE=fedora lima bash.


⭐ = "Tier 1"

☆ = "Tier 2"

Default: default (⭐Ubuntu, with containerd/nerdctl)

Distro:

Container engines:

Container image builders:

Container orchestration:

Optional feature enablers:

Lost+found:

Tier

  • "Tier 1" (marked with ⭐): Good stability. Regularly tested on the CI.
  • "Tier 2" (marked with ☆): Moderate stability. Regularly tested on the CI.

Other yamls are tested only occasionally and manually.

5 - Command Reference

5.1 - completion

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

SEE ALSO

5.2 - completion bash

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.

limactl completion bash

Options

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

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.3 - completion fish

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

SEE ALSO

5.4 - completion powershell

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

SEE ALSO

5.5 - completion zsh

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:

Linux:

limactl completion zsh > "${fpath[1]}/_limactl"

macOS:

limactl completion zsh > $(brew --prefix)/share/zsh/site-functions/_limactl

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

limactl completion zsh [flags]

Options

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

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.6 - copy

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.

Example: limactl copy default:/etc/os-release .

limactl copy SOURCE ... TARGET [flags]

Options

  -h, --help        help for copy
  -r, --recursive   copy directories recursively

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.7 - create

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"'

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/examples/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)
      --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
      --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-type string   mount type (reverse-sshfs, 9p, virtiofs)
      --mount-writable      make all mounts writable
      --name string         override the instance name
      --network strings     additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
      --plain               plain mode. Disable mounts, port forwarding, containerd, etc.
      --rosetta             enable Rosetta (for vz instances)
      --set string          modify the template inplace, using yq syntax
      --video               enable video output (has negative performance impact for QEMU)
      --vm-type string      virtual machine type (qemu, vz)

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.8 - delete

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

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.9 - disk

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

SEE ALSO

5.10 - disk create

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

SEE ALSO

5.11 - disk delete

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

SEE ALSO

5.12 - disk list

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

SEE ALSO

5.13 - disk resize

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

SEE ALSO

5.14 - disk unlock

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

SEE ALSO

5.15 - edit

limactl edit

Edit an instance of Lima

limactl edit INSTANCE [flags]

Options

      --cpus int            number of CPUs
      --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-type string   mount type (reverse-sshfs, 9p, virtiofs)
      --mount-writable      make all mounts writable
      --network strings     additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
      --rosetta             enable Rosetta (for vz instances)
      --set string          modify the template inplace, using yq syntax
      --video               enable video output (has negative performance impact for QEMU)

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.16 - factory-reset

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

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.17 - info

limactl info

Show diagnostic information

limactl info [flags]

Options

  -h, --help   help for info

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.18 - limactl

limactl

Lima: Linux virtual machines

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

SEE ALSO

5.19 - list

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.

These functions are available to go templates:

indent : add spaces to beginning of each line missing : return message if the text is empty

The following legacy flags continue to function: –json - equal to ‘–format json’

limactl list [flags] [INSTANCE]...

Options

      --all-fields      Show all fields
  -f, --format string   output format, one of: json, yaml, table, go-template (default "table")
  -h, --help            help for list
      --json            JSONify output
      --list-fields     List fields available for format
  -q, --quiet           Only show names

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.20 - protect

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

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.21 - prune

limactl prune

Prune garbage objects

limactl prune [flags]

Options

  -h, --help   help for prune

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.22 - shell

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.

Hint: try –debug to show the detailed logs, if it seems hanging (mostly due to some SSH issue).

limactl shell [flags] INSTANCE [COMMAND...]

Options

  -h, --help             help for shell
      --shell string     shell interpreter, e.g. /bin/bash
      --workdir string   working directory

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.23 - show-ssh

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

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.24 - snapshot

limactl snapshot

Manage instance snapshots

Options

  -h, --help   help for snapshot

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.25 - snapshot apply

limactl snapshot apply

Apply (load) a snapshot

limactl snapshot apply INSTANCE [flags]

Options

  -h, --help         help for apply
      --tag string   name of the snapshot

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.26 - snapshot create

limactl snapshot create

Create (save) a snapshot

limactl snapshot create INSTANCE [flags]

Options

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

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.27 - snapshot delete

limactl snapshot delete

Delete (del) a snapshot

limactl snapshot delete INSTANCE [flags]

Options

  -h, --help         help for delete
      --tag string   name of the snapshot

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.28 - snapshot list

limactl snapshot list

List existing snapshots

limactl snapshot list INSTANCE [flags]

Options

  -h, --help    help for list
  -q, --quiet   Only show tags

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

5.29 - start

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

'limactl start' also accepts the 'limactl create' flags such as '--set'.
See the examples in 'limactl create --help'.

Options

      --arch string         [limactl create] machine architecture (x86_64, aarch64, riscv64)
      --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
      --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-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
      --network strings     [limactl create] additional networks, e.g., "vzNAT" or "lima:shared" to assign vmnet IP
      --plain               [limactl create] plain mode. Disable mounts, port forwarding, containerd, etc.
      --rosetta             [limactl create] enable Rosetta (for vz instances)
      --set string          [limactl create] modify the template inplace, using yq syntax
      --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 (qemu, vz)

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.30 - start-at-login

limactl start-at-login

Register/Unregister an autostart file for the instance

limactl start-at-login INSTANCE [flags]

Options

      --enabled   Automatically start the instance when the user logs in (default true)
  -h, --help      help for start-at-login

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.31 - stop

limactl stop

Stop an instance

limactl stop INSTANCE [flags]

Options

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

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.32 - sudoers

limactl sudoers

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

Synopsis

Generate the content of the /etc/sudoers.d/lima file for enabling vmnet.framework support. The content is written to stdout, NOT to the file. This command must not run as the root user. See /usr/local/share/doc/lima/docs/network.md for the usage.

limactl sudoers [--check [SUDOERSFILE-TO-CHECK]] [flags]

Examples


To generate the /etc/sudoers.d/lima file:
$ limactl sudoers | sudo tee /etc/sudoers.d/lima

To validate the existing /etc/sudoers.d/lima file:
$ limactl sudoers --check /etc/sudoers.d/lima

Options

      --check   check that the sudoers file is up-to-date with "~/.lima/_config/networks.yaml"
  -h, --help    help for sudoers

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.33 - unprotect

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

SEE ALSO

  • limactl - Lima: Linux virtual machines

5.34 - validate

limactl validate

Validate YAML files

limactl validate FILE.yaml [FILE.yaml, ...] [flags]

Options

  -h, --help   help for validate

Options inherited from parent commands

      --debug              debug mode
      --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.

SEE ALSO

  • limactl - Lima: Linux virtual machines

6 - Configuration guide

For all the configuration items, see https://github.com/lima-vm/lima/blob/master/examples/default.yaml.

The current default spec:

  • OS: Ubuntu
  • CPU: 4 cores
  • Memory: 4 GiB
  • Disk: 100 GiB
  • Mounts: ~ (read-only), /tmp/lima (writable)
  • SSH: 127.0.0.1:60022

6.1 - VM types

Lima supports two ways of running guest machines:

The vmType can be specified only on creating the instance. The vmType of existing instances cannot be changed.

See the following flowchart to choose the best vmType for you:

flowchart
  host{"Host OS"} -- "Windows" --> wsl2["WSL2"]
  host -- "Linux" --> qemu["QEMU"]
  host -- "macOS" --> intel_on_arm{"Need to run <br> Intel binaries <br> on ARM?"}
  intel_on_arm -- "Yes" --> just_elf{"Just need to <br> run Intel userspace (fast), <br> or entire Intel VM (slow)?"}
  just_elf -- "Userspace (fast)" --> vz
  just_elf -- "VM (slow)" --> qemu
  intel_on_arm --  "No" --> vz["VZ"]

QEMU

“qemu” option makes use of QEMU to run guest operating system. This option is used by default if “vmType” is not set.

VZ

Warning “vz” mode is experimental

⚡ RequirementLima >= 0.14, macOS >= 13.0

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

An example configuration:

limactl start --vm-type=vz --mount-type=virtiofs
# Example to run ubuntu using vmType: vz instead of qemu (Default)
vmType: "vz"
images:
- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img"
  arch: "x86_64"
- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img"
  arch: "aarch64"
mounts:
  - location: "~"
mountType: "virtiofs"

Caveats

  • “vz” option is only supported on macOS 13 or above
  • Virtualization.framework doesn’t support running “intel guest on arm” and vice versa

Known Issues

  • “vz” doesn’t support legacyBIOS: true option, so guest machine like centos-stream, archlinux, oraclelinux will not work
  • When running lima using “vz”, ${LIMA_HOME}/<INSTANCE>/serial.log will not contain kernel boot logs
  • On Intel Mac with macOS prior to 13.5, Linux kernel v6.2 (used by Ubuntu 23.04, Fedora 38, etc.) is known to be unbootable on vz. kernel v6.3 and later should boot, as long as it is booted via GRUB. https://github.com/lima-vm/lima/issues/1577#issuecomment-1565625668 The issue is fixed in macOS 13.5.

WSL2

Warning “wsl2” mode is experimental

⚡ RequirementLima >= 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/Dockerfile
- location: "https://deps.runfinch.com/common/x86-64/finch-rootfs-production-amd64-1690920103.tar.zst"
  arch: "x86_64"
  digest: "sha256:53f2e329b8da0f6a25e025d1f6cc262ae228402ba615ad095739b2f0ec6babc9"
mountType: wsl2 
containerd:
  system: true
  user: false

Caveats

  • “wsl2” option is only supported on newer versions of Windows (roughly anything since 2019)

Known Issues

  • “wsl2” currently doesn’t support many of Lima’s options. See this file for the latest supported options.
  • When running lima using “wsl2”, ${LIMA_HOME}/<INSTANCE>/serial.log will not contain kernel boot logs
  • WSL2 requires a tar formatted rootfs archive instead of a VM image
  • Windows doesn’t ship with ssh.exe, gzip.exe, etc. which are used by Lima at various points. The easiest way around this is to run winget install -e --id Git.MinGit (winget is now built in to Windows as well), and add the resulting C:\Program Files\Git\usr\bin\ directory to your path.

6.2 - Intel-on-ARM and ARM-on-Intel

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

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

Lima can run a VM with a foreign architecture, just by specifying arch in the YAML.

arch: "x86_64"
# arch: "aarch64"

images:
  - location: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
    arch: "x86_64"
  - location: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-arm64.img"
    arch: "aarch64"

# Disable mounts and containerd, otherwise booting up may timeout if the host is slow
mounts: []
containerd:
  system: false
  user: false

Running a VM with a foreign architecture is extremely slow. Consider using Fast mode or Fast mode 2 whenever possible.

Fast mode: Intel containers on ARM VM on ARM Host / ARM containers on Intel VM on Intel Host

This mode uses QEMU User Mode Emulation. QEMU User Mode Emulation is significantly faster than QEMU System Mode Emulation, but it often sacrifices compatibility.

Set up:

lima sudo systemctl start containerd
lima sudo nerdctl run --privileged --rm tonistiigi/binfmt:qemu-v7.0.0-28@sha256:66e11bea77a5ea9d6f0fe79b57cd2b189b5d15b93a2bdb925be22949232e4e55 --install all

Run containers:

$ lima nerdctl run --platform=amd64 --rm alpine uname -m
x86_64

$ lima nerdctl run --platform=arm64 --rm alpine uname -m
aarch64

Build and push container images:

$ lima nerdctl build --platform=amd64,arm64 -t example.com/foo:latest .
$ lima nerdctl push --all-platforms example.com/foo:latest

See also https://github.com/containerd/nerdctl/blob/master/docs/multi-platform.md

Fast mode 2 (Rosetta): Intel containers on ARM VM on ARM Host

Warning “vz” mode, including support for Rosetta, is experimental

⚡ RequirementLima >= 0.14, macOS >= 13.0, ARM

Rosetta is known to be much faster than QEMU User Mode Emulation. Rosetta is available for VZ instances on ARM hosts.

limactl start --vm-type=vz --rosetta
vmType: "vz"
rosetta:
  # Enable Rosetta for Linux.
  # Hint: try `softwareupdate --install-rosetta` if Lima gets stuck at `Installing rosetta...`
  enabled: true
  # Register rosetta to /proc/sys/fs/binfmt_misc
  binfmt: true

6.3 - Network

See the following flowchart to choose the best network for you:

flowchart
  connect_to_vm_via{"Connect to the VM via"} -- "localhost" --> default["Default"]
  connect_to_vm_via -- "IP" --> connect_from{"Connect to the VM IP from"}
  connect_from -- "Host" --> vm{"VM type"}
  vm -- "vz" --> vzNAT["vzNAT"]
  vm -- "qemu" --> shared["socket_vmnet (shared)"]
  connect_from -- "Other VMs" --> userV2["user-v2"]
  connect_from -- "Other hosts" --> bridged["socket_vmnet (bridged)"]

Default user-mode network (192.168.5.0/24)

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

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 VMNet (see below) 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.

DNS (192.168.5.3)

The DNS.

If hostResolver.enabled in lima.yaml is true, then the hostagent is going to run a DNS server over tcp and udp - each on a separate randomly selected free port. This server does a local lookup using the native host resolver, so it will deal correctly with VPN configurations and split-DNS setups, as well as mDNS, local /etc/hosts etc. For this the hostagent has to be compiled with CGO_ENABLED=1 as default Go resolver is broken.

These tcp and udp ports are then forwarded via iptables rules to 192.168.5.3:53, overriding the DNS provided by QEMU via slirp.

Currently following request types are supported:

  • A
  • AAAA
  • CNAME
  • TXT
  • NS
  • MX
  • SRV

For all other queries hostagent will redirect the query to the nameservers specified in /etc/resolv.conf (or, if that fails - to 8.8.8.8 and 1.1.1.1).

DNS over tcp is rarely used. It is usually only used either when user explicitly requires it, or when request+response can’t fit into a single UDP packet (most likely in case of DNSSEC), or in the case of certain management operations such as domain transfers. Neither DNSSEC nor management operations are currently supported by a hostagent, but on the off chance that the response may contain an unusually long list of records - hostagent will also listen for the tcp traffic.

During initial cloud-init bootstrap, iptables may not yet be installed. In that case the repo server is determined using the slirp DNS. After iptables has been installed, the forwarding rule is applied, switching over to the hostagent DNS.

If hostResolver.enabled is false, then DNS servers can be configured manually in lima.yaml via the dns setting. If that list is empty, then Lima will either use the slirp DNS (on Linux), or the nameservers from the first host interface in service order that has an assigned IPv4 address (on macOS).

VMNet networks

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

The configuration steps are different for each network type:

socket_vmnet

Managed (192.168.105.0/24)

socket_vmnet is required for adding another guest IP that is accessible from the host and other guests.

# Install socket_vmnet
brew install socket_vmnet

# Set up the sudoers file for launching socket_vmnet from Lima
limactl sudoers >etc_sudoers.d_lima
sudo install -o root etc_sudoers.d_lima /etc/sudoers.d/lima

Note

Lima before v0.12 used vde_vmnet for managing the networks. vde_vmnet is no longer supported.

The networks are defined in $LIMA_HOME/_config/networks.yaml. If this file doesn’t already exist, it will be created with these default settings:

Default

# Path to socket_vmnet executable. Because socket_vmnet is invoked via sudo it should be
# installed where only root can modify/replace it. This means also none of the
# parent directories should be writable by the user.
#
# The varRun directory also must not be writable by the user because it will
# include the socket_vmnet pid file. Those will be terminated via sudo, so replacing
# the pid file would allow killing of arbitrary privileged processes. varRun
# however MUST be writable by the daemon user.
#
# None of the paths segments may be symlinks, why it has to be /private/var
# instead of /var etc.
paths:
# socketVMNet requires Lima >= 0.12 .
  socketVMNet: /opt/socket_vmnet/bin/socket_vmnet
  varRun: /private/var/run/lima
  sudoers: /private/etc/sudoers.d/lima

group: everyone

networks:
  shared:
    mode: shared
    gateway: 192.168.105.1
    dhcpEnd: 192.168.105.254
    netmask: 255.255.255.0
  bridged:
    mode: bridged
    interface: en0
    # bridged mode doesn't have a gateway; dhcp is managed by outside network
  host:
    mode: host
    gateway: 192.168.106.1
    dhcpEnd: 192.168.106.254
    netmask: 255.255.255.0

Instances can then reference these networks:

limactl start --network=lima:shared
networks:
  # Lima can manage the socket_vmnet daemon for networks defined in $LIMA_HOME/_config/networks.yaml automatically.
  # The socket_vmnet binary must be installed into a secure location only alterable by the admin.
  # - lima: shared
  #   # MAC address of the instance; lima will pick one based on the instance name,
  #   # so DHCP assigned ip addresses should remain constant over instance restarts.
  #   macAddress: ""
  #   # Interface name, defaults to "lima0", "lima1", etc.
  #   interface: ""

The network daemon is started automatically when the first instance referencing them is started, and will stop automatically once the last instance has stopped. Daemon logs will be stored in the $LIMA_HOME/_networks directory.

The IP address is automatically assigned by macOS’s bootpd. If the IP address is not assigned, try the following commands:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd

Unmanaged

networks:
  # 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.
  # - socket: "/var/run/socket_vmnet"

vzNAT

Warning “vz” mode is experimental

⚡ RequirementLima >= 0.14, macOS >= 13.0

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

limactl start --vm-type=vz --network=vzNAT
networks:
- vzNAT: true

The range of the IP address is not specifiable.

The “vzNAT” network does not need the socket_vmnet binary and the sudoers file.

Lima user-v2 network

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

Warning This network mode is experimental

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:

limactl start --network=lima:user-v2
networks:
   - lima: user-v2

An instance’s IP address is resolvable from another instance as lima-<NAME>.internal. (e.g., lima-default.internal.).

Note

6.4 - Filesystem mounts

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

The default mount type is shown in the following table:

Lima VersionDefault
< 0.10reverse-sshfs + Builtin SFTP server
>= 0.10reverse-sshfs + OpenSSH SFTP server
>= 0.17reverse-sshfs + OpenSSH SFTP server for QEMU, virtiofs for VZ
>= 1.0 (Planned)9p for QEMU, 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.

An example configuration:

limactl start --mount-type=reverse-sshfs
mountType: "reverse-sshfs"
mounts:
- location: "~"
  sshfs:
    # Enabling the SSHFS cache will increase performance of the mounted filesystem, at
    # the cost of potentially not reflecting changes made on the host in a timely manner.
    # Warning: It looks like PHP filesystem access does not work correctly when
    # the cache is disabled.
    # 🟢 Builtin default: true
    cache: null
    # SSHFS has an optional flag called 'follow_symlinks'. This allows mounts
    # to be properly resolved in the guest os and allow for access to the
    # contents of the symlink. As a result, symlinked files & folders on the Host
    # system will look and feel like regular files directories in the Guest OS.
    # 🟢 Builtin default: false
    followSymlinks: null
    # SFTP driver, "builtin" or "openssh-sftp-server". "openssh-sftp-server" is recommended.
    # 🟢 Builtin default: "openssh-sftp-server" if OpenSSH SFTP Server binary is found, otherwise "builtin"
    sftpDriver: null

The default value of sftpDriver has been set to “openssh-sftp-server” since Lima v0.10, when an OpenSSH SFTP Server binary such as /usr/libexec/sftp-server is detected on the host. Lima prior to v0.10 had used “builtin” as the SFTP driver.

Caveats

  • A mount is disabled when the SSH connection was shut down.
  • A compromised sshfs process in the guest may have an access to unexposed host directories.

9p

Warning “9p” mode is experimental

The “9p” mount type is implemented by using QEMU’s virtio-9p-pci devices. virtio-9p-pci is also known as “virtfs”, but note that this is unrelated to virtio-fs.

An example configuration:

limactl start --vm-type=qemu --mount-type=9p
vmType: "qemu"
mountType: "9p"
mounts:
- location: "~"
  9p:
    # Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
    # "mapped-xattr" and "mapped-file" are useful for persistent chown but incompatible with symlinks.
    # 🟢 Builtin default: "none" (since Lima v0.13)
    securityModel: null
    # Select 9P protocol version. Valid options are: "9p2000" (legacy), "9p2000.u", "9p2000.L".
    # 🟢 Builtin default: "9p2000.L"
    protocolVersion: null
    # The number of bytes to use for 9p packet payload, where 4KiB is the absolute minimum.
    # 🟢 Builtin default: "128KiB"
    msize: null
    # Specifies a caching policy. Valid options are: "none", "loose", "fscache" and "mmap".
    # Try choosing "mmap" or "none" if you see a stability issue with the default "fscache".
    # See https://www.kernel.org/doc/Documentation/filesystems/9p.txt
    # 🟢 Builtin default: "fscache" for non-writable mounts, "mmap" for writable mounts
    cache: null

The “9p” mount type requires Lima v0.10.0 or later.

Caveats

  • The “9p” mount type is known to be incompatible with CentOS, Rocky Linux, and AlmaLinux as their kernel do not support CONFIG_NET_9P_VIRTIO.

virtiofs

Warning “virtiofs” mode is experimental

⚡ RequirementLima >= 0.14, macOS >= 13.0Lima >= 0.17.0, Linux, QEMU 4.2.0+, virtiofsd (Rust version)

The “virtiofs” mount type is implemented via the virtio-fs device by using apple Virtualization.Framework shared directory on macOS and virtiofsd on Linux. Linux guest kernel must enable the CONFIG_VIRTIO_FS support for this support.

An example configuration:

limactl start --vm-type=vz --mount-type=virtiofs
vmType: "vz"  # only for macOS; Linux uses 'qemu'
mountType: "virtiofs"
mounts:
- location: "~"

Caveats

  • For macOS, the “virtiofs” mount type is supported only on macOS 13 or above with vmType: vz config. See also vmtype.
  • For Linux, the “virtiofs” mount type requires the Rust version of virtiofsd. Using the version from QEMU (usually packaged as qemu-virtiofsd) will not work, as it requires root access to run.

wsl2

Warning “wsl2” mode is experimental

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

The “wsl2” mount type relies on using WSL2’s native disk sharing, where the root disk is available by default at /mnt/$DISK_LETTER (e.g. /mnt/c/).

An example configuration:

limactl start --vm-type=wsl2 --mount-type=wsl2
vmType: "wsl2"
mountType: "wsl2"

Caveats

  • WSL2 file permissions may not work exactly as expected when accessing files that are natively on the Windows disk (more info)
  • WSL2’s disk sharing system uses a 9P protocol server, making the performance similar to Lima’s 9p mode (more info)

Mount Inotify

Warning “mountInotify” is experimental

⚡ RequirementLima >= 0.21.0

The mountInotify support enables inotify support for all different mountTypes like 9p, virtiofs etc.

When mountInotify is enabled,

  • hostagent will listen and send inotify events from host machine to guest.
  • Guest will modify the file to trigger inotify on guest side

This support will be enabled only for writable mounts because only for writable mount guest will be able to trigger inotify

An example configuration:

limactl start --mount-inotify
mountInotify: true
mounts:
  - location: "~"
    writable: true

Caveats

  • For mountType: 9p, Inotify events are not triggered for nested files from the listening directory.
  • Inotify events are not triggered when files are removed from host

7 - FAQs

Generic

“How does Lima work?”

“What’s my login password?”

Password is disabled and locked by default. You have to use limactl shell bash (or lima bash) to open a shell.

Alternatively, you may also directly ssh into the guest: ssh -p 60022 -i ~/.lima/_config/user -o NoHostAuthenticationForLocalhost=yes 127.0.0.1.

“Does Lima work on ARM Mac?”

Yes, it should work, but not regularly tested on ARM (due to lack of CI).

“Can I run non-Ubuntu guests?”

AlmaLinux, Alpine, Arch Linux, Debian, Fedora, openSUSE, Oracle Linux, and Rocky are also known to work.

See ./examples/.

An image has to satisfy the following requirements:

  • systemd or OpenRC
  • cloud-init
  • The following binaries to be preinstalled:
    • sudo
  • The following binaries to be preinstalled, or installable via the package manager:
    • sshfs
    • newuidmap and newgidmap
  • apt-get, dnf, apk, pacman, or zypper (if you want to contribute support for another package manager, run git grep apt-get to find out where to modify)

“Can I run other container engines such as Docker and Podman? What about Kubernetes?”

Yes, any container engine should work with Lima.

Container runtime examples:

Container image builder examples:

Container orchestrator examples:

The default Ubuntu image also contains LXD. Run lima sudo lxc init to set up LXD.

See also third party containerd projects based on Lima:

  • Rancher Desktop: Kubernetes and container management to the desktop
  • Colima: Docker (and Kubernetes) on macOS with minimal setup

Or third party "containers" projects compatible with Lima:

“Can I run Lima with a remote Linux machine?”

Lima itself does not support connecting to a remote Linux machine, but sshocker, the predecessor or Lima, provides similar features for remote Linux machines.

e.g., run sshocker -v /Users/foo:/home/foo/mnt -p 8080:80 <USER>@<HOST> to expose /Users/foo to the remote machine as /home/foo/mnt, and forward localhost:8080 to the port 80 of the remote machine.

“Advantages compared to Docker for Mac?”

Lima is free software (Apache License 2.0), while Docker for Mac is not.

Configuration

“Is it possible to disable mounts, port forwarding, containerd, etc. ?”

Yes, since Lima v0.18:

limactl start --plain
plain: true

When the “plain” mode is enabled:

  • the YAML properties for mounts, port forwarding, containerd, etc. will be ignored
  • guest agent will not be running
  • dependency packages like sshfs will not be installed into the VM

User-specified provisioning scripts will be still executed.

QEMU

“QEMU crashes with HV_ERROR

If you have installed QEMU v6.0.0 or later on macOS 11 via homebrew, your QEMU binary should have been already automatically signed to enable HVF acceleration.

However, if you see HV_ERROR, you might need to sign the binary manually.

cat >entitlements.xml <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.hypervisor</key>
    <true/>
</dict>
</plist>
EOF

codesign -s - --entitlements entitlements.xml --force /usr/local/bin/qemu-system-x86_64

Note: Only on macOS versions before 10.15.7 you might need to add this entitlement in addition:

    <key>com.apple.vm.hypervisor</key>
    <true/>

“QEMU is slow”

error “killed -9”

  • make sure qemu is codesigned, See “QEMU crashes with HV_ERROR.
  • if you are on macOS 10.15.7 or 11.0 or later make sure the entitlement com.apple.vm.hypervisor is not added. It only works on older macOS versions. You can clear the codesigning with codesign --remove-signature /usr/local/bin/qemu-system-x86_64 and start over.

“QEMU crashes with vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed

This error is known to happen when running an image of RHEL8-compatible distribution such as Rocky Linux 8.x on Intel Mac. A workaround is to set environment variable QEMU_SYSTEM_X86_64="qemu-system-x86_64 -cpu Haswell-v4".

https://bugs.launchpad.net/qemu/+bug/1838390

VZ

“Lima gets stuck at Installing rosetta...

Try softwareupdate --install-rosetta from a terminal.

Networking

“Cannot access the guest IP 192.168.5.15 from the host”

The default guest IP 192.168.5.15 is not accessible from the host and other guests.

To add another IP address that is accessible from the host and other virtual machines, enable socket_vmnet (since Lima v0.12).

See ./docs/network.md.

“Ping shows duplicate packets and massive response times”

Lima uses QEMU’s SLIRP networking which does not support ping out of the box:

$ ping google.com
PING google.com (172.217.165.14): 56 data bytes
64 bytes from 172.217.165.14: seq=0 ttl=42 time=2395159.646 ms
64 bytes from 172.217.165.14: seq=0 ttl=42 time=2396160.798 ms (DUP!)

For more details, see Documentation/Networking.

“IP address is not assigned for vmnet networks”

Try the following commands:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd

Filesystem sharing

“Filesystem is slow”

Try virtiofs. See docs/mount.md

“Filesystem is not writable”

The home directory is mounted as read-only by default. To enable writing, specify writable: true in the YAML:

mounts:
- location: "~"
  writable: true

Run limactl edit <INSTANCE> to open the YAML editor for an existing instance.

External projects

“I am using Rancher Desktop. How to deal with the underlying Lima?”

Rancher Desktop includes the rdctl tool (installed in ~/.rd/bin/rdctl) that provides shell access via rdctl shell.

It is not recommended to directly interact with the Rancher Desktop VM via limactl.

If you need to create an override.yaml file, its location should be:

  • macOS: $HOME/Library/Application Support/rancher-desktop/lima/_config/override.yaml
  • Linux: $HOME/.local/share/rancher-desktop/lima/_config/override.yaml

“Hints for debugging other problems?”

  • Inspect logs:
    • limactl --debug start
    • $HOME/.lima/<INSTANCE>/serial.log
    • /var/log/cloud-init-output.log (inside the guest)
    • /var/log/cloud-init.log (inside the guest)
  • Make sure that you aren’t mixing up tabs and spaces in the YAML.

7.1 - Colima (third-party project)

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

ContainerLimaColima
containerdlimactl startcolima start --runtime=containerd
Dockerlimactl start template://dockercolima start
Podmanlimactl start template://podman-
Kuberneteslimactl start template://k8scolima start --kubernetes

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

ConfigurationLimaColima
CPUslimactl start --cpus=4colima start --cpu=4
Reverse SSHFSlimactl start --mount-type=reverse-sshfscolima start --mount-type=sshfs
Rosettalimactl start --rosettacolima start --vz-rosetta
Access to VM by IPlimactl start --network=lima:sharedcolima start --network-address

8 - Talks

2022

KubeCon + CloudNativeCon Europe 2022

Akihiro Suda and Jan Dubois presented “Running containerd and k3s on macOS” about Lima.

It has been very hard to use Mac for developing containerized apps. A typical way is to use Docker for Mac, but it is not FLOSS. Another option is to install Docker and/or Kubernetes into VirtualBox, often via minikube, but it doesn’t propagate localhost ports, and VirtualBox also doesn’t support the ARM architecture. This session will show how to run containerd and k3s on macOS, using Lima and Rancher Desktop. Lima wraps QEMU in a simple CLI, with neat features for container users, such as filesystem sharing and automatic localhost port forwarding, as well as DNS and proxy propagation for enterprise networks. Rancher Desktop wraps Lima with k3s integration and GUI.

Read the slides or watch the video.

CNCF TAG-Runtime Meeting 2022-10-06

Akihiro Suda presented Lima in the CNCF TAG-Runtime Meeting.

Read the slides.

2023

DevOps Toolkit 2023-02-09

Anders Björklund presented Lima in The DevOps Toolkit Series.

Watch the video.

KubeCon + CloudNativeCon Europe 2023

Akihiro Suda presented Lima in the CNCF project pavilion.

Read the slides.

9 - Releases

See https://github.com/lima-vm/lima/releases for the latest release.

9.1 - Deprecated features

The following features are deprecated:

  • CentOS 7 support
  • Loading non-strict YAMLs (i.e., YAMLs with unknown properties)
  • limactl show-ssh command (Use ssh -F ~/.lima/default/ssh.config lima-default instead)

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

9.2 - Experimental features

The following features are experimental and subject to change:

  • mountType: 9p
  • mountType: virtiofs on Linux
  • vmType: vz and relevant configurations (mountType: virtiofs, rosetta, []networks.vzNAT)
  • vmType: wsl2 and relevant configurations (mountType: wsl2)
  • arch: riscv64
  • video.display: vnc and relevant configuration (video.vnc.display)
  • mode: user-v2 in networks.yml and relevant configuration in lima.yaml
  • audio.device
  • arch: armv7l
  • mountInotify: true

The following commands are experimental and subject to change:

  • limactl snapshot *

10 - Developers' guide

10.1 - Internal data structure

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.

Config directory (${LIMA_HOME}/_config)

The config directory contains global lima settings that apply to all instances.

User identity:

Lima creates a default identity and uses its public key as the authorized key to access all lima instances. In addition lima will also configure all public keys from ~/.ssh/*.pub as well, so the user can use the ssh endpoint without having to specify an identity explicitly.

  • user: private key
  • user.pub: public key

Instance directory (${LIMA_HOME}/<INSTANCE>)

An instance directory contains the following files:

Metadata:

  • lima-version: the Lima version used to create this instance
  • lima.yaml: the YAML
  • protected: empty file, used by limactl protect

cloud-init:

  • cidata.iso: cloud-init ISO9660 image. See cidata.iso.

disk:

  • basedisk: the base image
  • diffdisk: the diff image (QCOW2)

kernel:

  • kernel: the kernel
  • kernel.cmdline: the kernel cmdline
  • initrd: the initrd

QEMU:

  • qemu.pid: QEMU PID
  • qmp.sock: QMP socket
  • qemu-efi-code.fd: QEMU UEFI code (not always present)

VZ:

  • vz.pid: VZ PID
  • vz-identifier: Unique machine identifier file for a VM
  • vz-efi: EFIVariable store file for a VM

Serial:

  • serial.log: default serial log (QEMU only), for debugging
  • serial.sock: default serial socket (QEMU only), for debugging (Usage: socat -,echo=0,icanon=0 unix-connect:serial.sock)
  • serialp.log: PCI serial log (QEMU (ARM) only), for debugging
  • serialp.sock: PCI serial socket (QEMU (ARM) only), for debugging (Usage: socat -,echo=0,icanon=0 unix-connect:serialp.sock)
  • serialv.log: virtio serial log, for debugging
  • serialv.sock: virtio serial socket (QEMU only), for debugging (Usage: socat -,echo=0,icanon=0 unix-connect:serialv.sock)

SSH:

  • ssh.sock: SSH control master socket
  • ssh.config: SSH config file for ssh -F. Not consumed by Lima itself.

VNC:

  • vncdisplay: VNC display host/port
  • vncpassword: VNC display password

Guest agent:

Each drivers use their own mode of communication

  • qemu: uses virtio-port io.lima-vm.guest_agent.0
  • vz: uses vsock port 2222
  • wsl2: uses free random vsock port The fallback is to use port forward over ssh port
  • ga.sock: Forwarded to /run/lima-guestagent.sock in the guest, via SSH

Host agent:

  • ha.pid: hostagent PID
  • ha.sock: hostagent REST API
  • ha.stdout.log: hostagent stdout (JSON lines, see pkg/hostagent/events.Event)
  • ha.stderr.log: hostagent stderr (human-readable messages)

Disk directory (${LIMA_HOME}/_disk/<DISK>)

A disk directory contains the following files:

data disk:

  • datadisk: the qcow2 or raw disk that is attached to an instance

lock:

  • in_use_by: symlink to the instance directory that is using the disk

When using vmType: vz (Virtualization.framework), on boot, any qcow2 (default) formatted disks that are specified in additionalDisks will be converted to RAW since Virtualization.framework only supports mounting RAW disks. This conversion enables additional disks to work with both Virtualization.framework and QEMU, but it has some consequences when it comes to interacting with the disks. Most importantly, a regular macOS default cp command will copy the entire virtual disk size, instead of just the used/allocated portion. The easiest way to copy only the used data is by adding the -c option to cp: cp -c old_path new_path. cp -c uses clonefile(2) to create a copy-on-write clone of the disk, and should return instantly.

ls will also only show the full/virtual size of the disks. To see the allocated space, du -h disk_path or qemu-img info disk_path can be used instead. See #1405 for more details.

Lima cache directory (~/Library/Caches/lima)

Currently hard-coded to ~/Library/Caches/lima on macOS.

Uses $XDG_CACHE_HOME/lima, normally $HOME/.cache/lima, on Linux.

Uses %LocalAppData%\lima, C:\Users\<USERNAME>\AppData\Local\lima, on Windows.

Download cache (~/Library/Caches/lima/download/by-url-sha256/<SHA256_OF_URL>)

The directory contains the following files:

  • url: raw url text, without “\n”
  • data: data
  • <ALGO>.digest: digest of the data, in OCI format. e.g., file name sha256.digest, with content sha256:5ba3d476707d510fe3ca3928e9cda5d0b4ce527d42b343404c92d563f82ba967

Environment variables

  • $LIMA_HOME: The “Lima home directory” (see above).

    • Default : ~/.lima
  • $LIMA_INSTANCE: lima ... is expanded to limactl shell ${LIMA_INSTANCE} ....

    • Default : default
  • $LIMA_SHELL: lima ... is expanded to limactl shell --shell ${LIMA_SHELL} ....

    • No default : will use the user’s shell configured inside the instance
  • $LIMA_WORKDIR: lima ... is expanded to limactl shell --workdir ${LIMA_WORKDIR} ....

    • No default : will attempt to use the current directory from the host
  • $QEMU_SYSTEM_X86_64: path of qemu-system-x86_64

    • Default: qemu-system-x86_64 in $PATH
  • $QEMU_SYSTEM_AARCH64: path of qemu-system-aarch64

    • Default: qemu-system-aarch64 in $PATH
  • $QEMU_SYSTEM_ARM: path of qemu-system-arm

    • Default: qemu-system-arm in $PATH

cidata.iso

cidata.iso contains the following files:

  • user-data: Cloud-init user-data
  • meta-data: Cloud-init meta-data
  • network-config: Cloud-init Networking Config Version 2
  • lima.env: The LIMA_CIDATA_* environment variables (see below) available during boot.sh processing
  • lima-guestagent: Lima guest agent binary
  • nerdctl-full.tgz: nerdctl-full-<VERSION>-<OS>-<ARCH>.tar.gz
  • boot.sh: Boot script
  • boot/*: Boot script modules
  • util/*: Utility command scripts, executed in the boot script modules
  • provision.system/*: Custom provision scripts (system)
  • provision.user/*: Custom provision scripts (user)
  • etc_environment: Environment variables to be added to /etc/environment (also loaded during boot.sh)

Max file name length = 30

Volume label

The volume label is “cidata”, as defined by cloud-init NoCloud.

Environment variables

  • LIMA_CIDATA_NAME: the lima instance name
  • LIMA_CIDATA_MNT: the mount point of the disk. /mnt/lima-cidata.
  • LIMA_CIDATA_USER: the user name string
  • LIMA_CIDATA_UID: the numeric UID
  • LIMA_CIDATA_HOME: the guest home directory
  • LIMA_CIDATA_HOSTHOME_MOUNTPOINT: the mount point of the host home directory, or empty if not mounted
  • LIMA_CIDATA_MOUNTS: the number of the Lima mounts
  • LIMA_CIDATA_MOUNTS_%d_MOUNTPOINT: the N-th mount point of Lima mounts (N=0, 1, …)
  • LIMA_CIDATA_MOUNTTYPE: the type of the Lima mounts (“reverse-sshfs”, “9p”, …)
  • LIMA_CIDATA_CONTAINERD_USER: set to “1” if rootless containerd to be set up
  • LIMA_CIDATA_CONTAINERD_SYSTEM: set to “1” if system-wide containerd to be set up
  • LIMA_CIDATA_SLIRP_GATEWAY: set to the IP address of the host on the SLIRP network. 192.168.5.2.
  • LIMA_CIDATA_SLIRP_DNS: set to the IP address of the DNS on the SLIRP network. 192.168.5.3.
  • LIMA_CIDATA_SLIRP_IP_ADDRESS: set to the IP address of the guest on the SLIRP network. 192.168.5.15.
  • LIMA_CIDATA_UDP_DNS_LOCAL_PORT: set to the udp port number of the hostagent dns server (or 0 when not enabled).
  • LIMA_CIDATA_TCP_DNS_LOCAL_PORT: set to the tcp port number of the hostagent dns server (or 0 when not enabled).

VM lifecycle

(based on Lima 0.8.3)