## 1. Project Overview & Quickstart (abiosoft/colima)
## File: README.md
## Colima - container runtimes on macOS (and Linux) with minimal setup.
[](https://github.com/abiosoft/colima/actions/workflows/go.yml)
[](https://github.com/abiosoft/colima/actions/workflows/linux-integration.yml)
[](https://github.com/abiosoft/colima/actions/workflows/macos-integration.yml)
[](https://goreportcard.com/report/github.com/abiosoft/colima)
**Website & Documentation:** [colima.run](https://colima.run) | [colima.run/docs](https://colima.run/docs/)
## Features
Support for Intel and Apple Silicon macOS, and Linux
- Simple CLI interface with sensible defaults
- Automatic Port Forwarding
- Volume mounts
- Multiple instances
- Support for multiple container runtimes
- [Docker](https://docker.com) (with optional Kubernetes)
- [Containerd](https://containerd.io) (with optional Kubernetes)
- [Incus](https://linuxcontainers.org/incus) (containers and virtual machines)
- GPU accelerated containers for AI workloads
## Getting Started
### Installation
Colima is available on Homebrew, MacPorts, Nix and [Mise](http://github.com/jdx/mise). Check [here](docs/INSTALL.md) for other installation options.
```sh
# 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](https://github.com/containerd/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](https://github.com/containers/krunkit#installation)
Setup and use a model.
```
colima start --runtime docker --vm-type krunkit
colima model run gemma3
```
Colima supports two model runner backends:
- **Docker Model Runner** (default) — supports [Docker AI Registry](https://hub.docker.com/u/ai) and [HuggingFace](https://huggingface.co).
- **Ramalama** — supports [HuggingFace](https://huggingface.co) and [Ollama](https://ollama.com) registries.
The default registry is the Docker AI Registry. Models can be run by name without a prefix:
```sh
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](https://colima.run/docs/ai/) 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
- create VM with 1CPU, 2GiB memory and 10GiB storage.
```
colima start --cpu 1 --memory 2 --disk 10
```
- modify an existing VM to 4CPUs and 8GiB memory.
```
colima stop
colima start --cpu 4 --memory 8
```
- create VM with Rosetta 2 emulation. Requires v0.5.3 and macOS >= 13 (Ventura) on Apple Silicon.
```
colima start --vm-type=vz --vz-rosetta
```
## Project Goal
To provide container runtimes on macOS with minimal setup.
## What is with the name?
Colima means Containers on [Lima](https://github.com/lima-vm/lima).
Since Lima is aka Linux Machines. By transitivity, Colima can also mean Containers on Linux Machines.
## And the Logo?
The logo was contributed by [Daniel Hodvogner](https://github.com/dhodvogner). Check [this issue](https://github.com/abiosoft/colima/issues/781) for more.
## Troubleshooting and FAQs
Check [here](docs/FAQ.md) for Frequently Asked Questions, or visit the [online FAQ](https://colima.run/docs/faq/) for a searchable version.
## How to Contribute?
Check [here](docs/CONTRIBUTE.md) for the instructions on contributing to the project.
## Community
- [GitHub Discussions](https://github.com/abiosoft/colima/discussions)
- [GitHub Issues](https://github.com/abiosoft/colima/issues)
- [Announcements](https://colima.run/announcements/)
- `#colima` channel in the CNCF Slack
- New account:
- Login:
## License
MIT
## Sponsoring the Project
If you (or your company) are benefiting from the project and would like to support the contributors, kindly sponsor.
- [Github Sponsors](https://github.com/sponsors/abiosoft)
- [Buy me a coffee](https://www.buymeacoffee.com/abiosoft)
- [Patreon](https://patreon.com/colima)
---
[](https://macstadium.com)
---
## File: docs/FAQ.md
# FAQs
- [FAQs](#faqs)
- [How does Colima compare to Lima?](#how-does-colima-compare-to-lima)
- [Are Apple Silicon Macs supported?](#are-apple-silicon-macs-supported)
- [Are AI workloads supported?](#are-ai-workloads-supported)
- [Are older macOS versions supported?](#are-older-macos-versions-supported)
- [Does Colima support autostart?](#does-colima-support-autostart)
- [Can config file be used instead of cli flags?](#can-config-file-be-used-instead-of-cli-flags)
- [Specifying the config location](#specifying-the-config-location)
- [Editing the config](#editing-the-config)
- [Setting the default config](#setting-the-default-config)
- [Specifying the config editor](#specifying-the-config-editor)
- [How do I change where Colima files are stored?](#how-do-i-change-where-colima-files-are-stored)
- [How do I pass custom environment variables into the VM?](#how-do-i-pass-custom-environment-variables-into-the-vm)
- [Docker](#docker)
- [Can it run alongside Docker for Mac?](#can-it-run-alongside-docker-for-mac)
- [Docker socket location](#docker-socket-location)
- [v0.3.4 or older](#v034-or-older)
- [v0.4.0 or newer](#v040-or-newer)
- [Listing Docker contexts](#listing-docker-contexts)
- [Changing the active Docker context](#changing-the-active-docker-context)
- [Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?](#cannot-connect-to-the-docker-daemon-at-unixvarrundockersock-is-the-docker-daemon-running)
- [How to customize Docker config (e.g., adding insecure registries or registry mirrors)?](#how-to-customize-docker-config-eg-adding-insecure-registries-or-registry-mirrors)
- [Docker buildx plugin is missing](#docker-buildx-plugin-is-missing)
- [Installing Buildx](#installing-buildx)
- [Containerd](#containerd)
- [How to customize Containerd config?](#how-to-customize-containerd-config)
- [Per-profile overrides](#per-profile-overrides)
- [How does Colima compare to minikube, Kind, K3d?](#how-does-colima-compare-to-minikube-kind-k3d)
- [For Kubernetes](#for-kubernetes)
- [For Docker](#for-docker)
- [Is another Distro supported?](#is-another-distro-supported)
- [Version v0.5.6 and lower](#version-v056-and-lower)
- [Enabling Ubuntu layer](#enabling-ubuntu-layer)
- [Accessing the underlying Virtual Machine](#accessing-the-underlying-virtual-machine)
- [Version v0.6.0 and newer](#version-v060-and-newer)
- [The Virtual Machine's IP is not reachable](#the-virtual-machines-ip-is-not-reachable)
- [Enable reachable IP address](#enable-reachable-ip-address)
- [Incus instances are not reachable from the host](#incus-instances-are-not-reachable-from-the-host)
- [How can disk space be recovered?](#how-can-disk-space-be-recovered)
- [Automatic](#automatic)
- [Manual](#manual)
- [How can disk size be increased?](#how-can-disk-size-be-increased)
- [Are Lima overrides supported?](#are-lima-overrides-supported)
- [Example: Adding provision scripts](#example-adding-provision-scripts)
- [How can the VM and its tools be updated?](#how-can-the-vm-and-its-tools-be-updated)
- [Updating Colima](#updating-colima)
- [Updating the container runtime](#updating-the-container-runtime)
- [Accessing the Virtual Machine](#accessing-the-virtual-machine)
- [Troubleshooting](#troubleshooting)
- [Colima not starting](#colima-not-starting)
- [Broken status](#broken-status)
- [FATA\[0000\] error starting vm: error at 'starting': exit status 1](#fata0000-error-starting-vm-error-at-starting-exit-status-1)
- [Issues after an upgrade](#issues-after-an-upgrade)
- [Colima cannot access the internet.](#colima-cannot-access-the-internet)
- [Docker Compose and Buildx showing runc error](#docker-compose-and-buildx-showing-runc-error)
- [Version v0.5.6 or lower](#version-v056-or-lower)
- [Issue with Docker bind mount showing empty](#issue-with-docker-bind-mount-showing-empty)
- [Mount path with spaces is not supported](#mount-path-with-spaces-is-not-supported)
- [How can Docker version be updated?](#how-can-docker-version-be-updated)
- [How can I delete container data](#how-can-i-delete-container-data)
- [How do I use Colima with an AI coding assistant?](#how-do-i-use-colima-with-an-ai-coding-assistant)
## How does Colima compare to Lima?
Colima is basically a higher level usage of Lima and utilises Lima to provide Docker, Containerd and/or Kubernetes.
## Are Apple Silicon Macs supported?
Colima supports and works on both Intel and Apple Silicon Macs.
Feedbacks would be appreciated.
## Are AI workloads supported?
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:
```sh
colima start --runtime docker --vm-type krunkit
```
Then setup and run AI models:
```sh
colima model setup
colima model run gemma3
```
Multiple model registries are supported including HuggingFace (default) and Ollama:
```sh
colima model run hf://tinyllama
colima model run ollama://tinyllama
```
For more options, run `colima model --help`.
## Are older macOS versions supported?
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](https://github.com/lima-vm/lima) and [Qemu](https://www.qemu.org/).
## Does Colima support autostart?
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.
```sh
brew services start colima
```
## Can config file be used instead of cli flags?
Yes, from v0.4.0, Colima support YAML configuration file.
### Specifying the config location
Set the `$COLIMA_HOME` environment variable. When it is not set, the first match wins:
1. `$HOME/.colima`, if it exists
2. `$XDG_CONFIG_HOME/colima`, if the variable is set
3. `~/.config/colima`, if it exists (the XDG default when the variable is unset)
4. otherwise `$HOME/.colima` on macOS, and the user config directory on other platforms
### Editing the config
```
colima start --edit
```
For manual edit, the config file is located at `$HOME/.colima/default/colima.yaml`.
For other profiles, `$HOME/.colima//colima.yaml`
### Setting the default config
```
colima template
```
For manual edit, the template file is located at `$HOME/.colima/_templates/default.yaml`.
### Specifying the config editor
Set the `$EDITOR` environment variable or use the `--editor` flag.
```sh
colima start --edit --editor code # one-off config
colima template --editor code # default config
```
## How do I change where Colima files are stored?
Colima supports these environment variables, set on your host machine:
| Variable | Description |
|----------|-------------|
| `COLIMA_HOME` | Colima configuration directory (default: `$HOME/.colima`) |
| `COLIMA_CACHE_HOME` | Colima cache directory (default is host-specific, see [os.UserCacheDir()](https://pkg.go.dev/os#UserCacheDir)) |
| `COLIMA_PROFILE` | Active profile name (default: `default`) |
| `DOCKER_CONFIG` | Path to Docker client configuration directory (default: `~/.docker`) |
## How do I pass custom environment variables into the VM?
Pass environment variables into the VM at startup using the YAML configuration file:
```yaml
env:
MY_VAR: value
```
You can also use command-line flags:
```bash session
# On your host machine...
$ colima start --env MY_VAR=value
# Then, within the VM...
$ colima ssh
user@colima:~$ env | grep MY_VAR
MY_VAR=value
```
## Docker
### Can it run alongside Docker for Mac?
Yes, 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 location
#### v0.3.4 or older
Docker socket is located at `$HOME/.colima/docker.sock`
#### v0.4.0 or newer
Docker socket is located at `$HOME/.colima/default/docker.sock`
It can also be retrieved by checking status
```
colima status
```
#### Listing Docker contexts
```
docker context list
```
#### Changing the active Docker context
```
docker context use
```
### Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
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](#docker-socket-location).
1. Setting application specific Docker socket path if supported by the application. e.g. JetBrains IDEs.
2. Setting the `DOCKER_HOST` environment variable to point to Colima socket.
```sh
export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"
```
3. Linking the Colima socket to the default socket path. **Note** that this may break other Docker servers.
```sh
sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock
```
### How to customize Docker config (e.g., adding insecure registries or registry mirrors)?
* 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 `--edit` flag.
```sh
colima start --edit
```
Add the Docker config to the `docker` section.
```diff
- 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:
```sh
colima start --edit
```
```diff
- docker: {}
+ docker:
+ registry-mirrors:
+ - https://my.dockerhub.mirror.something
+ - https://my.quayio.mirror.something
```
Registry mirrors can also be set directly on start with the repeatable `--registry-mirror` flag, without editing the config:
```sh
colima start --registry-mirror https://my.dockerhub.mirror.something --registry-mirror https://my.quayio.mirror.something
```
As an alternative approach to the **colima start --edit**, make the changes via the **template** command (affecting the configuration for any new instances):
```sh
colima template
```
Then, the Docker ~/.docker/daemon.json file (as compared to the default):
```diff
- "experimental": false,
+ "experimental": false,
+ "registry-mirrors": [
+ "https://my.dockerhub.mirror.something",
+ "https://my.quayio.mirror.something"
+ ]
```
### Docker buildx plugin is missing
`buildx` can be installed as a Docker plugin
#### Installing Buildx
Using homebrew
```sh
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 installation
```
Alternatively
```sh
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 installation
```
## Containerd
### How to customize Containerd config?
On 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.
```sh
# edit the containerd config
$EDITOR ~/.config/containerd/config.toml
# restart colima
colima stop && colima start --runtime containerd
```
#### Per-profile overrides
To use a different config for a specific profile, place the config file at `$HOME/.colima//containerd/config.toml` (or `buildkitd.toml`). Per-profile configs take priority over the central config.
The resolution order is:
1. `~/.colima//containerd/` (per-profile override)
2. `~/.config/containerd/` or `~/.config/buildkit/` (central)
3. Embedded default
**Note:** `$XDG_CONFIG_HOME` is respected for the central config location if set.
## 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.
## Is another Distro supported?
### Version v0.5.6 and lower
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.
#### Enabling Ubuntu layer
* CLI
```
colima start --layer=true
```
* Config
```diff
- layer: false
+ layer: true
```
#### Accessing the underlying Virtual Machine
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.
### Version v0.6.0 and newer
Colima uses Ubuntu as the underlying image. Other distros are not supported.
## The Virtual Machine's IP is not reachable
Reachable IP address is not enabled by default due to root privilege and slower startup time.
### Enable reachable IP address
**NOTE:** this is only supported on macOS
* CLI
```
colima start --network-address
```
* Config
```diff
network:
- address: false
+ address: true
```
## Incus instances are not reachable from the host
**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:
```sh
colima stop
colima start --network-address
```
Or enable it in the config file:
```sh
colima start --edit
```
```diff
network:
- address: false
+ address: true
```
## How can disk space be recovered?
Disk 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.
### Automatic
For Colima v0.5.0 and above, unused disk space in the VM is released on startup. A restart would suffice.
### Manual
For Colima v0.5.0 and above, user can manually recover the disk space by running `sudo fstrim -a` in the VM.
```sh
# '-v' may be added for verbose output
colima ssh -- sudo fstrim -a
```
## How can disk size be increased?
Disk size is automatically increased on start up based on configuration in `colima.yaml`
```diff
- disk: 150
+ disk: 250
```
__Note:__ This feature is available from Version 0.5.3.
## 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.
```yaml
# $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`:
```sh
colima start --edit
```
```diff
- provision: []
+ provision:
+ - mode: system
+ script: |
+ #!/bin/bash
+ set -eux -o pipefail
+ apt-get update && apt-get install -y curl
```
## How can the VM and its tools be updated?
### Updating Colima
```sh
brew upgrade colima
```
After upgrading, delete and recreate the instance to use the latest VM image:
```sh
colima delete
colima start
```
To test the upgrade without affecting the existing setup, use a separate profile:
```sh
colima start debug
```
### Updating the container runtime
From v0.7.6, the container runtime (Docker, containerd) can be updated independently:
```sh
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:
```sh
colima ssh
```
Run a single command without an interactive session:
```sh
colima ssh -- uname -a
```
## Troubleshooting
These are some common issues reported by users and how to troubleshoot them.
### Colima not starting
There are multiple reasons that could cause Colima to fail to start.
#### Broken status
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
```
#### FATA[0000] error starting vm: error at 'starting': exit status 1
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.
1. Running on a device without virtualization support.
2. Running an x86_64 version of homebrew (and Colima) on an M1 device.
### Issues after an upgrade
The recommended way to troubleshoot after an upgrade is to test with a separate profile.
```sh
# start with a profile named 'debug'
colima start debug
```
If the separate profile starts successfully without issues, then the issue would be resolved by resetting the default profile.
```
colima delete
colima start
```
### Colima cannot access the internet.
Failure for Colima to access the internet is usually down to DNS.
Try custom DNS server(s)
```sh
colima start --dns 8.8.8.8 --dns 1.1.1.1
```
Ping 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
```
### Docker Compose and Buildx showing runc error
#### Version v0.5.6 or lower
Recent versions of Buildkit may show the following error.
```console
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 argument
```
From v0.5.6, start Colima with `--cgroups-v2` flag as a workaround.
**This is fixed in v0.6.0.**
### Issue with Docker bind mount showing empty
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.
### Mount path with spaces is not supported
Mount paths containing spaces (e.g. `/Volumes/External HD`) are not supported by the
underlying [Lima](https://github.com/lima-vm/lima) runtime and will fail to mount.
Colima now rejects such paths at startup with a clear error instead of failing silently.
As a workaround, mount a parent directory without spaces, or rename/alias the volume to
avoid spaces. See [#1471](https://github.com/abiosoft/colima/issues/1471).
## How can Docker version be updated?
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.
## How can I delete container data
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.
## How do I use Colima with an AI coding assistant?
The [`skills/`](../skills/) folder is an Agent Skill — Markdown that AI coding assistants (Claude Code, Cursor, Kimi Code, etc.) load on demand to give accurate, version-aware Colima guidance instead of generic Docker advice. Install it into your assistant's skills directory, e.g.:
```sh
cp -R skills ~/.claude/skills/colima
```
See [`skills/README.md`](../skills/README.md) for per-tool instructions and what each file covers.
---
## File: docs/INSTALL.md
# Installation Options
## Homebrew
Stable Version
```
brew install colima
```
Development Version
```
brew install --HEAD colima
```
## MacPorts
Stable version
```
sudo port install colima
```
## Nix
Only stable Version
```
nix-env -i colima
```
Or using solely in a `nix-shell`
```
nix-shell -p colima
```
## Arch
Install dependencies
```
sudo pacman -S qemu-full go docker
```
Install Lima and Colima from Aur
```
yay -S lima-bin colima-bin
```
## Binary
Binaries are available with every release on the [releases page](https://github.com/abiosoft/colima/releases).
```sh
# download binary
curl -LO https://github.com/abiosoft/colima/releases/latest/download/colima-$(uname)-$(uname -m)
# install in $PATH
sudo install colima-$(uname)-$(uname -m) /usr/local/bin/colima
```
## Building from Source
Requires [Go](https://golang.org).
```sh
# clone repo and cd into it
git clone https://github.com/abiosoft/colima
cd colima
make
sudo make install
```
## 2. Official Technical Reference & Guides (abiosoft/docs)
# .NET Docs
This repository contains the conceptual documentation for .NET. The [.NET documentation site](https://docs.microsoft.com/dotnet) is built from multiple repositories in addition to this one:
- [Code samples and snippets](https://github.com/dotnet/samples)
- [API reference](https://github.com/dotnet/dotnet-api-docs)
- [.NET Compiler Platform SDK reference](https://github.com/dotnet/roslyn-api-docs)
Issues and tasks for all three of those repositories are tracked here. We have a large community using these resources. We make our best effort to respond to issues in a timely fashion. You can read more about our procedures for classifying and resolving issues in our [Issues policy](issues-policy.md) topic.
We welcome contributions to help us improve and complete the .NET docs. To contribute, see the [Projects for .NET Community Contributors](https://github.com/dotnet/docs/projects/35) for ideas. The [Contributing Guide](CONTRIBUTING.md) has instructions on procedures we use. Or, check the [issues list](https://github.com/dotnet/docs/issues) for tasks that interest you.
We anticipate that [Xamarin](https://docs.microsoft.com/xamarin), [Mono](http://docs.go-mono.com/?link=root%3a%2fclasslib) and [Unity](https://docs.unity3d.com/Manual/index.html) will also use this documentation.
This project has adopted the code of conduct defined by the Contributor Covenant
to clarify expected behavior in our community.
For more information, see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).