Colima: Container Runtime on macOS Without Docker Desktop

If you’ve been developing on macOS for a while, you’ve probably felt the pinch of Docker Desktop’s licensing changes, hefty memory footprint, and occasional performance hiccups. Enter Colima – a lightweight, open‑source container runtime that mimics Docker Desktop’s CLI experience without the bloat. In this guide we’ll walk through why Colima matters, how to get it up and running, and how to leverage it for real‑world projects, all while keeping the Docker‑compatible workflow you already love.

What Is Colima?

Colima (short for “Containers on Lima”) builds on Lima, a macOS hypervisor that runs Linux virtual machines using QEMU. Colima configures a minimal VM, installs containerd, and then exposes the Docker CLI and Docker Compose as thin wrappers. The result is a Docker‑compatible environment that starts in seconds, uses far less RAM, and stays completely free.

From a developer’s perspective, the biggest win is that all existing Docker commands—docker run, docker compose up, docker build—continue to work unchanged. You simply point the Docker client at Colima’s socket, and you’re good to go.

Installing Colima on macOS

The installation process is intentionally simple. Homebrew is the recommended package manager, but you can also grab a pre‑built binary from the GitHub releases page.

# Install Lima first (Colima’s dependency)
brew install lima

# Then install Colima
brew install colima

# Verify the installation
colima version

Colima ships with a default configuration that allocates 2 CPU cores and 2 GB of RAM. For most web development tasks this is more than enough, but you can fine‑tune the resources before the first start.

Customizing Resources

# Example: 4 CPUs, 8 GB RAM, 100 GB disk
colima start --cpu 4 --memory 8 --disk 100

Running colima start for the first time creates a tiny Alpine‑based VM, pulls the containerd binaries, and sets up the Docker socket at ~/.colima/docker.sock. Subsequent starts are almost instantaneous because the VM is already cached.

Basic Colima Commands

Colima’s CLI mirrors Docker’s sub‑commands, making the learning curve negligible. Here are the most frequently used commands:

• colima start – Boots the VM and starts containerd.
• colima stop – Gracefully shuts down the VM.
• colima status – Shows VM health, resource allocation, and running containers.
• colima delete – Removes the VM and all stored images/containers (use with caution).

Because Colima creates a Docker socket, you can continue using the native Docker client without any extra flags.

Running a Quick Test Container

# Pull and run the official nginx image
docker run -d -p 8080:80 --name webserver nginx

# Verify it’s reachable
curl http://localhost:8080

The container runs inside the lightweight VM, but you access it on localhost just like you would with Docker Desktop. This seamless integration is what makes Colima a drop‑in replacement.

Docker Compose with Colima

Most modern projects rely on docker-compose.yml files to spin up multi‑service stacks. Colima supports Docker Compose out of the box because it forwards the Docker socket to the Compose CLI.

Sample Compose File

# docker-compose.yml
version: "3.9"
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    ports:
      - "5432:5432"
  api:
    build: ./api
    depends_on:
      - db
    environment:
      DATABASE_URL: postgres://dev:secret@db:5432/appdb
    ports:
      - "8000:8000"

Place the file at the root of your project, then bring the stack up with a single command.

docker compose up -d

Colima will automatically allocate additional resources if your services demand more memory or CPU, but you can also pre‑configure limits with the --cpu and --memory flags during colima start.

Real‑World Use Cases

Now that the basics are covered, let’s explore three practical scenarios where Colima shines.

1️⃣ Local Development of a Full‑Stack App

Imagine you’re building a Node.js API, a React front‑end, and a PostgreSQL database. With Colima you can spin up the entire stack in seconds, keep the VM lightweight, and avoid Docker Desktop’s licensing concerns.

# Directory layout
myapp/
├─ api/
│   └─ Dockerfile
├─ web/
│   └─ Dockerfile
└─ docker-compose.yml

Running docker compose up -d launches all three services. Because the VM runs on a Linux kernel, you get true Linux networking, file system permissions, and volume performance—something macOS’s native file sharing sometimes struggles with.

2️⃣ CI/CD on a Mac Mini Build Agent

Many small teams use Mac Minis as self‑hosted runners for iOS builds. Adding Docker Desktop to each runner inflates the footprint and introduces licensing headaches. Installing Colima instead reduces memory usage by ~70% and speeds up container start‑up time, which translates to faster test suites.

# .github/workflows/ci.yml (excerpt)
jobs:
  build:
    runs-on: macos-13
    steps:
      - uses: actions/checkout@v3
      - name: Install Colima
        run: brew install colima && colima start --cpu 2 --memory 4
      - name: Run Tests
        run: |
          docker compose -f docker-compose.test.yml up --abort-on-container-exit

The workflow boots a minimal VM, runs the test containers, and tears down automatically, keeping the runner clean for the next job.

3️⃣ Kubernetes Development with k3s

Colima also supports Kubernetes via the --kubernetes flag. It provisions a lightweight k3s cluster inside the same VM, giving you a full‑featured K8s API without the overhead of Docker Desktop’s integrated cluster.

# Start Colima with k3s enabled
colima start --kubernetes

# Verify the cluster
kubectl version --client
kubectl get nodes

Developers can now test Helm charts, custom resources, and ingress rules locally, all while staying within the familiar Docker ecosystem.

Performance & Resource Management

