Skip to main content

Colima - Container Runtime for macOS/Linux

Colima (Containers in Lima) provides a lightweight, open-source container runtime on macOS (Apple Silicon & Intel) and Linux, giving you a fast, configurable alternative to Docker Desktop with optional Kubernetes support.

1. Why Colima?​

Colima wraps Lima (Linux virtual machines with containerd/qemu) to deliver an ergonomic CLI for container workloads. It aims for:

  • Zero (or minimal) vendor lock-in
  • Familiar Docker/Moby tooling (Docker CLI, Compose)
  • Simplicity: colima start and you're productive
  • Optional Kubernetes cluster for local dev/testing
  • Lower resource usage vs Docker Desktop
  • Works natively on Apple Silicon (arm64) and supports x86 emulation when needed

When to Choose Colima​

ScenarioColima FitNotes
You want to avoid Docker Desktop licensing✅Fully OSS stack
Need quick switching of container runtime profiles✅colima start --profile ...
Local K8s just for helm/operator dev✅Lightweight alternative to kind/minikube
Heavy multi-cluster K8s testing⚠️Consider kind or k3d for multi-node
Need advanced GUI container management❌Pair with tools like Lens/Portainer

2. Architecture Overview​

+--------------------+
|  Your Host (macOS) |
|  docker / nerdctl  |
+----------+---------+
           |
           v (CLI calls socket)
+----------------------------+
| Colima CLI                |
|  - profile management     |
|  - lifecycle (start, stop)|
+-------------+--------------+
              |
              v
+----------------------------+
| Lima VM (QEMU HVF/WHV)    |
|  - Linux kernel           |
|  - containerd / dockerd   |
|  - (optional) k3s         |
+-------------+--------------+
              |
              v
        Containers / Pods

Key components:

  • Lima: Manages the lightweight VM
  • containerd / dockerd: Container runtime (Colima can enable Docker or rely on nerdctl+containerd)
  • k3s: Optional lightweight Kubernetes distro
  • QEMU + Hypervisor.framework on macOS for virtualization

3. Installation​

Prerequisites: brew (Homebrew) installed.

brew install colima
# (Optional) install docker client if you removed Docker Desktop
brew install docker
# (Optional) for nerdctl
brew install nerdctl

Upgrade:

brew upgrade colima

Verify:

colima version

4. Quick Start​

# Start default profile with Docker runtime
groupadd docker 2>/dev/null || true  # (Linux only, if needed)
colima start

# Use docker client
docker info

# Run a container
docker run --rm -it alpine:latest echo "Hello Colima"

Stop / Delete:

colima stop
colima delete  # removes VM state for the profile

5. Profiles & Lifecycle​

You can maintain separate environments (different memory, CPUs, k8s enabled, etc.):

colima start --profile k8s-dev --cpu 4 --memory 6 --disk 60 --kubernetes
colima stop --profile k8s-dev
colima list

Useful flags:

  • --arch x86_64 (on Apple Silicon for amd64 images)
  • --docker vs --containerd
  • --vm-type=vz (macOS 13+ Virtualization.framework, faster than QEMU; auto-detected in newer versions)
  • --mount TYPE for additional host mounts

Switch active profile (just include --profile on each command) or export COLIMA_PROFILE env var.

6. Configuration File (.colima/<profile>/colima.yaml)​

After first start you can tweak configuration. To open:

colima status --profile k8s-dev --show-config

Or manually edit:

$HOME/.colima/k8s-dev/colima.yaml

Common fields:

cpus: 4
memory: 6
disk: 60
autoActivate: true
kubernetes: true
docker: true
# runtime: containerd | docker
# mounts:
#   - location: ~/Projects
#     writable: true
# forwardPorts:
#   - guestSocket: /var/run/docker.sock

Apply changes:

colima stop --profile k8s-dev
colima start --profile k8s-dev

7. Resource Management & Performance​

Tips:

  • Allocate only what's needed; over-provisioning reduces host battery/perf.
  • Prefer --vm-type=vz on macOS Ventura+ for better I/O (if supported).
  • Use docker buildx with --platform for multi-arch builds, leveraging Colima's architecture emulation.
  • Periodically prune: docker system prune -af --volumes (CAUTION: removes unused resources).

Benchmark check:

time docker run --rm alpine:latest true

Compare after changing CPU/memory.

8. Docker vs containerd (nerdctl)​

Colima can expose either:

  • Classic Docker socket (/var/run/docker.sock) for Docker CLI & Compose
  • containerd accessible via nerdctl (nearly Docker-compatible)

Choose at start:

colima start --docker        # default Docker experience
colima start --containerd    # for pure containerd workflow

9. Kubernetes (k3s) Enablement​

Start with k8s:

colima start --kubernetes

Validate:

kubectl cluster-info
kubectl get nodes

