Docker Compose : commande introuvable — correctifs sur Mac, Linux et Windows

Ce tutoriel explique en profondeur pourquoi l’erreur docker-compose: commande introuvable (ou variantes comme docker compose: command not found, 'docker-compose' n’est pas reconnu en tant que commande interne) apparaît, et comment la corriger proprement sur macOS, Linux et Windows.
On couvrira aussi les différences entre Docker Compose v1 (docker-compose) et Docker Compose v2 (docker compose), les problèmes de PATH, les installations via Docker Desktop, paquets, pip, et les cas fréquents en CI, WSL, zsh/bash, etc.

1) Comprendre l’erreur : `docker-compose` vs `docker compose`

1.1 Docker Compose v1 (historique)

Commande : docker-compose (binaire séparé)
Souvent installé via :
- paquet système (Linux),
- pip (Python),
- téléchargement GitHub (binaire),
- ou inclus dans certaines distributions Docker plus anciennes.

1.2 Docker Compose v2 (actuel)

Commande : docker compose (sous-commande intégrée au CLI Docker via un plugin)
Généralement fourni avec :
- Docker Desktop (Mac/Windows),
- plugin docker-compose-plugin (Linux),
- ou installation manuelle du plugin.

1.3 Pourquoi “commande introuvable” arrive

Les causes typiques :

Compose n’est pas installé (ni v1 ni v2).
Vous utilisez la mauvaise commande :
- Compose v2 est installé, mais vous tapez docker-compose.
- Compose v1 est installé, mais vous tapez docker compose (plus rare aujourd’hui).
Problème de PATH :
- binaire installé mais non accessible,
- shell non rechargé,
- installation dans un répertoire non listé.
Docker CLI installé sans plugins (Linux minimal, serveur).
Contexte Windows/WSL confus :
- Docker Desktop côté Windows, commande lancée dans WSL sans intégration,
- ou inversement.
Alias/compatibilité manquante :
- certains scripts attendent docker-compose.

2) Diagnostic rapide (toutes plateformes)

Ouvrez un terminal et exécutez ces commandes dans l’ordre.

2.1 Vérifier Docker

docker --version
docker info

Si docker --version échoue : Docker n’est pas installé ou pas dans le PATH.
Si docker info échoue : Docker est installé mais le daemon ne tourne pas (ou permissions).

2.2 Vérifier Compose v2

docker compose version

Si ça affiche une version (ex. Docker Compose version v2.24.6) : Compose v2 est OK.

2.3 Vérifier Compose v1

docker-compose --version

Si ça affiche une version (ex. docker-compose version 1.29.2) : Compose v1 est OK.

2.4 Identifier ce qui est réellement exécuté

Sur macOS/Linux :

which docker
which docker-compose
type docker
type docker-compose

Sur Windows PowerShell :

Get-Command docker
Get-Command docker-compose

But : savoir si la commande existe, et d’où elle vient.

3) Correctif universel : utiliser la bonne commande

Si docker compose version fonctionne mais docker-compose échoue, vous êtes dans le cas le plus fréquent : Compose v2 est installé et Compose v1 ne l’est pas.

3.1 Solution immédiate

Utilisez :

docker compose up -d

au lieu de :

docker-compose up -d

3.2 Rendre vos scripts compatibles (alias)

Si vous avez des scripts/outils qui appellent docker-compose, vous pouvez créer un alias.

macOS / Linux (bash/zsh)

Ajoutez dans ~/.bashrc, ~/.bash_profile ou ~/.zshrc :

alias docker-compose='docker compose'

Rechargez :

source ~/.zshrc
# ou
source ~/.bashrc

Windows PowerShell (alias temporaire)

Set-Alias docker-compose "docker"

Mais attention : docker-compose up deviendrait docker up (ce qui ne marche pas). PowerShell ne gère pas un alias multi-mots comme docker compose de façon simple.

Approche recommandée : créer un petit script docker-compose.ps1 dans un dossier du PATH :

Créez un fichier docker-compose.ps1 contenant :

docker compose @args

Puis placez-le dans un répertoire présent dans $env:Path (ex. C:\Users\<Vous>\bin) et ajoutez ce répertoire au PATH si nécessaire.

4) macOS : causes et solutions

4.1 Cas le plus courant : Docker Desktop installé, mais vous tapez `docker-compose`

Docker Desktop fournit Compose v2. Vérifiez :

docker compose version

Si OK, utilisez docker compose ... ou créez l’alias docker-compose='docker compose'.

4.2 Docker Desktop non installé / Docker CLI seul

Si docker n’existe pas :

