Colima

Colima runs container runtimes on macOS (and Linux) with minimal setup. It's a higher-level wrapper over Lima: it boots a small VM and provisions Docker, containerd, Kubernetes and/or Incus inside it, then wires up the host client so docker (etc.) "just works".

Scope: the canonical source is the repo's own docs (docs/INSTALL.md, docs/FAQ.md) plus README usage. Behavior is version-gated in many places — keep the vX.Y.Z notes when advising, since users run a range of versions. Check the user's version with colima version.

Quick start

brew install colima      # + docker client if using Docker runtime: brew install docker
colima start             # boots the VM, Docker runtime by default
docker run hello-world   # docker client works with no extra setup

Full install options (MacPorts, Nix, Arch, binary, source) → references/install.md.

Core commands

Command	What it does
colima start [profile]	Create/start the VM. Flags: --runtime, --kubernetes, --cpu, --memory, --disk, --edit, --env, --dns, --network-address, --vm-type, --foreground
colima stop [--force]	Stop the VM. --force recovers a Broken status
colima status	Show running status (incl. Docker socket path)
colima list	List profiles and their status/arch/cpus/mem/disk/runtime
colima restart	Stop + start (needed after editing mounts/config)
colima delete [--data]	Delete the VM. --data also deletes container data (since v0.9.0 data lives on a separate disk)
colima ssh [-- <cmd>]	Shell into the VM, or run one command
colima start --edit	Start while editing the YAML config (since v0.4.0)
colima template	Edit the default config template for new instances
colima update	Update the container runtime in place (since v0.7.6)
colima nerdctl ...	nerdctl wrapper for the containerd runtime
colima model ...	Set up / run AI models (GPU, krunkit; since v0.10.0)
colima version	Print the version (use it before applying version-gated advice)

Profiles isolate independent VMs: colima start work operates on the work profile; default is default. colima --help / colima start --help list everything.

Runtimes — chosen at start

Default is Docker. Switching the runtime requires re-creating the VM — a stop/start alone does not change it: colima delete --data && colima start --runtime <new>.

• Docker (default): colima start → docker ... works directly. Needs the docker client (brew install docker).
• Containerd: colima start --runtime containerd → use colima nerdctl ... (run colima nerdctl install to add a nerdctl alias to $PATH).
• Kubernetes: colima start --kubernetes (needs kubectl). Shares images with the chosen container runtime.
• Incus (v0.7.0+): colima start --runtime incus → incus ....
• AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+): colima start --runtime docker --vm-type krunkit then colima model run gemma3.

Per-runtime config, socket location, registry mirrors, buildx, nerdctl, AI model registries → references/runtimes.md.

Registry mirror (common task): colima start --registry-mirror <url> (repeatable) or --edit → add under docker.registry-mirrors. For the client to honor mirrors, the host ~/.docker/daemon.json may also need the same entries. Details → references/runtimes.md.

Customizing the VM

Defaults: 2 CPUs, 2 GiB memory, 100 GiB disk. Customize via flags or the config file.

colima start --cpu 4 --memory 8 --disk 100      # at create time
colima stop && colima start --cpu 4 --memory 8  # change an existing VM (disk can only grow)
colima start --vm-type=vz --vz-rosetta          # Rosetta 2 (v0.5.3+, Apple Silicon, macOS 13+)

Config files, profiles, COLIMA_HOME, passing env into the VM, Lima overrides → references/configuration.md.

Writing a bootstrap / CI / deploy script? See references/automation.md for non-interactive patterns: idempotent start (colima status guard), readiness wait (docker info loop), DOCKER_HOST wiring so the rest of the script targets Colima, --foreground for supervisors, teardown, and a GitHub Actions sketch.

Common gotchas (quick)

• Cannot connect to the Docker daemon at unix:///var/run/docker.sock — an app isn't using Colima's Docker context. Point it at Colima's socket (export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock") or relink the socket. Details + socket location by version → references/troubleshooting.md.
• Broken status (e.g. after a macOS restart): colima stop --force, then colima start.
• Docker bind mount shows empty — the host path must be under /Users/$USER, or add it to the mounts section of the config and colima restart. Paths with spaces are unsupported.
• Won't start / fatal error — re-run with --verbose; common causes are no virtualization support or an x86_64 Homebrew/Colima on Apple Silicon. See references/troubleshooting.md.

Full troubleshooting (no internet/DNS, runc/cgroups error, disk recovery & resize, reachable IP, post-upgrade issues, deleting data) → references/troubleshooting.md.

References

• references/install.md — all install methods (Homebrew, MacPorts, Nix, Arch, binary, source).
• references/configuration.md — config file & profiles, file locations & env vars, custom VM env, Lima overrides, autostart.
• references/runtimes.md — Docker (socket/contexts/registries/buildx), Containerd, Kubernetes, Incus, AI models; comparisons to Lima/minikube/Kind/K3d.
• references/troubleshooting.md — startup failures, networking, mounts, disk, updates, deleting data.
• references/automation.md — non-interactive patterns for bootstrap / CI / deploy scripts.