Default single-node k3s cluster. Helm ready:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install demo bitnami/nginx
kubectl get svc

Load images you build locally without pushing:

# Build with docker
docker build -t local/demo:1 .
# Save & load into k3s (if needed)
ctr -n k8s.io images import <(docker save local/demo:1)

Often unnecessary if using Docker runtime; images become available automatically.

Reset k8s:

colima kubernetes reset

Disable later:

colima stop
colima start --without-kubernetes

10. Networking & Port Forwarding​

By default Colima sets up automatic host<->VM networking; exposing container ports works as usual:

docker run -d -p 8080:80 nginx
curl localhost:8080

Custom host port forwards (advanced): in colima.yaml:

portForwards:
  - guestPort: 3000
    hostPort: 3000
    hostIP: 127.0.0.1

Then restart profile.

Access services inside k3s via kubectl port-forward or LoadBalancer simulation using tools like metallb.

11. File Mounts & Volumes​

Bind mounts (host directory into containers):
Add in config:

mounts:
  - location: ~/Projects
    writable: true

Runtime volume example:

docker run -v colima-data:/data alpine sh -c 'echo hi > /data/hi.txt'
docker run --rm -v colima-data:/data alpine cat /data/hi.txt

Performance: Keep heavy I/O inside the VM volume when possible (use named volumes) to reduce host<->VM filesystem overhead.

12. Multi-Architecture Images​

On Apple Silicon needing amd64 images:

colima start --arch x86_64

Or build multi-arch:

docker buildx create --name multi --use
docker buildx build --platform linux/amd64,linux/arm64 -t your/image:latest --push .

13. Troubleshooting​

IssueCommand / Action
VM fails to startcolima delete && colima start (note: destructive)
Docker cannot connectcolima status then ensure profile running
Permission denied on socketAdd user to docker group (Linux) / restart shell
High CPU idleReduce cpus in config; ensure no runaway container
Disk fulldocker system df; increase disk: in colima.yaml then restart
K8s pods ImagePullBackOffCheck local image names/tags; use docker images
Networking issuesRestart profile: colima stop && colima start

Logs:

colima status --show-config
colima ssh  # drop into VM
journalctl -u docker --no-pager | tail -n 50

14. Security Considerations​

  • Colima runs a local VM; isolation boundary is the hypervisor.
  • Manage secrets using environment injection or secret management (e.g., docker run --env-file).
  • Avoid mounting sensitive host paths read-write unless necessary.
  • Keep images updated and prune unused layers.
  • For SBOM scanning: integrate trivy or grype on built images.

15. Comparison Cheat Table​

FeatureColimaDocker Desktopkindminikubek3d
Docker CLI Support✅✅Via hostOptionalOptional
Kubernetes Built-in✅ (k3s optional)✅✅ (multi-cluster)✅✅
GUI❌✅❌❌❌
Multi-arch (Apple Silicon)✅✅Host dependentHost dependentHost dependent
Profiles✅LimitedPer clusterFlagsPer cluster
License Cost (Business)OSSLicense tiersOSSOSSOSS

16. Automation & CI Integration​

You can script environment preparation:

if ! colima list | grep -q dev; then
  colima start --profile dev --cpu 4 --memory 8 --disk 80 --docker
fi

Pre-build in CI on macOS runners (GitHub Actions self-hosted): ensure virtualization enabled, then install via Homebrew and start with tuned resources.

17. Aliases & Quality of Life​

Add to shell profile (~/.zshrc):

alias k=kubectl
alias d=docker
alias cologs='colima ssh -- sudo journalctl -u docker -f'

Reload: source ~/.zshrc.

18. Cleanup & Reset​

# Remove dangling images
docker image prune -f
# Remove all (CAUTION)
docker system prune -af --volumes
# Reset Colima profile
colima delete --profile dev

19. FAQ​

Q: Does Colima replace Docker Desktop entirely?
A: For CLI workflows, yes. For GUI features (image scanning UI, extensions), you'll need alternative tools.

Q: How to switch from Docker Desktop?
A: Uninstall Docker Desktop (optional), install Colima & docker CLI via Homebrew, ensure $PATH points to the brewed docker client, then colima start.

Q: Where are images stored?
A: Inside the VM disk image under the Colima profile directory (managed by container runtime).

Q: Can I run multiple profiles simultaneously?
A: Typically one active VM per profile; you can run multiple but resource contention may occur.

20. Quick Command Cheat Sheet​

# Start with k8s
docker context use default
colima start --kubernetes
# Status
colima status
# List profiles
colima list
# Stop
colima stop
# Delete
colima delete
# Show config
colima status --show-config
# Enter VM
colima ssh
# Reset k8s
colima kubernetes reset

21. References​

If you have internal platform-specific standards (naming, tagging, security baselines), layer them on top of this baseline workflow.

Happy containerizing with Colima! 🚀