Getting Started with Colima

📚 3 min read Tweet this post

Colima is a new container platform that aims to simplify the container experience for developers. Built on top of Docker Compose, Colima is designed to be a lightweight and user-friendly alternative to Docker. In this article, we will walk through how to get started with Colima on macOS and Linux.


Before we start, make sure that you have the following:

  • A macOS or Linux machine
  • Homebrew (for macOS) or APT package manager (for Linux)
  • Basic knowledge of Docker and Docker Compose

Step 1: Install Colima

To install Colima on macOS, run the following command in your terminal:

brew install colima

For Linux, run the following commands:

echo "deb [trusted=yes] /" | sudo tee /etc/apt/sources.list.d/colima.list
sudo apt-get update
sudo apt-get install colima

Step 2: Initialize Colima

Once Colima is installed, you need to initialize it. To do this, run the following command in your terminal:

colima init

This will create a new directory called .colima in your home directory, which contains the configuration files and other settings for Colima.

Step 3: Start Colima

To start Colima, run the following command in your terminal:

colima start

This will start the Colima daemon, which runs in the background and manages your containers.

Step 4: Test Colima

To test that Colima is working correctly, run the following command:

colima run hello-world

This will pull the official hello-world Docker image and run it inside a Colima container.

Step 5: Run Docker Compose with Colima

Since Colima is built on top of Docker Compose, you can use Docker Compose to manage your containers with Colima. To do this, create a new docker-compose.yml file in your project directory and add your container configuration. For example:

version: '3'
    image: nginx
      - "8080:80"

Then, run the following command to start the containers:

colima compose up

This will start the containers defined in your docker-compose.yml file, using Colima as the container platform.

When Colima is initially started, it uses a user-specified runtime, which defaults to Docker. However, Colima also supports Containerd and Kubernetes as alternative runtimes.

To use Docker as a runtime, the Docker client must be installed. On macOS, the client can be installed using the following command:

brew install docker

After starting Colima, the Docker client can be used with no additional setup.

To use Containerd as a runtime, start Colima with the --runtime containerd flag. This will initiate and set up Containerd. You can then use colima nerdctl to interact with Containerd using nerdctl.

It is recommended to run colima nerdctl install to install the nerdctl alias script in $PATH.

To use Kubernetes as a runtime, kubectl must be installed. On macOS, kubectl can be installed using the following command:

brew install kubectl

To enable Kubernetes, start Colima with the --kubernetes flag:

colima start --kubernetes

For Docker runtime, images built or pulled with Docker are accessible to Kubernetes. For Containerd runtime, images built or pulled in the namespace are accessible to Kubernetes.

The default VM created by Colima has 2 CPUs, 2GiB memory and 60GiB storage.

The VM can be customized either by passing additional flags to colima start. e.g. —cpu, —memory, —disk, —runtime. Or by editing the config file with colima start —edit.

  • create VM with 2CPU, 4GiB memory and 10GiB storage.
colima start --cpu 2 --memory 4 --disk 10
  • modify an existing VM to 4CPUs and 8GiB memory.
colima stop
colima start --cpu 4 --memory 8
  • create VM with Rosetta 2 emulation. Requires v0.5.3 and MacOS >= 13 (Ventura)
colima start --arch aarch64 --vm-type=vz --vz-rosetta

Colima is a promising alternative to Docker for macOS and Linux users who want a lightweight and easy-to-use container platform. With its simplified user interface and compatibility with Docker Compose, Colima provides developers with a familiar development experience while also providing the benefits of a simplified user interface. By following the steps outlined in this article, you can quickly get started with Colima and start managing your containers with ease.