I have never really loved Docker Desktop for Mac.

It seems to want to download and install huge updates every other day, each offering little user-facing benefit, comes with a clunky management UI I never use,¹ and requires you to accept an onerous license agreement.

So why use it? To run containers, of course! And although there are several container runtime interfaces, Docker is particularly common. Whether you’re a sole developer or working as part of a team, chances are it’s Docker you’ll reach for first. Docker Desktop for Mac is an easy way to get access to all the components needed to start working with containers.

Containers are a feature of the Linux kernel, and so a lot of what Docker Desktop for Mac does is managing a Linux virtual machine for you using macOS’s virtualisation framework. Your containers will run within that VM.

Lima is a tool to run and manage Linux virtual machines on macOS. Colima builds on top of Lima to provide simple access to container runtimes, including Docker. It runs a Docker-compatible process inside the Linux VM (a ‘Docker daemon’) allowing us to use all the docker CLI commands we’re familiar with, including Docker Compose, without needing to install Docker Desktop for Mac.

Installation

If you use Nix and/or home-manager you can easily try out Colima in a subshell:

$ nix shell nixpkgs#colima nixpkgs#docker nixpkgs#kubectl

Or you can include the packages in your home-manager configuration to make them always available:

{ config, pkgs, ... }:

{
  home = {
    packages = with pkgs; [
      colima
      docker
      kubectl
    ];
  };
}

If you use Homebrew you can install Colima in a similar way.

$ brew install colima docker kubectl

Note that Colima provides a Docker-compatible runtime but does not ship with the docker or kubectl CLIs, so we must install those separately.

Usage

All that’s required to get going is to tell Colima to start the Linux VM.

$ colima start
INFO[0000] starting colima
INFO[0000] runtime: docker
INFO[0000] preparing network ...                         context=vm
INFO[0000] starting ...                                  context=vm
INFO[0021] provisioning ...                              context=docker
INFO[0022] starting ...                                  context=docker
INFO[0027] done

This will download the VM’s base image and boot it. Once the machine is running Colima will start a Docker daemon inside of it and advertise a socket on the host (macOS) to the Docker CLI.

We can verify that docker can see Colima’s daemon by using the context command.²

$ docker context list
NAME       DESCRIPTION                               DOCKER ENDPOINT                                      KUBERNETES ENDPOINT                ORCHESTRATOR
colima *   colima                                    unix:///Users/username/.colima/default/docker.sock
default    Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                          https://127.0.0.1:6443 (default)   swarm

As promised, we can now use the docker commands we’re familiar with.

$ docker run --rm grycap/cowsay /usr/games/cowsay 'Hello, Colima!'
 ________________
< Hello, Colima! >
 ----------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Colima even includes supports for running a local Kubernetes cluster!

$ colima kubernetes start
INFO[0000] installing ...                                context=kubernetes
INFO[0005] loading oci images ...                        context=kubernetes
INFO[0010] updating config ...                           context=kubernetes
INFO[0010] Switched to context "colima".                 context=kubernetes

As Colima will add the necessary connection details to our $HOME/.kube/config file, we can immediately interact with the cluster using kubectl as usual.

$ kubectl config get-contexts
CURRENT   NAME     CLUSTER   AUTHINFO   NAMESPACE
*         colima   colima    colima

$ kubectl get all --output wide
NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE   SELECTOR
service/kubernetes   ClusterIP   10.43.0.1    <none>        443/TCP   52s   <none>

To stop the cluster or base VM, use the corresponding stop commands.

$ colima kubernetes stop

$ colima stop
INFO[0000] stopping colima
INFO[0000] stopping ...                                  context=docker
INFO[0002] stopping ...                                  context=vm
INFO[0005] done

More advanced usage is given in the README and FAQ, including details of the VM configuration stored under $HOME/.colima/default/colima.yaml.

I’ve found Colima to be a complete, pain-free replacement for my usage of Docker Desktop for Mac.

Footnotes

1. I will admit to being a particularly terminal-happy developer but the docker CLI is well structured and prints pretty output. The Docker Desktop UI is just a wrapper around a subset of the CLI’s feature set. ↩

2. The CLI’s context support allows Colima to run alongside Docker Desktop for Mac, if desired. You just need to select which context the CLI by default with docker context use. ↩