Installez Docker Desktop (recommandé sur macOS) :
- Téléchargement : https://www.docker.com/products/docker-desktop/

Après installation, vérifiez :

docker --version
docker compose version

4.3 Problèmes de PATH sur macOS (zsh)

Sur macOS récent, le shell par défaut est zsh. Si vous avez installé des outils via Homebrew, assurez-vous que Homebrew est bien dans le PATH :

Apple Silicon (M1/M2/M3) :

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel :

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

Ensuite, vérifiez :

echo $PATH
which docker

4.4 Installation via Homebrew (cas avancé)

En pratique, sur macOS, Compose est surtout via Docker Desktop. Mais si vous utilisez Docker CLI via brew, vous pouvez installer le plugin Compose selon la formule disponible (cela évolue). Vérifiez d’abord :

docker compose version

Si absent, la voie la plus simple reste Docker Desktop.

5) Linux : installer Compose v2 correctement (recommandé)

Sur Linux, l’erreur “commande introuvable” vient souvent d’une installation Docker “Engine” sans plugin Compose.

5.1 Vérifier si le plugin est présent

docker compose version

Si vous obtenez :

docker: 'compose' is not a docker command.
=> le plugin n’est pas installé.

5.2 Installation via paquets (Debian/Ubuntu)

Sur Debian/Ubuntu, installez le plugin officiel :

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

Vérifiez :

docker compose version

Remarque sur les dépôts Docker

Selon votre distribution, il peut être préférable d’installer Docker depuis les dépôts officiels Docker (plutôt que ceux de la distribution). Mais pour Compose, le paquet docker-compose-plugin est la méthode moderne.

5.3 Installation via paquets (Fedora/RHEL/CentOS)

Selon la distribution :

sudo dnf install -y docker-compose-plugin

Puis :

docker compose version

5.4 Installation manuelle du plugin (si paquet indisponible)

Docker Compose v2 est un plugin placé dans un répertoire spécifique.

Répertoire plugin utilisateur :

~/.docker/cli-plugins/

Répertoire plugin système (souvent) :

/usr/local/lib/docker/cli-plugins/
/usr/lib/docker/cli-plugins/ (selon distro)

Exemple d’installation manuelle (adaptez la version et l’architecture) :

Créer le dossier :

mkdir -p ~/.docker/cli-plugins

Télécharger le binaire (exemple Linux x86_64) :

curl -SL https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-linux-x86_64 \
  -o ~/.docker/cli-plugins/docker-compose

Rendre exécutable :

chmod +x ~/.docker/cli-plugins/docker-compose

Vérifier :

docker compose version

5.5 Permissions Docker : ne pas confondre avec “commande introuvable”

Parfois la commande existe, mais vous avez :

permission denied
ou Cannot connect to the Docker daemon

Ajoutez votre utilisateur au groupe docker (si pertinent) :

sudo usermod -aG docker $USER
newgrp docker

Puis test :

docker ps

6) Linux : Compose v1 (ancien) — quand et comment

Vous pouvez encore rencontrer des environnements où docker-compose est attendu.

6.1 Installer `docker-compose` (v1) via paquet (selon distro)

Sur certaines distros :

sudo apt install -y docker-compose
docker-compose --version

Mais attention : ce paquet peut être ancien.

6.2 Installer via pip (déconseillé sauf cas précis)

Compose v1 est un projet Python historique. Installer via pip peut créer des conflits Python.

Exemple (si vous savez ce que vous faites) :

python3 -m pip install --user docker-compose
~/.local/bin/docker-compose --version

Assurez-vous que ~/.local/bin est dans le PATH :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

6.3 Stratégie recommandée

Utiliser Compose v2 : docker compose
Ajouter un alias docker-compose='docker compose' pour compatibilité

7) Windows : corriger “n’est pas reconnu en tant que commande”

7.1 Comprendre les environnements Windows

Vous pouvez exécuter Docker depuis :

PowerShell
cmd.exe
Git Bash
WSL (Ubuntu, Debian, etc.)

Et vous pouvez avoir :

Docker Desktop (Windows) qui fournit docker et docker compose
Un Docker installé dans WSL (Linux) séparément

7.2 Cas standard : Docker Desktop

Installez Docker Desktop (si pas déjà fait) :
https://www.docker.com/products/docker-desktop/
Redémarrez le terminal après installation.
Vérifiez dans PowerShell :

docker --version
docker compose version

Si docker est introuvable, c’est souvent un problème de PATH ou d’installation incomplète.

7.3 Vérifier le PATH Windows

Dans PowerShell :

$env:Path -split ';'
Get-Command docker

