FAQ

Frequently asked questions about Colima.

• General
  • How does Colima compare to Lima?
  • How does Colima compare to minikube, Kind, K3d?
    • For Kubernetes
    • For Docker
  • Are Apple Silicon Macs supported?
  • Are AI workloads supported?
  • Are older macOS versions supported?
• Configuration
  • Does Colima support autostart?
  • Can config files replace CLI flags?
  • Can I edit configurations?
  • How do I set the default config?
• Docker
  • Can Colima run alongside Docker for Mac?
  • Where is the Docker socket located?
  • How do I change Docker contexts?
  • Cannot connect to Docker daemon error?
  • How do I customize Docker configuration?
  • Docker buildx plugin is missing?
  • Docker bind mount showing empty?
• Containerd
  • How do I customize Containerd config?
    • Per-profile overrides
• Networking
  • The VM’s IP is unreachable?
  • Incus instances not reachable from host?
  • Colima cannot access internet?
• Storage
  • How can disk space be recovered?
  • How can disk size be increased?
• Maintenance
  • How can the VM and tools be updated?
    • Updating Colima
    • Updating the container runtime
    • Accessing the Virtual Machine
  • How can Docker version be updated?
  • How do I delete container data?
• Troubleshooting
  • Colima shows “Broken” status?
  • Fatal error on startup (exit status 1)?
  • Issues after upgrading?
  • Colima cannot access internet?
  • Docker Compose/Buildx showing runc errors?
  • Docker bind mount showing empty?
• Advanced
  • Is another distro supported?
  • Are Lima overrides supported?
    • Example: Adding provision scripts
  • Environment variables

General

How does Colima compare to Lima?

Colima is a higher level usage of Lima. It utilises Lima to provide Docker, Containerd, Kubernetes, and Incus runtimes with minimal configuration.

How does Colima compare to minikube, Kind, K3d?

For Kubernetes

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.

For Docker

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.

Are Apple Silicon Macs supported?

Yes, Colima works on both Intel and Apple Silicon Macs.

Are AI workloads supported?

Colima supports GPU-accelerated containers for AI workloads on Apple Silicon Macs running macOS 13 or newer. Launch with Docker runtime and krunkit VM type:

colima start --runtime docker --vm-type krunkit

Set up and run AI models:

colima model setup
colima model run gemma3

Multiple registries are supported including HuggingFace (default) and Ollama:

colima model run hf://tinyllama
colima model run ollama://tinyllama

Are older macOS versions supported?

Colima requires macOS 13 or newer. Building from source on older versions may be possible but requires Lima and QEMU dependencies.

Configuration

Does Colima support autostart?

Yes. Since v0.5.6, foreground mode is available via --foreground. For Homebrew installations, use:

brew services start colima

Can config files replace CLI flags?

Yes, YAML configuration is supported from v0.4.0 onward. Config files are located at $HOME/.colima/default/colima.yaml. For other profiles, $HOME/.colima/<profile-name>/colima.yaml.

Use $COLIMA_HOME environment variable to customize the location.

Can I edit configurations?

Run colima start --edit for interactive editing. Set the $EDITOR environment variable or use the --editor flag to specify your preferred editor:

colima start --edit --editor code  # one-off config
colima template --editor code      # default config

How do I set the default config?

Use the template command to set default configuration for new instances:

colima template

The template is stored at $HOME/.colima/_templates/default.yaml.

Docker

Can Colima run alongside Docker for Mac?

Yes, via Docker contexts since v0.3.0. Colima automatically becomes the default context at startup. You can switch contexts as needed.

Where is the Docker socket located?

• v0.3.4 or older: $HOME/.colima/docker.sock
• v0.4.0 or newer: $HOME/.colima/default/docker.sock

Use colima status to verify the socket path.

How do I change Docker contexts?

# List available contexts
docker context list

# Switch to a specific context
docker context use <context-name>

# Switch to Colima
docker context use colima

# Switch to default (Docker Desktop)
docker context use default

Cannot connect to Docker daemon error?

Try these approaches:

1. Configure application-specific socket paths in the application settings

2. Set DOCKER_HOST environment variable:

   export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"
   

3. Create a symlink to the default location:

   sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock
   

How do I customize Docker configuration?

Use colima start --edit and add settings under the docker section:

- docker: {}
+ docker:
+   insecure-registries:
+     - myregistry.com:5000
+     - host.docker.internal:5000

For registry mirrors, also add the mirrors to your host ~/.docker/daemon.json:

{
  "registry-mirrors": [
    "https://my.dockerhub.mirror.something"
  ]
}

Docker buildx plugin is missing?

Install via Homebrew and link the plugin:

