# Colima: container runtimes on macOS without Docker Desktop

> Colima wraps Lima virtual machines into a single CLI that starts Docker, containerd, Incus or Kubernetes on macOS and Linux. Here is what it actually does, how to install and run it, and where it stops being the right tool.

**abiosoft/colima** — Container runtimes on macOS (and Linux) with minimal setup

- Repository: https://github.com/abiosoft/colima
- Website: https://colima.run
- Stars: 30,945 · Forks: 619
- Language: Go
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/abiosoft-colima

## The gap Colima fills on a Mac

Docker on macOS cannot run natively. The Linux kernel is not there, so something has to host it: a virtual machine, and a daemon inside that VM that the macOS Docker client talks to over a socket. Docker Desktop bundled all of that into one installer, and for years it was the default answer. Colima takes the opposite route. It gives you the VM and the runtime plumbing as a command line tool, and nothing else. No GUI, no extensions marketplace, no background auto-update service.

The README states the project goal plainly: to provide container runtimes on macOS with minimal setup. The name is an abbreviation of Containers on Lima, and Lima is the Linux virtual machine manager doing the heavy lifting underneath. Colima is therefore a configuration and lifecycle layer: it creates the Lima VM, installs the runtime you asked for, wires up port forwarding and volume mounts, and exposes a client socket that the standard docker CLI can use.

Who is this for? Developers on Intel or Apple Silicon Macs who want docker run to work without installing Docker Desktop. Also people who need containerd rather than Docker, or Incus for system containers and virtual machines, or a single-node Kubernetes cluster for local testing. The README lists all four runtimes under one CLI, which is the part that distinguishes Colima from a plain Lima setup.

## How the VM, runtimes and port forwarding fit together

Colima's architecture is visible in the repository layout. There is a cli/ directory for command definitions, a daemon/ directory for the long-running process, a core/ directory for the runtime logic, and an environment/ directory. The Go module depends on spf13/cobra for the command tree, sevlyar/go-daemon for daemonization, rjeczalik/notify for filesystem events, and gopkg.in/yaml.v3 for configuration files. That is a CLI that manages a background process, not a container engine itself.

Startup works in stages. colima start creates or reuses a Lima VM, boots it, then installs and configures the selected runtime inside. The runtime defaults to Docker. Port forwarding is automatic, and volume mounts are supported, both listed as features in the README. Multiple instances are supported, so you can keep a Docker VM and a Kubernetes VM side by side rather than tearing one down to get the other.

The Kubernetes integration differs by runtime, and the README is specific about it. With the Docker runtime, images built or pulled with Docker are visible to Kubernetes. With containerd, only images in the k8s.io namespace are visible to Kubernetes. That single sentence matters more than it looks: if you build an image with nerdctl and then try to run it as a pod, the namespace rule decides whether it resolves.

For AI workloads, v0.10.0 added GPU-accelerated containers using the krunkit VM type, requiring Apple Silicon and macOS 13 or newer, with krunkit installed separately. Two runner backends exist: Docker Model Runner by default, and Ramalama. That is a recent addition layered on top of the same VM lifecycle.

## Installing Colima and starting your first VM

Colima ships through several package managers. The README lists Homebrew, MacPorts, Nix and Mise. On a Mac, Homebrew is the shortest path:

```bash
brew install colima
```

If you want the development build instead of a tagged release, the README offers a Homebrew-only variant:

```bash
brew install --HEAD colima
```

The Docker runtime needs the Docker client, which is a separate install. The README notes it is installable with brew install docker. Colima provides the engine and the socket; it does not ship the client.

```bash
brew install docker
colima start
```

After colima start completes, the docker CLI on macOS works with no additional setup, according to the README. The first real check is the standard hello-world image:

```bash
docker run hello-world
docker ps
```

You should see the hello-world container print its message and exit, and docker ps should return an empty table rather than a connection error. A connection error at this point almost always means the VM did not finish starting or the client is pointing somewhere else.

If you would rather edit settings than pass flags, the README gives colima start --edit for config-file editing, and colima --help plus colima start --help for the full option list. The default VM is 2 CPUs, 2 GiB of memory and 100 GiB of storage. Disk size can be increased after creation; the README does not say it can be decreased.

## Switching runtimes: containerd, Kubernetes and Incus

The runtime is chosen at first start and defaults to Docker. To use containerd instead:

```bash
colima start --runtime containerd
nerdctl run hello-world
nerdctl ps
```

The README recommends running colima nerdctl install to place a nerdctl alias script in $PATH. Note the command form: colima nerdctl is the documented way to reach containerd through Colima's own wrapper, while the alias makes plain nerdctl work.

Kubernetes is a flag rather than a runtime. It requires kubectl, installable with brew install kubectl:

```bash
colima start --kubernetes
kubectl run caddy --image=caddy
kubectl get pods
```

Incus, which requires v0.7.0, handles both containers and virtual machines. The client is installable with brew install incus:

```bash
colima start --runtime incus
incus launch images:alpine/edge
incus list
```

One constraint is stated outright: running virtual machines on Incus is only supported on m3 or newer Apple Silicon devices. If you are on an older Mac, Incus containers may work but Incus VMs will not, and that is a hardware boundary rather than a configuration problem.

Resource changes follow a stop-then-start pattern. The README's own example modifies an existing VM to 4 CPUs and 8 GiB:

```bash
colima stop
colima start --cpu 4 --memory 8
```

## Where Colima is the wrong choice

