Search tools, AI agents, MCP servers
Submit a tool

Search iThub

Search tools, categories and collections. Type at least two characters.

Explore all tools
↑ ↓ to explore resultsEnter to open · Esc to close

Containers & Kubernetes

How to use Lima: run Linux VMs and containers on macOS

How to use Lima 2.3 on macOS and Linux: install, templates, shell, file sharing, ports, Rosetta, nerdctl and Docker, resources, fixes, and Lima vs Colima.

iThub Insights cover: Tutorial, How to Use Lima, with the Lima logo tile
On this page
  1. Before you start
  2. Step 1: install Lima
  3. Step 2: create and start your first VM
  4. Step 3: open a shell and run commands
  5. Step 4: pick a template for your distro or engine
  6. Step 5: share files between macOS and the VM
  7. Step 6: choose a VM type and run x86_64 software on Apple silicon
  8. Step 7: reach guest services through port forwarding
  9. Step 8: run containers with nerdctl
  10. Step 9: use the Docker CLI with the docker template
  11. Step 10: set CPUs, memory and disk in YAML
  12. Step 11: stop, restart and delete instances
  13. Common problems and fixes
  14. Lima vs Colima, OrbStack, Docker Desktop and other options
  15. Sources

To use Lima, install it with brew install lima, run limactl start to create and boot an Ubuntu virtual machine, then type lima to open a shell inside it. The default VM comes with containerd and nerdctl, sees your home directory read-only and forwards ports that guest services open to localhost on your Mac. For Docker, Podman or Kubernetes, start from a template instead, for example limactl start template:docker.

Lima, short for Linux Machines, is an open source command-line tool released under the Apache 2.0 license. It started in May 2021 to bring containerd and nerdctl to Mac users, joined the Cloud Native Computing Foundation in September 2022 and moved up to the Incubating level in October 2025. macOS and Linux are its supported hosts, and other tools are built on it: Colima and Rancher Desktop both run their VMs through Lima.

This tutorial covers Lima v2.3.0, released on November 6, 2026. Commands, defaults and template names follow the official documentation, the v2.3.0 template files and the limactl help text as of November 21, 2026.

Before you start

  • A Mac or a Linux machine. On macOS 13.5 or later, Lima uses Apple's Virtualization.framework, so no separate hypervisor is needed. Apple silicon and Intel Macs both work.
  • QEMU on Linux. QEMU is the default VM type on Linux hosts, and the docs recommend version 6.2.0 or later. On a Mac you only need QEMU if you choose the qemu VM type, with 8.2.1 or later recommended.
  • Homebrew For the simplest install, or write access to /usr/local for the release tarball.

Step 1: install Lima

With Homebrew, on macOS or Linux:

brew install lima
limactl --version

Without Homebrew, the installation page downloads the latest release archive from GitHub and unpacks it into /usr/local. Prefix tar with sudo if that folder is not writable for your user:

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

Since Lima 1.1, the guest agents for foreign CPU architectures ship separately. You need them only to boot a VM of another architecture, such as a full x86_64 VM on Apple silicon: run brew install lima-additional-guestagents, or extract the lima-additional-guestagents archive from the same release. MacPorts (sudo port install lima) and Nix (nix-env -i lima) packages are also available.

Step 2: create and start your first VM

Run limactl start without arguments to create an instance named default from the default template:

limactl start

Lima offers to proceed with the current configuration, open it in an editor, choose another template or exit. Pick the first option and wait for a log line ending in READY. The first start downloads the Ubuntu cloud image and Lima's containerd bundle, so it is the slowest. In scripts, add --tty=false to skip the prompt.

Without any changes, the new instance gets these settings:

Setting Default in Lima 2.3
VM type vz on macOS 13.5 and later, qemu elsewhere
Guest OS Ubuntu 26.10
CPUs 4, or the number of host cores if lower
Memory 4 GiB, or half the host memory if lower
Disk 100 GiB
File sharing Host home directory, read-only
Containers Rootless containerd with nerdctl

limactl list shows each instance with its status, VM type, architecture, resources and directory. Instances live in folders under ~/.lima, or under $LIMA_HOME if you set it. Each folder holds the instance's disk, logs, YAML configuration and a generated SSH config.

Step 3: open a shell and run commands

lima is a short form of limactl shell default:

lima                      # interactive shell in "default"
lima uname -a             # run one command and return
limactl shell dev         # shell in an instance named "dev"
LIMA_INSTANCE=dev lima    # same thing, via the environment