Si Get-Command docker ne trouve rien :

Vérifiez que Docker Desktop est bien installé.
Vérifiez que le répertoire Docker est dans le PATH (Docker Desktop le fait normalement).
Essayez de relancer Docker Desktop, puis rouvrez PowerShell.

7.4 Git Bash : attention aux chemins

Dans Git Bash, docker doit être accessible via le PATH Windows. Testez :

docker --version
docker compose version

Si ça ne marche pas dans Git Bash mais marche dans PowerShell, c’est un problème d’héritage de PATH ou de configuration Git Bash.

7.5 WSL : deux stratégies possibles

Stratégie A (recommandée) : utiliser Docker Desktop depuis WSL

Docker Desktop peut exposer le moteur Docker à WSL2.

Dans Docker Desktop :
Settings → Resources → WSL Integration
Activez l’intégration pour votre distribution.
Dans WSL :

docker --version
docker compose version
docker ps

Si docker est introuvable dans WSL, il faut parfois installer le CLI dans WSL (selon config). Mais souvent Docker Desktop fournit déjà l’accès.

Stratégie B : installer Docker Engine dans WSL (indépendant)

Vous installez Docker comme sur Linux dans WSL. Dans ce cas, Compose doit être installé dans WSL aussi :

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

Attention : vous aurez alors un Docker “Linux dans WSL” séparé de Docker Desktop, avec ses propres images/containers.

8) Cas fréquents et pièges

8.1 Vous avez `docker compose` mais pas `docker-compose`

C’est normal en 2026 : Compose v2 est la norme.

Solutions :

Migrer vos usages vers docker compose
Ajouter un alias (macOS/Linux)
Adapter vos scripts CI

8.2 Vous avez installé Compose, mais le shell ne le voit pas

Sur macOS/Linux :

vous avez modifié ~/.bashrc mais vous utilisez zsh,
ou vous êtes dans un shell non interactif.

Vérifiez votre shell :

echo $SHELL
ps -p $$ -o comm=

Rechargez le bon fichier :

zsh : ~/.zshrc (interactif), ~/.zprofile (login)
bash : ~/.bashrc (interactif), ~/.bash_profile (login)

8.3 Compose plugin installé, mais `docker compose` ne marche pas

Vérifiez où Docker cherche les plugins :

docker info | sed -n '/Plugins:/,/^$/p'

Et listez les plugins :

ls -la ~/.docker/cli-plugins/

Si le plugin est là mais ne s’exécute pas :

architecture incorrecte (ARM vs x86_64),
fichier non exécutable (chmod +x),
binaire corrompu.

8.4 Erreur “exec format error”

Typique si vous téléchargez le mauvais binaire (ex. x86_64 sur ARM).

Vérifiez l’architecture :

uname -m

x86_64 : prenez ...linux-x86_64
aarch64 / arm64 : prenez ...linux-aarch64 (ou arm64 selon release)

8.5 CI/CD : runner minimal sans Compose

Sur un runner Linux minimal, docker peut exister sans Compose.

Ajoutez une étape d’installation :

Debian/Ubuntu :

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

Ou installez le plugin manuellement dans ~/.docker/cli-plugins/.

9) Migration : de `docker-compose.yml` vers Compose v2

Bonne nouvelle : le fichier s’appelle toujours docker-compose.yml dans la plupart des projets, et Compose v2 le lit très bien.

9.1 Commandes équivalentes

Compose v1	Compose v2
`docker-compose up -d`	`docker compose up -d`
`docker-compose down`	`docker compose down`
`docker-compose logs -f`	`docker compose logs -f`
`docker-compose build`	`docker compose build`
`docker-compose ps`	`docker compose ps`

9.2 Exemple réel

Dans un projet contenant un docker-compose.yml :

docker compose up -d
docker compose ps
docker compose logs -f
docker compose down

9.3 Forcer un fichier spécifique

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

10) Vérification finale : checklist par OS

10.1 macOS

Docker Desktop installé et lancé
Test :

docker --version
docker compose version
docker ps

Optionnel : alias

alias docker-compose='docker compose'

10.2 Linux

Docker Engine installé
Plugin Compose installé :

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

Permissions daemon :

docker ps

10.3 Windows

Docker Desktop installé et démarré
PowerShell :

docker --version
docker compose version
docker ps

WSL : activer l’intégration et retester dans WSL.

11) Dépannage avancé (commandes utiles)

11.1 Inspecter la version et l’emplacement

macOS/Linux :

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

Windows PowerShell :

Get-Command docker
docker --version
docker compose version

11.2 Vérifier les variables d’environnement

