How to use docker engine without Docker Desktop on macOS with Colima

In August 2021, Docker announced that they would change their licensing model and that Docker Desktop would no longer be free for commercial use. This made a lot of companies and developers look for alternatives to run docker containers on their Mac machines. That's because, if you are like me and a lot of other professional developers, your are probably coding for a company with a MacBook or another macOs machine, and you only use docker for development purposes, like say, have a local database instance for development. Probably, you don't even use the Docker Desktop GUI nor any of its "fancy" features, and you only interact with the docker engine from the command line. Ah, those good old fashioned docker and docker-compose commands.

Good news are, docker engine is licensed under Apache license, so you can use it for free, even for commercial purposes. There is not need to migrate to another container solution.

So okay, let's get rid of Docker Desktop and continue using docker from the CLI then. At the end of the day, Docker Desktop is just a GUI for the docker engine, and you don't need it, right? Well, not so fast.

The thing is, Docker containers are a linux native technology. You cannot have docker containers, or any other kind of containers, outside of Linux. So, in order to run docker on macOS (or even Windows), you need to have a Linux virtual machine running on your Mac. And that's exactly what Docker Desktop does. And that's why it's so heavy on your machine. It configures and run a full Linux virtual machine for you, out of the box, to use docker on it.

Hopefully, there are other alternatives to run docker on macOS without needed Docker Desktop. We just need a way to run and integrate a Linux VM with docker in the Mac, and one way is to use Colima, a container runtime for macOS that provides a backend for docker using qemu. It's build on top of Lima, that is like WSL2 in Windows, but for macOS: a lightweight virtual machine that runs a Linux distribution.

In this article, I'll show you how to use docker on macOS using Colima. It's very easy to install and use, and it's free and open source. Let's get started.

Step by step guide to run docker engine on macOS with Colima

First what is first, get rid of Docker Desktop! You can uninstall it like any other app in macOS, just drag it to the trash bin. But I recommend you to first clean the installation from Docker Desktop itself, as we already saw it does a lot of things under the hook for you (set ups the linux VM, links docker, etc). It's better to ensure that everything is clean before installing Colima. To do so, open Docker Desktop and go to the Troubleshoot menu (the one with the bug in the upper right corner), and click on the "Uninstall" button. This will remove all the data and configuration files that Docker Desktop created on your machine.

Then, move the Docker Desktop app to the trash bin if required (the Desktop app will probably ask you to do so).

Next, let's move to the installation of Colima. You can install it using Homebrew, the package manager for macOS. Just run the following command in your terminal. Note that installing docker engine is necessary, as you deleted it when you uninstalled Docker Desktop.

brew install docker-credential-helper docker colima

Now, let's create the linux virtual machine that will run the docker engine.

colima start

This will create a new VM with the default config (2 CPUs, 2GiB RAM, 60GiB disk), but you can customize it to your needs. You can check colima start --help for more information. For example, if you want to use 4 CPUs, 4GiB RAM and 100GiB disk, you can run the following command:

colima start -c 4 -m 4 -d 100

Now, if you do docker ps, you will see that the docker engine is running as before!

Using docker-compose

If you use docker-compose or the compose command in docker, we need to install it separately and link it as a CLI addon for docker. To do so, run the following command:

brew install docker-compose
mkdir -p ~/.docker/cli-plugins
ln -sfn /opt/homebrew/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

Autostart on login

If you want to start the VM automatically when you login to your Mac, you can do so by running the following command:

brew services start colima

Troubleshooting

Colima works with docker out of the box, and this is because it uses docker contexts to correctly set the docker daemon for you. However, some docker applications doesn't honor the docker contexts, and instead, relies on a hardcoded path for the usual location of the docker daemon.

If after having the above steps you get the following error when running docker commands:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

You probably need to set the DOCKER_HOST environment variable to the correct value, like this:

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

Or you can instead link the Colima socket to the default socket path, but note that this may break other Docker servers

sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock

If you have other problems, take a look at their docs in their repo. I hope not! I didn't have any problem at all.