Use Colima to Run Docker Containers on macOS

Published March 29, 2022 and last verified on March 9, 2024

The official Docker for Mac application is subject to some licensing terms that may not work for some people or organizations, and some users have reported issues with forced updates that disrupt their workflows. If you need to run containers on your Mac, Colima is an open-source container runtime with minimal setup that works on MacOS and Linux.

In this tutorial you’ll install Colima and Docker’s command-line tools with Homebrew. Then you’ll manage your images and containers.

What You Need

To complete this tutorial, you’ll need Homebrew installed, which you can do by following the Install Homebrew tutorial.

Uninstalling Docker for Mac

Before moving forward, you’ll want to remove the existing Docker for Mac application if you have it running. Unfortunately, this process will remove all of your containers as well as your images. You’ll have to rebuild your local images and redownload any upstream images again.

To uninstall Docker for Mac, right-click on the Docker icon in your task bar, select Troubleshooting, and then select Uninstall. This process will warn you that it will remove all of your containers and images, and will then perform the uninstallation process. At the end, the Docker for Mac application will exit.

Once it’s completed, you can install Colima.

Installing Colima and Docker’s CLI with Homebrew

The fastest way to get Colima installed is through Homebrew.

brew install colima

Once Colima installs, install Docker and Docker Compose.

brew install docker docker-compose

Then configure docker-compose as a Docker plugin so you can use docker compose as a command instead of the legacy docker-compose script. First, create a folder in your home directory to hold Docker CLI plugins:

mkdir -p ~/.docker/cli-plugins

Then symlink the docker-compose command into that new folder:

ln -sfn $(brew --prefix)/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

Run docker compose:

docker compose

Ensure you see the help message similar to the following:

Usage:  docker compose [OPTIONS] COMMAND

Docker Compose

Options:
      --ansi string                Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto")
      --compatibility              Run compose in backward compatibility mode
      --env-file string            Specify an alternate environment file.

...
  version     Show the Docker Compose version information

Run 'docker compose COMMAND --help' for more information on a command.

You’ll also need Buildx to build some Docker containers. This is installed with Docker Engine on macOS, but you can install this with Homebrew:

brew install docker-Buildx

Once downloaded, symlink it to the cli-plugins folder:

ln -sfn $(brew --prefix)/opt/docker-buildx/bin/docker-buildx ~/.docker/cli-plugins/docker-buildx

With the commands installed, you can start Colima and work with containers

Using Colima to Run Images

The colima command is installed, but Colima itself is not running yet. Colima works by using a virtual machine to run containers, which is similar to how DOcker for Mac works. On the first run, Colima will download and configure a virtual machine to run the containers. This virtual machine has 2 CPUs, 2GiB memory and 60GiB storage, which should be enough for moderate use. You can change the memory size and number of virtual CPUs at any time.

Start Colima with the following command:

colima start

You’ll see the following output as Colima downloads the virtual machine:

INFO[0000] starting colima
INFO[0000] creating and starting ...                     context=vm
> msg="Terminal is not available, proceeding without opening an editor"
> msg="Attempting to download the image from \"https://github.com/abiosoft/alpine-lima/releases/download/colima-v0.3.4-1/alpine-lima-clm-3.14.3-x86_64.iso\"" \

Once it’s downloaded the virtual machine it’ll disconnect and reconnect and you’ll be ready to start using it:

INFO[0000] starting colima
INFO[0000] creating and starting ...                     context=vm
INFO[0041] provisioning ...                              context=docker
INFO[0041] restarting VM to complete setup ...           context=docker
INFO[0041] stopping ...                                  context=vm
INFO[0048] starting ...                                  context=vm
INFO[0068] starting ...                                  context=docker
INFO[0073] waiting for startup to complete ...           context=docker
INFO[0074] done

With Colima running, run Docker’s hello-world image, which is a quick way to verify that your Docker runtime works:

docker run hello-world

You’ll see the following output which shows that the hello-world image wasn’t found locally, so Docker needs to download it. It then runs and exits:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
2db29710123e: Pull complete
Digest: sha256:bfea6278a0a267fad2634554f4f0c6f31981eea41c553fdf5a83e95a41d40c38
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:

