Migrating a Team From Docker Desktop to Colima

After uninstalling Docker Desktop and installing Colima, the first docker compose up fails with Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? — and once that is fixed, hot reload is slow, docker buildx is missing, and the local database is empty. None of these are Colima bugs; they are the four places where Docker Desktop did something implicitly that now has to be configured. This page is a repeatable migration for a whole team, under the container runtime selection and tuning topic.

Colima is a good default replacement because it runs the real Docker engine inside a Lima VM, is free and open source, and is driven entirely from the command line, which makes it easy to script into onboarding. The steps below assume macOS 13 or later.

Diagnostic

Before migrating, capture what the current setup depends on. After migrating, the same script shows exactly which assumption broke:

#!/usr/bin/env bash
set -euo pipefail
echo "context: $(docker context show 2>&1)"
echo "socket:  ${DOCKER_HOST:-unset}; /var/run/docker.sock -> $(readlink /var/run/docker.sock 2>/dev/null || echo missing)"
docker info --format 'engine={{.ServerVersion}} mem={{.MemTotal}} cpus={{.NCPU}}' 2>&1 | tail -1
docker buildx version 2>&1 | head -1
docker volume ls --format '{{.Name}}' | head -20

Expected bad output immediately after removing Docker Desktop:

context: desktop-linux
socket:  unset; /var/run/docker.sock -> missing
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
docker: 'buildx' is not a docker command.

The CLI still points at the desktop-linux context, the global socket symlink that Docker Desktop maintained is gone, and the buildx plugin that shipped inside Docker Desktop was removed with it.

Root cause

Docker Desktop is more than an engine: it installs the CLI and plugins, creates a desktop-linux Docker context, maintains /var/run/docker.sock as a symlink into its VM, provides host.docker.internal, and keeps images and volumes in its own disk image. Colima provides an engine and a context named colima, with its socket at ~/.colima/default/docker.sock. Tools that follow the current context (the Docker CLI, Compose) work once the context switches; tools that hard-code /var/run/docker.sock (Testcontainers, some IDE plugins, older CI scripts) do not. Volumes stay inside Docker Desktop's VM, so they have to be exported before Docker Desktop is removed, not after.

There is also an ordering trap in how teams usually attempt this. The instinct is to uninstall Docker Desktop first, "to avoid conflicts", and then install Colima. That destroys the only copy of every developer's local volumes and removes the plugins before replacements exist, so the first hour on the new runtime is spent recovering rather than validating. Running both side by side for a week costs a little disk space and removes all of that risk: the developer can switch contexts back and forth, compare behaviour on the real stack, and uninstall Docker Desktop only once nothing depends on it. The migration below follows that order deliberately, and the same order makes a rollback trivial if a blocker appears during the trial week.

Resolution

1. Export volume data while Docker Desktop still runs. Use each database's native dump tool; copying raw volume directories between engine versions is unreliable.

#!/usr/bin/env bash
set -euo pipefail
mkdir -p ~/docker-migration
docker compose exec -T db pg_dumpall -U postgres > ~/docker-migration/postgres.sql
docker image ls --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>' > ~/docker-migration/images.txt
wc -l ~/docker-migration/*

2. Install Colima and standalone CLI plugins. Homebrew's docker-compose and docker-buildx formulae install as CLI plugins once the plugin directory is registered:

#!/usr/bin/env bash
set -euo pipefail
brew install colima docker docker-compose docker-buildx docker-credential-helper
mkdir -p ~/.docker
jq -n --arg d "$(brew --prefix)/lib/docker/cli-plugins" '{cliPluginsExtraDirs: [$d]}' > ~/.docker/config.json.new
[ -f ~/.docker/config.json ] && jq -s '.[0] * .[1]' ~/.docker/config.json ~/.docker/config.json.new > ~/.docker/config.json.tmp && mv ~/.docker/config.json.tmp ~/.docker/config.json || mv ~/.docker/config.json.new ~/.docker/config.json
rm -f ~/.docker/config.json.new

Check ~/.docker/config.json for a "credsStore": "desktop" entry left behind by Docker Desktop and change it to "osxkeychain"; otherwise every docker pull from a private registry fails with docker-credential-desktop: executable file not found.

3. Start the VM with the team's settings. vz uses Apple's Virtualization.framework, which enables virtiofs mounts and Rosetta for amd64 images:

#!/usr/bin/env bash
set -euo pipefail
colima start --cpu 4 --memory 6 --disk 80 \
  --vm-type vz --vz-rosetta --mount-type virtiofs
docker context use colima
docker info --format '{{.Name}} {{.OperatingSystem}}'

4. Restore the socket path for tools that hard-code it. Either export DOCKER_HOST in the shell profile or recreate the global symlink:

#!/usr/bin/env bash
set -euo pipefail
sudo ln -sf "$HOME/.colima/default/docker.sock" /var/run/docker.sock
echo 'export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock' >> ~/.zshrc

5. Restore data and rebuild images. Start the database service alone, load the dump, then bring up the rest:

#!/usr/bin/env bash
set -euo pipefail
docker compose up -d db
until docker compose exec -T db pg_isready -U postgres; do sleep 1; done
docker compose exec -T db psql -U postgres < ~/docker-migration/postgres.sql
docker compose up -d --build

Expected output

$ docker context show
colima
$ docker info --format 'engine={{.ServerVersion}} mem={{.MemTotal}} cpus={{.NCPU}}'
engine=27.1.1 mem=6213541888 cpus=4
$ docker buildx version
github.com/docker/buildx v0.16.2
$ docker compose ps --format '{{.Service}} {{.State}}'
api running
db running
web running

The engine runs inside Colima's VM with the requested resources, buildx is available as a plugin, and every service is up with its restored data.

Prevention

1. Script it once for everyone. Put steps 2–4 in a scripts/runtime-colima.sh invoked by make bootstrap, so the second through fiftieth migrations are one command and identical.

2. Check the context in the doctor script. Fail with a clear message when the context is still desktop-linux or the socket is missing — the two most common post-migration states.

3. Pin Colima's VM settings in the repo (runtime.env) and start the VM from those values, so a developer who deletes and recreates the VM gets the team's configuration rather than Colima's 2 CPU / 2 GiB defaults.

Platform caveats

macOS (Intel): --vm-type vz requires macOS 13+. On older Intel Macs Colima falls back to QEMU with sshfs mounts, which are much slower; move dependency directories to named volumes before migrating those machines.

Apple Silicon (ARM64): --vz-rosetta requires Rosetta 2 (softwareupdate --install-rosetta --agree-to-license). Without it, amd64 images fall back to QEMU emulation and run several times slower.

host.docker.internal: Colima resolves it inside containers on recent versions. If an older version does not, add extra_hosts: ["host.docker.internal:host-gateway"] to the service.

WSL2 / Linux: Colima is a macOS-first tool. On Linux, install Docker Engine directly; on Windows, Docker Engine inside WSL2 is the closest equivalent.

Rollback

Docker Desktop can be reinstalled at any time; switching back is a context change. Keep the dump files until the migration is confirmed:

#!/usr/bin/env bash
set -euo pipefail
colima stop
docker context use desktop-linux
docker compose up -d

Frequently Asked Questions

Related

• Compare Colima with OrbStack and Docker Desktop on Apple Silicon
• Restore local databases into the new engine
• Script the runtime into one-command setup