Skip to content
Get packs

Guide · Open source

How to use Colima: install, start Docker and run containers on macOS

Updated · written with AI from the project's own documentation and checked against our catalogue data

Colima is a command-line tool that starts a lightweight Linux virtual machine on your Mac and runs a container runtime inside it, such as Docker or containerd. This guide is for developers who want containers on macOS without installing a full desktop application. By the end you will be able to install Colima, start it, run a container and adjust the virtual machine's resources.

Colimaabiosoft/colima · ★ 31.5k · MIT

Quick start

  1. 1Install Colima. Run brew install colima using Homebrew, or use MacPorts, Nix or Mise as listed in the README.
  2. 2Start the default environment. Run colima start to launch the Linux virtual machine with the Docker runtime.
  3. 3Test Docker. Run docker run hello-world to confirm containers work. Install the Docker client with brew install docker if it is missing.
  4. 4Adjust resources if needed. Use --cpu, --memory and --disk flags, or colima start --edit, to change the VM settings.
  5. 5Enable Kubernetes if needed. Install kubectl, then start with colima start --kubernetes.
  6. 6Stop when finished. Run colima stop to shut down the virtual machine.

Install Colima on macOS

Colima is available through several package managers: Homebrew, MacPorts, Nix and Mise. The project's README shows Homebrew as the main route.

You will also need a Docker client if you want the Docker runtime, which you can install with brew install docker. For Kubernetes, install kubectl with brew install kubectl.

  • Homebrew: brew install colima
  • MacPorts, Nix and Mise are also listed in the README
  • Other installation options are documented in docs/INSTALL.md in the project repository
brew install colima

Start Colima with default settings

Run colima start to launch the virtual machine with defaults. On first startup, Colima uses a runtime that defaults to Docker.

Use colima --help and colima start --help to see the full list of options.

colima start

Run containers with the Docker runtime

After colima start, you can use the docker client on macOS with no additional setup. The README's example runs a test container and lists running containers.

colima start docker run hello-world docker ps

Use containerd or Incus instead of Docker

To start containerd, pass the runtime flag. You then interact with it through colima nerdctl, which uses nerdctl. The README recommends running colima nerdctl install to place an nerdctl alias script in your PATH.

Incus is also supported as a runtime, with the incus client installed by brew install incus. The README notes that running virtual machines on Incus requires an m3 or newer Apple Silicon device.

colima start --runtime containerd nerdctl run hello-world nerdctl ps

Run Kubernetes locally

Start Colima with the --kubernetes flag to enable Kubernetes. Docker and containerd both support optional Kubernetes. With the Docker runtime, images built or pulled with Docker are accessible to Kubernetes. With containerd, images must be in the k8s.io namespace.

colima start --kubernetes kubectl run caddy --image=caddy kubectl get pods

Customize the virtual machine

The default VM has 2 CPUs, 2GiB memory and 100GiB storage. You can change these with flags such as --cpu, --memory, --disk and --runtime, or by editing the config file with colima start --edit. The README notes that disk size can be increased after the VM is created.

To change an existing VM, stop it first, then start it with new values.

  • Create a small VM: colima start --cpu 1 --memory 2 --disk 10
  • Resize an existing VM: colima stop, then colima start --cpu 4 --memory 8
colima start --cpu 1 --memory 2 --disk 10 colima stop colima start --cpu 4 --memory 8

Try GPU-accelerated AI models on Apple Silicon

The README describes GPU-accelerated containers for AI workloads using the krunkit VM type. This requires Apple Silicon and macOS 13 or newer, and krunkit must be installed separately following its own instructions. The README also lists two model runner backends: Docker Model Runner (the default) and Ramalama.

  • Docker Model Runner supports the Docker AI Registry and HuggingFace
  • Ramalama supports HuggingFace and Ollama registries
  • See the AI Workloads documentation at colima.run/docs/ai/
colima start --runtime docker --vm-type krunkit colima model run gemma3

What people use it for

  • Running Docker containers on a Mac without installing Docker Desktop
  • Starting a local Kubernetes environment with kubectl for testing deployments
  • Using containerd with nerdctl for container work
  • Running Incus containers from the command line
  • Experimenting with local AI models on Apple Silicon Macs using krunkit

Frequently asked questions

Is Colima free to use?

Colima is open source under the MIT licence, as stated in the README. The project also lists sponsorship options for supporters who want to fund the contributors.

Does Colima work on Windows?

The README lists support for Intel and Apple Silicon macOS, and Linux only. It does not list Windows, so Windows users should look at other tools.

Do I need Docker Desktop to use Colima?

No. Colima runs the Docker runtime inside a Linux virtual machine, and you use the docker client on macOS after colima start with no additional setup. You still need to install the Docker client separately.

How do I install Colima?

Run brew install colima if you use Homebrew. The README also lists MacPorts, Nix and Mise as installation options.

Why does Colima need kubectl?

The README says kubectl is required for Kubernetes. Install it with brew install kubectl, then start Colima with the --kubernetes flag.

How does Colima compare to Docker Desktop, Rancher Desktop or Podman Desktop?

The project lists Docker Desktop, Rancher Desktop, Podman Desktop and Lima as comparable projects. Colima's stated goal is providing container runtimes on macOS with minimal setup, and it is driven from the command line.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Colima suits Mac developers who want Docker, containerd or optional Kubernetes from a single command without a desktop application. It is not for Windows users, and Intel Mac users should note that the krunkit GPU features are limited to Apple Silicon and macOS 13 or newer.

Install options & downloads