Colima’s design prioritizes efficiency. It uses QEMU’s virtiofs for file sharing, which offers near‑native performance compared to Docker Desktop’s osxfs. Additionally, the VM runs headless, meaning no GUI overhead.

To monitor resource consumption, use the built‑in colima status command or macOS’s Activity Monitor. If you notice memory pressure, simply stop the VM, adjust the --memory flag, and restart.

# Quick status check
colima status

# Example output (truncated)
CPU: 2
Memory: 4 GiB
Disk: 30 GiB
Running containers: 3

Because the VM is isolated, you can also experiment with different Linux kernel versions without affecting your host. Colima lets you specify a custom Lima template if you need a newer kernel for particular workloads.

Pro Tips & Common Pitfalls

Tip 1: Use colima ssh to drop into the VM shell. This is handy for debugging low‑level networking or inspecting containerd logs directly.

Tip 2: Persist data across VM restarts by mounting a host directory as a volume. Colima’s --mount flag automatically sets up a virtiofs share, which is faster than the legacy osxfs approach.

Tip 3: When running heavy builds (e.g., compiling Go binaries), allocate more CPU cores temporarily: colima stop && colima start --cpu 6 --memory 8. Remember to scale back after the build to keep your laptop snappy.

Gotchas: The first docker pull after a fresh start may appear slower because the VM needs to download the image layers over the virtual network. Subsequent pulls are cached inside the VM, so performance improves dramatically.

Troubleshooting Checklist

• Docker client can’t connect to the daemon – Verify the socket path: export DOCKER_HOST=unix://$HOME/.colima/docker.sock or add it to your shell profile.
• Ports not reachable on localhost – Ensure the VM’s port forwarding is active; you can list forwarded ports with colima list.
• Out‑of‑memory errors – Increase the --memory allocation and restart the VM.
• File change events not triggering – Use --watch flag in your development tools, or mount the volume with cached mode for better sync.

Comparing Colima to Docker Desktop

Below is a quick side‑by‑side comparison that highlights where Colima excels and where Docker Desktop still holds an edge.

Feature	Docker Desktop	Colima
License Cost	Free tier limited; paid for professional use	Completely free, open source
Memory Footprint	~4 GB idle	~500 MB idle
Startup Time	30‑45 seconds	5‑10 seconds
Kubernetes Support	Integrated, but heavy	k3s via --kubernetes, lightweight
GUI Dashboard	Built‑in	None (use third‑party tools)
File‑System Performance	osxfs (moderate)	virtiofs (near‑native)

For most developers who only need container orchestration and occasional Kubernetes experimentation, Colima provides a faster, cheaper, and more transparent experience.

Advanced Configuration – Lima Templates

Colima’s underlying VM is defined by a Lima YAML template. Advanced users can create a custom template to tweak network settings, enable nested virtualization, or switch the base image.

# ~/.colima/lima.yaml (example)
arch: "x86_64"
images:
  - location: "https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img"
    arch: "x86_64"
    digest: "sha256:..."
mounts:
  - location: "~"
    writable: true
    type: "virtiofs"
cpu: 4
memory: "8GiB"
disk: "30GiB"

After saving the file, start Colima with colima start --template ~/.colima/lima.yaml. This level of control is useful for testing kernel modules, custom sysctl parameters, or specific Linux distributions.

Integrating with IDEs

Most modern IDEs (VS Code, IntelliJ, JetBrains Rider) detect the Docker socket automatically. If you’ve set DOCKER_HOST as recommended, the IDE will list containers, images, and even allow you to attach a debugger inside a running service.

For VS Code, add the following to .vscode/settings.json to ensure the extension points at Colima’s socket:

{
  "docker.host": "unix:///Users/yourname/.colima/docker.sock"
}

Now you can right‑click a container in the Docker view and select “Attach Shell” or “Open Logs” without any extra configuration.

Backup & Migration Strategies

Because Colima stores images and containers inside a VM disk file (~/.colima/colima.qcow2), backing up is as simple as copying that file. For teams that need reproducible environments, you can export images to a tarball and import them on a new machine.

# Export an image
docker save myapp:latest -o myapp.tar

# Transfer the tarball to another Mac
scp myapp.tar user@newmac:~/ 

# Import on the new machine (with Colima running)
docker load -i myapp.tar

For a full VM snapshot, use colima stop && cp ~/.colima/colima.qcow2 ~/backup/colima-backup.qcow2. Restoring involves replacing the file and running colima start.

Future Roadmap & Community

Colima is actively maintained by the open‑source community. Upcoming features include native support for BuildKit’s docker buildx caching, improved Windows Subsystem for Linux (WSL) interop, and a GUI dashboard built with Tauri. Contributing is straightforward: fork the repo, open an issue, or submit a PR with a new Lima template.

If you run into a bug, the GitHub Issues page is the first stop. The maintainers are responsive, and many common problems already have community‑provided workarounds.

Conclusion

Colima delivers a Docker‑compatible, low‑overhead container runtime that feels native on macOS. By leveraging Lima’s lightweight VM, it sidesteps Docker Desktop’s licensing and performance constraints while preserving the familiar CLI workflow. Whether you’re iterating on a full‑stack web app, running CI jobs on a Mac Mini, or experimenting with a local Kubernetes cluster, Colima provides the speed, flexibility, and cost‑effectiveness that modern developers demand. Give it a try, tweak the resources to match your workload, and enjoy a smoother, more transparent container experience on your Mac.