[{"content":"Colima is a container runtime for macOS (and Linux) with minimal setup. It supports Docker, Containerd, and Kubernetes out of the box.\nPrerequisites macOS (Intel or Apple Silicon) or Linux Homebrew package manager For Kubernetes: kubectl (optional) Install brew install colima Start Colima Once installed, start Colima with:\ncolima start This starts a VM with the Docker runtime. You can now use Docker commands:\ndocker ps docker run hello-world Verify Installation Check that Colima is running:\ncolima status You should see output indicating the VM is running:\nINFO[0000] colima is running using QEMU INFO[0000] arch: aarch64 INFO[0000] runtime: docker INFO[0000] mountType: sshfs Next Steps Learn about Installation options for your platform Explore Runtimes to use Docker, Kubernetes, Containerd, or Incus Customize your setup with Configuration options Check the Commands reference for all available commands ","description":"Get started with Colima in minutes","headings":["prerequisites","install","start-colima","verify-installation","next-steps"],"section":"docs","title":"Getting Started","url":"\/docs\/getting-started\/"},{"content":"This guide covers installation methods for all supported platforms.\nmacOS Homebrew (Recommended) brew install colima To install with Docker client:\nbrew install colima docker MacPorts sudo port install colima Manual Installation Download the latest release from GitHub Releases:\n# For Intel Macs curl -LO https:\/\/github.com\/abiosoft\/colima\/releases\/latest\/download\/colima-Darwin-x86_64 sudo install colima-Darwin-x86_64 \/usr\/local\/bin\/colima # For Apple Silicon Macs curl -LO https:\/\/github.com\/abiosoft\/colima\/releases\/latest\/download\/colima-Darwin-arm64 sudo install colima-Darwin-arm64 \/usr\/local\/bin\/colima Linux Homebrew (Recommended) brew install colima To install with Docker client:\nbrew install colima docker Nix nix-env -i colima Manual Installation Download the latest release from GitHub Releases:\n# For x86_64 curl -LO https:\/\/github.com\/abiosoft\/colima\/releases\/latest\/download\/colima-Linux-x86_64 sudo install colima-Linux-x86_64 \/usr\/local\/bin\/colima # For ARM64 curl -LO https:\/\/github.com\/abiosoft\/colima\/releases\/latest\/download\/colima-Linux-arm64 sudo install colima-Linux-arm64 \/usr\/local\/bin\/colima Development Version To install the latest development version (bleeding edge) with the newest features and fixes:\nHomebrew HEAD brew install --HEAD colima Build from Source Requires Go 1.22 or later:\n# Clone the repository git clone https:\/\/github.com\/abiosoft\/colima.git cd colima # Build and install make sudo make install Note: Development versions may contain unstable features. Use stable releases for production environments.\nDependencies Docker CLI If you want to use the Docker runtime, install the Docker CLI:\nbrew install docker Docker Compose Plugin To use docker compose commands:\nbrew install docker-compose Create the CLI plugins directory and symlink the plugin:\nmkdir -p ~\/.docker\/cli-plugins ln -sfn $(brew --prefix)\/opt\/docker-compose\/bin\/docker-compose ~\/.docker\/cli-plugins\/docker-compose Docker Buildx Plugin To use docker buildx for advanced builds:\nbrew install docker-buildx Symlink the plugin:\nmkdir -p ~\/.docker\/cli-plugins ln -sfn $(brew --prefix)\/opt\/docker-buildx\/bin\/docker-buildx ~\/.docker\/cli-plugins\/docker-buildx All-in-One Docker Setup Install Docker with all plugins at once:\nbrew install docker docker-compose docker-buildx mkdir -p ~\/.docker\/cli-plugins ln -sfn $(brew --prefix)\/opt\/docker-compose\/bin\/docker-compose ~\/.docker\/cli-plugins\/docker-compose ln -sfn $(brew --prefix)\/opt\/docker-buildx\/bin\/docker-buildx ~\/.docker\/cli-plugins\/docker-buildx Containerd\/nerdctl For containerd runtime, nerdctl is included with Colima. Use colima nerdctl -- <command> directly, or install it for direct use:\ncolima nerdctl install kubectl For Kubernetes support:\nbrew install kubectl Incus Client For Incus runtime, install the Incus client:\nbrew install incus Verifying Installation After installation, verify Colima is available:\ncolima version Start Colima:\ncolima start Check the status:\ncolima status Updating Colima Homebrew brew upgrade colima MacPorts sudo port selfupdate sudo port upgrade colima Manual Update Download and install the latest release as shown in the manual installation section.\nUninstalling Homebrew # Stop and delete all Colima instances colima delete # Uninstall brew uninstall colima MacPorts colima delete sudo port uninstall colima Manual colima delete sudo rm \/usr\/local\/bin\/colima Troubleshooting Permission Issues If you encounter permission errors on Linux, ensure your user has access to the KVM device:\nsudo usermod -aG kvm $USER Log out and back in for changes to take effect.\nVM Not Starting If the VM fails to start, try resetting:\ncolima delete colima start For more troubleshooting tips, see the GitHub Issues.\n","description":"Install Colima on macOS and Linux","headings":["macos","homebrew-recommended","macports","manual-installation","linux","homebrew-recommended-1","nix","manual-installation-1","development-version","homebrew-head","build-from-source","dependencies","docker-cli","containerdnerdctl","kubectl","incus-client","verifying-installation","updating-colima","homebrew","macports-1","manual-update","uninstalling","homebrew-1","macports-2","manual","troubleshooting","permission-issues","vm-not-starting"],"section":"docs","title":"Installation","url":"\/docs\/installation\/"},{"content":"Complete reference for all Colima commands.\ncolima start Start the Colima VM.\ncolima start [profile] [flags] Resource Flags Flag Short Description Default --cpus -c Number of CPUs 2 --memory -m Memory in GiB 2 --disk -d Disk size in GiB 100 --root-disk Root filesystem disk size in GiB 20 Runtime Flags Flag Short Description Default --runtime -r Container runtime (docker, containerd, incus) docker --activate Set as active Docker\/Kubernetes\/Incus context on startup true VM Configuration Flags Flag Short Description Default --arch -a Architecture (aarch64, x86_64) host --vm-type -t Virtual machine type (qemu, vz, krunkit) qemu --cpu-type CPU type (qemu-system-specific options) --hostname Custom VM hostname --disk-image -i Path to custom disk image file --vz-rosetta Enable Rosetta for amd64 emulation (macOS ARM only) false --nested-virtualization -z Enable nested virtualization (macOS only) false --binfmt Use binfmt for foreign architecture emulation true --foreground -f Keep Colima running in foreground false Network Flags Flag Description Default --network-address Assign reachable IP address to VM (macOS only) false --network-host-addresses Enable port forwarding to specific host IPs false --network-mode Network mode: shared, bridged (macOS only) shared --network-interface Host interface for bridged mode (macOS only) en0 --network-preferred-route Use assigned IP as preferred route (macOS only) false --gateway-address Gateway address for VM network 192.168.5.2 --port-forwarder Port forwarder mechanism (ssh, grpc, none) ssh Mount Flags Flag Short Description Default --mount -V Directories to mount (suffix :w for writable, none to disable) --mount-type Volume driver (sshfs, 9p, virtiofs) sshfs --mount-inotify Propagate inotify file events to VM true Kubernetes Flags Flag Short Description Default --kubernetes -k Start with Kubernetes false --kubernetes-version Kubernetes (k3s) version k3s default --k3s-arg Additional k3s arguments –disable=traefik --k3s-listen-port k3s server listen port 0 (random) SSH Flags Flag Short Description Default --ssh-agent -s Forward SSH agent to VM false --ssh-config Generate SSH config in ~\/.ssh\/config true --ssh-port SSH server port 0 (random) DNS Flags Flag Short Description Default --dns -n DNS resolvers for VM --dns-host Custom DNS host mappings (host=IP) Configuration Flags Flag Short Description Default --edit -e Edit configuration file before starting false --editor Editor application (vim, nano, code, etc.) --template Use template file for initial configuration true --save-config Persist config file with specified flags env-dependent --env Environment variables for VM (key=value) Examples # Basic start colima start # Custom resources colima start --cpus 4 --memory 8 --disk 100 # With Kubernetes colima start --kubernetes # Using containerd runtime colima start --runtime containerd # Using Incus runtime colima start --runtime incus # VZ framework on macOS 13+ with virtiofs mounts colima start --vm-type vz --mount-type virtiofs # Enable Rosetta for x86_64 emulation on Apple Silicon colima start --vm-type vz --vz-rosetta # Mount directories (read-only and writable) colima start --mount ~\/projects:w --mount ~\/data # Custom DNS servers colima start --dns 8.8.8.8 --dns 8.8.4.4 # With SSH agent forwarding colima start --ssh-agent # Edit configuration before starting colima start --edit # Named profile with custom resources colima start dev --cpus 4 --memory 8 # Enable network address (macOS) colima start --network-address # Disable volume mounts colima start --mount=none # Disable port forwarding colima start --port-forwarder=none colima stop Stop the Colima VM.\ncolima stop [profile] [flags] Examples # Stop default profile colima stop # Stop specific profile colima stop dev colima restart Restart the Colima VM.\ncolima restart [profile] [flags] Examples # Restart default profile colima restart # Restart specific profile colima restart dev colima delete Delete the Colima VM instance.\ncolima delete [profile] [flags] Flags Flag Description --data Delete instance and all associated data (images, volumes) --force Force delete without confirmation By default, colima delete removes the VM but preserves container data (images, volumes). Use --data for a complete teardown. Data is only restored when the profile is restarted with the same runtime. See Data Persistence for details.\nExamples # Delete default profile (preserves container data) colima delete # Delete and remove all data colima delete --data # Force delete without confirmation colima delete --force # Delete specific profile colima delete dev # Complete teardown of a specific profile colima delete dev --data --force colima status Show the status of the Colima VM.\ncolima status [profile] [flags] Example Output INFO[0000] colima is running using QEMU INFO[0000] arch: aarch64 INFO[0000] runtime: docker INFO[0000] mountType: sshfs INFO[0000] socket: unix:\/\/\/Users\/user\/.colima\/default\/docker.sock colima list List all Colima profiles.\ncolima list [flags] Flags Flag Description --json Output in JSON format Example Output PROFILE STATUS ARCH CPUS MEMORY DISK RUNTIME default Running aarch64 4 8GiB 100GiB docker dev Stopped aarch64 2 4GiB 60GiB docker test Running x86_64 2 4GiB 60GiB containerd colima ssh SSH into the Colima VM.\ncolima ssh [profile] [flags] [-- command] Examples # Interactive SSH session colima ssh # Run a command colima ssh -- ls -la # Run command in specific profile colima ssh dev -- docker ps colima ssh-config Show SSH configuration for the Colima VM.\ncolima ssh-config [profile] [flags] Example Output Host colima HostName 127.0.0.1 User user Port 60022 IdentityFile \/Users\/user\/.colima\/_lima\/_config\/user StrictHostKeyChecking no UserKnownHostsFile \/dev\/null colima kubernetes Manage Kubernetes in a running Colima instance.\nStart Kubernetes colima kubernetes start [profile] Stop Kubernetes colima kubernetes stop [profile] Reset Kubernetes colima kubernetes reset [profile] Examples # Start Kubernetes on default profile colima kubernetes start # Stop Kubernetes on specific profile colima kubernetes stop dev # Reset Kubernetes cluster colima kubernetes reset colima model Manage AI models (requires krunkit VM type). See AI Workloads for detailed usage.\ncolima model run Run an AI model interactively:\ncolima model run <model> [flags] colima model serve Serve an AI model with a web-based chat interface:\ncolima model serve <model> [flags] The chat interface will be available at http:\/\/localhost:8080.\nFlags Flag Short Description --profile -p Colima profile to use --runner Model runner backend (docker, ramalama) --port Port for the web UI (model serve only) Model Runners Colima supports two model runner backends:\ndocker (default) - Docker’s native AI model runner. Supports Docker AI Registry and HuggingFace. ramalama - Uses Ramalama. Supports HuggingFace and Ollama registries. Examples # Run a model from Docker AI Registry (default runner) colima model run gemma3 # Run a HuggingFace model with docker runner colima model run hf.co\/microsoft\/Phi-3-mini-4k-instruct-gguf # Run a HuggingFace model with ramalama runner colima model run hf:\/\/microsoft\/Phi-3-mini-4k-instruct-gguf --runner ramalama # Run an Ollama model (requires ramalama runner) colima model run ollama:\/\/llama3.2 --runner ramalama # Serve a model colima model serve gemma3 # Serve a model on a custom port colima model serve gemma3 --port 9000 # Use a specific profile colima model run gemma3 -p ai colima nerdctl Run nerdctl commands (when using containerd runtime). No separate nerdctl installation required.\ncolima nerdctl [profile] -- [command] Examples colima nerdctl -- ps colima nerdctl -- images colima nerdctl -- run -it alpine colima nerdctl -- compose up -d colima nerdctl install Install nerdctl for direct use without the colima nerdctl -- prefix:\n# Install for default profile colima nerdctl install # Install for a custom profile colima nerdctl install -p myprofile After installation, you can use nerdctl directly:\nnerdctl run hello-world nerdctl ps colima template Generate a configuration template.\ncolima template [flags] This outputs a YAML template with all available configuration options that can be used with --edit.\ncolima update Update Colima to the latest version.\ncolima update [flags] colima prune Prune unused data to free up disk space.\ncolima prune [profile] [flags] colima version Show Colima version information.\ncolima version Example Output colima version 0.8.0 colima completion Generate shell completion scripts.\ncolima completion [shell] Supported shells: bash, zsh, fish, powershell\nExamples # Bash colima completion bash > \/etc\/bash_completion.d\/colima # Zsh colima completion zsh > "${fpath[1]}\/_colima" # Fish colima completion fish > ~\/.config\/fish\/completions\/colima.fish Environment Variables COLIMA_HOME Override the Colima home directory:\nexport COLIMA_HOME=\/custom\/path Default: ~\/.colima\nTips and Tricks Docker Context Colima automatically creates a Docker context. Switch between contexts:\n# List contexts docker context ls # Use Colima context docker context use colima # Use default context docker context use default Multiple Profiles Use profiles for different environments. See the Profiles documentation for complete details on creating, managing, and deleting instances.\nAliases Add useful aliases to your shell:\n# Start with default config alias colima-up="colima start --cpus 4 --memory 8" # Quick Kubernetes cluster alias colima-k8s="colima start --kubernetes --cpus 4 --memory 8" # VZ mode with virtiofs (macOS 13+) alias colima-vz="colima start --vm-type vz --mount-type virtiofs" ","description":"Colima command reference","headings":["colima-start","resource-flags","runtime-flags","vm-configuration-flags","network-flags","mount-flags","kubernetes-flags","ssh-flags","dns-flags","configuration-flags","examples","colima-stop","examples-1","colima-restart","examples-2","colima-delete","flags","examples-3","colima-status","example-output","colima-list","flags-1","example-output-1","colima-ssh","examples-4","colima-ssh-config","example-output-2","colima-kubernetes","start-kubernetes","stop-kubernetes","reset-kubernetes","examples-5","colima-model","colima-model-run","colima-model-serve","flags-2","model-runners","examples-6","colima-nerdctl","examples-7","colima-nerdctl-install","colima-template","colima-update","colima-prune","colima-version","example-output-3","colima-completion","examples-8","environment-variables","colima_home","tips-and-tricks","docker-context","multiple-profiles","aliases"],"section":"docs","title":"Commands","url":"\/docs\/commands\/"},{"content":"Colima can be configured using command-line flags or a YAML configuration file.\nConfiguration File Edit the configuration file interactively:\ncolima start --edit This opens the configuration in your default editor. Specify a different editor with:\ncolima start --edit --editor code Config file locations:\n~\/.colima\/default\/colima.yaml (default profile) ~\/.colima\/<profile>\/colima.yaml (named profiles) Default Configuration Template Use colima template to set default configuration applied to all new instances:\ncolima template This opens the template file at ~\/.colima\/_templates\/default.yaml. You can also specify an editor:\ncolima template --editor code The $COLIMA_HOME environment variable overrides the base directory (default: ~\/.colima).\nVM Resources CPU, Memory, and Disk # Number of CPUs cpu: 4 # Memory in GiB memory: 8 # Disk size in GiB (can only be increased after creation) disk: 100 # Root filesystem disk size in GiB rootDisk: 20 Or via command line:\ncolima start --cpus 4 --memory 8 --disk 100 Default values:\nCPU: 2 cores Memory: 2 GiB Disk: 100 GiB VM Configuration Architecture Set the VM architecture (immutable after creation):\n# Options: x86_64, aarch64, host arch: host Run x86_64 containers on Apple Silicon:\ncolima start --arch x86_64 VM Type Choose the virtualization technology (immutable after creation):\n# Options: qemu, vz, krunkit # vz and krunkit require macOS 13+ on Apple Silicon vmType: qemu QEMU (default): Works on all platforms.\nVZ Framework (macOS 13+): Apple’s Virtualization framework with better performance:\ncolima start --vm-type vz VZ framework benefits:\nBetter performance Rosetta 2 support for x86_64 emulation VirtioFS support for faster file mounts Krunkit (macOS 13+ on Apple Silicon): Lightweight VMs with GPU access for AI workloads:\ncolima start --vm-type krunkit Krunkit benefits:\nDirect GPU access for AI\/ML workloads Lightweight and fast startup Ideal for running AI models See the AI Workloads documentation for details on running AI models. CPU Type Specify CPU type for QEMU (supports instruction set extensions):\ncpuType: host Rosetta Enable Rosetta for amd64 emulation on Apple Silicon (requires VZ):\nrosetta: true colima start --vm-type vz --vz-rosetta Nested Virtualization Enable nested virtualization on M3+ Macs (requires VZ):\nnestedVirtualization: true Hostname Set a custom VM hostname:\nhostname: my-colima Default: colima or colima-<profile_name>\nRuntime Configuration Container Runtime Choose the container runtime (immutable after creation):\n# Options: docker, containerd, incus runtime: docker Kubernetes Enable and configure Kubernetes:\nkubernetes: # Enable Kubernetes enabled: true # k3s version (default: latest stable) version: v1.28.3+k3s1 # Additional k3s arguments k3sArgs: - --disable=traefik # Kubernetes API port (0 = random) port: 6443 colima start --kubernetes --kubernetes-version v1.28.3+k3s1 Docker Daemon Configuration Configure Docker daemon settings (maps to daemon.json):\ndocker: # Insecure registries insecure-registries: - myregistry.local:5000 # Registry mirrors registry-mirrors: - https:\/\/mirror.gcr.io # Other daemon options features: buildkit: true Note: For registry mirrors, the Docker client also needs the mirrors configured in ~\/.docker\/daemon.json on the host:\n{ "registry-mirrors": [ "https:\/\/mirror.gcr.io" ] } Network Configuration Network Address Assign a reachable IP address to the VM (macOS only):\nnetwork: address: true colima start --network-address Note: Requires root privilege and increases startup time.\nNetwork Mode Set the network mode (macOS only):\nnetwork: # Options: shared, bridged mode: shared # Interface for bridged mode interface: en0 DNS Configuration Set custom DNS resolvers:\nnetwork: dns: - 8.8.8.8 - 1.1.1.1 colima start --dns 8.8.8.8 --dns 1.1.1.1 DNS Host Mappings Map hostnames to custom targets:\nnetwork: dnsHosts: myapp.local: 192.168.1.100 api.local: host.docker.internal Gateway Address Custom gateway address (last octet must be 2):\nnetwork: gatewayAddress: 192.168.5.2 Host Addresses Replicate host IP addresses for port forwarding:\nnetwork: hostAddresses: true Port Forwarding Ports are automatically forwarded from containers to the host:\ndocker run -p 8080:80 caddy # Access at http:\/\/localhost:8080 Configure the port forwarder:\n# Options: ssh, grpc portForwarder: ssh Volume Mounts Mount Type Choose the volume mount driver (immutable after creation):\n# Options: sshfs, 9p, virtiofs mountType: sshfs Mount type recommendations:\nsshfs (default): Works everywhere, good compatibility 9p: Better performance than sshfs virtiofs: Best performance (requires VZ on macOS 13+) colima start --vm-type vz --mount-type virtiofs Mount Configuration Configure volume mounts:\nmounts: # Home directory (default, writable) - location: ~ writable: true # Additional mount (read-only) - location: \/data writable: false # Project directory - location: ~\/projects writable: true Disabling Mounts To disable all volume mounts entirely:\nmounts: null This is useful when mounts are not needed e.g. for CI\/CD environments or AI agents.\nMount Inotify Propagate inotify file events to VM (experimental):\nmountInotify: true colima start --mount-inotify SSH Configuration SSH Agent Forwarding Forward host SSH agent to the VM:\nforwardAgent: true colima start --ssh-agent SSH Config Auto-update ~\/.ssh\/config with VM connection details:\nsshConfig: true SSH Port Set a specific SSH port (0 = random):\nsshPort: 0 Provisioning Run scripts on VM startup (idempotent):\nprovision: - mode: system script: | apt-get update apt-get install -y htop - mode: user script: | echo "Hello from user script" Modes:\nsystem: Runs as root user: Runs as the default user Environment Variables Set environment variables in the VM:\nenv: HTTP_PROXY: http:\/\/proxy.example.com:8080 HTTPS_PROXY: http:\/\/proxy.example.com:8080 NO_PROXY: localhost,127.0.0.1 Auto Activation Automatically set as active Docker\/Kubernetes context on startup:\nautoActivate: true Profiles Each profile has its own configuration file at ~\/.colima\/<profile>\/colima.yaml.\nSee the Profiles documentation for details on creating and managing multiple Colima instances.\nImmutable Settings Some settings cannot be changed after the VM is created:\narch (architecture) runtime (container runtime) vmType (VM type) mountType (volume mount driver) To change these, delete and recreate the instance:\ncolima delete colima start --runtime containerd --vm-type vz Example Configurations Development Machine cpu: 4 memory: 8 disk: 100 vmType: vz mountType: virtiofs forwardAgent: true docker: features: buildkit: true CI\/CD Environment cpu: 2 memory: 4 disk: 50 runtime: docker env: CI: true Kubernetes Development cpu: 4 memory: 8 disk: 100 kubernetes: enabled: true version: v1.28.3+k3s1 k3sArgs: - --disable=traefik AI Workloads cpu: 4 memory: 16 disk: 50 vmType: krunkit # Model runner backend: docker (default), ramalama modelRunner: docker Or via command line:\ncolima start --vm-type krunkit --cpus 4 --memory 16 --disk 50 --model-runner docker Model runner options:\ndocker (default): Docker Model Runner ramalama: Uses Ramalama for model execution See AI Workloads for more details on running AI models.\n","description":"Configure Colima for your needs","headings":["configuration-file","default-configuration-template","vm-resources","cpu-memory-and-disk","vm-configuration","architecture","vm-type","cpu-type","rosetta","nested-virtualization","hostname","runtime-configuration","container-runtime","kubernetes","docker-daemon-configuration","network-configuration","network-address","network-mode","dns-configuration","dns-host-mappings","gateway-address","host-addresses","port-forwarding","volume-mounts","mount-type","mount-configuration","disabling-mounts","mount-inotify","ssh-configuration","ssh-agent-forwarding","ssh-config","ssh-port","provisioning","environment-variables","auto-activation","profiles","immutable-settings","example-configurations","development-machine","cicd-environment","kubernetes-development","ai-workloads"],"section":"docs","title":"Configuration","url":"\/docs\/configuration\/"},{"content":"Colima supports multiple container runtimes out of the box. This guide covers how to start and use each runtime.\nDocker Docker is the default runtime. It provides full compatibility with the Docker CLI and ecosystem.\nStarting Docker Runtime colima start Or explicitly specify the runtime:\ncolima start --runtime docker Using Docker Once started, you can use Docker commands directly:\n# Run a container docker run hello-world # Run an interactive container docker run -it alpine sh # List running containers docker ps # List all containers docker ps -a # List images docker images Docker Compose Docker Compose works out of the box:\n# Start services docker compose up -d # View logs docker compose logs -f # Stop services docker compose down Docker Context Colima automatically creates and activates a Docker context. You can manage contexts with:\n# List contexts docker context ls # Switch to Colima context docker context use colima # Switch to default context docker context use default Kubernetes Colima can run a local Kubernetes cluster using k3s.\nStarting Kubernetes colima start --kubernetes With custom resources for larger workloads:\ncolima start --kubernetes --cpus 4 --memory 8 Using Kubernetes Once started, kubectl is automatically configured:\n# Check cluster status kubectl cluster-info # Run a pod kubectl run caddy --image=caddy # List pods kubectl get pods # List all resources kubectl get all # View pod logs kubectl logs <pod-name> Kubernetes Version Specify a k3s version:\ncolima start --kubernetes --kubernetes-version v1.28.3+k3s1 Additional k3s Arguments Pass additional arguments to k3s:\ncolima start --kubernetes --k3s-arg "--disable=traefik" Managing Kubernetes You can start, stop, or reset Kubernetes on a running Colima instance:\n# Start Kubernetes colima kubernetes start # Stop Kubernetes colima kubernetes stop # Reset Kubernetes cluster colima kubernetes reset Containerd Containerd is a lightweight container runtime. Colima includes a built-in nerdctl wrapper for a Docker-compatible CLI experience.\nStarting Containerd Runtime colima start --runtime containerd Using colima nerdctl Use Colima’s built-in nerdctl command (no installation required):\n# Run a container colima nerdctl -- run hello-world # Run an interactive container colima nerdctl -- run -it alpine sh # List running containers colima nerdctl -- ps # List images colima nerdctl -- images # Build an image colima nerdctl -- build -t myapp . Compose with nerdctl nerdctl supports Docker Compose files:\n# Start services colima nerdctl -- compose up -d # Stop services colima nerdctl -- compose down Installing nerdctl for Direct Use If you prefer to use nerdctl directly without the colima nerdctl -- prefix, you can install it:\n# Install nerdctl for the default profile colima nerdctl install # Install nerdctl for a custom profile colima nerdctl install -p myprofile After installation, you can use nerdctl directly:\nnerdctl run hello-world nerdctl ps nerdctl images Customizing Containerd Config On first startup, Colima generates default config files at the standard user config locations:\nFile Location Containerd config ~\/.config\/containerd\/config.toml BuildKit config ~\/.config\/buildkit\/buildkitd.toml These are shared across all Colima profiles. Edit the files and restart for changes to take effect:\n$EDITOR ~\/.config\/containerd\/config.toml colima stop && colima start --runtime containerd To use a different config for a specific profile, place the file at ~\/.colima\/<profile>\/containerd\/config.toml (or buildkitd.toml). Per-profile configs take priority over the central config.\nNote: $XDG_CONFIG_HOME is respected for the central config location if set.\nIncus Incus is a modern container and virtual machine manager (fork of LXD). It supports both system containers and VMs.\nStarting Incus Runtime colima start --runtime incus Using Incus Once started, you can use incus commands:\n# Launch an Alpine container incus launch images:alpine\/edge mycontainer # Launch an Ubuntu container incus launch images:ubuntu\/24.04 ubuntu # List containers incus list # Execute command in container incus exec mycontainer -- sh # Stop a container incus stop mycontainer # Delete a container incus delete mycontainer Incus Virtual Machines Incus can also run full virtual machines:\n# Launch a VM incus launch images:ubuntu\/24.04 myvm --vm # List VMs and containers incus list Note: Running Incus virtual machines requires nested virtualization. On Apple Silicon Macs, this feature is only available on M3 chips or newer.\nIncus Profiles Manage resource limits with profiles:\n# List profiles incus profile list # Show default profile incus profile show default # Edit profile incus profile edit default Direct Host Access As of v0.10.0, Incus instances are directly reachable from your macOS host via their IP addresses when network address is enabled:\n# Start with network address enabled colima start --runtime incus --network-address # Launch a container incus launch images:alpine\/edge mycontainer # Get the container's IP address incus list # Access the container directly from macOS ping <container-ip> ssh user@<container-ip> This makes it easy to access services running inside Incus containers without port forwarding.\nSwitching Runtimes To switch between runtimes, you need to stop and restart Colima:\n# Stop current instance colima stop # Start with different runtime colima start --runtime containerd Or use different profiles for different runtimes:\n# Docker profile colima start docker # Containerd profile colima start containerd --runtime containerd # Kubernetes profile colima start k8s --kubernetes # Incus profile colima start incus --runtime incus # List all profiles colima list Updating Runtimes Colima can update the runtime components within the VM using the colima update command. This updates the runtime to the latest available version without recreating the VM.\n# Update the runtime for the default profile colima update # Update the runtime for a specific profile colima update myprofile Note: The update command works for Docker, Kubernetes, and Incus runtimes. Containerd runtime updates are not currently supported.\nData Persistence Soft Delete Running colima delete without the --data flag performs a soft delete: the VM is removed but the runtime data is preserved on disk. On the next colima start, data is automatically restored.\nRuntime Auto-restore on next start Docker \u2705 Yes Containerd \u2705 Yes Kubernetes \u274c Not supported Incus \u26a0\ufe0f Requires recovery steps Note: Hard delete (colima delete --data) permanently removes all data and cannot be recovered.\nNote: Data recovery only applies to the same runtime. Colima will refuse to restore the data when started with a different runtime.\nRecovering Incus Data After Soft Delete When starting an Incus instance after a soft delete, Colima detects existing data and prompts for recovery. Colima will run incus admin recover interactively to restore the storage pool and containers.\nStep-by-step recovery:\nRespond y when asked whether to recover existing storage pool(s).\nColima prints the paths of all found storage pools and begins the incus admin recover process.\nRespond yes when asked “Would you like to recover another storage pool?”\nEnter default when asked for the name of the storage pool.\nEnter zfs when asked for the storage backend.\nEnter the exact path printed by Colima when asked for the source of the storage pool (e.g. \/var\/lib\/incus\/disks\/default.img).\nPress Enter to leave additional configuration properties empty.\nRespond no when asked again if you would like to recover another storage pool (unless you have additional manually-created pools \u2014 repeat steps 3\u20137 for each).\nPress Enter to accept the default (yes) when asked to continue scanning for lost volumes.\nRespond yes when asked whether to recover the listed containers.\nIf you have multiple storage pools (created manually), Colima prints the paths for all of them. Repeat the pool-entry steps for each pool before answering no to finish.\nExample recovery session:\nexisting Incus data found, would you like to recover the storage pool(s)? [y\/N] y INFO[0030] Running 'incus admin recover' ... context=incus INFO[0030] Found 1 storage pool source(s): context=incus INFO[0030] \/var\/lib\/incus\/disks\/default.img context=incus This server currently has the following storage pools: Would you like to recover another storage pool? (yes\/no) [default=no]: yes Name of the storage pool: default Name of the storage backend (lvm, dir, truenas, zfs, btrfs): zfs Source of the storage pool (block device, volume group, dataset, path, ... as applicable): \/var\/lib\/incus\/disks\/default.img Additional storage pool configuration property (KEY=VALUE, empty when done): Would you like to recover another storage pool? (yes\/no) [default=no]: no The recovery process will be scanning the following storage pools: - NEW: "default" (backend="zfs", source="\/var\/lib\/incus\/disks\/default.img") Would you like to continue with scanning for lost volumes? (yes\/no) [default=yes]: Scanning for unknown volumes... The following unknown storage pools have been found: - Storage pool "default" of type "zfs" The following unknown volumes have been found: - Container "ubuntu" on pool "default" in project "default" (includes 0 snapshots) Would you like those to be recovered? (yes\/no) [default=no]: yes Starting recovery... INFO[0111] starting ... context=incus INFO[0112] done After the recovery process completes, the existing containers and storage pool are fully restored.\nRuntime Comparison Feature Docker Containerd Kubernetes Incus OCI Containers \u2705 \u2705 \u2705 \u2705 System Containers \u274c \u274c \u274c \u2705 Virtual Machines \u274c \u274c \u274c \u2705 Compose Support \u2705 \u2705 (nerdctl) \u274c \u274c Orchestration \u2705 (Swarm) \u274c \u2705 \u274c CLI Tool docker nerdctl kubectl incus ","description":"Configure and use different container runtimes with Colima","headings":["docker","starting-docker-runtime","using-docker","docker-compose","docker-context","kubernetes","starting-kubernetes","using-kubernetes","kubernetes-version","additional-k3s-arguments","managing-kubernetes","containerd","starting-containerd-runtime","using-colima-nerdctl","compose-with-nerdctl","installing-nerdctl-for-direct-use","customizing-containerd-config","incus","starting-incus-runtime","using-incus","incus-virtual-machines","incus-profiles","direct-host-access","switching-runtimes","updating-runtimes","data-persistence","soft-delete","recovering-incus-data-after-soft-delete","runtime-comparison"],"section":"docs","title":"Runtimes","url":"\/docs\/runtimes\/"},{"content":"A profile in Colima is an independent instance of a virtual machine with its own configuration, runtime, and container data. Profiles allow you to run multiple isolated environments simultaneously, each with different settings tailored to specific use cases.\nUnderstanding Profiles Each profile is a completely separate Colima instance with:\nIts own VM resources (CPU, memory, disk) Its own container runtime (Docker, Containerd, or Incus) Its own containers, images, and volumes Its own configuration file at ~\/.colima\/<profile>\/colima.yaml The default profile is named default and is used when no profile is specified.\nCreating Profiles Create a new profile by specifying a name when starting Colima:\n# Create a profile named "dev" colima start dev # Create a profile with custom resources colima start dev --cpus 4 --memory 8 # Create a profile with Kubernetes colima start k8s --kubernetes # Create a profile with containerd runtime colima start containerd --runtime containerd Each profile name creates a new, independent instance.\nListing Profiles View all profiles and their status:\ncolima list Example output:\nPROFILE STATUS ARCH CPUS MEMORY DISK RUNTIME default Running aarch64 4 8GiB 100GiB docker dev Running aarch64 2 4GiB 60GiB docker k8s Stopped aarch64 4 8GiB 100GiB docker Starting and Stopping Instances Starting an Instance Start an existing profile:\n# Start the default profile colima start # Start a named profile (profile as argument) colima start dev # Start using the --profile flag colima start --profile dev Stopping an Instance Stop a running profile:\n# Stop the default profile colima stop # Stop a named profile (profile as argument) colima stop dev # Stop using the --profile flag colima stop --profile dev Restarting an Instance Restart a profile:\n# Restart the default profile colima restart # Restart a named profile colima restart dev Deleting Instances Soft Delete (Preserve Container Data) Delete the VM instance while retaining container data (images, volumes):\n# Delete the default profile colima delete # Delete a named profile colima delete dev This removes the VM but preserves container data. When you recreate the profile with the same name, the container data will be restored.\nSee Data Persistence for more.\nComplete Teardown Delete the VM instance and all associated data including containers, images, and volumes:\n# Completely remove the default profile colima delete --data # Completely remove a named profile colima delete dev --data # Force delete without confirmation colima delete dev --data --force The --data flag ensures a complete cleanup, removing:\nThe virtual machine All container images All container volumes All configuration files Use this when you want to start fresh or reclaim disk space.\nSpecifying a Profile There are three ways to specify which profile to use:\nProfile as Argument Commands like start, stop, delete, and restart accept the profile name as an argument:\ncolima start dev colima stop dev colima delete dev colima restart dev Profile as Flag All commands support the --profile (or -p) flag:\ncolima start --profile dev colima stop --profile dev colima status --profile dev colima ssh --profile dev colima list --profile dev Environment Variable Set the COLIMA_PROFILE environment variable to avoid specifying the profile with every command:\n# Set for the current session export COLIMA_PROFILE=dev # Now all commands use the "dev" profile colima start colima status colima stop Add to your shell configuration (~\/.bashrc, ~\/.zshrc, etc.) for persistence:\nexport COLIMA_PROFILE=dev The environment variable is especially useful when you primarily work with a single non-default profile.\nPriority: --profile flag > command argument > COLIMA_PROFILE environment variable > default profile.\nOther Relevant Environment Variables Variable Description COLIMA_HOME Base directory for all profiles (default: ~\/.colima) COLIMA_PROFILE Active profile name (default: default) DOCKER_CONFIG Path to Docker client configuration directory (default: ~\/.docker) Common Use Cases Different Environments # Development: more resources, SSH agent forwarding colima start dev --cpus 4 --memory 8 --ssh-agent # CI: minimal resources colima start ci --cpus 2 --memory 2 Multiple Container Runtimes # Docker runtime (default) colima start docker # Containerd runtime colima start containerd --runtime containerd # Incus runtime colima start incus --runtime incus Testing Different Architectures # Native architecture colima start native # x86_64 on Apple Silicon colima start x86 --arch x86_64 Kubernetes Development # Kubernetes cluster colima start k8s --kubernetes --cpus 4 --memory 8 # Multiple Kubernetes versions colima start k8s-128 --kubernetes --kubernetes-version v1.28.3+k3s1 colima start k8s-127 --kubernetes --kubernetes-version v1.27.7+k3s1 Docker Context with Profiles Each profile creates its own Docker context. Switch between them:\n# List Docker contexts docker context ls # Use a specific profile's context docker context use colima-dev # Use the default profile's context docker context use colima ","description":"Manage multiple Colima instances with profiles","headings":["understanding-profiles","creating-profiles","listing-profiles","starting-and-stopping-instances","starting-an-instance","stopping-an-instance","restarting-an-instance","deleting-instances","soft-delete-preserve-container-data","complete-teardown","specifying-a-profile","profile-as-argument","profile-as-flag","environment-variable","other-relevant-environment-variables","common-use-cases","different-environments","multiple-container-runtimes","testing-different-architectures","kubernetes-development","docker-context-with-profiles"],"section":"docs","title":"Profiles","url":"\/docs\/profiles\/"},{"content":"Colima provides an ideal environment to run GPU-powered AI workloads on Apple Silicon devices.\nBy leveraging Krunkit for GPU access, AI models run in confined, isolated and secure containers.\nRequirements Apple Silicon Mac (M1, M2, M3, or newer) macOS 13 or newer Sufficient RAM for your chosen model (8GB+ recommended) Krunkit installed (see below) Installing Krunkit Krunkit is required for GPU access on Apple Silicon. Install it via Homebrew:\nbrew tap slp\/krunkit && brew install krunkit Getting Started 1. Start Colima with Krunkit The krunkit VM type enables GPU access for AI workloads:\ncolima start --vm-type krunkit 2. Run a Model Run an AI model:\n# Start an interactive chat session colima model run gemma3 # Or run a one-off prompt colima model run gemma3 "Explain quantum computing in simple terms" This downloads the model (if not cached) and either starts an interactive chat session or returns the response for a one-off prompt.\nModel Runners Colima supports two model runner backends:\nDocker Model Runner (default) - Uses Docker’s native AI model runner. Supports Docker AI Registry and HuggingFace. Ramalama - Uses Ramalama for model execution. Supports HuggingFace and Ollama registries. To switch between runners:\n# Use docker runner (default) colima model run gemma3 --runner docker # Use ramalama runner colima model run gemma3 --runner ramalama The runner can also be configured in the Colima config file. See Configuration - AI Workloads for details.\nSupported Model Registries Colima supports models from multiple registries:\nDocker AI Registry (Default) NOTE: Docker AI Registry is only available with the Docker Model Runner.\nThe Docker AI Registry provides curated, optimized models for local inference. When no prefix is specified, Docker AI Registry is used by default.\n# Run models from Docker AI Registry (default, no prefix needed) colima model run gemma3 colima model run llama3.2 colima model run qwen2.5 colima model run phi4 colima model run mistral Browse available models at hub.docker.com\/u\/ai.\nHuggingFace Hub HuggingFace hosts thousands of open-source models. The prefix syntax differs by runner:\n# Docker Model Runner uses hf.co\/ prefix colima model run hf.co\/microsoft\/Phi-3-mini-4k-instruct-gguf # Ramalama uses hf:\/\/ prefix colima model run hf:\/\/microsoft\/Phi-3-mini-4k-instruct-gguf --runner ramalama Browse models at huggingface.co\/models.\nOllama Registry NOTE: Ollama Registry is only available with the Ramalama runner.\nOllama provides a curated collection of popular open-source models optimized for local inference. Use the ollama:\/\/ prefix.\n# Run Ollama models with ollama:\/\/ prefix (requires ramalama runner) colima model run ollama:\/\/gemma3 --runner ramalama colima model run ollama:\/\/llama3.2 --runner ramalama Browse available models at ollama.com\/library.\nAvailable Commands Running Models Without a prompt, you enter an interactive chat session for continuous conversation:\n# Start an interactive chat session colima model run gemma3 For one-off prompts, specify the prompt before the model name:\n# One-off prompt colima model run gemma3 "What is the capital of France?" More examples:\n# Run different models from Docker AI Registry colima model run llama3.2 colima model run qwen2.5 colima model run phi4 # Run a HuggingFace model (requires hf.co\/ prefix) colima model run hf.co\/microsoft\/Phi-3-mini-4k-instruct-gguf # See all available options colima model --help Serving Models Serve a model with a web-based chat interface:\n# Serve a model (available at localhost:8080) colima model serve gemma3 # Or serve a HuggingFace model colima model serve hf.co\/microsoft\/Phi-3-mini-4k-instruct-gguf # Serve on a custom port colima model serve gemma3 --port 9000 The chat interface will be available at http:\/\/localhost:8080 by default. Use --port to specify a different port.\nOpen WebUI Open WebUI is a feature-rich, self-hosted web interface for AI models. You can use it with Colima by serving a model and pointing OpenWebUI to the served endpoint.\nFirst, serve a model:\ncolima model serve gemma3 Then run OpenWeb UI in Docker, specifying the Colima model server as the OpenAI API base URL:\ndocker run --rm -it -p 3000:8080 \\ -e OPENAI_API_BASE_URL=http:\/\/host.docker.internal:8080 \\ -v open-webui:\/app\/backend\/data \\ --name open-webui \\ ghcr.io\/open-webui\/open-webui:main OpenWebUI will be available at http:\/\/localhost:3000.\nWith web search enabled:\ndocker run --rm -it -p 3000:8080 \\ -e OPENAI_API_BASE_URL=http:\/\/host.docker.internal:8080 \\ -e ENABLE_WEB_SEARCH=true \\ -v open-webui:\/app\/backend\/data \\ --name open-webui \\ ghcr.io\/open-webui\/open-webui:main Note: host.docker.internal allows the Docker container to access services running on the host machine (in this case, the Colima model server on port 8080).\nResource Management One of the key benefits of running AI workloads in Colima is the ability to control resource usage. This prevents models from consuming all available system resources.\nCPU and Memory Limits Allocate specific resources to your AI instance:\n# Start with 4 CPUs and 8GB RAM colima start --vm-type krunkit --cpus 4 --memory 8 Disk Space Set the disk size for model storage:\n# Start with 50GB disk colima start --vm-type krunkit --disk 50 Recommended Resources Model Size Minimum RAM Recommended RAM Examples Tiny (1-2B) 4GB 8GB TinyLlama (1.1B), Gemma 2B Small (3-4B) 8GB 12GB Phi-3 Mini (3.8B), Gemma 3 Medium (7-8B) 12GB 16GB Llama 3.2 (8B), Mistral 7B Large (13B+) 16GB 32GB Phi-4 (14B), Llama 13B, Mixtral Tip: Check the model page on HuggingFace or Ollama for specific hardware requirements before running a model.\nNote: TinyLlama is useful for validating your setup but has limited capabilities. For meaningful results, use models with 3B+ parameters.\nUsing Profiles for AI Create a dedicated profile for AI workloads to keep them separate from your container development:\n# Create an AI-specific profile colima start ai --vm-type krunkit --cpus 4 --memory 16 --disk 50 # Setup and run models on the AI profile colima model setup -p ai colima model run gemma3 -p ai # Your main development profile remains unaffected colima start # default profile with Docker This allows you to:\nKeep AI resources isolated from development containers Quickly switch between AI and development workloads Delete AI resources without affecting your development environment Security Colima’s AI workloads benefit from multiple layers of security:\nContainer Isolation Models run inside containerized environments, isolated from:\nYour host filesystem Other running containers Network access (unless explicitly enabled) Resource Limits Unlike running models directly on your host, Colima enforces:\nCPU limits to prevent system freeze Memory limits to prevent OOM conditions Disk quotas to manage storage Extra Isolation While the mounted host volumes are not accessible to AI containers by default, you can take security a step further by completely disabling volume mounts:\ncolima start --vm-type krunkit --mount=none This ensures no host filesystem access is possible from within the VM, providing maximum isolation for untrusted models.\nTroubleshooting Model Download Issues If a model fails to download:\n# Check available disk space colima ssh -- df -h # Increase disk if needed (stop, then start with larger disk) colima stop colima start --vm-type krunkit --disk 100 GPU Not Detected Ensure you’re using the krunkit VM type:\n# Check current VM type colima status # Restart with krunkit colima stop colima start --vm-type krunkit Out of Memory If models crash or run slowly:\n# Stop current instance colima stop # Start with more memory colima start --vm-type krunkit --memory 16 Resetting AI Setup To completely reset your AI environment:\n# Delete the profile and its data colima delete --data # Start fresh colima start --vm-type krunkit colima model setup ","description":"Run GPU-accelerated AI models securely with Colima","headings":["requirements","installing-krunkit","getting-started","1-start-colima-with-krunkit","2-run-a-model","model-runners","supported-model-registries","docker-ai-registry-default","huggingface-hub","ollama-registry","available-commands","running-models","serving-models","open-webui","resource-management","cpu-and-memory-limits","disk-space","recommended-resources","using-profiles-for-ai","security","container-isolation","resource-limits","extra-isolation","troubleshooting","model-download-issues","gpu-not-detected","out-of-memory","resetting-ai-setup"],"section":"docs","title":"AI Workloads","url":"\/docs\/ai\/"},{"content":"Frequently asked questions about Colima.\nGeneral 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.\nHow 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.\nThose are better options if you need multiple clusters, or do not need Docker and Kubernetes to share the same images and runtime.\nColima with Docker runtime is fully compatible with Minikube (with Docker driver), Kind and K3d.\nFor Docker Minikube with Docker runtime can expose the cluster’s Docker with minikube docker-env. But there are some caveats:\nKubernetes 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.\nAre 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:\ncolima start --runtime docker --vm-type krunkit Set up and run AI models:\ncolima model setup colima model run gemma3 Multiple registries are supported including HuggingFace (default) and Ollama:\ncolima 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.\nConfiguration Does Colima support autostart? Yes. Since v0.5.6, foreground mode is available via --foreground. For Homebrew installations, use:\nbrew 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.\nUse $COLIMA_HOME environment variable to customize the location.\nCan 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:\ncolima 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:\ncolima template The template is stored at $HOME\/.colima\/_templates\/default.yaml.\nDocker 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.\nWhere 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.\nHow 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:\nConfigure application-specific socket paths in the application settings\nSet DOCKER_HOST environment variable:\nexport DOCKER_HOST="unix:\/\/$HOME\/.colima\/default\/docker.sock" Create a symlink to the default location:\nsudo 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:\n- docker: {} + docker: + insecure-registries: + - myregistry.com:5000 + - host.docker.internal:5000 For registry mirrors, also add the mirrors to your host ~\/.docker\/daemon.json:\n{ "registry-mirrors": [ "https:\/\/my.dockerhub.mirror.something" ] } Docker buildx plugin is missing? Install via Homebrew and link the plugin:\nbrew 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:\nARCH=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:\ncolima start --edit Add your mount paths, then restart:\ncolima 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:\nFile Location Containerd config ~\/.config\/containerd\/config.toml BuildKit config ~\/.config\/buildkit\/buildkitd.toml These are shared across all Colima profiles. Modify the files and restart Colima for changes to take effect:\n# 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.\nPer-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.\nThe resolution order is:\n~\/.colima\/<profile>\/containerd\/<file> (per-profile override) ~\/.config\/containerd\/<file> or ~\/.config\/buildkit\/<file> (central) Embedded default Networking The VM’s IP is unreachable? Enable network address with:\ncolima start --network-address Note: This requires root privilege and increases startup time.\nIncus 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:\ncolima stop colima start --network-address Or edit the configuration:\ncolima start --edit network: - address: false + address: true Colima cannot access internet? Try custom DNS servers:\ncolima start --dns 8.8.8.8 --dns 1.1.1.1 Verify connectivity:\ncolima 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+):\ncolima start --edit Change the disk value and save. Changes apply automatically on next startup.\nMaintenance 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:\ncolima delete colima start To test the upgrade without affecting the existing setup, use a separate profile:\ncolima start debug Updating the container runtime From v0.7.6+, the container runtime (Docker, Containerd) can be updated independently:\ncolima update This updates Docker (or Containerd) to the latest version without needing to update Colima itself.\nAccessing the Virtual Machine SSH into the VM to inspect or modify it directly:\ncolima ssh Run a single command without an interactive session:\ncolima 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:\ncolima update How do I delete container data? From v0.9.0+:\n# 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.\nTroubleshooting Colima shows “Broken” status? This can happen after a macOS restart. Reset the state with:\ncolima stop --force colima start Fatal error on startup (exit status 1)? Enable debug output to diagnose:\ncolima start --verbose If the log output includes exiting, status={Running:false Degraded:false Exiting:true ...} it is most likely due to one of:\nRunning 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:\ncolima start debug If successful, reset the default profile:\ncolima delete colima start Colima cannot access internet? Failure to access the internet is usually down to DNS. Try custom DNS servers:\ncolima start --dns 8.8.8.8 --dns 1.1.1.1 Verify connectivity:\ncolima 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.\nDocker 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.\nThis is resolved by mounting the volume on the VM first. Edit the configuration and add to the mounts section, then restart:\ncolima 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.\nFor v0.5.6 and earlier, an optional Ubuntu layer can be enabled:\ncolima start --layer=true With layer enabled, colima ssh routes to the layer. Access the underlying VM with --layer=false.\nAre Lima overrides supported? Yes, however this should only be done by advanced users.\nLima 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).\nSettings in override.yaml are applied before the instance config, while settings in default.yaml are applied after (as fallback defaults).\nNote: Overriding the image is not supported as Colima’s image includes bundled dependencies that would be missing in a user-specified image.\nExample: Adding provision scripts Provision scripts can be added via Lima overrides to run commands during VM boot:\n# $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:\ncolima start --edit - provision: [] + provision: + - mode: system + script: | + #!\/bin\/bash + set -eux -o pipefail + apt-get update && apt-get install -y curl Environment variables 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:\ncolima start --env MY_VAR=value ","description":"Frequently asked questions about Colima","headings":["general","how-does-colima-compare-to-lima","how-does-colima-compare-to-minikube-kind-k3d","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","networking","the-vms-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","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-1","docker-composebuildx-showing-runc-errors","docker-bind-mount-showing-empty-1","advanced","is-another-distro-supported","are-lima-overrides-supported","environment-variables"],"section":"docs","title":"FAQ","url":"\/docs\/faq\/"},{"content":"This incremental update introduces Docker Model Runner support and enhances AI functionality from v0.10.0.\nDocker Model Runner Support Docker Model Runner is now the default AI model runner backend, simplifying requirements. Ramalama remains available as an alternative.\n# run a model (uses docker runner by default) colima model run gemma3 # serve a model, chat interface available at localhost:8080 colima model serve gemma3 # use ramalama runner instead colima model run gemma3 --runner ramalama The runner can be configured via the --runner flag, --model-runner flag, or in the config file.\nOther Updates Respect for the DOCKER_CONFIG environment variable Upgrading To upgrade to v0.10.1:\nbrew upgrade colima For details on AI features introduced in this release cycle, see the v0.10.0 release notes.\nFor the full changelog, see the GitHub release.\n","description":"Colima v0.10.1 adds Docker Model Runner support as the default AI model runner backend.","headings":["docker-model-runner-support","other-updates","upgrading"],"section":"announcements","title":"Colima v0.10.1 Released","url":"\/announcements\/colima-v0.10.1-release\/"},{"content":"This release introduces AI support and other updates.\nAI is here Colima now has AI support.\nBy leveraging Krunkit and Ramalama, Colima is able to provide the ideal platform to run confined, isolated and secure GPU-powered AI workloads on Apple Silicon devices.\n# run a model colima model run gemma3 # serve a model, chat interface would be available at localhost:8080 colima model serve gemma3 # for more colima model --help Other Updates Addition of krunkit virtual machine type with GPU support: colima start --vm-type krunkit Incus instances are now reachable directly from the host if network address is enabled: colima start --network-address Containerd runtime (with nerdctl command) now inherits CONTAINERD_* and NERDCTL_* environment variables on the host Port forwarding can now be disabled by passing --port-forwarder=none to colima start Volume mounts can now be disabled by passing --mount=none to colima start Download mechanism has been reworked in native Go, eliminating dependency on curl and shasum on the host New after-boot and ready provision modes for provision scripts Runtime Updates Note: Container runtime versions can be updated manually by running the colima update command.\nDocker version updated to v29.2.0 Nerdctl version updated to v2.2.1 Incus version updated to v6.21 K3s version defaults to v1.35.0+k3s1 Upgrading To upgrade to v0.10.0:\nbrew upgrade colima For the latest updates in this release cycle, see the v0.10.1 release notes.\nFor the full changelog, see the GitHub release.\n","description":"Colima v0.10.0 introduces AI support with GPU-powered workloads on Apple Silicon.","headings":["ai-is-here","other-updates","runtime-updates","upgrading"],"section":"announcements","title":"Colima v0.10.0 Released","url":"\/announcements\/colima-v0.10.0-release\/"},{"content":"Colima v0.9.1 is a hotfix release to address disk error issues for a subset of users.\nFixes VM Disk Fix - Resolved root disk size being incorrectly set to zero K3s Enhancement - Added customizable listen port capability Upgrading To upgrade to v0.9.1:\nbrew upgrade colima For comprehensive details on new features introduced in this release cycle, see the v0.9.0 release notes.\nFor the full changelog, see the GitHub release.\n","description":"Colima v0.9.1 is a hotfix release addressing disk error issues.","headings":["fixes","upgrading"],"section":"announcements","title":"Colima v0.9.1 Released","url":"\/announcements\/colima-v0.9.1-release\/"},{"content":"We’re excited to announce the release of Colima v0.9.0, bringing new features, important fixes, and runtime updates.\nNew Features Bridged Network Mode A new --network-mode flag enables bridged networking alongside the default shared mode:\ncolima start --network-address --network-mode bridged Note: Bridged mode should only be used if required for your specific use case.\nPersistent Disk Storage Colima now separates container data onto a dedicated virtual machine disk. If an instance is deleted, the data disk persists and can be recovered on the next startup. To remove all data including the persistent disk, use:\ncolima delete --data Notable Fixes Template configuration loading has been reinstated DNS resolution for host.docker.internal improved across Docker, Containerd, and Kubernetes \/tmp\/colima removed as a default mount due to multi-user conflicts on macOS Fixed 386 architecture emulation with Rosetta enabled Configurable port forwarding (SSH or gRPC) New --network-preferred-route flag for network routing adjustments Runtime Updates Docker upgraded to v28.4.0 Nerdctl upgraded to v2.1.4 Incus upgraded to v6.16 K3s defaults to v1.33.4+k3s1 Upgrading To upgrade to v0.9.0:\nbrew upgrade colima After upgrading, update your runtime:\ncolima update For the full changelog, see the GitHub release.\n","description":"Colima v0.9.0 introduces bridged network mode, persistent disk storage, and runtime updates.","headings":["new-features","bridged-network-mode","persistent-disk-storage","notable-fixes","runtime-updates","upgrading"],"section":"announcements","title":"Colima v0.9.0 Released","url":"\/announcements\/colima-v0.9.0-release\/"},{"content":"We’re excited to announce that Colima has been selected for the GitHub Secure Open Source Fund.\nThe program supported 71 open source projects, bringing together 125 maintainers to improve security practices across the open source ecosystem. Colima was recognized among DevOps, build-system, and container tooling projects that power modern software development.\nThis selection reflects Colima’s growing importance in the container ecosystem and our commitment to security and reliability.\nRead the official announcement: Securing the supply chain at scale: Starting with 71 important open source projects\n","description":"Colima was selected for the GitHub Secure Open Source Fund alongside 70 other important open source projects.","headings":[],"section":"announcements","title":"Colima Selected for GitHub Secure Open Source Fund","url":"\/announcements\/colima-github-secure-open-source\/"},{"content":"Colima has a growing community of users and contributors. Join us to get help, share your experiences, and contribute to the project.\nGitHub Discussions \u2014 for general questions, ideas, tips, and community conversations Issues \u2014 for bug reports and feature requests Open an Issue \u2192 Slack Join the #colima channel on the CNCF Slack workspace for real-time discussions with the community.\nJoining the Slack Channel New to CNCF Slack? Sign up at slack.cncf.io Already a member? Log in at cloud-native.slack.com Search for and join the #colima channel Code Contribution Interested in contributing code to Colima? Check out the Contributing Guide for details on how to get started.\n","description":"Join the Colima community for support, discussions, and contributions","headings":["github","slack","joining-the-slack-channel","code-contribution"],"section":"","title":"Community","url":"\/community\/"}]