“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

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


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

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:


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



“Lima gets stuck at Installing rosetta...

Try softwareupdate --install-rosetta from a terminal.


“Cannot access the guest IP from the host”

The default guest IP 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) or vde_vmnet (Deprecated).

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 ( 56 data bytes
64 bytes from seq=0 ttl=42 time=2395159.646 ms
64 bytes from 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:

- 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.
Last modified October 25, 2023: docs: fix typos (15470ab)