- Filesystem sharing
- External projects
- “Hints for debugging other problems?”
“How does Lima work?”
- Hypervisor: QEMU with HVF accelerator (default), or Virtualization.framework
- Filesystem sharing: Reverse SSHFS (default), or virtio-9p-pci aka virtfs, or virtiofs
- Port forwarding:
ssh -L, automated by watching
iptablesevents 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, 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.
An image has to satisfy the following requirements:
- systemd or OpenRC
- The following binaries to be preinstalled:
- The following binaries to be preinstalled, or installable via the package manager:
zypper(if you want to contribute support for another package manager, run
git grep apt-getto 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:
- 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.
sshocker -v /Users/foo:/home/foo/mnt -p 8080:80 <USER>@<HOST> to expose
/Users/foo to the remote machine as
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.
“QEMU crashes with
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:
“QEMU is slow”
- Make sure that HVF is enabled with
com.apple.security.hypervisorentitlement. See "QEMU crashes with
- Emulating non-native machines (ARM-on-Intel, Intel-on-ARM) is slow by design. See
docs/multi-arch.mdfor a workaround.
error “killed -9”
- make sure qemu is codesigned, See “QEMU crashes with
- if you are on macOS 10.15.7 or 11.0 or later make sure the entitlement
com.apple.vm.hypervisoris not added. It only works on older macOS versions. You can clear the codesigning with
codesign --remove-signature /usr/local/bin/qemu-system-x86_64and 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
softwareupdate --install-rosetta from a terminal.
“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.
“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 (184.108.40.206): 56 data bytes 64 bytes from 220.127.116.11: seq=0 ttl=42 time=2395159.646 ms 64 bytes from 18.104.22.168: seq=0 ttl=42 time=2396160.798 ms (DUP!)
For more details, see Documentation/Networking.
“IP address is not assigined 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 is slow”
Try virtiofs. See
“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
limactl edit <INSTANCE> to open the YAML editor for an existing instance.
“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
It is not recommended to directly interact with the Rancher Desktop VM via
If you need to create an
override.yaml file, its location should be:
“Hints for debugging other problems?”
- Inspect logs:
limactl --debug start
/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.