Docker Compose on Mac without Docker Desktop

Run docker compose on a Mac without Docker Desktop: brew install the docker CLI and Compose plugin, set cliPluginsExtraDirs, point it at Kiri or Colima, and fix "command not found".

Docker Compose runs fine on a Mac without Docker Desktop. You need three things: the docker command-line client, the Compose plugin, and an engine to talk to. With Homebrew that’s brew install docker docker-compose, one line in ~/.docker/config.json so the client can find the plugin, and an engine such as Kiri or Colima. Then docker compose version should answer. This post covers each step, and the errors people hit on the way: docker compose not found, docker-compose: command not found, the daemon socket, and empty bind mounts.

New to some of the terms? Our container basics explain them: image layers, registries and containerd vs Docker.

What Docker Compose is, and why there are two commands

Compose starts a set of containers from one file, compose.yaml: your services, their networks and their volumes, with one up and one down.

There are two generations, and that’s where most confusion starts:

  • Compose v1, the docker-compose command with a hyphen, was a Python tool. Docker’s migration guide says “Compose v1 is no longer maintained, and users should migrate to Compose v2” (migrate to Compose v2).
  • Compose v2 and later “is written in Go and integrates with the Docker CLI”. It’s a CLI plugin, a separate program called docker-compose that the docker client runs when you type docker compose with a space.

So docker compose doesn’t come from the engine or from Docker Desktop. It’s a file on your Mac that the docker client has to find. Docker Desktop puts it somewhere the client looks. Without Docker Desktop, you do that yourself.

Compose is a plug, the engine is a socket: docker compose works when two connections hold, the CLI finds the plugin and the CLI reaches an engine. On the left, the plug: the docker-compose plugin from brew install docker-compose, one Go binary that runs as docker compose up; the old Python docker-compose v1 is no longer maintained. In the middle, the strip: the docker CLI looks for plugins in cliPluginsExtraDirs, such as /opt/homebrew/lib/docker/cli-plugins, in your config folder ~/.docker/cli-plugins, and in system folders such as /usr/local/lib/docker/cli-plugins. It's set in ~/.docker/config.json; brew puts the plugin in its own folder, so the CLI can't see it until you list that folder. On the right, the socket: the docker context picks the engine, Kiri at ~/.kiri/run/docker.sock, Colima at ~/.colima/default/docker.sock, or the default /var/run/docker.sock with no context; check with docker context ls. Below, where it breaks: 1, plug not found, docker: unknown command: docker compose, fixed by adding the brew folder to cliPluginsExtraDirs. 2, socket dead, Cannot connect to the Docker daemon, fixed by starting the engine, switching context or setting DOCKER_HOST. 3, bind mount is empty, ./src:/app shows nothing, because the folder isn't shared into the engine's VM; move it or share it. Check both connections with docker compose version for the plug and docker info for the socket.

Step 1. Install the docker CLI and Compose with Homebrew

brew install docker docker-compose docker-buildx

What each formula is:

  • docker is the command-line client only, built from Docker’s docker/cli repository (formula). It has no engine: on its own, every command fails with “Cannot connect to the Docker daemon”.
  • docker-compose is current Compose (5.8.0 when we checked), Apache-2.0 licensed (formula). It installs a docker-compose program and links it into $(brew --prefix)/lib/docker/cli-plugins/.
  • docker-buildx is the BuildKit build plugin, installed the same way (formula). Optional, but docker compose build works better with it.

Don’t confuse these with the docker-desktop cask (once called docker), which is Docker Desktop itself (cask).

Step 2. Tell docker where the plugin is (cliPluginsExtraDirs)

Homebrew puts the plugin in its own folder, and the docker client doesn’t look there by default. The formula says so in its caveats: “Compose is a Docker plugin. For Docker to find the plugin, add “cliPluginsExtraDirs” to ~/.docker/config.json”.

The client looks for plugins in the folders listed in cliPluginsExtraDirs, in ~/.docker/cli-plugins, and in system folders starting with /usr/local/lib/docker/cli-plugins (docker/cli source). Two ways to connect them:

Add the folder to ~/.docker/config.json. If you don’t have the file yet:

mkdir -p ~/.docker
cat > ~/.docker/config.json <<EOF
{
  "cliPluginsExtraDirs": [
    "$(brew --prefix)/lib/docker/cli-plugins"
  ]
}
EOF

brew --prefix prints /opt/homebrew on Apple silicon and /usr/local on Intel Macs. If the file already exists, don’t overwrite it: open it and add the cliPluginsExtraDirs key next to what’s there, keeping the JSON valid.

Or link the plugin into your own plugin folder:

mkdir -p ~/.docker/cli-plugins
ln -sfn "$(brew --prefix)/lib/docker/cli-plugins/docker-compose" ~/.docker/cli-plugins/docker-compose
ln -sfn "$(brew --prefix)/lib/docker/cli-plugins/docker-buildx"  ~/.docker/cli-plugins/docker-buildx

Either way, check:

docker compose version
# Docker Compose version v5.8.0

This works before any engine is running, because it only asks the plugin for its version. It proves the plugin is found, nothing more.

Step 3. Point docker at an engine

Containers on a Mac need a Linux VM, because macOS has no Linux kernel. Docker Desktop provides one. Here are two free replacements.

Kiri

Kiri is our open-source container engine for Apple silicon Macs (macOS 14 or later), Linux and Windows, in beta. It serves the Docker Engine API from its own small VM, so docker compose talks to it like any engine. Install the app from the download page, or:

