Docker Compose command not found: oplossing voor Mac, Linux en Windows

Als je bij het uitvoeren van docker-compose of docker compose de melding krijgt “command not found”, betekent dat bijna altijd één van deze dingen:

1. Docker is niet geïnstalleerd (of niet goed geïnstalleerd).
2. Docker is wel geïnstalleerd, maar staat niet in je PATH (je shell kan het commando niet vinden).
3. Je gebruikt de “verkeerde” variant: Compose v1 (docker-compose) versus Compose v2 (docker compose).
4. Je gebruikt een shell/terminal die niet dezelfde omgeving (PATH) heeft als waar Docker wél werkt.
5. Op Windows: je zit in PowerShell/CMD zonder Docker Desktop, of WSL/Windows PATH is niet goed gekoppeld.

Deze tutorial helpt je stap voor stap, met echte commando’s en diepgaande uitleg, voor macOS, Linux en Windows. Aan het einde kun je Compose betrouwbaar gebruiken, en weet je ook waarom het misging.

1) Begrijp eerst het verschil: docker-compose (v1) vs docker compose (v2)

Compose v1 (oud)

• Commando: docker-compose
• Losstaande binary (Python-gebaseerd in oudere varianten).
• Wordt steeds minder gebruikt en is op veel systemen niet standaard aanwezig.

Compose v2 (nieuw, aanbevolen)

• Commando: docker compose (met spatie)
• Is een Docker CLI plugin.
• Wordt meegeleverd met Docker Desktop (Mac/Windows) en vaak ook met recente Docker Engine pakketten op Linux.

Belangrijk: Als je tutorial of projectdocumentatie docker-compose up zegt, maar jij hebt Compose v2, dan werkt meestal dit:

docker compose up

En omgekeerd: als je alleen docker-compose probeert, maar je installatie levert alleen docker compose, dan krijg je “command not found”.

Snel testen welke je hebt

Voer deze commando’s uit:

docker --version
docker compose version
docker-compose --version

Interpretatie:

• Werkt docker compose version? Dan heb je Compose v2.
• Werkt docker-compose --version? Dan heb je Compose v1 (of een compatibiliteitswrapper).
• Werkt geen van beide? Dan is Compose niet geïnstalleerd of niet vindbaar via PATH.

2) Diagnose: wat betekent “command not found” precies?

Op macOS/Linux (bash/zsh)

“command not found” betekent: je shell zoekt in de directories die in PATH staan, maar vindt geen executable met die naam.

Check je PATH:

echo "$PATH"

Check of Docker/Compose ergens staat:

which docker
which docker-compose
which docker

(De dubbele which docker is niet nodig; ik laat hieronder betere checks zien.)

Beter:

command -v docker
command -v docker-compose
command -v docker

Als command -v docker niets teruggeeft, is Docker niet vindbaar.

Op Windows (PowerShell)

Je ziet vaak:

• docker : The term 'docker' is not recognized...
• docker-compose : The term 'docker-compose' is not recognized...

Check:

Get-Command docker
Get-Command docker-compose
Get-Command "docker"

Als Get-Command docker niets vindt, is Docker CLI niet in PATH of niet geïnstalleerd.

3) Oplossing op macOS

3.1 Installeer Docker Desktop (aanbevolen)

De meest betrouwbare manier op Mac is Docker Desktop. Compose v2 zit daar standaard bij.

1. Download en installeer Docker Desktop.
2. Start Docker Desktop (belangrijk: de daemon moet draaien).
3. Open een nieuwe terminal.

Test:

docker version
docker compose version

Als docker version werkt maar docker compose version niet, is er iets mis met de plugin-installatie of PATH.

3.2 Controleer of Docker Desktop draait

Als Docker niet draait, krijg je soms niet “command not found” maar wel connectiefouten. Toch is het goed dit te checken:

docker info

Als dit klaagt over “Cannot connect to the Docker daemon”, start Docker Desktop.

3.3 PATH-problemen op macOS (zsh, bash, iTerm, VS Code)

Soms is Docker wel geïnstalleerd, maar je terminal-sessie ziet het niet. Dit gebeurt bijvoorbeeld als:

