Docker Compose : stop ou down, quelle différence ?

La réponse courte

docker compose stop arrête les conteneurs et les laisse sur le disque. docker compose down les arrête, puis supprime les conteneurs et le réseau que Compose a créés pour le projet. Aucune de ces commandes ne touche à un volume nommé. Votre base de données n'est supprimée que lorsque vous ajoutez -v, comme dans docker compose down -v, ce qui supprime les volumes nommés déclarés dans la section volumes du fichier Compose.

C'est toute la différence en un paragraphe. Le reste de ce guide le démontre avec un volume Postgres que vous pouvez voir survivre à un down et disparaître lors d'un down -v. Il explique également les deux cas où vous devez utiliser --force-recreate.

docker compose stop : les conteneurs restent présents

stop envoie SIGTERM au processus principal de chaque conteneur, attend, puis envoie SIGKILL si le processus est toujours actif. L’attente par défaut est de 10 secondes, et -t permet de la modifier. Rien n’est supprimé. Le conteneur conserve son ID, sa couche inscriptible, sa réservation d’adresse IP et ses journaux.

docker compose stop
docker compose ps -a

docker compose ps affiche uniquement les conteneurs en cours d’exécution. Après stop, il affiche donc un tableau vide, ce qui donne l’impression que les conteneurs ont disparu. ps -a inclut les conteneurs arrêtés. C’est là que vous verrez Exited (0) à côté de chaque service. Relancez-les avec docker compose start, qui réutilise exactement les mêmes conteneurs.

Comme les conteneurs existent toujours, tout ce qui y a été écrit en dehors d’un volume est conservé. Cela inclut un paquet installé manuellement avec docker compose exec et un fichier de configuration modifié dans le conteneur. C’est la raison pratique de préférer stop pendant le débogage : vous pouvez redémarrer dans le même état.

docker compose down : les conteneurs et les réseaux sont supprimés

down arrête les conteneurs, puis les supprime avec le réseau par défaut que Compose a créé pour le projet. La documentation Docker le décrit comme une commande qui arrête les conteneurs et supprime les conteneurs, les réseaux, les volumes et les images créés par up. Toutefois, les volumes et les images ne sont concernés que si vous le demandez avec -v et --rmi.

docker compose down
docker compose ps -a
docker network ls

Après down, ps -a n’affiche rien pour le projet et le réseau <project>_default a disparu. Le nom du projet provient du nom du répertoire, sauf si vous définissez name: dans le fichier Compose ou si vous transmettez -p. Toutes les modifications effectuées dans la couche inscriptible d’un conteneur sont désormais irrécupérables. Considérez donc down comme une commande qui supprime le conteneur et conserve les données placées dans les volumes.

Si vous l’exécutez dans le mauvais répertoire, vous obtenez no configuration file provided: not found. Compose ne sait pas quel projet vous avez indiqué et refuse donc de continuer. Utilisez docker compose -f /srv/myapp/compose.yaml down lorsque vous n’êtes pas dans le répertoire du projet.

La commande docker compose down supprime-t-elle mes volumes ?

Non. Un volume nommé déclaré sous la clé de niveau supérieur volumes persiste au-delà de down et du conteneur auquel il était attaché. C’est la crainte la plus fréquente concernant cette commande. La réponse reste la même avec Compose v2.

Préparez une stack que vous pourrez tester. Placez ceci dans compose.yaml, dans un répertoire vide nommé voltest.

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Démarrez-la et écrivez une ligne que vous pourrez reconnaître ensuite.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

Détruisez maintenant le conteneur et vérifiez le volume.

docker compose down
docker volume ls

La sortie contient toujours voltest_pgdata. Le conteneur a été supprimé, mais les données sont toujours présentes. Redémarrez la stack et lisez la ligne.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

Vous obtenez une ligne contenant survived. Le nouveau conteneur est un conteneur différent, avec un ID différent, attaché au même volume. Pour une vue d’ensemble, le guide des bases de Compose explique la différence entre les volumes nommés et les bind mounts, ainsi que l’emplacement réel de chacun sur l’hôte.

Ce que détruit exactement down -v

