Comment installer Docker Compose : Linux, macOS et Windows

Vous avez Docker en marche et maîtrisez les commandes de base, mais vous en avez assez de lancer vos conteneurs un par un ?

Docker Compose vous permet de définir et d'exécuter des applications multi-conteneurs à partir d'un seul fichier YAML. Le piège, c'est qu'il circule deux versions : l'ancien binaire autonome (v1) et le nouveau plugin CLI (v2). La plupart des tutoriels ne précisent pas laquelle ils utilisent, et vous vous retrouvez à suivre des étapes qui ne correspondent pas à votre configuration.

Docker Compose v2 est un plugin inclus avec les versions récentes de Docker, ce qui simplifie vraiment l'installation, l'exécution et la vérification. Le processus n'est plus aussi manuel qu'avant.

Dans cet article, je vous guide pas à pas pour installer Docker Compose sur Linux, macOS et Windows — correctement, avec la v2.

Vous débutez avec la virtualisation et la conteneurisation ? Lisez notre article Docker for Beginners pour pratiquer.

Avant d'installer Docker Compose

Avant tout, vous devez avoir Docker Engine sur votre machine. Docker Compose ne fonctionne pas seul : il a besoin de Docker.

Exécutez cette commande pour vérifier votre version de Docker :

docker --version

Version de Docker installée

Si Docker n'est pas installé, arrêtez-vous ici et installez-le d'abord. S'il est bien installé, vous pouvez vérifier si Compose est déjà disponible :

docker compose version

Version de Docker Compose installée

Si la commande renvoie un numéro de version, c'est bon : Compose v2 est déjà inclus avec votre installation de Docker. Vous pouvez passer directement à la section de vérification.

Si vous obtenez un « commande introuvable » générique, poursuivez la lecture.

Voici la distinction essentielle à connaître :

• Docker Compose v1 est l'ancien binaire autonome. On l'appelait avec docker-compose (avec un tiret). Il est déprécié et n'est plus maintenu.

• Docker Compose v2 est un plugin CLI fourni avec les versions modernes de Docker. On l'appelle avec docker compose (sans tiret).

Si votre installation de Docker est récente, vous avez très probablement déjà la v2. La suite de l'article suppose la v2.

Installer Docker Compose sur Linux

Sous Linux, vous avez deux façons d'obtenir Docker Compose. La première utilise le dépôt officiel de Docker — c'est la voie recommandée. La seconde est une installation manuelle utile si vous ne pouvez pas utiliser de gestionnaire de paquets ou si vous avez besoin d'une version précise.

Méthode 1 : via le dépôt officiel de Docker (recommandé)

Cette méthode maintient Compose lié à votre installation de Docker, pour des mises à jour synchronisées.

Si Docker Engine n'est pas encore installé, commencez par configurer le dépôt apt officiel de Docker :

# Add Docker's GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

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

sudo apt-get update

Installez ensuite Docker Engine et le plugin Compose ensemble :

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

Le paquet docker-compose-plugin vous fournit la commande CLI docker compose. Vérifiez que tout fonctionne :

docker compose version

Version de Docker Compose sur une VM Ubuntu

C'est tout.

Méthode 2 : installation manuelle (binaire autonome)

Utilisez cette méthode si vous avez besoin d'une version précise de Compose, ou si votre environnement ne supporte pas le dépôt Docker.

Commencez par télécharger la dernière version directement depuis GitHub. Remplacez v5.0.1 par la version voulue :

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v5.0.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose

Rendez le binaire exécutable :

chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Enfin, vérifiez l'installation :

docker compose version

Version de Docker Compose sur une VM Ubuntu

Gardez simplement en tête que les installations manuelles ne se mettent pas à jour automatiquement. Si vous installez un binaire puis l'oubliez, vous risquez d'utiliser une version obsolète avec des bogues ou des failles connues. Si vous optez pour cette voie, pensez à consulter de temps en temps la page des versions de Docker Compose.

Installer Docker Compose sur macOS

Sur macOS, inutile d'installer Docker Compose séparément : il est inclus avec Docker Desktop.

Téléchargez Docker Desktop depuis le site officiel de Docker. Veillez à choisir la bonne version pour votre puce : Apple Silicon (M1–M5) ou Intel.

Une fois installé, ouvrez Docker Desktop et laissez le démarrage se terminer. Puis vérifiez que Compose est disponible avec cette commande :

docker compose version

Version de Docker Compose sur macOS

Et voilà. Compose v2 est prêt à l'emploi.

Optionnel : installation via Homebrew

