- FAQs
- How does Colima compare to Lima?
- Are Apple Silicon Macs supported?
- Are AI workloads supported?
- Are older macOS versions supported?
- Does Colima support autostart?
- Can config file be used instead of cli flags?
- Docker
- Containerd
- How does Colima compare to minikube, Kind, K3d?
- Is another Distro supported?
- The Virtual Machine's IP is not reachable
- Incus instances are not reachable from the host
- How can disk space be recovered?
- How can disk size be increased?
- Are Lima overrides supported?
- How can the VM and its tools be updated?
- Troubleshooting
- How can Docker version be updated?
- How can I delete container data
Colima is basically a higher level usage of Lima and utilises Lima to provide Docker, Containerd and/or Kubernetes.
Colima supports and works on both Intel and Apple Silicon Macs.
Feedbacks would be appreciated.
Yes, Colima supports GPU accelerated containers for AI workloads on Apple Silicon Macs running macOS 13 or newer.
To get started, start Colima with Docker runtime and krunkit VM type:
colima start --runtime docker --vm-type krunkitThen setup and run AI models:
colima model setup
colima model run gemma3Multiple model registries are supported including HuggingFace (default) and Ollama:
colima model run hf://tinyllama
colima model run ollama://tinyllamaFor more options, run colima model --help.
Colima is supported and regularly tested on the latest macOS version. However, Colima requires macOS 13 or newer.
You may be able to build Colima and it's dependencies from source on older macOS version. Colima requires Lima and Qemu.
Since v0.5.6 Colima supports foreground mode via the --foreground flag. i.e. colima start --foreground.
If Colima has been installed using brew, the easiest way to autostart Colima is to use brew services.
brew services start colimaYes, from v0.4.0, Colima support YAML configuration file.
Set the $COLIMA_HOME environment variable, otherwise it defaults to $HOME/.colima.
colima start --edit
For manual edit, the config file is located at $HOME/.colima/default/colima.yaml.
For other profiles, $HOME/.colima/<profile-name>/colima.yaml
colima template
For manual edit, the template file is located at $HOME/.colima/_templates/default.yaml.
Set the $EDITOR environment variable or use the --editor flag.
colima start --edit --editor code # one-off config
colima template --editor code # default configYes, from version v0.3.0 Colima leverages Docker contexts and can thereby run alongside Docker for Mac.
Colima makes itself the default Docker context on startup and should work straight away.
Docker socket is located at $HOME/.colima/docker.sock
Docker socket is located at $HOME/.colima/default/docker.sock
It can also be retrieved by checking status
colima status
docker context list
docker context use <context-name>
Colima uses Docker contexts to allow co-existence with other Docker servers and sets itself as the default Docker context on startup.
However, some applications are not aware of Docker contexts and may lead to the error.
This can be fixed by any of the following approaches. Ensure the Docker socket path by checking the socket location.
-
Setting application specific Docker socket path if supported by the application. e.g. JetBrains IDEs.
-
Setting the
DOCKER_HOSTenvironment variable to point to Colima socket.export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"
-
Linking the Colima socket to the default socket path. Note that this may break other Docker servers.
sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock
-
v0.3.4 or lower
On first startup, Colima generates Docker daemon.json file at
$HOME/.colima/docker/daemon.json. Modify the daemon.json file accordingly and restart Colima. -
v0.4.0 or newer
Start Colima with
--editflag.colima start --edit
Add the Docker config to the
dockersection.- docker: {} + docker: + insecure-registries: + - myregistry.com:5000 + - host.docker.internal:5000
Note: In order for the Docker client to respect (at least some) configuration value changes, modification of the host ~/.docker/daemon.json file may also be required.
For example, if adding registry mirrors, modifications are needed as follows:
First, colima:
colima start --edit- docker: {}
+ docker:
+ registry-mirrors:
+ - https://my.dockerhub.mirror.something
+ - https://my.quayio.mirror.somethingAs an alternative approach to the colima start --edit, make the changes via the template command (affecting the configuration for any new instances):
colima templateThen, the Docker ~/.docker/daemon.json file (as compared to the default):
- "experimental": false,
+ "experimental": false,
+ "registry-mirrors": [
+ "https://my.dockerhub.mirror.something",
+ "https://my.quayio.mirror.something"
+ ]buildx can be installed as a Docker plugin
Using homebrew
brew install docker-buildx
# Follow the caveats mentioned in the install instructions:
# mkdir -p ~/.docker/cli-plugins
# ln -sfn $(which docker-buildx) ~/.docker/cli-plugins/docker-buildx
docker buildx version # verify installationAlternatively
ARCH=amd64 # change to 'arm64' for m1
VERSION=v0.11.2
curl -LO https://github.com/docker/buildx/releases/download/${VERSION}/buildx-${VERSION}.darwin-${ARCH}
mkdir -p ~/.docker/cli-plugins
mv buildx-${VERSION}.darwin-${ARCH} ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx
docker buildx version # verify installationOn first startup with the containerd runtime, Colima generates default config files at the standard user config locations:
| File | Location |
|---|---|
| Containerd config | ~/.config/containerd/config.toml |
| BuildKit config | ~/.config/buildkit/buildkitd.toml |
These follow the standard rootless containerd/buildkit config paths and are shared across all Colima profiles.
Modify the files accordingly and restart Colima for changes to take effect.
# edit the containerd config
$EDITOR ~/.config/containerd/config.toml
# restart colima
colima stop && colima start --runtime containerdTo use a different config for a specific profile, place the config file at $HOME/.colima/<profile-name>/containerd/config.toml (or buildkitd.toml). Per-profile configs take priority over the central config.
The resolution order is:
~/.colima/<profile>/containerd/<file>(per-profile override)~/.config/containerd/<file>or~/.config/buildkit/<file>(central)- Embedded default
Note: $XDG_CONFIG_HOME is respected for the central config location if set.
Yes, you can create a Kubernetes cluster with minikube (with Docker driver), Kind or K3d instead of enabling Kubernetes in Colima.
Those are better options if you need multiple clusters, or do not need Docker and Kubernetes to share the same images and runtime.
Colima with Docker runtime is fully compatible with Minikube (with Docker driver), Kind and K3d.
Minikube with Docker runtime can expose the cluster's Docker with minikube docker-env. But there are some caveats.
-
Kubernetes is not optional, even if you only need Docker.
-
All of minikube's free drivers for macOS fall-short in one of performance, port forwarding or volumes. While port-forwarding and volumes are non-issue for Kubernetes, they can be a deal breaker for Docker-only use.
Colima uses a lightweight Alpine image with bundled dependencies. Therefore, user interaction with the Virtual Machine is expected to be minimal (if any).
However, Colima optionally provides Ubuntu container as a layer.
-
CLI
colima start --layer=true -
Config
- layer: false + layer: true
When the layer is enabled, the underlying Virtual Machine is abstracted and both the ssh and ssh-config commands routes to the layer.
The underlying Virtual Machine is still accessible by specifying --layer=false to the ssh and ssh-config commands, or by running colima in the SSH session.
Colima uses Ubuntu as the underlying image. Other distros are not supported.
Reachable IP address is not enabled by default due to root privilege and slower startup time.
NOTE: this is only supported on macOS
- CLI
colima start --network-address - Config
network: - address: false + address: true
Requires v0.10.0
Incus containers and virtual machines are not reachable from the host by default. This is because network address is not enabled by default.
To fix this, stop Colima and restart with network address enabled:
colima stop
colima start --network-addressOr enable it in the config file:
colima start --editnetwork:
- address: false
+ address: trueDisk space can be freed in the VM by removing containers or running docker system prune.
However, it will not reflect on the host on Colima versions v0.4.x or lower.
For Colima v0.5.0 and above, unused disk space in the VM is released on startup. A restart would suffice.
For Colima v0.5.0 and above, user can manually recover the disk space by running sudo fstrim -a in the VM.
# '-v' may be added for verbose output
colima ssh -- sudo fstrim -aDisk size is automatically increased on start up based on configuration in colima.yaml
- disk: 150
+ disk: 250Note: This feature is available from Version 0.5.3.
Yes, however this should only be done by advanced users.
Lima supports override.yaml and default.yaml files that can modify the VM configuration.
The override file is located at $HOME/.colima/_lima/_config/override.yaml (or $LIMA_HOME/_config/override.yaml if LIMA_HOME is set).
Settings in override.yaml are applied before the instance config, while settings in default.yaml are applied after (as fallback defaults).
Note: Overriding the image is not supported as Colima's image includes bundled dependencies that would be missing in a user-specified image.
Provision scripts can be added via Lima overrides to run commands during VM boot.
# $HOME/.colima/_lima/_config/override.yaml
provision:
- mode: system
script: |
#!/bin/bash
set -eux -o pipefail
# install additional packages
apt-get update && apt-get install -y curlAlternatively, provision scripts can be specified directly in colima.yaml:
colima start --edit- provision: []
+ provision:
+ - mode: system
+ script: |
+ #!/bin/bash
+ set -eux -o pipefail
+ apt-get update && apt-get install -y curlbrew upgrade colimaAfter upgrading, delete and recreate the instance to use the latest VM image:
colima delete
colima startTo test the upgrade without affecting the existing setup, use a separate profile:
colima start debugFrom v0.7.6, the container runtime (Docker, containerd) can be updated independently:
colima updateThis updates Docker (or containerd) to the latest version without needing to update Colima itself.
SSH into the VM to inspect or modify it directly:
colima sshRun a single command without an interactive session:
colima ssh -- uname -a| Variable | Description |
|---|---|
COLIMA_HOME |
Colima configuration directory (default: $HOME/.colima) |
COLIMA_PROFILE |
Active profile name (default: default) |
DOCKER_CONFIG |
Path to Docker client configuration directory (default: ~/.docker) |
Pass environment variables into the VM at startup:
colima start --env MY_VAR=valueThese are some common issues reported by users and how to troubleshoot them.
There are multiple reasons that could cause Colima to fail to start.
This is the case when the output of colima list shows a broken status. This can happen due to macOS restart.
colima list
PROFILE STATUS ARCH CPUS MEMORY DISK RUNTIME ADDRESS
default Broken aarch64 2 2GiB 60GiB
This can be fixed by forcefully stopping Colima. The state will be changed to Stopped and it should start up normally afterwards.
colima stop --force
This indicates that a fatal error is preventing Colima from starting, you can enable the debug log with --verbose flag to get more info.
If the log output includes exiting, status={Running:false Degraded:false Exiting:true Errors:[] SSHLocalPort:0} then it is most certainly due to one of the following.
- Running on a device without virtualization support.
- Running an x86_64 version of homebrew (and Colima) on an M1 device.
The recommended way to troubleshoot after an upgrade is to test with a separate profile.
# start with a profile named 'debug'
colima start debugIf the separate profile starts successfully without issues, then the issue would be resolved by resetting the default profile.
colima delete
colima start
Failure for Colima to access the internet is usually down to DNS.
Try custom DNS server(s)
colima start --dns 8.8.8.8 --dns 1.1.1.1Ping an internet address from within the VM to ascertain
colima ssh -- ping -c4 google.com
PING google.com (216.58.223.238): 56 data bytes
64 bytes from 216.58.223.238: seq=0 ttl=42 time=0.082 ms
64 bytes from 216.58.223.238: seq=1 ttl=42 time=0.557 ms
64 bytes from 216.58.223.238: seq=2 ttl=42 time=0.465 ms
64 bytes from 216.58.223.238: seq=3 ttl=42 time=0.457 ms
--- google.com ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 0.082/0.390/0.557 ms
Recent versions of Buildkit may show the following error.
runc run failed: unable to start container process: error during container init: error mounting "cgroup" to rootfs at "/sys/fs/cgroup": mount cgroup:/sys/fs/cgroup/openrc (via /proc/self/fd/6), flags: 0xf, data: openrc: invalid argumentFrom v0.5.6, start Colima with --cgroups-v2 flag as a workaround.
This is fixed in v0.6.0.
When using docker to bind mount a volume (e.g. using -v or --mount) from the host where the volume is not contained within /Users/$USER, the container will start without raising any errors but the mapped mountpoint on the container will be empty.
This is rectified by mounting the volume on the VM, and only then can docker map the volume or any subdirectory. Edit $HOME/.colima/default/colima.yaml and add to the mounts section (examples are provided within the yaml file), and then run colima restart. Start the container again with the desired bind mount and it should show up correctly.
Each Colima release includes the latest Docker version at the time of release.
From v0.7.6, there is a new colima update command to update the container runtime without needing to update Colima or to wait for the next Colima release.
From v0.9.0, Colima utilises a different disk for the container runtime data. This guards against accidental data loss after deletion and the container data should be reinstated on colima start.
To clear all data, colima delete --data should be run instead. The --data flag ensures that the container data is also deleted.