macOS/Linux :

echo $PATH
env | grep -E 'DOCKER|COMPOSE|PATH'

Windows PowerShell :

echo $env:Path
gci env: | ? Name -match 'DOCKER|COMPOSE|PATH'

11.3 Vérifier que le daemon tourne

docker info
docker ps

Si docker info échoue :

Sur macOS/Windows : démarrez Docker Desktop.
Sur Linux : démarrez le service :

sudo systemctl status docker
sudo systemctl start docker

12) Conclusion : la solution la plus robuste en 2026

Privilégiez Docker Compose v2 : utilisez docker compose.
Sur Linux, installez docker-compose-plugin via votre gestionnaire de paquets quand possible.
Si vous devez conserver docker-compose pour compatibilité :
- créez un alias docker-compose='docker compose' (macOS/Linux),
- ou adaptez vos scripts CI pour appeler docker compose.

Si vous me dites :

votre OS (macOS/Linux/Windows),
la sortie de docker --version et docker compose version,
et le shell utilisé (bash/zsh/PowerShell/WSL), je peux proposer un correctif précis et minimal pour votre cas.

Docker Compose : commande introuvable — correctifs sur Mac, Linux et Windows

Docker Compose : commande introuvable — correctifs sur Mac, Linux et Windows

1) Comprendre l’erreur : docker-compose vs docker compose

1.1 Docker Compose v1 (historique)

1.2 Docker Compose v2 (actuel)

1.3 Pourquoi “commande introuvable” arrive

2) Diagnostic rapide (toutes plateformes)

2.1 Vérifier Docker

2.2 Vérifier Compose v2

2.3 Vérifier Compose v1

2.4 Identifier ce qui est réellement exécuté

3) Correctif universel : utiliser la bonne commande

3.1 Solution immédiate

3.2 Rendre vos scripts compatibles (alias)

macOS / Linux (bash/zsh)

Windows PowerShell (alias temporaire)

4) macOS : causes et solutions

4.1 Cas le plus courant : Docker Desktop installé, mais vous tapez docker-compose

4.2 Docker Desktop non installé / Docker CLI seul

4.3 Problèmes de PATH sur macOS (zsh)

4.4 Installation via Homebrew (cas avancé)

5) Linux : installer Compose v2 correctement (recommandé)

5.1 Vérifier si le plugin est présent

5.2 Installation via paquets (Debian/Ubuntu)

Remarque sur les dépôts Docker

5.3 Installation via paquets (Fedora/RHEL/CentOS)

5.4 Installation manuelle du plugin (si paquet indisponible)

5.5 Permissions Docker : ne pas confondre avec “commande introuvable”

6) Linux : Compose v1 (ancien) — quand et comment

6.1 Installer docker-compose (v1) via paquet (selon distro)

6.2 Installer via pip (déconseillé sauf cas précis)

6.3 Stratégie recommandée

7) Windows : corriger “n’est pas reconnu en tant que commande”

7.1 Comprendre les environnements Windows

7.2 Cas standard : Docker Desktop

7.3 Vérifier le PATH Windows

7.4 Git Bash : attention aux chemins

7.5 WSL : deux stratégies possibles

Stratégie A (recommandée) : utiliser Docker Desktop depuis WSL

Stratégie B : installer Docker Engine dans WSL (indépendant)

8) Cas fréquents et pièges

8.1 Vous avez docker compose mais pas docker-compose

8.2 Vous avez installé Compose, mais le shell ne le voit pas

8.3 Compose plugin installé, mais docker compose ne marche pas

8.4 Erreur “exec format error”

8.5 CI/CD : runner minimal sans Compose

9) Migration : de docker-compose.yml vers Compose v2

9.1 Commandes équivalentes

9.2 Exemple réel

9.3 Forcer un fichier spécifique

10) Vérification finale : checklist par OS

10.1 macOS

10.2 Linux

10.3 Windows

11) Dépannage avancé (commandes utiles)

11.1 Inspecter la version et l’emplacement

11.2 Vérifier les variables d’environnement

11.3 Vérifier que le daemon tourne

12) Conclusion : la solution la plus robuste en 2026

Tutoriels associés

1) Comprendre l’erreur : `docker-compose` vs `docker compose`

4.1 Cas le plus courant : Docker Desktop installé, mais vous tapez `docker-compose`

6.1 Installer `docker-compose` (v1) via paquet (selon distro)

8.1 Vous avez `docker compose` mais pas `docker-compose`

8.3 Compose plugin installé, mais `docker compose` ne marche pas

9) Migration : de `docker-compose.yml` vers Compose v2