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
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.
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”:
If you have installed Lima by make install, the nerdctl.lima command is also available as nerdctl.
If you have installed Lima by brew install lima, you may make an alias (or a symlink) by yourself:
alias nerdctl=nerdctl.lima
--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
3.1 - GitHub Actions
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.
The following GitHub Actions workflow illustrates how to run multiple instances of Fedora using Lima.
The instances are connected by the user-v2 network.
name:Fedoraon:workflow_dispatch:pull_request:jobs:fedora:runs-on:ubuntu-24.04steps:- name:Check out codeuses:actions/checkout@v4- name:"Install QEMU"run:| set -eux
sudo apt-get update
sudo apt-get install -y --no-install-recommends ovmf qemu-system-x86 qemu-utils
sudo modprobe kvm
# `sudo usermod -aG kvm $(whoami)` does not take an effect on GHA
sudo chown $(whoami) /dev/kvm- name:"Install Lima"env:GITHUB_TOKEN:${{ github.token }} # required by `gh attestation verify`run:| set -eux
LIMA_VERSION=$(curl -fsSL https://api.github.com/repos/lima-vm/lima/releases/latest | jq -r .tag_name)
FILE="lima-${LIMA_VERSION:1}-Linux-x86_64.tar.gz"
curl -fOSL https://github.com/lima-vm/lima/releases/download/${LIMA_VERSION}/${FILE}
gh attestation verify --owner=lima-vm "${FILE}"
sudo tar Cxzvf /usr/local "${FILE}"
rm -f "${FILE}"- name:"Cache ~/.cache/lima"uses:actions/cache@v4with:path:~/.cache/limakey:lima-${{ env.LIMA_VERSION }}- name:"Start an instance of Fedora"run:| set -eux
limactl start --name=default --cpus=1 --memory=1 --network=lima:user-v2 template://fedora
lima sudo dnf install -y httpd
lima sudo systemctl enable --now httpd- name:"Start another instance of Fedora"run:| set -eux
limactl start --name=another --cpus=1 --memory=1 --network=lima:user-v2 template://fedora
limactl shell another curl http://lima-default.internal
Plain mode
The --plain mode is useful when you want the VM instance to be as close as possible to a physical host:
- name:"Start Fedora"# --plain is set to disable file sharing, port forwarding, built-in containerd, etc.run:limactl start --plain --name=default --cpus=1 --memory=1 --network=lima:user-v2 template://fedora- name:"Initialize Fedora"# plain old rsync and ssh are used for the initialization of the guest,# so that people who are not familiar with Lima can understand the initialization steps.run:| set -eux -o pipefail
# Initialize SSH
mkdir -p -m 0700 ~/.ssh
cat ~/.lima/default/ssh.config >> ~/.ssh/config
# Sync the current directory to /tmp/repo in the guest
rsync -a -e ssh . lima-default:/tmp/repo
# Install packages
ssh lima-default sudo dnf install -y httpd
~centos-stream-8~: Remove in Lima v0.23.0, as CentOS Stream 8 reached EOL.
~deprecated/centos-7~: Remove in Lima v0.23.0, as CentOS 7 reached EOL.
~experimental/vz~: Merged into the default template in Lima v1.0. See also <https://lima-vm.io/docs/config/vmtype/>.
~experimental/armv7l~: Merged into the default template in Lima v1.0. Use limactl create --arch=armv7l template://default.
~experimental/riscv64~: Merged into the default template in Lima v1.0. Use limactl create --arch=riscv64 template://default.
~vmnet~: Removed in Lima v1.0. Use limactl create --network=lima:shared template://default instead. See also <https://lima-vm.io/docs/config/network/>.
~experimental/net-user-v2~: Removed in Lima v1.0. Use limactl create --network=lima:user-v2 template://default instead. See also <https://lima-vm.io/docs/config/network/>.
~experimental/9p~: Removed in Lima v1.0. Use limactl create --vm-type=qemu --mount-type=9p template://default instead. See also <https://lima-vm.io/docs/config/mount/>.
~experimental/virtiofs-linux~: Removed in Lima v1.0. Use limactl create --mount-type=virtiofs-linux template://default instead. See also <https://lima-vm.io/docs/config/mount/>.
Tier
"Tier 1" (marked with ⭐): Good stability. Regularly tested on the CI.
"Tier 2" (marked with ☆): Moderate stability. Regularly tested on the CI.
Other templates 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-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.
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-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.
SEE ALSO
limactl completion - Generate the autocompletion script for the specified shell
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-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.
SEE ALSO
limactl completion - Generate the autocompletion script for the specified shell
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:
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.
SEE ALSO
limactl completion - Generate the autocompletion script for the specified shell
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:
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-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.
SEE ALSO
limactl completion - Generate the autocompletion script for the specified shell
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-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.
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/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)
--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-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.
-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.
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.
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.
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.
--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.
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.
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.
--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-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.
--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.
--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.
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.
SEE ALSO
limactl completion - Generate the autocompletion script for the specified shell
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-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.
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.
-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.
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-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.
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.
--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.
-h, --help help for apply
--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.
-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.
-h, --help help for delete
--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.
-h, --help help for list
-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.
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-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.
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-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.
-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.
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 https://lima-vm.io/docs/config/network/#socket_vmnet for the usage.
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-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.
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.
--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.
--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.
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"]
The default vmType is QEMU in Lima prior to v1.0.
Starting with Lima v1.0, Lima will use VZ by default on macOS (>= 13.5) for new instances,
unless the config is incompatible with VZ. (e.g., legacyBIOS or 9p is enabled)
QEMU
“qemu” option makes use of QEMU to run guest operating system.
VZ
⚡ Requirement
Lima >= 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 and 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
⚡ 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).
# Example to run Fedora using vmType: wsl2vmType:wsl2images:# 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:trueuser: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:
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 time out if the host is slowmounts:[]containerd:system:falseuser:false
Running a VM with a foreign architecture is extremely slow.
Consider using Fast mode or Fast mode 2 whenever possible.
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
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_miscbinfmt: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)
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).
Lima user-v2 network
⚡ 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).
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.
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.
Note that installation using Homebrew is not secure and not recommended by the Lima project.
Homebrew installation will only work with Lima if password-less sudo is enabled for the current user.
The limactl sudoers command requires that socket_vmnet is installed into a secure path only
writable by root and will reject socket_vmnet installed by Homebrew into a user-writable location.
# Install socket_vmnet as root from source to /opt/socket_vmnet# using instructions on https://github.com/lima-vm/socket_vmnet# This assumes that Xcode Command Line Tools are already installedgit clone https://github.com/lima-vm/socket_vmnet
cd socket_vmnet
# Change "v1.2.0" to the actual latest release in https://github.com/lima-vm/socket_vmnet/releasesgit checkout v1.2.0
make
sudo make PREFIX=/opt/socket_vmnet install.bin
# Set up the sudoers file for launching socket_vmnet from Limalimactl sudoers >etc_sudoers.d_lima
less etc_sudoers.d_lima # verify that the file looks correctsudo install -o root etc_sudoers.d_lima /etc/sudoers.d/lima
rm etc_sudoers.d_lima
Note
Lima before v0.12 used vde_vmnet for managing the networks.
vde_vmnet is no longer supported.
Lima v0.14.0 and later used to also accept socket_vmnet installations if they were
owned by the admin user. Starting with v1.0.0 only root ownership is acceptable.
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_vmnetvarRun:/private/var/run/limasudoers:/private/etc/sudoers.d/limagroup:everyonenetworks:shared:mode:sharedgateway:192.168.105.1dhcpEnd:192.168.105.254netmask:255.255.255.0bridged:mode:bridgedinterface:en0# bridged mode doesn't have a gateway; dhcp is managed by outside networkhost:mode:hostgateway:192.168.106.1dhcpEnd:192.168.106.254netmask: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 "root" user.# - 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.
Since the commands to start and stop the socket_vmnet daemon requires root, the user either must
have password-less sudo enabled, or add the required commands to a sudoers file. This can
be done via:
limactl sudoers >etc_sudoers.d_lima
less etc_sudoers.d_lima # verify that the file looks correctsudo install -o root etc_sudoers.d_lima /etc/sudoers.d/lima
rm etc_sudoers.d_lima
The IP address is automatically assigned by macOS’s bootpd.
If the IP address is not assigned, try the following commands:
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.
networks:- socket:"/var/run/socket_vmnet"
6.4 - Port Forwarding
Lima supports automatic port-forwarding of localhost ports from guest to host.
Port forwarding types
Lima supports two port forwarders: SSH and GRPC.
The default port forwarder is SSH.
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.
In future, it is expected that GRPC will take over the default position again.
Using SSH
SSH based port forwarding is the default and current model that is supported in Lima.
To explicitly use SSH forwarding use the below command
LIMA_SSH_PORT_FORWARDER=true limactl start
Caveats
Doesn’t support UDP based port forwarding
Spawns child process on host for running SSH master.
Using GRPC
⚡ Requirement
Lima >= 1.0
In this model, lima uses existing GRPC communication (Host <-> Guest) to tunnel port forwarding requests.
For each port forwarding request, a GRPC tunnel is created and this will be used for transmitting data
To enable this feature, set LIMA_SSH_PORT_FORWARDER to false:
LIMA_SSH_PORT_FORWARDER=false limactl start
Advantages
Supports both TCP and UDP based port forwarding
Performs faster compared to SSH based forwarding
No additional child process for port forwarding
Benchmarks
Use case
GRPC
SSH
TCP
3.80 Gbits/sec
3.38 Gbits/sec
TCP Reverse
4.77 Gbits/sec
3.08 Gbits/sec
The benchmarks detail above are obtained using the following commands
Lima supports several methods for mounting the host filesystem into the guest.
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, 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: truecache: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: falsefollowSymlinks: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 access to unexposed host directories.
9p
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 mountscache: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 on Linux hosts
⚡ Requirement
Lima >= 0.14, macOS >= 13.0
Lima >= 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
⚡ Requirement
Lima >= 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
⚡ Requirement
Lima >= 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
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:
Podman Desktop: Containers and Kubernetes for application developers
“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.
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".
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.
“Filesystem is unmounted after upgrading Lima to v1.0”
Lima v1.0 changed the default mount type for QEMU from reverse-sshfs to 9p.
The 9p mount type is known to be incompatible with the following guest operating systems:
AlmaLinux, CentOS Stream, Oracle Linux, and RockyLinux
Debian GNU/Linux
openSUSE
A new instance of these OS still use reverse-sshfs by default.
However, an existing instance created with a previous version of Lima may potentially need
running the following command (usually not needed):
limactl edit --mount-type=reverse-sshfs <NAME>
Ubuntu users are not affected by this issue.
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:
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.csv.
Reviewer (Limited maintainership): Reviewers may moderate GitHub issues and pull requests (such as adding labels and cleaning up spams),
but they do not have any access to merge pull requests nor push commits.
A Reviewer is considered as a candidate to become a Committer.
Reviewers are not recognized as Maintainers in https://github.com/cncf/foundation/blob/main/project-maintainers.csv.
An active contributor to the project can be invited as a Reviewer,
and can be eventually promoted to a Committer after 2 months at least.
A contributor who have made significant contributions in quality and in quantity
can be also directly invited as a Committer.
A proposal to add or promote a Maintainer must be approved by 2/3 of the Committers who vote within 7 days.
Voting needs 2 approvals at least. The proposer can vote too.
A proposal should happen as a GitHub pull request to the Maintainer list above.
It is highly suggested to reach out to the Committers before submitting a pull request to check the will of the Committers.
Removal and demotion of Maintainers
A Maintainer who do not show significant activities for 6 months, or, who have been violating the Code of Conduct,
may be demoted or removed from the project.
A proposal to demote or remove a Maintainer must be approved by 2/3 of the Committers (excluding the person in question) who vote within 14 days.
Voting needs 2 approvals at least. The proposer can vote too.
A proposal may happen as a GitHub pull request, or, as a private discussion in the case of removal of a harmful Maintainer.
It is highly suggested to reach out to the Committers before submitting a pull request to check the will of the Committers.
Other decisions
Any decision that is not documented here can be made by the Committers.
When a dispute happens across the Committers, it will be resolved through a majority vote within the Committers.
A tie should be considered as a failed vote.
Release process
Eligibility to be a release manager:
MUST be an active Committer
MUST have the GPG fingerprint listed in the maintainer list above
MUST upload the GPG public key to https://github.com/USERNAME.gpg
MUST protect the GPG key with a passphrase or a hardware token.
Release steps:
Open an issue to propose making a new release, e.g. https://github.com/lima-vm/lima/issues/2296.
The proposal should be public, with an exception for vulnerability fixes.
If this is the first time for you to take a role of release management,
you SHOULD make a beta (or alpha, RC) release as an exercise before releasing GA.
Make sure that all the merged PRs are associated with the correct Milestone.
Download SHA256SUMS from the draft release, and confirm that it corresponds to the hashes printed in the build logs on the Release action.
Sign SHA256SUMS with gpg --detach-sign -a SHA256SUMS to produce SHA256SUMS.asc, and upload it to the draft release.
Add release notes in the draft release, to explain the changes and show appreciation to the contributors.
Make sure to fulfill the Release manager: [ADD YOUR NAME HERE] (@[ADD YOUR GITHUB ID HERE]) line with your name.
e.g., Release manager: Akihiro Suda (@AkihiroSuda) .
Click the Set as a pre-release checkbox if this release is a beta (or alpha, RC).
It is highly suggested to add tests for every non-trivial pull requests.
A test can be implemented as a unit test rather than an integration test when it is possible,
to avoid slowing the integration test CI.
Merging pull requests
Committers can merge pull requests.
Reviewers can approve, but cannot merge, pull requests.
A Committer shouldn’t merge their own pull requests without approval by at least one other Maintainer (Committer or Reviewer).
This rule does not apply to trivial pull requests such as fixing typos, CI failures,
and updating image references in templates (e.g., https://github.com/lima-vm/lima/pull/2318).
10.3 - Roadmap
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.
Non-roadmap issues are kept open (as long as they fit the scope of the project) in case a volunteer one day appears and offers to work on them.
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.
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:
cloud-config.yaml: cloud-init configuration, for reference only.
cidata.iso: cloud-init ISO9660 image. See cidata.iso.
Ansible:
ansible-inventory.yaml: the Ansible node inventory. See ansible.
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.
<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
Ansible
The instance directory contains an inventory file, that might be used with Ansible playbooks and commands.
See Building Ansible inventories about dynamic inventories.
