Lima: Linux VMs with Automatic File Sharing and Port Forwarding

The gap Lima fills between macOS and Linux containers

Containers need a Linux kernel. On macOS there is none, so anything that runs a Linux container image has to put a Linux kernel somewhere first. Lima's answer is a virtual machine with the plumbing already wired: the README describes it as launching Linux virtual machines with automatic file sharing and port forwarding, similar to WSL2. The comparison to WSL2 is the clearest statement of intent, because WSL2 is what Windows users get as a first-party feature and macOS users do not.

The README also states the original goal plainly: promoting containerd, including nerdctl, to Mac users. That origin explains the defaults. A fresh Lima instance is a general Linux VM, but the project ships templates for Docker, Podman and Kubernetes, and the README says Lima can be used for non-container applications as well. So the audience is wider than the origin story. Anyone who wants a reproducible Linux box on a machine that does not run Linux is in scope, whether the workload is containers or not.

How Lima wires a guest VM to your host

The architecture visible in the repository is a Go control plane around a hypervisor. The go.mod file lists github.com/Code-Hex/vz/v3, which is the Virtualization.framework binding used on macOS, alongside github.com/digitalocean/go-qemu for QEMU. The Makefile shows how the driver set is decided at build time: on darwin/arm64 with an SDK version of 14 or later, the build adds the krunkit driver, and when the macOS SDK is older than 13 the build tag no_vz disables the vz mode entirely. That is a build-time decision, not a runtime preference, which matters if you are packaging Lima for a fleet of machines with mixed OS versions.

Two dependencies describe the host-guest integration. github.com/lima-vm/sshocker is the SSH and file-sharing layer, and github.com/containers/gvisor-tap-vsock appears in the dependency list for the user-space network stack. Together with the README's promise of automatic file sharing and port forwarding, that is the mechanism: the host reaches the guest over SSH, and traffic is proxied rather than bridged. The practical consequence is that a service listening inside the VM becomes reachable on the host without manual port mapping, and files are visible on both sides without a separate mount step.

Installing Lima and running your first Linux command

The README gives Homebrew as the setup path. The first command installs the package, and the second starts an instance with the default template. The first start downloads an image, so expect a wait rather than an instant prompt.

brew install lima
limactl start

Once an instance is running, the lima wrapper executes commands inside it. The README uses uname to show that you are now on Linux rather than the host.

lima uname -a

For containers, the README's containerd path goes through nerdctl, which is bundled into the guest. The hello-world image is the README's own example.

lima nerdctl run --rm hello-world

If you want Docker instead of containerd, start the Docker template and point DOCKER_HOST at the socket inside the instance directory. The README uses limactl list with a Go template to build that path, so the socket location follows the instance rather than a fixed path you have to remember.

limactl start template:docker
export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')
docker run --rm hello-world

The Kubernetes path follows the same shape, with KUBECONFIG pointed at a kubeconfig copied out of the guest.

limactl start template:k8s
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
kubectl apply -f ...

Those four snippets cover the whole getting-started surface the README documents. Everything beyond them lives at lima-vm.io/docs.

Where Lima is the wrong tool

The README's own framing is the first limitation. Lima is a VM manager, not a container runtime, and the containerd goal is stated as historical motivation rather than a restriction. If your workload is already a container and your host is Linux, adding a VM between the two buys you a second kernel to patch and a second network hop for no isolation gain. The documentation does not present Lima as a production orchestrator either; the README's examples are local development commands, and the adopters it lists are desktop-oriented products.

The build-time driver selection is a second constraint. The Makefile only adds krunkit on darwin/arm64 with a recent SDK, and it compiles out vz mode on older SDKs. A binary built on one machine therefore has a different driver set from one built on another, and the README does not document how to reconcile that at runtime. If you distribute Lima internally, the driver question lands on your build pipeline, not on the user.

The README is also silent on several operational questions. It does not document rollback, snapshot behaviour, or what happens to an instance when the host reboots. The SBOM section is detailed about what the CycloneDX files contain, with separate app and mod variants and an explicit note that mod SBOMs do not evaluate build constraints, but supply-chain metadata is not a substitute for lifecycle documentation. Plan to read the website docs before you depend on any of it.

Lima versus Colima and the other adopters

The most informative comparison comes from Lima's own adopter list. Colima is described there as Docker and Kubernetes on macOS with minimal setup, and Rancher Desktop as Kubernetes and container management to the desktop. Both build on Lima rather than compete with it at the VM layer. The difference is where the opinion lives. Colima wraps Lima with a smaller, container-first command surface, so you get fewer knobs and a faster path to a running Docker socket. Rancher Desktop adds a desktop application and Kubernetes management on top.

Choosing between them is choosing how much of Lima you want to see. If you want to write your own instance YAML, pick a driver, and treat the VM as the unit of configuration, use Lima directly. If you want a Docker socket and nothing else, a wrapper removes decisions you did not want to make. The trade-off is real in both directions: wrappers hide the YAML that lets you tune the guest, and Lima itself hands you a VM to maintain rather than a finished product.

Licence, release cadence and upgrade cost

Lima is Apache-2.0 and a Cloud Native Computing Foundation incubating project, according to the README. Apache-2.0 is permissive, and the repository carries a NOTICE file alongside the LICENSE, which is the standard arrangement for a project with attribution requirements. That is a description of the files present, not legal advice; if you redistribute Lima or a derivative, read the LICENSE and NOTICE yourself.

The release history shows a steady cadence rather than a frozen one. v2.2.0 landed on 2026-07-21, preceded by v2.2.0-rc.0 on 2026-07-16, and v2.3.0-beta.0 appeared on 2026-09-01. The last push to the repository was on 2026-09-20. The README notes that the sbom download has contained CycloneDX SBOMs since v2.3, so the 2.3 line is where that artifact appears. Upgrade cost concentrates in two places: the instance templates, which are YAML you may have edited, and the build tags, which change the available drivers. Neither is documented as an automatic migration, so treat a major version bump as something to read the release notes for.

Editorial conclusion

Adopt Lima if you want a Linux VM on macOS or another non-Linux host and you prefer plain YAML plus a CLI over a bundled desktop product. Do not adopt it if you need a polished GUI, because the README lists GUI options as third-party projects rather than shipped features. Before committing, read the templates directory to see which container engine you actually need, and confirm the guest image and driver your host can run.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. lima-vm/lima on GitHub
3. Project website
4. README
5. Releases