Translations: 日本語(Japanese)
[📖Getting started] [❓FAQs & Troubleshooting]
Lima launches Linux virtual machines with automatic file sharing and port forwarding (similar to WSL2), and containerd.
Lima can be considered as a some sort of unofficial "containerd for Mac".
Lima is expected to be used on macOS hosts, but can be used on Linux hosts as well.
✅ Automatic file sharing
✅ Automatic port forwarding
✅ Built-in support for containerd (Other container engines can be used too)
✅ Intel on Intel
✅ ARM on ARM
✅ Various guest Linux distributions: AlmaLinux, Alpine, Arch Linux, Debian, Fedora, openSUSE, Oracle Linux, Rocky, Ubuntu (default), ...
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 talks page contains links to slides and video from conference presentations about Lima.
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.
Container environments:
- Rancher Desktop: Kubernetes and container management to the desktop
- Colima: Docker (and Kubernetes) on macOS with minimal setup
- Finch: Finch is a command line client for local container development
GUI:
- Lima xbar plugin: xbar plugin to start/stop VMs from the menu bar and see their running status.
- lima-gui: Qt GUI for Lima
- GitHub Discussions
#lima
channel in the CNCF Slack- New account: https://slack.cncf.io/
- Login: https://cloud-native.slack.com/
Lima follows the CNCF Code of Conduct.
$ 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
See ./docs/multi-arch.md
for Intel-on-ARM and ARM-on-Intel .
$ 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
$ lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
You don't need to run "lima nerdctl" everytime, instead you can use special shortcut called "nerdctl.lima" to do the same thing. By default, it'll be installed along with the lima, so, you don't need to do anything extra. There will be a symlink called nerdctl pointing to nerdctl.lima. This is only created when there is no nerdctl entry in the directory already though. It worths to mention that this is created only via make install. Not included in Homebrew/MacPorts/nix packages.
http://127.0.0.1:8080 is accessible from both macOS and Linux.
For the usage of containerd and nerdctl (contaiNERD ctl), visit https://github.com/containerd/containerd and https://github.com/containerd/nerdctl.
Homebrew package is available.
brew install lima
Manual installation steps
Install QEMU 7.0 or later.
- Download the binary archive of Lima from https://github.com/lima-vm/lima/releases ,
and extract it under
/usr/local
(or somewhere else). For instance:
brew install jq
VERSION=$(curl -fsSL https://api.github.com/repos/lima-vm/lima/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/lima-vm/lima/releases/download/${VERSION}/lima-${VERSION:1}-$(uname -s)-$(uname -m).tar.gz" | tar Cxzvm /usr/local
- To install Lima from the source, run
make && make install
.
NOTE Lima is not regularly tested on ARM Mac (due to lack of CI).
[macOS]$ limactl start
...
INFO[0029] READY. Run `lima` to open the shell.
[macOS]$ lima uname
Linux
limactl start [--name=NAME] [--tty=false] <template://TEMPLATE>
: start the Linux instance
$ limactl start
? Creating an instance "default" [Use arrows to move, type to filter]
> Proceed with the current configuration
Open an editor to review or modify the current configuration
Choose another example (docker, podman, archlinux, fedora, ...)
Exit
...
INFO[0029] READY. Run `lima` to open the shell.
Choose Proceed with the current configuration
, and wait until "READY" to be printed on the host terminal.
For automation, --tty=false
flag can be used for disabling the interactive user interface.
To create an instance "default" from a template "docker":
$ limactl start --name=default template://docker
NOTE:
limactl start template://TEMPLATE
requires Lima v0.9.0 or later. Older releases requirelimactl start /usr/local/share/doc/lima/examples/TEMPLATE.yaml
instead.
To see the template list:
$ limactl start --list-templates
To create an instance "default" from a local file:
$ limactl start --name=default /usr/local/share/lima/examples/fedora.yaml
To create an instance "default" from a remote URL (use carefully, with a trustable source):
$ limactl start --name=default https://raw.githubusercontent.com/lima-vm/lima/master/examples/alpine.yaml
limactl shell <INSTANCE> <COMMAND>
: 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
.
limactl copy <SOURCE> ... <TARGET>
: copy files between instances, or between instances and the host
Use <INSTANCE>:<FILENAME>
to specify a source or target inside an instance.
limactl list [--json]
: show the instances
limactl stop [--force] <INSTANCE>
: stop the instance
limactl delete [--force] <INSTANCE>
: delete the instance
limactl factory-reset <INSTANCE>
: factory reset the instance
limactl edit <INSTANCE>
: edit the instance
limactl disk create <DISK> --size <SIZE>
: create a new external disk to attach to an instance
limactl disk delete <DISK>
: delete an existing disk
limactl disk list
: list all existing disks
-
To enable bash completion, add
source <(limactl completion bash)
to~/.bash_profile
. -
To enable zsh completion, see
limactl completion zsh --help
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
The current default spec:
- OS: Ubuntu 22.10 (Kinetic Kudu)
- CPU: 4 cores
- Memory: 4 GiB
- Disk: 100 GiB
- Mounts:
~
(read-only),/tmp/lima
(writable) - SSH: 127.0.0.1:60022
- 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/proc/net/tcp
andiptables
events in the guest
-
Please certify your Developer Certificate of Origin (DCO), by signing off your commit with
git commit -s
and with your real name. -
Please squash commits.
🙏
- Documents
- CLI user experience
- Performance optimization
- Windows hosts
- vsock to replace SSH (work has to be done on QEMU repo)
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
.
Yes, it should work, but not regularly tested on ARM (due to lack of CI).
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
andnewgidmap
apt-get
,dnf
,apk
,pacman
, orzypper
(if you want to contribute support for another package manager, rungit grep apt-get
to find out where to modify)
Yes, any container engine should work with Lima.
Container runtime examples:
./examples/docker.yaml
: Docker./examples/podman.yaml
: Podman./examples/apptainer.yaml
: Apptainer
Container image builder examples:
./examples/buildkit.yaml
: BuildKit
Container orchestrator examples:
./examples/k3s.yaml
: Kubernetes (k3s)./examples/k8s.yaml
: Kubernetes (kubeadm)./examples/nomad.yaml
: Nomad
The default Ubuntu image also contains LXD. Runlima 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
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.
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:
- On-demand image pulling (aka lazy-pulling, eStargz)
- Running an encrypted container
- Importing and exporting local OCI archives
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/>
- Make sure that HVF is enabled with
com.apple.security.hypervisor
entitlement. See "QEMU crashes withHV_ERROR
". - Emulating non-native machines (ARM-on-Intel, Intel-on-ARM) is slow by design. See
docs/multi-arch.md
for a workaround.
- 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 withcodesign --remove-signature /usr/local/bin/qemu-system-x86_64
and start over.
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
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)
or vde_vmnet
(Deprecated).
See ./docs/network.md
.
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.
Try virtiofs. See docs/mount.md
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.
On macOS hosts, Rancher Desktop (as of v1.0) launches Lima with the following configuration:
$LIMA_HOME
directory:$HOME/Library/Application Support/rancher-desktop/lima
limactl
binary:/Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/lima/bin/limactl
- Lima instance name:
0
To open a shell, run the following command:
LIMA_HOME="$HOME/Library/Application Support/rancher-desktop/lima" "/Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/lima/bin/limactl" shell 0
On Linux hosts, try the following command:
LIMA_HOME="$HOME/.local/share/rancher-desktop/lima" /opt/rancher-desktop/resources/resources/linux/lima/bin/limactl shell 0
If you have installed Rancher Desktop as an AppImage:
LIMA_HOME="$HOME/.local/share/rancher-desktop/lima" "$(ls -d /tmp/.mount_ranche*/opt/rancher-desktop/resources/resources/linux/lima/bin)/limactl" shell 0
- 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.
We are a Cloud Native Computing Foundation sandbox project.
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.