colima

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

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.