Si vous préférez gérer vos outils avec Homebrew et ne souhaitez pas l'interface graphique de Docker Desktop, vous pouvez installer Docker et Compose ainsi :

brew install docker
brew install docker-compose

Dans ce cas, gardez à l'esprit que Homebrew installe Docker Engine sans l'application Desktop. C'est très bien pour un usage en CLI, mais vous n'aurez pas le Dashboard Docker ni les mises à jour automatiques. Pour la plupart des utilisateurs macOS, Docker Desktop reste la voie la plus simple.

Installer Docker Compose sur Windows

Comme sur macOS, Windows obtient Docker Compose automatiquement via Docker Desktop. Aucune installation séparée n'est nécessaire.

Avant d'installer Docker Desktop, vous devez activer WSL2 (Windows Subsystem for Linux 2). WSL2 permet à Docker d'exécuter un vrai noyau Linux sous Windows, ce qui rend les conteneurs possibles sur cette plateforme. Pour l'activer, ouvrez PowerShell en tant qu'administrateur et exécutez :

wsl --install

Redémarrez la machine lorsque cela est proposé. Puis téléchargez et installez Docker Desktop depuis le site officiel de Docker.

Pendant l'installation, assurez-vous que l'option « Use WSL2 instead of Hyper-V » est cochée. Une fois Docker Desktop lancé, vérifiez que Compose est disponible — vous pouvez le faire depuis PowerShell ou votre terminal WSL :

docker compose version

Problèmes de droits fréquents

Si vous obtenez une erreur « permission denied », c'est généralement l'une de ces deux causes :

• Docker Desktop n'est pas lancé. Il doit être actif dans la zone de notification avant que les commandes docker fonctionnent.
• Votre utilisateur n'est pas dans le bon groupe. Sous WSL, assurez-vous que votre utilisateur Linux a accès au socket Docker. Vous pouvez corriger cela en ouvrant votre terminal WSL en tant qu'administrateur, ou en ajoutant votre utilisateur au groupe docker dans WSL :

sudo usermod -aG docker $USER

Déconnectez-vous puis reconnectez-vous à WSL pour appliquer le changement.

Vérifier l'installation de Docker Compose

Une fois Docker Compose installé, exécutez cette commande pour confirmer que tout fonctionne :

docker compose version

Vous devriez voir une sortie de ce type :

Version de Compose installée

Le numéro de version exact variera selon la date de lecture, mais tant que vous voyez v5.0.1 ou plus récent, c'est tout bon.

Si vous voyez docker compose: command not found, Compose n'est pas installé ou n'est pas dans votre PATH. Passez à la section dépannage ci-dessous.

docker compose vs docker-compose

Vous verrez peut-être en ligne des articles qui utilisent docker-compose avec un tiret. Voici la différence :

• docker-compose est la commande légacy v1. C'était un binaire Python autonome installé séparément de Docker.

• docker compose (sans tiret) est le plugin CLI v2, intégré directement au CLI Docker.

Docker a abandonné la v1 en 2023, donc docker-compose n'est plus maintenu. Si vous l'avez encore, vous pouvez vérifier à quelle version il pointe :

docker-compose --version

Si cela renvoie une version 1.x.x, vous utilisez l'ancien binaire. Désinstallez-le et utilisez désormais docker compose. Les commandes sont quasi identiques, mais la v2 est plus rapide et activement maintenue.

Mettre à niveau Docker Compose

La procédure de mise à niveau de Compose dépend de la méthode d'installation initiale.

Sur macOS et Windows, Docker Desktop s'en charge : ouvrez l'application, allez dans Settings > Software Updates et lancez la mise à jour si nécessaire. Compose se met à jour automatiquement avec Docker.

Sous Linux avec le gestionnaire de paquets, exécutez :

sudo apt-get update
sudo apt-get upgrade docker-compose-plugin

Cela récupère la dernière version depuis le dépôt officiel de Docker.

Si vous avez procédé manuellement, vous devrez répéter l'étape de téléchargement avec le nouveau numéro de version. Consultez la page des versions de Docker Compose pour la dernière version, puis remplacez le binaire :

curl -SL https://github.com/docker/compose/releases/download/v5.0.2/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Après chaque mise à niveau, vérifiez simplement la nouvelle version :

docker compose version

Rien de plus.

Désinstaller Docker Compose

Les étapes de désinstallation dépendent de la méthode d'installation initiale.

Si vous l'avez installé via le gestionnaire de paquets sous Linux, supprimez le plugin avec :