• je een andere shell gebruikt,
• je terminal app een afwijkende login shell heeft,
• je PATH in .zshrc of .bash_profile overschrijft.

Check waar docker staat:

ls -l /usr/local/bin/docker
ls -l /usr/bin/docker
ls -l /Applications/Docker.app

Docker Desktop plaatst meestal symlinks naar /usr/local/bin of gebruikt een andere route afhankelijk van versie en CPU (Intel/Apple Silicon).

Herstart je terminal na installatie. PATH wordt vaak pas bij een nieuwe sessie goed geladen.

3.4 Als je per se docker-compose wilt (alias naar v2)

Als je Compose v2 hebt, maar scripts verwachten docker-compose, kun je een alias maken:

echo 'alias docker-compose="docker compose"' >> ~/.zshrc
source ~/.zshrc

Voor bash:

echo 'alias docker-compose="docker compose"' >> ~/.bashrc
source ~/.bashrc

Let op: aliases werken meestal alleen interactief. Voor scripts is een echte wrapper soms beter.

Een wrapper script (macOS/Linux):

sudo tee /usr/local/bin/docker-compose >/dev/null <<'EOF'
#!/usr/bin/env bash
exec docker compose "$@"
EOF
sudo chmod +x /usr/local/bin/docker-compose

Test:

docker-compose version

4) Oplossing op Linux

Linux is het platform waar “command not found” het vaakst voorkomt, omdat er meerdere installatiemethoden zijn (distro packages, Docker repo, snap, handmatig).

4.1 Check eerst: is Docker Engine geïnstalleerd?

docker --version

Als dit “command not found” geeft: installeer Docker Engine.

Debian/Ubuntu (via officiële Docker repository)

Verwijder mogelijk conflicterende oude pakketten:

sudo apt-get remove -y docker docker-engine docker.io containerd runc

Installeer prerequisites:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

Docker GPG key en repo:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Repo toevoegen (Ubuntu; pas $(. /etc/os-release && echo "$VERSION_CODENAME") aan indien nodig):

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Installeren:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Let op die laatste twee:

• docker-buildx-plugin
• docker-compose-plugin ← dit is Compose v2

Test:

docker version
docker compose version

Fedora/RHEL/CentOS (conceptueel)

Veel distros hebben vergelijkbare pakketten. Belangrijk is dat je docker-compose-plugin installeert (Compose v2).

4.2 Compose v2 plugin ontbreekt: installeer docker-compose-plugin

Als docker wel werkt, maar docker compose niet:

docker compose version

Krijg je iets als “docker: ‘compose’ is not a docker command”? Dan mist de plugin.

Op Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y docker-compose-plugin

Test opnieuw:

docker compose version

4.3 Compose v1 installeren (alleen als je het echt nodig hebt)

Sommige oude omgevingen verwachten docker-compose. Je kunt Compose v1 installeren via distro packages, maar dat is vaak oud. Beter is: maak een wrapper naar v2 (zie eerder) of installeer de standalone binary.

Een moderne aanpak is: gebruik v2 en maak docker-compose compatibel.

Wrapper:

sudo tee /usr/local/bin/docker-compose >/dev/null <<'EOF'
#!/usr/bin/env bash
exec docker compose "$@"
EOF
sudo chmod +x /usr/local/bin/docker-compose

4.4 PATH en permissies op Linux

PATH check

command -v docker
command -v docker-compose

Als docker in /usr/bin/docker staat, maar je shell ziet het niet, dan is je PATH kapot. Dit is zeldzaam, maar kan gebeuren als je PATH overschrijft in ~/.bashrc of ~/.profile.

Permissies: “permission denied” vs “command not found”

Soms lijkt het op “werkt niet”, maar het is geen “command not found”. Als je ziet:

• permission denied
• of Docker vraagt om root

Dan is Docker wel gevonden, maar je gebruiker mag de socket niet gebruiken.

Voeg je user toe aan de docker groep:

sudo usermod -aG docker $USER

Log uit en weer in (of herstart je sessie), en test:

