FAQs

• Generic
  • “How does Lima work?”
  • “What’s my login password?”
  • “Does Lima work on ARM Mac?”
  • “Can I run non-Ubuntu guests?”
  • “Can I run other container engines such as Docker and Podman? What about Kubernetes?”
  • “Can I run Lima with a remote Linux machine?”
  • “Advantages compared to Docker for Mac?”
• Configuration
  • “Is it possible to disable mounts, port forwarding, containerd, etc. ?”
• QEMU
  • “QEMU crashes with HV_ERROR”
  • “QEMU is slow”
  • error “killed -9”
  • “QEMU crashes with vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed”
• VZ
  • “Lima gets stuck at Installing rosetta...”
• Networking
  • “Cannot access the guest IP 192.168.5.15 from the host”
  • “Ping shows duplicate packets and massive response times”
  • “IP address is not assigned for vmnet networks”
• Filesystem sharing
  • “Filesystem is slow”
  • “Filesystem is not writable”
  • “Filesystem is unmounted after upgrading Lima to v1.0”
• External projects
  • “I am using Rancher Desktop. How to deal with the underlying Lima?”
• “Hints for debugging other problems?”

Generic

“How does Lima work?”

• Hypervisor: QEMU (default on Linux), or Virtualization.framework (default on macOS)
• Filesystem sharing: Reverse SSHFS, virtio-9p-pci aka virtfs (default for QEMU), or virtiofs (default for Virtualization.framework)
• Port forwarding: ssh -L, automated by watching /proc/net/tcp and iptables events in the guest

“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

“Can I run non-Ubuntu guests?”

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

See ./templates/.

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

• ./templates/docker.yaml: Docker
• ./templates/podman.yaml: Podman
• ./templates/apptainer.yaml: Apptainer

Container image builder templates:

• ./templates/buildkit.yaml: BuildKit

Container orchestrator templates:

• ./templates/k3s.yaml: Kubernetes (k3s)
• ./templates/k8s.yaml: Kubernetes (kubeadm)

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:

• CLI
• YAML

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”

• Make sure that HVF is enabled with com.apple.security.hypervisor entitlement. See "QEMU crashes with HV_ERROR".
• Emulating non-native machines (ARM-on-Intel, Intel-on-ARM) is slow by design. See docs/multi-arch.md for a workaround.

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.

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

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