sudo apt-get remove docker-compose-plugin

Si vous l'avez installé manuellement, supprimez simplement le binaire :

rm $DOCKER_CONFIG/cli-plugins/docker-compose

Si l'ancien binaire v1 autonome est encore présent sur votre système, trouvez-le et supprimez-le avec :

sudo rm /usr/local/bin/docker-compose

Après suppression, vérifiez qu'il n'est plus là en exécutant docker compose version. Si la commande renvoie une erreur, la désinstallation a réussi.

Problèmes d'installation courants

Installer et désinstaller Docker Compose est simple, mais certains problèmes peuvent survenir. Voici comment corriger les points de friction les plus fréquents.

"docker compose: command not found"

Cela signifie que Compose n'est pas installé, ou que Docker ne le trouve pas. Commencez par confirmer que Docker lui-même fonctionne :

docker --version

Si Docker va bien mais que Compose manque, réinstallez simplement le plugin :

sudo apt-get install docker-compose-plugin

Erreurs de permission

Si vous voyez une erreur de permission lors de l'exécution de docker compose, votre utilisateur n'a probablement pas accès au socket Docker. Ajoutez-vous au groupe docker :

sudo usermod -aG docker $USER

Déconnectez-vous/reconnectez-vous pour appliquer le changement. Sous Docker Desktop (macOS/Windows), assurez-vous que l'application est bien lancée avant toute commande.

Incohérence de version

Si Compose a un comportement étrange, vérifiez quelle version vous utilisez vraiment :

docker compose version

Si vous êtes sur une version ancienne, suivez les étapes de mise à niveau vues plus haut. Si vous avez à la fois v1 et v2, c'est probablement la source de la confusion.

Conflits entre v1 et v2

Avoir docker-compose (v1) et docker compose (v2) sur la même machine peut créer des conflits. Vérifiez si v1 est encore présent avec :

which docker-compose

Si un chemin est retourné, supprimez-le :

sudo rm $(which docker-compose)

Utilisez désormais docker compose (sans tiret).

Problèmes de PATH

Si Docker est installé mais que les commandes sont introuvables, le répertoire des plugins CLI n'est peut-être pas dans votre PATH. Vérifiez où se trouve le binaire Compose :

ls $DOCKER_CONFIG/cli-plugins/

S'il est présent mais ne fonctionne pas, ajoutez ce répertoire à votre PATH dans ~/.bashrc ou ~/.zshrc :

export PATH=$PATH:$HOME/.docker/cli-plugins

Puis rechargez votre shell avec :

source ~/.bashrc

Docker Compose v1 vs v2

Si vous utilisez Docker depuis un moment, vous avez sans doute vu passer docker-compose et docker compose dans des articles ou vidéos. Ce n'est pas la même chose.

Docker Compose v1 était un binaire Python autonome, installé séparément de Docker. Il utilisait la commande docker-compose (avec tiret). Docker l'a déprécié en 2023 ; il n'est plus maintenu ni mis à jour.

Docker Compose v2 est un plugin CLI écrit en Go, intégré directement au CLI Docker. On l'appelle avec docker compose (sans tiret). Il est fourni avec Docker Engine et Docker Desktop, donc rien de plus à installer sur les configurations modernes.

La syntaxe des commandes est presque identique entre les deux versions : la plupart des commandes docker-compose fonctionnent de la même manière avec docker compose. Les différences majeures sont sous le capot : la v2 est plus rapide, mieux intégrée à l'écosystème Docker et activement maintenue.

Voici un comparatif :

Tableau de comparaison Compose v1/v2

En 2026, restez sur la v2. Si vos scripts ou pipelines CI utilisent encore docker-compose, remplacez simplement le tiret par un espace : c'est la seule modification nécessaire dans la plupart des flux.

Conclusion

Si vous utilisez une version moderne de Docker, vous avez déjà Compose v2. Aucune étape supplémentaire n'est nécessaire. Sur macOS et Windows, l'application Docker Desktop inclut Compose. Sous Linux, il est géré par le paquet docker-compose-plugin.

Avant d'écrire ou d'exécuter des fichiers Compose, lancez docker compose version pour confirmer que tout est en place.

Si vous utilisez encore Compose v1, c'est le moment de basculer. Supprimez le tiret et retirez l'ancien binaire : c'est tout. Tous vos fichiers Compose existants fonctionneront tels quels avec la v2.

Vous cherchez d'autres ressources sur Docker ? Inscrivez-vous à notre Introduction to Docker pour découvrir les conteneurs, les images et plus encore.