Lima runs Linux virtual machines on macOS and Linux, with your home folder shared into the guest and guest ports forwarded to localhost. limactl creates, starts, stops and deletes those VMs, which Lima calls instances. lima is a shortcut for opening a shell in the default one. This sheet covers both. Every command and flag below is in Lima v2.2.1 (released 2026-10-03) and is checked against the official docs and command reference at lima-vm.io. Those docs follow the development version, so they list a few flags that 2.2.1 doesn’t have yet. The commands were tested on limactl 2.2.0 on macOS (Apple silicon) with the vz VM type. We attempt to test on all versions.
what it is and when to use it
- Instance: one Lima VM. The name defaults to
default. - Template: a YAML file describing an instance. Lima ships templates such as
default,debian,alpine,fedoraanddocker. - VM type: QEMU on Linux. On macOS 13.5 and later, new instances use Apple’s Virtualization.framework (
vz) by default, since Lima v1.0.
Reach for it when you’re on a Mac and need a real Linux machine, when you want to try a different distribution without touching your own, or when you want containers without Docker Desktop.
install and check the version
These are the install routes on the Lima installation page. On Linux, Lima also needs QEMU from your distribution.
| Command | What it does |
|---|---|
brew install lima | macOS or Linux with Homebrew |
sudo port install lima | MacPorts |
limactl --versionoutput limactl version 2.2.0 | Print the installed version |
The docs also offer a binary tarball from the GitHub releases page, extracted under /usr/local.
create and start
| Command | What it does |
|---|---|
limactl start | Create and start the default instance, asking before it proceeds |
limactl start -y | Create and start without any prompts, for scripts |
limactl start --name=deb template:debian | Start from another template, with your own name |
limactl start --name=small --cpus=2 --memory=2 --disk=20 template:debian | Set CPUs, memory in GiB, and disk in GiB |
limactl create --name=deb template:debian | Create an instance without starting it |
limactl start deb | Start it later |
limactl create --list-templates | List every template that ships with Lima |
-y is short for --tty=false, which skips the interactive menu.
shell and run commands
| Command | What it does |
|---|---|
lima | Open a shell in the default instance |
lima uname -a | Run one command in the default instance |
limactl shell deb uname -a | Same thing for a named instance |
limactl shell --start deb | Start the instance first if it’s stopped, then open the shell |
limactl shell --workdir /tmp deb ls | Run in a given directory inside the guest |
lima runs limactl shell against the instance named in $LIMA_INSTANCE, which defaults to default.
list, stop, restart, delete
| Command | What it does |
|---|---|
limactl list output NAME STATUS VMTYPE ARCH demo Stopped vz aarch64 | List instances with status, resources, and directory (output trimmed to 4 of 9 columns) |
The full output also has SSH, CPUS, MEMORY, DISK and DIR columns. DIR is where the instance lives, ~/.lima/<name> by default.
| Command | What it does |
|---|---|
limactl list -q | Just the names |
limactl list --format '{{.Name}} {{.Status}}' | Custom columns |
limactl list --json | JSON |
limactl stop deb | Stop an instance |
limactl stop -f deb | Force it to stop |
limactl restart deb | Restart a running instance |
limactl delete deb | Delete an instance and its disk. No undo. protect blocks it. |
limactl protect deb | Stop deleting by accident |
limactl unprotect deb | Undo that |
Deleting a protected instance fails with "instance is protected to prohibit accidental removal".
change an instance
| Command | What it does |
|---|---|
limactl edit deb --cpus=4 --memory=8 | Change CPUs or memory on an existing instance |
limactl rename deb debian | Rename an instance |
limactl clone deb deb2 --start | Clone an instance, then start the copy |
limactl factory-reset deb | Reset an instance to a fresh disk, keeping its config. No undo. |
limactl template copy template:alpine ./my.yaml limactl validate ./my.yaml | Copy a shipped template to a file you can edit, then check it |
limactl start --name=mine ./my.yaml | Start an instance from your own template file |
limactl start --name=deb --set '.cpus = 2' template:debian | Change one template field from the command line, in yq syntax |
files, mounts, and ports
| Command | What it does |
|---|---|
limactl copy deb:/usr/lib/os-release . | Copy a file from the guest to the host |
limactl copy ./notes.txt deb:/tmp/ | Copy a file from the host into the guest |
limactl copy --backend=scp deb:/etc/os-release . | Force the scp backend instead of rsync |
The default backend, auto, uses rsync when it’s installed on both sides, and rsync copies a symlink as a symlink. /etc/os-release is a symlink to /usr/lib/os-release, so copying it with rsync exits 0 but leaves a broken link on the host. Copy the real file, or use --backend=scp, which copies the file the link points to.
| Command | What it does |
|---|---|
limactl copy -r ./mydir deb:/tmp/ | Copy a directory recursively |
limactl start --mount-only ~/projects --mount-writable template:debian | Mount only one host folder, writable, instead of your whole home folder |
--mount-writable makes every mount writable. On its own, that’s your whole home folder, so anything running in the guest can change or delete your files. Pair it with --mount-only to limit it to one folder.
| Command | What it does |
|---|---|
limactl start --mount-none template:debian | Start with no host folders mounted at all |
limactl start --port-forward 8080:80 template:debian | Forward host port 8080 to guest port 80 |
- Your host home directory is mounted read-only in the guest by default, at
/home/<user>on Linux hosts and/Users/<user>on macOS. - The guest’s own home directory is separate:
/home/<user>.guestsince Lima v2.1./home/<user>.linux, the path before v2.1, is a symlink to it. - Ports a guest program opens on localhost are forwarded to the host’s localhost automatically.
snapshots
Snapshots work only with the QEMU VM type. They don’t work with vz, the default for new instances on macOS: there, every snapshot command fails with fatal msg=unimplemented. On a Mac, an instance needs to be created with --vm-type=qemu for these to work.
Tested on limactl 2.2.0 with QEMU 11.1.2, on a running instance and a stopped one. Every snapshot command prints a warning that it’s experimental.
| Command | What it does |
|---|---|
limactl snapshot create deb --tag before-upgrade | Take a snapshot with a tag (experimental, QEMU only) |
limactl snapshot list deb | List snapshots |
limactl snapshot apply deb --tag before-upgrade | Roll the instance back to the before-upgrade snapshot |
limactl snapshot delete deb --tag before-upgrade | Delete the before-upgrade snapshot. No undo. |
housekeeping
| Command | What it does |
|---|---|
limactl info | Diagnostic info as JSON: version, templates, VM types, Lima’s home directory |
limactl prune | Remove cached downloads, such as VM images |
eval "$(limactl completion bash)" | Bash completion for this shell (works in the bash 3.2 that ships with macOS) |
source <(limactl completion bash) silently does nothing in bash 3.2, the version macOS ships. In zsh, the macOS default shell, use the zsh completion instead: limactl completion zsh --help shows how to set it up.
gotchas
- In a terminal, plain
limactl startopens a menu and waits for an answer; without one it goes ahead with defaults. Add-yin scripts so it never waits. - The host home folder is read-only in the guest by default. Writes there fail unless the mount is writable. Prefer
--mount-only <dir> --mount-writableover--mount-writablealone, which makes your whole home folder writable. - Snapshots need the QEMU VM type. On
vz, the macOS default, they fail withfatal msg=unimplemented. - After
snapshot applyon a running instance, the nextlimactl shellstalled for about 10 minutes in our tests before it connected. Stop the instance before you apply, or wait it out. Applying to a stopped instance didn’t stall. limactl copywith the rsync backend copies symlinks as symlinks, which can leave a broken link on the host.--mount-noneand--plainmean the guest can’t see your files at all.--plainalso turns off port forwarding and containerd.limactl copyandlimactl cloneare different things: copy moves files, clone duplicates a whole instance.- On Linux, Lima runs VMs with QEMU. On our Linux test machine, itself a VM, QEMU couldn’t use KVM and the instance never booted. If
limactl starthangs, the instance’sha.stderr.logandserial*.logfiles in~/.lima/<instance>/show what QEMU said. - Cached VM images stay in Lima’s cache after you delete an instance.
limactl pruneclears them.
related on terminal-life
sources
Checked against the Lima documentation and command reference on lima-vm.io (which follow the development version), read Oct 24, 2026, and the Lima v2.2.1 release (2026-10-03). Tested on limactl 2.2.0.
Run in a VM on macOS (Apple silicon), VM type vz, VM deleted afterward:
start -y,startwith a template, a name, resources,--setor a template file,createthenstartlima,shell(--start,--workdir),stop(-f),restart,clone,factory-resetcopy(including-r, and--backend=scp),--mount-writable,--mount-only <dir> --mount-writable,--mount-none,--port-forwardcompletion bash(witheval "$(limactl completion bash)")- plain
start(it asks before proceeding in a terminal, and proceeds without asking when there’s no terminal)
Run on a QEMU instance (QEMU 11.1.2), VM deleted afterward:
snapshot create,list,apply,delete(they fail onvzwithfatal msg=unimplemented)
Not run in a VM on our Linux test machine:
- The test box has
/dev/kvm, but creating a vCPU there triggered a host kernel error, and QEMU hung. - Without KVM access, QEMU through Lima exited with "Could not access KVM kernel module: Permission denied".
Run on the Linux host only, with no VM started:
limactl --versioncreate(with-y),list(-q,--format,--json)edit --cpus,rename,protect/unprotect,deletetemplate copy,validate,create --list-templatesinfo,disk list,prune
Sources:
- Installation: https://lima-vm.io/docs/installation/
- Usage: https://lima-vm.io/docs/usage/
- VM types: https://lima-vm.io/docs/config/vmtype/
- Filesystem mounts: https://lima-vm.io/docs/config/mount/
- Port forwarding: https://lima-vm.io/docs/config/port/
- limactl command reference: https://lima-vm.io/docs/reference/limactl/
- limactl start: https://lima-vm.io/docs/reference/limactl_start/
- limactl shell: https://lima-vm.io/docs/reference/limactl_shell/
- limactl copy: https://lima-vm.io/docs/reference/limactl_copy/
- limactl snapshot: https://lima-vm.io/docs/reference/limactl_snapshot/
- Releases: https://github.com/lima-vm/lima/releases
terminal-life.com/cheatsheets/limactl/ · tested on limactl 2.2.0 against the Lima docs on lima-vm.io