Colima is a CLI, and that is a limitation as much as a design decision. Docker Desktop ships a graphical interface for browsing images and containers, an extensions system, and its own Kubernetes distribution. None of that exists here. If your team relies on the GUI or on extensions, Colima is a downgrade in ergonomics, not a lateral move.

Windows is not covered. The README describes support for Intel and Apple Silicon macOS, and Linux. The topics list includes macos and the feature list says Linux, but nothing in the repository documentation describes a Windows VM backend. Users searching for a Windows install path will not find one documented here.

Resource defaults are modest. A 2 CPU, 2 GiB VM is fine for a few containers and tight for a full local stack with a database, a message broker and a build. You can raise the limits, but every change means stopping and starting the VM, so the cost is a restart cycle rather than a live resize.

The AI workload path has hard prerequisites that are easy to miss: v0.10.0 or later, Apple Silicon, macOS 13 or newer, and krunkit installed separately by following its own installation instructions. On an Intel Mac that feature is simply unavailable.

Finally, the README does not document rollback or downgrade behaviour. If an upgrade to a newer Colima changes how a VM is configured, there is no described way to return to the previous state. Treat that as an unknown to test in a scratch instance rather than an assumption.

## Colima against OrbStack and Podman Desktop

The comparison people actually search for is Colima versus OrbStack. The difference in approach is architectural. OrbStack is a commercial product built around its own lightweight virtualisation layer, with a GUI and a tighter integration story. Colima is MIT-licensed and builds on Lima, an open source VM manager, exposing the result through a CLI. If you want a polished desktop application, that is a different product category. If you want a scriptable tool with no licence key and no GUI, Colima is the closer fit.

Against Podman, the split is about what runs inside the VM. Podman is a daemonless container engine with its own CLI and its own Compose implementation. Colima is a VM manager that installs a runtime for you, and one of those runtimes is Docker, so docker and docker compose keep working against the same commands your CI already uses. The README's runtime list is the point: Docker, containerd, Incus and Kubernetes behind one start flag. Podman is one engine with one CLI; Colima is a host for several.

The honest trade-off is that Colima inherits Lima's model. Everything runs inside a Linux VM, so filesystem performance across the mount boundary is a VM property, not something Colima optimises away. The README lists volume mounts as a feature but says nothing about mount performance characteristics.

## Licence, maintenance and upgrade cost

Colima is MIT licensed. That is permissive: you can use it commercially, modify it and redistribute it, provided the licence text and copyright notice are preserved. The repository also carries a SECURITY.md and a CONTRIBUTE.md, and the README points to GitHub Discussions, GitHub Issues and a #colima channel in the CNCF Slack for community support. None of this is legal advice; if your organisation has licence review requirements, run the MIT text past whoever handles that.

Maintenance looks current. The last push to the default branch was on 2026-08-31, and the most recent tagged release is v0.10.3 from 2026-06-04. The repository is not archived. The release cadence shows v0.10.1 in February 2026, then v0.10.2 and v0.10.3 in June 2026, so patches arrive in small batches rather than on a fixed schedule.

Upgrade cost is mostly the VM lifecycle. Colima manages a Lima VM and a daemon, so upgrading the binary can mean recreating or reconfiguring the VM depending on what changed between versions. The README does not document a migration path between releases. If your VM holds images you cannot easily rebuild, that is the risk to plan around, and the mitigation is to keep image definitions in files rather than in the VM's local state.

Homebrew users can check what they have and what is available with brew info colima before upgrading.

## Conclusion

Adopt Colima if you want a Docker-compatible CLI on macOS without Docker Desktop's licensing and background services, or if you want to switch between Docker, containerd, Incus and Kubernetes in one tool. Skip it if you need a native Windows runtime (the documentation covers macOS and Linux only), or if you depend on Docker Desktop's GUI, extensions or its own Kubernetes distribution. Before committing, verify three things: that your Docker client is installed separately, that you can live with the default 2 CPU / 2 GiB / 100 GiB VM or have planned the --cpu, --memory and --disk flags, and that any workflow depending on Compose behaves under whichever runtime you pick, since the README does not document Compose behaviour per runtime.

## FAQ

### Is Colima a Docker engine?

Colima is not an engine itself. It creates a Lima virtual machine and installs a runtime inside it, and Docker is the default runtime. The README states that after colima start the docker client on macOS works with no additional setup.

### How do I use Colima instead of Docker Desktop?

Install Colima and the Docker client separately (brew install colima, then brew install docker), run colima start, and the docker CLI works against the Colima VM. The README gives docker run hello-world and docker ps as the first commands to confirm it.

### How do I install Colima on a Mac?

The README lists Homebrew, MacPorts, Nix and Mise. The Homebrew command is brew install colima, and brew install --HEAD colima gets the development build if you want it.

### How do I use Colima with Docker?

Run colima start with the default Docker runtime, then use the docker client as normal. The README notes that the Docker client is required and is installable with brew install docker.

### Does Colima support Kubernetes?

Yes, by starting with the --kubernetes flag, which requires kubectl. The README notes that with the Docker runtime, images built or pulled with Docker are visible to Kubernetes, while with containerd only images in the k8s.io namespace are.

### Can I run Colima on Windows?

The README describes support for Intel and Apple Silicon macOS, and Linux. It does not document a Windows installation path.

## Sources

- [abiosoft/colima on GitHub](https://github.com/abiosoft/colima)
- [License: MIT](https://github.com/abiosoft/colima/blob/main/LICENSE)
- [Project website](https://colima.run)
- [README](https://github.com/abiosoft/colima/blob/main/README.md)
- [Releases](https://github.com/abiosoft/colima/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/abiosoft-colima