-v (forme longue --volumes) supprime les volumes nommés déclarés dans la section volumes du fichier Compose, ainsi que les volumes anonymes attachés aux conteneurs. Exécutez-le sur la même stack.

docker compose down -v
docker volume ls

voltest_pgdata n'est plus listé. Redémarrez la stack. L'entrypoint Postgres trouve alors un répertoire de données vide et initialise un nouveau cluster. Le journal du conteneur l'indique clairement.

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

Si ce bloc apparaît sur une stack qui fonctionne depuis plusieurs mois, le volume a été supprimé. Votre table marker a disparu et la seule solution est de restaurer une sauvegarde.

Certains stockages ne sont jamais supprimés par -v. Un bind mount correspond à un chemin sur l'hôte. Docker le démonte donc uniquement et vos fichiers restent à leur emplacement. Un volume marqué external: true est déclaré comme appartenant à un élément externe à ce projet. Compose ne le supprime jamais. Un volume nommé que vous avez supprimé du fichier Compose avant d'exécuter down -v n'est plus déclaré. Compose ne sait donc pas qu'il doit le supprimer et le laisse comme volume orphelin pour docker volume prune.

Ce dernier cas survient souvent lors d'une refactorisation. Supprimez un service et son volume du fichier, puis exécutez down -v. Le volume subsiste, car le fichier ne le mentionne plus. Exécutez down -v avant de modifier le fichier, pas après.

Quand vous avez réellement besoin de --force-recreate

docker compose up -d ne reconstruit pas tout à chaque exécution. Compose stocke le hash de la configuration résolue de chaque service sur le conteneur, sous forme de label. Si le hash et l’ID de l’image correspondent, le conteneur reste inchangé et vous obtenez Container voltest-db-1 Running au lieu de Recreated. C’est le comportement souhaité dans presque tous les cas, car il permet d’exécuter up -d plusieurs fois sans risque.

C’est également la raison pour laquelle certaines modifications semblent ne rien faire. Compose calcule le hash de la définition résolue du service, et non du contenu des fichiers vers lesquels cette définition pointe. Un fichier de configuration monté dans le conteneur et lu une seule fois au démarrage ne déclenche pas de recréation lorsque vous le modifiez, car le chemin de montage n’a pas changé. Le service continue de fonctionner avec les valeurs lues au démarrage.

docker compose up -d --force-recreate

Cette commande arrête et supprime chaque conteneur, puis en crée un nouveau à partir de la même définition. Utilisez-la après la modification d’un fichier de configuration monté, ou lorsqu’un conteneur se trouve dans un état que vous ne pouvez pas expliquer. Les volumes ne sont pas modifiés. Une base de données survit donc à une recréation forcée. Pour récupérer une image plus récente portant le même tag, vous devez également effectuer le pull.

docker compose pull
docker compose up -d

pull récupère le nouvel ID de l’image. up -d constate ensuite que l’ID de l’image diffère de celui du conteneur en cours d’exécution et recrée le conteneur automatiquement. Ajouter --force-recreate sans pull vous donne un nouveau conteneur basé sur la même ancienne image. C’est pourquoi la plainte « J’ai effectué une recréation forcée et la version est toujours l’ancienne » est si fréquente.

docker compose restart ne fait rien de tout cela. Cette commande redémarre les conteneurs existants et ne relit pas du tout le fichier Compose. Une variable d’environnement ou une correspondance de port modifiée ne sera donc pas appliquée. Si vous avez modifié le fichier, utilisez up -d.

Le modèle mental à retenir

Les conteneurs sont remplaçables. Un conteneur est un processus accompagné d’une fine couche accessible en écriture, et Compose peut en recréer un identique à partir du fichier en environ une seconde. Les volumes ne sont pas remplaçables, car ils contiennent l’unique copie de l’état qu’aucun fichier de votre dépôt ne peut régénérer.

Chaque commande Compose correspond à cette distinction. stop et start conservent le conteneur. down et up remplacent le conteneur tout en conservant le volume. down -v est la seule commande courante qui supprime l’état, d’où la nécessité d’utiliser un flag explicite. Avant de l’exécuter sur un système réel, vérifiez que vous disposez d’une sauvegarde que vous avez déjà restaurée au moins une fois.