docker run --rm hello-world

4.5 Snap-installatie: valkuilen

Als je Docker via snap installeert, kunnen plugins en paden anders werken. Als je problemen hebt met Compose, overweeg de officiële Docker repo (zoals hierboven) voor minder verrassingen.

5) Oplossing op Windows

Op Windows zijn er grofweg drie manieren waarop je Docker/Compose gebruikt:

1. Docker Desktop (aanbevolen)
2. Docker in WSL2 (met of zonder Docker Desktop integratie)
3. “Native” Docker Engine zonder Desktop (minder gebruikelijk)

5.1 Docker Desktop installeren (aanbevolen)

Installeer Docker Desktop en start het. Compose v2 zit inbegrepen.

Test in PowerShell:

docker version
docker compose version

Als je docker compose hebt, maar docker-compose niet, is dat normaal.

5.2 PATH-problemen op Windows

Als PowerShell zegt dat docker niet herkend wordt:

1. Sluit alle terminals.
2. Open PowerShell opnieuw.
3. Test opnieuw:

docker --version

Docker Desktop voegt meestal C:\Program Files\Docker\Docker\resources\bin toe aan PATH. Je kunt je PATH bekijken:

$env:Path -split ';'

Als Docker niet in PATH staat, herinstalleer Docker Desktop of voeg het pad handmatig toe (Systeeminstellingen → Environment Variables).

5.3 docker-compose compatibiliteit op Windows

Veel projecten gebruiken nog docker-compose. Je kunt vaak simpelweg overstappen op:

docker compose up -d

Wil je toch docker-compose gebruiken, dan zijn er opties:

• Sommige Docker Desktop versies leveren een docker-compose shim mee.
• Anders kun je een PowerShell function toevoegen aan je profiel.

Open je PowerShell profielpad:

$PROFILE

Bewerk het bestand (maak aan als het niet bestaat) en voeg toe:

function docker-compose { docker compose @args }

Herstart PowerShell en test:

docker-compose version

5.4 WSL2 scenario’s: waar voer je de commando’s uit?

Veel verwarring komt doordat je Docker in Windows hebt, maar je commando’s in WSL uitvoert (Ubuntu in WSL), of andersom.

Scenario A: Docker Desktop + WSL integratie

• Je installeert Docker Desktop op Windows.
• Je zet WSL integration aan voor je distro.
• In WSL werkt dan:

docker version
docker compose version

Als docker in WSL “command not found” is, staat de integratie uit of is je distro niet aangevinkt.

Scenario B: Docker Engine binnen WSL (zonder Desktop)

Dan moet je Docker Engine en compose plugin in WSL zelf installeren (Linux stappen volgen). In dat geval is Windows PowerShell mogelijk niet relevant.

5.5 Controleer context en endpoints

Soms werkt docker wel, maar niet zoals je verwacht. Check je context:

docker context ls
docker context show

En in WSL:

docker context ls
docker context show

6) Veelvoorkomende fouten en hun gerichte fixes

Fout: docker: 'compose' is not a docker command

Betekenis: Docker CLI werkt, maar de Compose plugin ontbreekt.

Fix (Linux):

sudo apt-get install -y docker-compose-plugin

Fix (Mac/Windows): Update Docker Desktop naar een recente versie en herstart.

Fout: docker-compose: command not found

Betekenis: Compose v1 binary ontbreekt. Je hebt mogelijk Compose v2 (docker compose).

Fix: Gebruik:

docker compose up

Of maak alias/wrapper zoals eerder beschreven.

Fout: docker: command not found

Betekenis: Docker CLI ontbreekt of PATH is fout.

Fix:

• Installeer Docker (Desktop of Engine).
• Herstart terminal.
• Check PATH.

Fout: Cannot connect to the Docker daemon

Betekenis: Docker is wél gevonden, maar de daemon draait niet of je hebt geen rechten.

Fix:

• Mac/Windows: start Docker Desktop.
• Linux: start service:

sudo systemctl status docker
sudo systemctl start docker
sudo systemctl enable docker

En permissies (docker group):

sudo usermod -aG docker $USER