Use the docker ps -a command to see the stopped container:

docker ps -a

The container and image are displayed:

CONTAINER ID   IMAGE         COMMAND    CREATED         STATUS                     PORTS     NAMES
a8fb0e8a2e32   hello-world   "/hello"   2 minutes ago   Exited (0) 2 minutes ago             amazing_antonelli

Use docker rm to remove the container by using its name or container ID. In this case, the name is amazing_antonelli. Yours will be different:

docker rm amazing_antonelli

Now use docker images to view the images installed:

docker images

You’ll see the hello-world image listed:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    feb5d9fea6a5   6 months ago   13.3kB

Use the docker rmi command to remove the image using its image ID. Your image ID will be different:

docker rmi feb5d9fea6a5

Now that you can manage images, it’s time to build your own.

Building Your Own Image

You can run pre-built images on Colima, so the next step is to try to use Docker to build your own images. To test this out, you’ll create a Dockerfile and create your own container image that runs a custom HTML file inside of Nginx.

Create a new project folder called docker-test and switch to that folder:

mkdir docker-test && cd docker-test

Create a new folder to hold your HTML file:

mkdir html

Create a new HTML file in that folder.

cat <<EOF > html/index.html
<h1>Hi from Docker</h1>
EOF

Then create a new file called Dockerfile that uses the nginx:latest image and copies your HTML files into the /usr/share/nginx/html folder where Nginx looks for them:

cat <<EOF > Dockerfile
FROM nginx:latest
COPY ./html /usr/share/nginx/html
EOF

Build the image and call it docker-nginx-test:

docker build -t docker-nginx-test .

The image builds:

[+] Building 0.9s (7/7) FINISHED
 => [internal] load build definition from Dockerfile                                          0.0s
 => => transferring dockerfile: 94B                                                           0.0s
 ,,,
 => exporting to image                                                                        0.0s
 => => exporting layers                                                                       0.0s
 => => writing image sha256:04f227cdc8d163456a2b10fb4d91e56a4b158bae68b5232b431008a475c88c60  0.0s
 => => naming to docker.io/library/docker-nginx-test                                          0.0s

View the image:

docker images

You’ll see your new image in the list:

REPOSITORY          TAG       IMAGE ID       CREATED         SIZE
docker-nginx-test   latest    04f227cdc8d1   6 minutes ago   142MB

Run your image with terminal support and set it to destroy the container when you quit:

docker run --rm -t -p 3000:80 docker-nginx-test

Visit http://localhost:3000 in your browser and you’ll see the “Hello from Docker” message.

Back in your terminal, press CTRL+C to stop the container. The container stops and Docker removes the container.

Now that you know the basics are working, you can start using Colima with the rest of your Docker workflow. Before wrapping up, take a look at how to customize the virtual machine settings.

Customizing Colima’s Virtual Machine

You can control the memory, CPUs, and disk space the virtual machine uses, and you can specify whether or not Kubernetes is supported. You can change the CPUs and memory on an exiting machine by stopping the machine and starting it again with new options.

To use 4 CPUs and 4GiB of memory with your existing machine, stop the machine and restart it, passing the --cpu and --memory options:

colima stop

colima start --cpu 4 --memory 4

If you need more disk space, you have to create a new virtual machine. Unfortunately you can’t resize the virtual machine’s disk.

To create a VM with four CPUs, 4GB of memory, and 100GiB of disk space, start Colima with the following options:

colima start --cpu 4 --memory 4 --disk 100

Finally, if you need Kubernetes support, you can start the VM with the --with-kubernetes support. You’ll need kubectl installed, which you can do through Homebrew with brew install kubectl.

Review all of the available startup options with colima help start.

Conclusion

Colima provides a free and open container runtime you can use instead of the official Docker for Mac client. It’s lightweight, installs quickly, and has many of the same options the official client has, without some of the drawbacks.

Learn more on Colima’s GitHub page, or by exploring colima help.