June 10, 2021

1506 words 8 mins read



Linux virtual machines, on macOS (aka "Linux-on-Mac", "macOS subsystem for Linux", "containerd for Mac", unofficially)

repo name AkihiroSuda/lima
repo link https://github.com/AkihiroSuda/lima
language Go
size (curr.) 279 kB
stars (curr.) 2654
created 2021-05-14
license Apache License 2.0

[⬇️ Download] [📖Getting started] [❓FAQs & Troubleshooting]

Lima: Linux virtual machines (on macOS, in most cases)

Lima launches Linux virtual machines with automatic file sharing, port forwarding, and containerd.

Lima can be considered as a some sort of unofficial “macOS subsystem for Linux”, or “containerd for Mac”.

Lima is expected to be used on macOS hosts, but can be used on Linux hosts as well. It may work on NetBSD and Windows hosts as well.

✅ Automatic file sharing

✅ Automatic port forwarding

✅ Built-in support for containerd

✅ Intel on Intel

✅ ARM on Intel

✅ ARM on ARM

✅ Intel on ARM

✅ Various guest Linux distributions: Ubuntu, Debian, Fedora, Alpine, …

Related project: sshocker (ssh with file sharing and port forwarding)

This project is unrelated to The Lima driver project (driver for ARM Mali GPUs).


The goal of Lima is to promote containerd including nerdctl (contaiNERD ctl) to Mac users, but Lima can be used for non-container applications as well.



$ uname -a
Darwin macbook.local 20.4.0 Darwin Kernel Version 20.4.0: Thu Apr 22 21:46:47 PDT 2021; root:xnu-7195.101.2~1/RELEASE_X86_64 x86_64

$ lima uname -a
Linux lima-default 5.11.0-16-generic #17-Ubuntu SMP Wed Apr 14 20:12:43 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

$ LIMA_INSTANCE=arm lima uname -a
Linux lima-arm 5.11.0-16-generic #17-Ubuntu SMP Wed Apr 14 20:10:16 UTC 2021 aarch64 aarch64 aarch64 GNU/Linux

Sharing files across macOS and Linux

$ echo "files under /Users on macOS filesystem are readable from Linux" > some-file

$ lima cat some-file
files under /Users on macOS filesystem are readable from Linux

$ lima sh -c 'echo "/tmp/lima is writable from both macOS and Linux" > /tmp/lima/another-file'

$ cat /tmp/lima/another-file
/tmp/lima is writable from both macOS and Linux"

Running containerd containers (compatible with Docker containers)

$ lima nerdctl run -d --name nginx -p nginx:alpine is accessible from both macOS and Linux.

NOTE Privileged ports (1-1023) cannot be forwarded

For the usage of containerd and nerdctl (contaiNERD ctl), visit https://github.com/containerd/containerd and https://github.com/containerd/nerdctl.

Getting started

Requirements (Intel Mac)

  • QEMU v6.0.0 or later (brew install qemu)

Requirements (ARM Mac)

NOTE Lima is not regularly tested on ARM Mac.


Download the binary archive from https://github.com/AkihiroSuda/lima/releases , and extract it under /usr/local (or somewhere else).

To install from the source, run make && make install.


[macOS]$ limactl start
INFO[0029] READY. Run `lima` to open the shell.

[macOS]$ lima uname

Detailed usage:

  • Run limactl start <INSTANCE> to start the Linux instance. The default instance name is “default”. Lima automatically opens an editor (vi) for reviewing and modifying the configuration. Wait until “READY” to be printed on the host terminal.

  • Run limactl shell <INSTANCE> <COMMAND> to launch <COMMAND> on Linux. For the “default” instance, this command can be shortened as lima <COMMAND>. The lima command also accepts the instance name as the environment variable $LIMA_INSTANCE.

  • Run limactl list [--json] to show the instances.

  • Run limactl stop [--force] <INSTANCE> to stop the instance.

  • Run limactl delete [--force] <INSTANCE> to delete the instance.

  • To enable bash completion, add source <(limactl completion bash) to ~/.bash_profile.

:warning: CAUTION: make sure to back up your data

Lima may have bugs that result in loss of data.

Make sure to back up your data before running Lima.

Especially, the following data might be easily lost:

  • Data in the shared writable directories (/tmp/lima by default), probably after hibernation of the host machine (e.g., after closing and reopening the laptop lid)
  • Data in the VM image, mostly when upgrading the version of lima


See ./pkg/limayaml/default.yaml.

The current default spec:

  • OS: Ubuntu 21.04 (Hirsute Hippo)
  • CPU (x86_64): Haswell v4, 4 cores
  • CPU (aarch64): Cortex A72, 4 cores
  • Memory: 4 GiB
  • Disk: 100 GiB
  • Mounts: ~ (read-only), /tmp/lima (writable)
  • SSH:

How it works

  • Hypervisor: QEMU with HVF accelerator
  • Filesystem sharing: reverse sshfs (planned to be replaced with 9p soon)
  • Port forwarding: ssh -L, automated by watching /proc/net/tcp in the guest

Developer guide

Contributing to Lima

Help wanted


FAQs & Troubleshooting



“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 -o NoHostAuthenticationForLocalhost=yes

“Does Lima work on ARM Mac?”

Yes, it should work, but not regularly tested on ARM.

“Can I run non-Ubuntu guests?”

Debian, Fedora, and Alpine 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, or apk (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 Podman?”

Yes, if you install it.

containerd can be stopped with systemctl --user disable --now containerd.

“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. Their EULA even prohibits disclosure of benchmarking result.

On the other hand, Moby, aka Docker for Linux, is free software, but Moby/Docker lacks several novel features of containerd, such as:


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

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

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.


“Port forwarding does not work”

Privileged ports (1-1023) cannot be forwarded. e.g., you have to use 8080, not 80.

stuck on “Waiting for the essential requirement 1 of X: “ssh”

libslirp v4.6.0 used by QEMU is known to be broken. If you have libslirp v4.6.0 in /usr/local/Cellar/libslirp, you have to upgrade it to v4.6.1 or later (brew upgrade).

error “field SSHPubKeys must be set”

Make sure you have a ssh keypair in ~/.ssh. To create:

ssh-keygen -q -t rsa -N '' -f ~/.ssh/id_rsa <<<n 2>&1 >/dev/null

error “hostkeys_foreach failed: No such file or directory”

Make sure you have a ssh known_hosts file:

touch ~/.ssh/known_hosts

error “failed to execute script ssh: […] Permission denied (publickey)”

If you have a ~/.ssh/config with a username overwrite for all hosts, exclude from it. Example:

Host * !
        User root

“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.
  • If you have passphrases for any private key under ~/.ssh, you will need to have ssh-agent running.
comments powered by Disqus