brew install docker-buildx
mkdir -p ~/.docker/cli-plugins
ln -sfn $(brew --prefix)/opt/docker-buildx/bin/docker-buildx ~/.docker/cli-plugins/docker-buildx
docker buildx version  # verify installation

Alternatively, install a specific version manually:

ARCH=amd64  # change to 'arm64' for Apple Silicon
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 installation

Docker bind mount showing empty?

For volumes outside /Users/$USER, add mount entries to the configuration:

colima start --edit

Add your mount paths, then restart:

colima restart

Containerd

How do I customize Containerd config?

On first startup with the containerd runtime, Colima generates default config files at the standard user config locations:

These are shared across all Colima profiles. Modify the files and restart Colima for changes to take effect:

# edit the containerd config
$EDITOR ~/.config/containerd/config.toml

# restart colima
colima stop && colima start --runtime containerd

Note: $XDG_CONFIG_HOME is respected for the central config location if set.

Per-profile overrides

To 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:

1. ~/.colima/<profile>/containerd/<file> (per-profile override)
2. ~/.config/containerd/<file> or ~/.config/buildkit/<file> (central)
3. Embedded default

Networking

The VM’s IP is unreachable?

Enable network address with:

colima start --network-address

Note: This requires root privilege and increases startup time.

Incus instances not reachable from host?

Requires v0.10.0 or newer. Incus containers and VMs are not reachable from the host by default. Enable network address:

colima stop
colima start --network-address

Or edit the configuration:

colima start --edit

network:
-  address: false
+  address: true

Colima cannot access internet?

Try custom DNS servers:

colima start --dns 8.8.8.8 --dns 1.1.1.1

Verify connectivity:

colima ssh -- ping -c4 google.com

Storage

How can disk space be recovered?

• Automatic (v0.5.0+): Space is released automatically on startup
• Manual: Run colima ssh -- sudo fstrim -a

How can disk size be increased?

Edit the configuration to increase the disk value (available from v0.5.3+):

colima start --edit

Change the disk value and save. Changes apply automatically on next startup.

Maintenance

How can the VM and tools be updated?

Updating Colima

brew upgrade colima

After upgrading, delete and recreate the instance to use the latest VM image:

colima delete
colima start

To test the upgrade without affecting the existing setup, use a separate profile:

colima start debug

Updating the container runtime

From v0.7.6+, the container runtime (Docker, Containerd) can be updated independently:

colima update

This updates Docker (or Containerd) to the latest version without needing to update Colima itself.

Accessing the Virtual Machine

SSH into the VM to inspect or modify it directly:

colima ssh

Run a single command without an interactive session:

colima ssh -- uname -a

How can Docker version be updated?

From v0.7.6+, use the colima update command for runtime updates without a full Colima upgrade:

colima update

How do I delete container data?

From v0.9.0+:

# Delete instance but preserve container data
colima delete

# Delete instance and all container data
colima delete --data

When using soft delete, data is automatically restored on the next colima start for supported runtimes. See Data Persistence for details.

Troubleshooting

Colima shows “Broken” status?

This can happen after a macOS restart. Reset the state with:

colima stop --force
colima start

Fatal error on startup (exit status 1)?

Enable debug output to diagnose:

colima start --verbose

If the log output includes exiting, status={Running:false Degraded:false Exiting:true ...} it is most likely due to one of:

• Running on a device without virtualization support
• Running an x86_64 version of Homebrew (and Colima) on an Apple Silicon Mac

Issues after upgrading?

Test with a separate profile:

colima start debug

If successful, reset the default profile:

colima delete
colima start

Colima cannot access internet?

Failure to access the internet is usually down to DNS. Try custom DNS servers:

colima start --dns 8.8.8.8 --dns 1.1.1.1

Verify connectivity:

colima ssh -- ping -c4 google.com

Docker Compose/Buildx showing runc errors?

This was fixed in v0.6.0. If using v0.5.6 or lower, try the --cgroups-v2 flag as a workaround.

Docker bind mount showing empty?

When using Docker to bind mount a volume from the host where the volume is not contained within /Users/$USER, the container will start without errors but the mapped mountpoint will be empty.

This is resolved by mounting the volume on the VM first. Edit the configuration and add to the mounts section, then restart:

colima start --edit

colima restart

Advanced

Is another distro supported?

From v0.6.0 onward, Colima uses Ubuntu as the underlying image. Other distributions are not supported.

For v0.5.6 and earlier, an optional Ubuntu layer can be enabled:

colima start --layer=true

With layer enabled, colima ssh routes to the layer. Access the underlying VM with --layer=false.

Are Lima overrides supported?

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.

Example: Adding provision scripts

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 curl

Alternatively, 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 curl

Environment variables

Pass environment variables into the VM at startup:

colima start --env MY_VAR=value