La même logique s’applique aux secrets. Un mot de passe défini via POSTGRES_PASSWORD n’est lu que lors de la première initialisation de la base de données. Modifier ce mot de passe dans votre fichier d’environnement, puis exécuter up -d, produit donc password authentication failed for user "postgres". Le conteneur est nouveau, mais le volume est ancien et contient toujours l’ancien mot de passe. Comment Compose résout les fichiers env et les secrets explique quelle couche est prioritaire lorsqu’une même variable est définie deux fois.

Modes d’échec et messages affichés

no configuration file provided: not found signifie que Compose s’exécute dans un répertoire qui ne contient ni compose.yaml ni docker-compose.yml. Indiquez -f avec le chemin complet.

network voltest_default has active endpoints sur down signifie qu’un conteneur extérieur à ce projet est attaché au réseau du projet, généralement un conteneur démarré manuellement avec docker run --network. Supprimez ce conteneur, puis exécutez de nouveau down.

Found orphan containers ([voltest-old-1]) for this project apparaît après le renommage ou la suppression d’un service. L’ancien conteneur porte toujours le label du projet. docker compose down --remove-orphans les supprime, et vous pouvez l’exécuter sans risque sur une stack saine.

Error response from daemon: remove voltest_pgdata: volume is in use lors d’un docker volume rm manuel signifie qu’un conteneur référence encore le volume, y compris un conteneur arrêté. Exécutez d’abord docker compose down, puis supprimez le volume, ou utilisez simplement down -v. Dans un projet plus important, une stack Compose multiservice montre combien de volumes un projet peut accumuler.

FAQ

Est-ce que docker compose down supprime ma base de données ?

Non, si la base de données se trouve dans un volume nommé ou un bind mount. down supprime les conteneurs et le réseau du projet, mais le volume reste sur le disque avec ses données intactes. Le docker compose up -d suivant rattache un nouveau conteneur au même volume, et les données sont présentes. Seul docker compose down -v supprime les volumes nommés, et uniquement ceux déclarés dans la section volumes du fichier Compose.

Quelle est la différence entre stop et down pour un conteneur que je veux réutiliser ?

stop conserve le conteneur. docker compose start vous ramène donc au même conteneur, avec la même couche inscriptible. Tout ce que vous avez installé ou modifié manuellement dans le conteneur est toujours présent. down supprime le conteneur. Le up -d suivant en crée donc un nouveau à partir de l’image, et ces modifications manuelles sont perdues. Pendant le débogage, utilisez stop.

Comment supprimer tout ce qu’un projet Compose a créé ?

docker compose down -v --rmi all --remove-orphans supprime les conteneurs, le réseau du projet, les volumes nommés déclarés dans le fichier, les images utilisées par les services et tout conteneur encore marqué avec le nom du projet. Cette commande ne modifie pas les bind mounts ni les volumes marqués external: true. Vérifiez ce que vous allez perdre avec docker volume ls avant de l’exécuter.

Pourquoi mon conteneur ignore-t-il la modification apportée à un fichier de configuration monté ?

Compose détermine s’il doit recréer un conteneur en comparant le hash de la définition résolue du service. Ce hash n’inclut pas le contenu d’un fichier monté. Le chemin n’a pas changé. Compose laisse donc le conteneur en cours d’exécution avec les valeurs lues au démarrage. Exécutez docker compose up -d --force-recreate pour créer un nouveau conteneur qui relira le fichier.

Pourquoi mon nouveau POSTGRES_PASSWORD ne fonctionne-t-il pas après sa modification ?

L’image Postgres ne lit POSTGRES_PASSWORD que lorsqu’elle initialise un répertoire de données vide. Votre volume contient déjà un cluster initialisé. La variable est donc ignorée et l’ancien mot de passe reste actif. Vous verrez password authentication failed for user "postgres". Modifiez le mot de passe avec ALTER USER dans la base de données en cours d’exécution, ou acceptez de perdre les données et recommencez avec docker compose down -v.