curl -fsSL https://runkiri.com/install.sh | bash

Kiri brings its own docker CLI, Compose and buildx, so Steps 1 and 2 are optional with Kiri. Its setup adds its Compose and buildx to cliPluginsExtraDirs in ~/.docker/config.json and creates a kiri docker context at unix://$HOME/.kiri/run/docker.sock (install docs). Its docker goes at the end of your PATH, so a Homebrew docker you already have keeps priority. On a Mac with no other engine, Kiri also becomes the default context.

docker context use kiri
docker compose up -d
kiri compose ps          # always talks to Kiri, whatever context is selected

Compose features that work on Kiri include depends_on with condition: service_healthy, healthchecks, several networks per service, network_mode: service:x and docker compose build through BuildKit. Each service also answers at http://<service>.<project>.kiri.localhost with no setup (Compose on Kiri). In our 2 November 2026 run on one Apple silicon Mac, docker run --rm alpine true took 22 ms on Kiri, 152 ms on Colima and 178 ms on Docker Desktop (benchmarks).

Colima

Colima is a free, MIT-licensed command-line tool that runs a Linux VM with Docker’s engine in it. Its README says the “Docker client is required for Docker runtime. Installable with brew install docker”, which is Step 1.

brew install colima
colima start
docker compose up -d

The default VM has 2 CPUs, 2 GiB of memory and 100 GiB of disk. Colima “makes itself the default Docker context on startup”, and its socket is at $HOME/.colima/default/docker.sock (Colima FAQ). Colima doesn’t install Compose for you, so you need Steps 1 and 2.

Check the whole chain

docker context ls        # the * marks the engine docker will use
docker info --format '{{.ServerVersion}}'

Then a real project. Save this as compose.yaml:

services:
  web:
    image: nginx:alpine
    ports: ["8080:80"]
  cache:
    image: redis:7-alpine
docker compose up -d
curl -sI localhost:8080 | head -1    # HTTP/1.1 200 OK
docker compose down

Common Docker Compose problems on a Mac without Docker Desktop

“unknown command: docker compose”

Current docker clients print docker: unknown command: docker compose. Older ones print docker: 'compose' is not a docker command. If you added a flag, you may see unknown shorthand flag: 'd' in -d instead, because the client tried to read -d as its own flag.

All three mean the client didn’t find the plugin. Check:

ls -l "$(brew --prefix)/lib/docker/cli-plugins/"
cat ~/.docker/config.json

Then add cliPluginsExtraDirs or the link from Step 2. A typo in config.json, such as a trailing comma, also breaks it.

“docker-compose: command not found”

That’s the hyphenated v1 name. Either type docker compose with a space, which is the current form, or run brew install docker-compose: the formula also installs a docker-compose program on your PATH, so old scripts that call docker-compose up keep working with current Compose.

“Cannot connect to the Docker daemon at unix:///var/run/docker.sock”

Compose found itself but not an engine. Either the engine isn’t running (colima start, or open Kiri), or the current context points somewhere dead. Run docker context ls and switch. Some tools ignore contexts and only read /var/run/docker.sock or DOCKER_HOST. For those:

export DOCKER_HOST=unix://$HOME/.kiri/run/docker.sock          # Kiri
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock    # Colima

Cannot connect to the Docker daemon has the full checklist.

Bind mounts that come up empty

A bind mount like ./src:/app needs the folder shared from your Mac into the engine’s VM. When it isn’t, the container usually starts anyway, with an empty /app.

  • Kiri shares paths under /Users, /Volumes, /private, /tmp and /var/folders over virtiofs. Any other absolute path is the VM’s own (volumes and mounts).
  • Colima: a bind mount from outside /Users/$USER “will start without raising any errors but the mapped mountpoint on the container will be empty”. Add the folder to the mounts section of ~/.colima/default/colima.yaml and run colima restart (Colima FAQ). Colima also doesn’t support mount paths with spaces.

If mounts work but feel slow, see Why Docker bind mounts are slow on a Mac. To be fair to Colima, it read a 1 GB file from a bind mount at 5235 MB/s against Kiri’s 1724 MB/s in that same benchmark run. Kiri led every other row we measured.

Which engine should you pick?

  • You want a free CLI-only engine with Docker’s own dockerd: Colima, with Steps 1 and 2.
  • You want Compose, buildx and the CLI in one install, a native app, and names like web.myapp.kiri.localhost: Kiri on an Apple silicon Mac, keeping in mind it’s in beta.
  • You’re on an Intel Mac: Kiri doesn’t run there, so use Colima.

Moving off Docker Desktop entirely? Read How to switch from Docker Desktop and Docker Desktop alternatives compared. If your images are amd64-only, amd64 images on Apple silicon covers that, and Kiri vs Docker Desktop compares the two side by side. On Windows, see How to run Docker on Windows without Docker Desktop.

In short

  • Compose is a CLI plugin called docker-compose, run as docker compose. The old Python v1 is no longer maintained.
  • Install it with Homebrew: brew install docker docker-compose. The docker formula is the client only.
  • Point the client at the plugin: add "$(brew --prefix)/lib/docker/cli-plugins" to cliPluginsExtraDirs in ~/.docker/config.json, or link it into ~/.docker/cli-plugins.
  • Add an engine: Kiri brings its own CLI and Compose and sets up the plugin folder itself; Colima needs the Homebrew client and plugin.
  • Check with docker compose version (finds the plugin) and docker info (reaches the engine).
  • Empty bind mounts mean the folder isn’t shared into the VM. Keep projects under your home folder.