Colima + Docker CLI Setup Guide (macOS)

This article introduces how to set up Colima + Docker CLI on macOS.

Background

When using Docker on macOS, many people use Docker Desktop. However, due to the Docker Desktop license change in 2021, companies with more than 250 employees or annual revenue exceeding $10 million now require a paid subscription.

This is where Colima comes in. With Colima, you can use Docker CLI without Docker Desktop.

What is Colima?

Colima is a lightweight container runtime for macOS (and Linux). The name stands for Container on Lima, and it’s built on Lima (Linux virtual machines).

Features

Open source (MIT license)
Lightweight - Works with minimal setup
Docker CLI compatible - Use your existing workflows as-is
Multi-architecture support - Works on both Intel Mac and Apple Silicon

Prerequisites

macOS (Intel Mac / Apple Silicon supported)
Homebrew installed
If Docker Desktop is installed, uninstall or stop it

Installation Steps

1. Install Colima

Install Colima using Homebrew.

brew install colima

2. Install Docker CLI

If you uninstalled Docker Desktop, Docker CLI may have been removed as well. Install Docker CLI separately.

brew install docker

3. Install Docker Compose (Optional)

If you want to use Docker Compose, install it as well.

brew install docker-compose

Starting Colima

Once installation is complete, start Colima.

colima start

The first startup takes some time as it downloads the virtual machine image.

Once startup is complete, you can use Docker CLI.

docker ps

If this runs without errors, setup is complete. Let’s verify by running the hello-world image.

docker run hello-world

If you see the “Hello from Docker!” message, everything is working correctly.

Basic Usage

Starting and Stopping Colima

# Start
colima start
 
# Stop
colima stop
 
# Restart
colima restart
 
# Check status
colima status

Resource Configuration

By default, Colima starts with 2 CPUs, 2GB memory, and 100GB disk. To change resources, specify options at startup.

# Start with 4 CPU cores, 8GB memory, 200GB disk
colima start --cpu 4 --memory 8 --disk 200

To change resources of an existing Colima instance, you need to delete and recreate it.

colima delete
colima start --cpu 4 --memory 8 --disk 200

x86_64 Emulation on Apple Silicon

To run x86_64 images on Apple Silicon Mac, you can use Rosetta 2 emulation.

colima start --arch x86_64

Alternatively, start with the default aarch64 and use Docker’s --platform option.

docker run --platform linux/amd64 your-image

Using Docker Compose

Docker Compose works without any issues.

# In the directory containing docker-compose.yml
docker compose up -d

Managing Multiple Environments

Colima supports multiple profiles, allowing you to switch environments based on your needs.

# Create development environment
colima start --profile dev --cpu 4 --memory 8
 
# Create test environment
colima start --profile test --cpu 2 --memory 4
 
# List profiles
colima list
 
# Stop a specific profile
colima stop --profile dev

Volume Mounts

You can mount macOS directories to Docker containers.

docker run -v ~/projects:/app alpine ls /app

To customize mount settings, edit the Colima configuration file.

colima start --edit

Troubleshooting

Docker CLI Cannot Connect

Check if Colima is running.

colima status

If it’s not running, start it with colima start.

Disk Space Exhausted

To expand Colima’s disk size, you need to delete and recreate it.

colima delete
colima start --disk 200

Checking Docker Context

If you’re using multiple Docker environments (e.g., Docker Desktop and Colima), verify that the context is set correctly.

docker context ls
docker context use colima

Comparison with Docker Desktop

Feature	Colima	Docker Desktop
License	MIT	Conditionally paid
GUI	None	Available
Extensions	None	Available

Since Colima doesn’t have a GUI, be aware if you depend on Docker Desktop’s GUI. However, if you use a Docker CLI-based development workflow, you’ll get nearly the same experience.

Summary

With Colima, you can use Docker CLI on macOS without Docker Desktop.

Easy installation with Homebrew - brew install colima docker
Easy to start - colima start
Docker CLI compatible - Migrate your existing workflows seamlessly

For those concerned about Docker Desktop licensing or seeking a lighter environment, Colima is a great choice.

That’s all about setting up Colima + Docker CLI from the Gemba.