colima README

The project's README from github.com/abiosoft/colima. As one markdown file: README.md.

colima-logo

Colima - container runtimes on macOS (and Linux) with minimal setup.

Go Integration Integration Go Report Card

Demonstration

Website & Documentation: colima.run | colima.run/docs

Features

Support for Intel and Apple Silicon macOS, and Linux

Getting Started

Installation

Colima is available on Homebrew, MacPorts, Nix and Mise. Check here for other installation options.

# Homebrew
brew install colima

# MacPorts
sudo port install colima

# Nix
nix-env -iA nixpkgs.colima

# Mise
mise use -g colima@latest

Or stay on the bleeding edge (only Homebrew)

brew install --HEAD colima

Usage

Start Colima with defaults

colima start

For more usage options

colima --help
colima start --help

Or use a config file

colima start --edit

Runtimes

On initial startup, Colima initiates with a user specified runtime that defaults to Docker.

Docker

Docker client is required for Docker runtime. Installable with brew install docker.

colima start
docker run hello-world
docker ps

You can use the docker client on macOS after colima start with no additional setup.

Containerd

colima start --runtime containerd starts and setup Containerd. You can use colima nerdctl to interact with Containerd using nerdctl.

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

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

Kubernetes

kubectl is required for Kubernetes. Installable with brew install kubectl.

To enable Kubernetes, start Colima with --kubernetes flag.

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

Interacting with Image Registry

For Docker runtime, images built or pulled with Docker are accessible to Kubernetes.

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

Incus

Requires v0.7.0

Incus client is required for Incus runtime. Installable with brew brew install incus.

colima start --runtime incus starts and setup Incus.

colima start --runtime incus
incus launch images:alpine/edge
incus list

You can use the incus client on macOS after colima start with no additional setup.

Note: Running virtual machines on Incus is only supported on m3 or newer Apple Silicon devices.

AI Models (GPU Accelerated)

Requires v0.10.0, Apple Silicon and macOS 13+

Colima supports GPU accelerated containers for AI workloads using the krunkit VM type.

Note: To use krunkit with colima, ensure it is installed. Please follow their installation instructions

Setup and use a model.

colima start --runtime docker --vm-type krunkit
colima model run gemma3

Colima supports two model runner backends:

The default registry is the Docker AI Registry. Models can be run by name without a prefix:

colima model run gemma3
colima model run llama3.2
# HuggingFace (Docker Model Runner)
colima model run hf.co/microsoft/Phi-3-mini-4k-instruct-gguf
# Ollama (requires ramalama runner)
colima model run ollama://gemma3 --runner ramalama

See the AI Workloads documentation for more details.

Customizing the VM

The default VM created by Colima has 2 CPUs, 2GiB memory and 100GiB 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.

NOTE: Disk size can be increased after the VM is created.

Customization Examples

Project Goal

To provide container runtimes on macOS with minimal setup.

What is with the name?

Colima means Containers on Lima.

Since Lima is aka Linux Machines. By transitivity, Colima can also mean Containers on Linux Machines.

The logo was contributed by Daniel Hodvogner. Check this issue for more.

Troubleshooting and FAQs

Check here for Frequently Asked Questions, or visit the online FAQ for a searchable version.

How to Contribute?

Check here for the instructions on contributing to the project.

Community

License

MIT

Sponsoring the Project

If you (or your company) are benefiting from the project and would like to support the contributors, kindly sponsor.

colima (abiosoft/colima)

containerd
Searching Database…

31.3K ·GitHub
Colima
What is this?Colima provides container runtimes on macOS (and Linux) with minimal setup: it starts a Linux VM running Docker, Containerd or Incus, all managed through one simple command.
Is there a GUI, or how do I work with it?It is a command-line tool: colima start boots a Linux VM with your chosen runtime inside. You manage everything with the colima command, which also gives you automatic port forwarding, volume mounts and multiple instances.
How do I get it running?Install with Homebrew, MacPorts, Nix or Mise (e.g. brew install colima), then run colima start. The first start uses the Docker runtime by default.
Do I need to install Docker or other clients separately?Clients are not bundled: the Docker runtime needs a Docker client (brew install docker), Kubernetes needs kubectl, Incus needs the incus client. Once the matching runtime is started, the client works with no additional setup.
Are there hardware requirements for the fancier features?Incus virtual machines only run on M3 or newer Apple Silicon devices. Other extras like Rosetta 2 emulation also need macOS 13 (Ventura) or newer on Apple Silicon.
Does it only work on Apple Silicon Macs?No - Colima supports both Intel and Apple Silicon Macs, and it runs on Linux as well.
Can containers use the Mac's GPU for AI workloads?Yes, from v0.10.0 on Apple Silicon with macOS 13+, via the krunkit VM type. Two model runner backends are supported: Docker Model Runner (default, Docker AI Registry and HuggingFace) and Ramalama (HuggingFace and Ollama registries).
Can I run Kubernetes with it?Yes - start Colima with 'colima start --kubernetes' (kubectl required, installable with brew install kubectl). Images built or pulled with Docker are accessible to Kubernetes automatically; with Containerd, images in the k8s.io namespace are.
How much CPU and memory does the VM get by default?The default VM has 2 CPUs, 2GiB memory and 100GiB storage. Change it with --cpu, --memory and --disk flags or by editing the config with 'colima start --edit'; disk size can be increased after creation.
Why is it called Colima?Colima means Containers on Lima, and Lima is aka Linux Machines. By transitivity, it can also be read as Containers on Linux Machines.
What are similar projects?lima, containerd, xpipe, vcluster, k9s, tilt, nerdctl, minikube
Which topics is it in?containerd, k8s, runtime, virtualization, containers, homebrew, local-llm, apple-silicon, kubernetes, docker-compose, devops, go
Creator
abiosoft
Size
3.2 MB
Stars
31.3K
Updated
CommitOct 02Releasev0.10.3Jun 04
Age
5y
Commits · 90 Days