7) Praktische test: een werkende Compose run

Maak een map en een minimal project. (Je hebt een compose.yaml nodig; dit is géén frontmatter, maar een echte Compose file.)

mkdir -p ~/compose-test
cd ~/compose-test

Maak compose.yaml met een simpele container die een webserver draait. (Gebruik je editor; hieronder een voorbeeldinhoud.)

Inhoud van compose.yaml:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Start:

docker compose up -d

Check:

docker compose ps

Test in je browser:

• http://localhost:8080

Stop en ruim op:

docker compose down

Als dit werkt, is Compose correct geïnstalleerd en vindbaar.

8) Dieper: hoe Docker Compose gevonden wordt (CLI plugins en PATH)

Compose v2 als CLI plugin

Bij Compose v2 is compose geen los commando, maar een subcommand van docker. De Docker CLI zoekt plugins in specifieke directories, afhankelijk van OS.

Je kunt zien welke plugins Docker ziet met:

docker info

En soms ook:

docker --help

Als compose daar niet tussen staat, mist de plugin of staat hij niet op de juiste plek.

Waarom docker compose kan werken terwijl docker-compose niet werkt

• docker compose → onderdeel van Docker CLI + plugin.
• docker-compose → aparte executable die in PATH moet staan.

Daarom is het heel normaal dat alleen docker compose werkt op moderne installaties.

9) Migratie: van docker-compose naar docker compose in bestaande projecten

De meeste commando’s zijn identiek, alleen de spatie verschilt.

Voorbeelden:

# oud
docker-compose up -d
docker-compose logs -f
docker-compose exec web sh
docker-compose down -v

# nieuw
docker compose up -d
docker compose logs -f
docker compose exec web sh
docker compose down -v

Let op: sommige flags en edge cases verschillen licht tussen v1 en v2, maar voor 95% van de projecten is het een drop-in vervanging.

10) Checklist per platform (snelle samenvatting)

macOS

1. Installeer Docker Desktop.
2. Start Docker Desktop.
3. Test:

   docker version
   docker compose version

4. Gebruik docker compose ... of maak alias/wrapper voor docker-compose.

Linux (Debian/Ubuntu)

1. Installeer Docker Engine + compose plugin:

   sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2. Test:

   docker version
   docker compose version

3. Optioneel: wrapper voor docker-compose.

Windows

1. Installeer Docker Desktop.
2. Herstart terminal.
3. Test:

   docker version
   docker compose version

4. WSL: zet integratie aan of installeer Docker in WSL.

11) Extra troubleshooting: als het nog steeds niet lukt

11.1 Verzamel diagnostische info

Voer uit en plak de output (zonder gevoelige info) als je hulp vraagt:

macOS/Linux:

uname -a
echo "$SHELL"
echo "$PATH"
command -v docker
docker --version
docker compose version
docker-compose --version

Windows PowerShell:

$PSVersionTable.PSVersion
$env:Path
Get-Command docker -ErrorAction SilentlyContinue
docker --version
docker compose version

11.2 Meerdere Docker-installaties tegelijk

Soms heb je Docker via verschillende bronnen geïnstalleerd (bijv. oude docker.io package én Docker repo). Dan kan je per ongeluk een oude docker binary gebruiken zonder plugins.

Check welk pad je gebruikt:

which docker
ls -l "$(which docker)"

Op Windows:

(Get-Command docker).Source

Verwijder dubbele installaties en houd één bron aan.

12) Conclusie

“Docker Compose command not found” is bijna nooit een mysterie: het is meestal een mismatch tussen Compose v1 (docker-compose) en Compose v2 (docker compose), of een installatie/PATH-probleem. Door systematisch te testen:

• Bestaat docker?
• Bestaat docker compose?
• Bestaat docker-compose?
• Draait de daemon?
• Zit je in de juiste omgeving (Windows vs WSL)?

…kun je het probleem snel isoleren en oplossen.

Als je wilt, kan ik je situatie gericht debuggen: zeg welk OS je gebruikt, welke terminal (PowerShell/WSL/zsh), en plak de output van docker --version en docker compose version.