Three details save confusion later:

  • If your current host directory is mounted in the guest, the shell opens in the same path inside the VM. --workdir overrides this.
  • Your Linux home directory is separate from the mounted host home. Since Lima 2.1 it is /home/<user>.guest, so dotfiles and caches created in the VM stay out of your Mac's home folder.
  • There is no login password. It is disabled and locked on Linux guests, so use limactl shell or SSH rather than the VM console.

For SSH clients and editors, add Include ~/.lima/*/ssh.config to ~/.ssh/config. After that, ssh lima-default works, and so does the Remote SSH mode of Visual Studio Code. To move a single file without a shared folder, use limactl copy:

limactl copy ./report.csv default:/tmp/
limactl copy default:/etc/os-release .

Step 4: pick a template for your distro or engine

A template is a YAML file that sets the image, mounts, provisioning scripts and port rules for an instance. limactl create --list-templates prints the ones your version ships. Lima v2.3.0 includes these groups:

Group Templates
Default default (Ubuntu with containerd and nerdctl)
Linux distributions ubuntu, ubuntu-lts, debian, fedora, archlinux, alpine, almalinux, rocky, oraclelinux, centos-stream, opensuse-leap, plus pinned versions such as ubuntu-24.04 or debian-12
Container engines docker, docker-rootful, podman, podman-rootful, apptainer, apptainer-rootful
Image builder buildkit
Orchestration k3s, k8s (kubeadm), k0s, faasd, plus experimental/rke2 and experimental/u7s (Usernetes)
Package managers linuxbrew (Homebrew on Ubuntu), homebrew-macos
Non-Linux, experimental macos (15, 26 and 27), freebsd, windows-2025

The project marks default, debian, fedora, opensuse-leap, docker and k8s as Tier 1: good stability and regular testing in CI. Since Lima 2.0 you reference templates as template:NAME; older guides use template://NAME.

limactl start template:fedora              # instance named "fedora"
limactl start --name=deb template:debian   # pick your own name
limactl start ./dev.yaml                   # a template file of your own

Lima also accepts a template URL, which its help text says to use only with a source you trust: provisioning scripts in a template run inside the VM, many of them as root.

Step 5: share files between macOS and the VM

By default, your home directory appears in the guest at the same path, such as /Users/you, and it is read-only. Since Lima 2.0, /tmp/lima is no longer shared. The mechanism depends on the VM type:

VM type Default mount type Notes
vz (macOS default) virtiofs The fix the FAQ suggests when file access is slow
qemu on macOS or Linux 9p Templates whose guest kernels lack working 9p, such as AlmaLinux, CentOS Stream, Oracle Linux, Rocky Linux and Debian, use reverse-sshfs
qemu on Windows reverse-sshfs QEMU for Windows has no 9p support

With reverse-sshfs, the host serves files over SFTP through an SSH connection it opens into the guest, so no TCP port opens on the host, but the mount drops if that connection does.

To make files writable, choose the narrowest option that works:

  1. Everything writable. Start a new instance with limactl start --mount-writable.
  2. One writable project folder. limactl start --mount-only ~/code:w replaces the home mount with ~/code only. Drop :w to keep it read-only.
  3. Only the current folder. limactl start --mount-only .:w is the pattern the Lima docs recommend for AI coding agents, which then cannot read the rest of your home directory.
  4. An existing instance. Stop it, run limactl edit NAME --mount-writable, or edit the YAML directly, then start it again.
mounts:
- location: "~/code"
  writable: true

Overlapping mounts, such as ~ together with ~/code, are not supported. Pick one or the other.

Step 6: choose a VM type and run x86_64 software on Apple silicon

The VM type is fixed when you create an instance. To switch, create a new one.

  • vz Uses Apple's Virtualization.framework and has been the macOS default since Lima 1.0. It supports virtiofs, Rosetta and the fast vzNAT network, but it cannot boot a guest of a different CPU architecture.
  • qemu Is the Linux default. On a Mac you need it for a full foreign-architecture VM, for example limactl start --vm-type=qemu --arch=x86_64. The docs call that mode extremely slow, and it needs the additional guest agents from Step 1.
  • krunkit Is an experimental driver for Apple silicon Macs on macOS 14 or later, built on libkrun, whose main draw is Vulkan GPU access inside the guest.
  • wsl2 And hcs apply only to Windows hosts.

For x86_64 containers or binaries on Apple silicon, Rosetta is the fast path. --rosetta enables Rosetta in the guest and registers it with binfmt_misc, so amd64 binaries run transparently:

limactl start --vm-type=vz --rosetta
lima nerdctl run --rm --platform=linux/amd64 alpine uname -m   # prints x86_64

The flag only applies when an instance is created. For an existing one, stop it and run limactl edit NAME --rosetta.

The equivalent YAML, since the top-level rosetta key was deprecated in Lima 2.0:

vmType: "vz"
vmOpts:
  vz:
    rosetta:
      enabled: true
      binfmt: true

If the start stops at Installing rosetta..., run softwareupdate --install-rosetta on the Mac and try again.

Step 7: reach guest services through port forwarding

Lima watches the guest for listening sockets and forwards them to the host automatically. A service listening on port 3000 on 127.0.0.1 or 0.0.0.0 inside the VM shows up at 127.0.0.1:3000 on your Mac without any configuration. The default gRPC forwarder handles TCP and UDP. From inside the VM, the hostname host.lima.internal points back to the host.

Add static rules when you need a different host port or want the service visible to other machines:

portForwards:
- guestPort: 80
  hostPort: 8080        # guest port 80 appears as localhost:8080
- guestPort: 5432
  hostIP: "0.0.0.0"     # also reachable from your local network

For a quick rule at creation time, limactl start --port-forward 8080:80 does the same as the first entry. The guest's default IP address, 192.168.5.15, is not reachable from the host. If you need to reach the VM by IP, start it with --network vzNAT (vz only) or --network lima:shared. The port forwarding page has throughput benchmarks for each option.

Step 8: run containers with nerdctl

The default instance runs containerd in rootless mode, with nerdctl as its Docker-compatible command line. Call it through lima:

lima nerdctl run -d --name web -p 127.0.0.1:8080:80 nginx:alpine
curl http://127.0.0.1:8080       # on the Mac
lima nerdctl ps
lima nerdctl compose up -d       # in a folder with a compose.yaml

Lima also installs a nerdctl.lima wrapper on the host, which you can alias to nerdctl. For rootful containerd, create the instance with --containerd=system and use lima sudo nerdctl. If you only want a Linux VM, --containerd=none skips the container stack, and --plain goes further by switching off mounts, automatic port forwarding and the guest agent.

Step 9: use the Docker CLI with the docker template

When your tools expect a docker command and a Docker socket, run Docker Engine inside Lima and point the Docker CLI on your Mac at it:

  1. Install the Docker client only. Homebrew's docker formula is the CLI, without Docker Desktop.
  2. Create a VM from the docker template. It installs Docker Engine in rootless mode and forwards its socket into the instance folder on the host.
  3. Create a Docker context for that socket and switch to it, as the template's start message suggests.
  4. Run a test container.
brew install docker
limactl start template:docker
docker context create lima-docker --docker "host=unix://$(limactl list docker --format '{{.Dir}}')/sock/docker.sock"
docker context use lima-docker
docker run --rm hello-world

A context persists across terminals. For a single shell, the docs export DOCKER_HOST instead:

export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')

Inside containers, host.docker.internal resolves to the host. Use template:docker-rootful if an image or tool requires rootful Docker. Docker Compose is a CLI plugin: brew install docker-compose, then add its plugin folder to ~/.docker/config.json as the formula's install notes explain.

Podman and Kubernetes follow the same pattern:

limactl start template:podman
podman system connection add lima-podman "unix://$(limactl list podman --format '{{.Dir}}')/sock/podman.sock"
podman system connection default lima-podman

limactl start template:k3s
export KUBECONFIG="$(limactl list k3s --format '{{.Dir}}')/copied-from-guest/kubeconfig.yaml"
kubectl get nodes

The k8s template sets up a kubeadm cluster instead of k3s, and both templates can form multi-node clusters over the lima:user-v2 network. If you are still deciding whether a project needs Kubernetes at all, read Docker vs Kubernetes: which do you need?.

Step 10: set CPUs, memory and disk in YAML

Set resources when you create an instance, with flags or in a template file. Memory and disk flags take sizes in GiB:

limactl create --name=dev --cpus=6 --memory=12 --disk=80 template:ubuntu-lts
limactl start dev

A template file keeps the whole machine definition in one file you can review and commit:

# dev.yaml, started with: limactl start ./dev.yaml
minimumLimaVersion: 2.0.0
base:
- template:_images/ubuntu-lts
cpus: 6
memory: "12GiB"
disk: "80GiB"
mounts:
- location: "~/code"
  writable: true
portForwards:
- guestPort: 80
  hostPort: 8080

To resize an existing instance, stop it first, because limactl edit refuses to change a running one:

limactl stop dev
limactl edit dev --cpus=8 --memory=16 --disk=120
limactl start dev

Without flags, limactl edit dev opens the YAML in your editor. The disk grows on the next start, but it cannot shrink, and the VM type and architecture stay fixed.

Step 11: stop, restart and delete instances

limactl stop dev              # shut down; Lima 2.3 accepts several names
limactl restart dev
limactl delete dev            # removes the VM and its disk (stop it first, or add --force)
limactl factory-reset dev     # wipes the disk but keeps the YAML configuration
limactl prune                 # clears cached images and downloads

limactl protect dev blocks accidental deletion and factory resets until you run limactl unprotect dev. To boot an instance when you log in, use limactl autostart enable dev, available since Lima 2.2. Lima 2.3 also adds limactl menu, an experimental text interface for the same tasks, which opens when you run limactl without arguments in an interactive terminal.

Common problems and fixes

  • Permission denied in a shared folder. The host home is read-only by default. Make a narrower mount writable as shown in Step 5, or stop the instance and run limactl edit NAME --mount-writable.
  • Cannot connect to the Docker daemon. The CLI is pointed at another context or the instance is stopped. Check docker context ls and limactl list, then run docker context use lima-docker.
  • A port does not show up on the Mac. Only sockets bound to localhost or to all interfaces in the guest are forwarded. Bind the service to 0.0.0.0 or 127.0.0.1, publish container ports with -p, or add a static portForwards rule.
  • Slow file access. Use the vz VM type with virtiofs. Since an instance cannot change VM type, create a new one and move your work to it.
  • Mount errors on QEMU guests. Some guest kernels lack 9p support, and 9p is broken in Linux 6.9, 6.10 and 6.11. Switch the instance with limactl edit NAME --mount-type=reverse-sshfs.
  • QEMU crashes with HV_ERROR. The QEMU binary lacks the hypervisor entitlement. Homebrew builds should already be signed; the Lima FAQ shows the codesign command for other builds.
  • Anything else. Run limactl --debug start NAME, or add --progress to follow cloud-init as it provisions. Then read ~/.lima/NAME/serial.log on the host, which contains no kernel boot messages on vz, and /var/log/cloud-init-output.log inside the guest.

Lima vs Colima, OrbStack, Docker Desktop and other options

Lima is a VM manager first and a container setup second. The tools below overlap with it; licenses come from each project's repository or terms, and prices from official pages on November 21, 2026.

Tool License Default engine GUI Cost
Lima Apache 2.0 containerd with nerdctl; Docker, Podman and Kubernetes through templates No, command line plus the experimental limactl menu Free
Colima MIT Docker; containerd, Incus and k3s as options No, command line Free
OrbStack Proprietary Unmodified Docker Engine, plus Kubernetes and Linux machines Yes, macOS 14 or later only Free for personal use; $8 per user per month for commercial use
Docker Desktop Proprietary (Docker Subscription Service Agreement) Docker Engine Yes Free for personal use, education, non-commercial open source and businesses under 250 employees and $10 million revenue; paid plan otherwise
Podman Desktop Apache 2.0 Podman; can also connect to Docker, Lima, Kind and Minikube Yes Free
Rancher Desktop Apache 2.0 containerd or Moby (dockerd), with k3s; runs in a Lima VM on macOS and Linux Yes Free
Kiri Apache 2.0 Its own Rust runtime serving the Docker Engine API Yes Free, in beta

Lima vs Colima. Colima wraps Lima and changes the defaults: colima start gives you Docker, while limactl start gives you containerd. The Lima FAQ maps the flags between the two, for example --cpus against --cpu, reverse-sshfs against sshfs and --rosetta against --vz-rosetta. According to the same FAQ, Colima has no preset for Podman or kubeadm, which Lima covers with its podman and k8s templates. Choose Colima if you want a working docker command with one line and no YAML. Choose Lima if you want several distros side by side, Podman or kubeadm, or a machine definition you can commit.

Desktop apps. OrbStack and Docker Desktop add a container dashboard, a menu bar and vendor support. OrbStack charges for any commercial use, and Docker Desktop charges companies above its small-business limit. Podman Desktop is a free graphical front end for Podman that can also manage Lima instances. Rancher Desktop puts a graphical interface and a k3s cluster on top of Lima, and the Lima FAQ advises using its rdctl shell command rather than limactl against that VM. Kiri is a new Rust runtime for macOS, Linux and Windows that speaks the Docker Engine API; its first public release came out in August 2026.

Pick Lima when the Linux machine itself is what you need, with containers as an option. For a point-and-click container workflow, a desktop app fits better. The containers and Kubernetes category lists more tools.

Sources

Frequently asked questions

Is Lima free for commercial use?

Yes. Lima is released under the Apache License 2.0, so companies can use it at work without a subscription or license fee. The Lima FAQ points to this as its main advantage over Docker Desktop for Mac.

Does Lima run on Apple silicon Macs?

Yes, and on Intel Macs too. On recent macOS it creates VMs with Apple's Virtualization.framework, and on Apple silicon you can turn on Rosetta to run amd64 container images and Linux binaries at close to native speed.

What is the difference between Lima and Colima?

Colima is a separate open source project that uses Lima underneath. It starts Docker by default and keeps the CLI to a few flags, while Lima starts containerd with nerdctl and offers many more templates, including Podman, kubeadm and a long list of Linux distributions.

Can I use Docker Compose with Lima?

Yes. Either run nerdctl compose in the default instance, or start the docker template, point the Docker CLI at its socket and install the Compose plugin on the host. Both read the same compose.yaml format.

Where does Lima store its virtual machines?

In ~/.lima, one folder per instance, unless the LIMA_HOME variable points elsewhere. Deleting an instance removes its folder and disk, and limactl prune removes cached images and other downloads that no instance or template still uses.

Can Lima run Kubernetes on a Mac?

Yes. The k3s, k8s (kubeadm) and k0s templates each create a single-node cluster and copy its kubeconfig to the host, so kubectl on the Mac can reach it. k8s and k3s can also join several VMs into one cluster.

Does Lima have a graphical interface?

Not a desktop app. Lima is driven from the terminal, and version 2.3 adds an experimental text menu. If you want windows and buttons, Rancher Desktop is built on Lima, and Podman Desktop can manage Lima instances.

Tools in this article

  1. ColimaConfigure local container runtimes on macOS and Linux with a CLIContainers & Kubernetes3 views
  2. Rancher DesktopManage local containers and Kubernetes with a choice of container engineContainers & Kubernetes5 views
  3. HomebrewOpen-source package manager for macOS, Linux and WSL that installs CLI tools as formulae and apps as casksSystem Utilities & Windows Tweaks6 views
  4. DockerDocker Engine, Desktop, Hub, Scout and Build Cloud for building, sharing and running containerized appsContainers & Kubernetes42 views
  5. PodmanManage OCI containers and pods with a daemonless, rootless-capable engineContainers & Kubernetes8 views
  6. KubernetesOpen-source container orchestration for deploying and scaling workloadsContainers & Kubernetes20 views
  7. OrbStackRun Docker containers, Kubernetes and Linux machines locally on macOSContainers & Kubernetes7 views
  8. KiriRust container runtime for macOS, Windows and Linux with the Docker Engine API, k3s and Kiri Share tunnelsContainers & Kubernetes30 views
Share this article

Facts link to their official sources. Product details can change after publication: report an error or read the editorial methodology.

Emanuel DE ALMEIDA

Written by

Emanuel DE ALMEIDA

Entrepreneur · IT consultant · Software creator

Geneva-based entrepreneur, IT consultant and creator of SuniPDF and SuniCapture. Emanuel shares practical IT, cybersecurity and software insights on iThub.

Keep reading

More guides and analysis from the iThub editors.

All insights
What is containerization? How containers work, from kernel to registryWhat containerization is and how containers work: namespaces, cgroups v2, image layers, OCI specs, runtimes, rootless, macOS and Windows, with a Dockerfile.12 open source projects for developers to know in 202612 open source projects for developers in late 2026, from Ghostty and Tauri to Langfuse and Zerobyte, with licenses and latest releases checked.Docker vs Kubernetes: which do you need?Compare Docker Compose and Kubernetes by host failure risk, scaling needs, operational cost and recovery testing.