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

Return to the regular view of this page.

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.

“Filesystem is unmounted after upgrading Lima to v1.0 (pre-release)”

Lima v1.0 (pre-release) 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.

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-
Kubernetes (k3s)limactl start template://k3scolima start --kubernetes
Kubernetes (kubeadm)limactl start template://k8s-

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