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 modifie un volume nommé. Votre base de données n’est supprimée que si vous ajoutez -v, comme dans docker compose down -v, qui supprime les volumes nommés déclarés dans la section volumes du fichier Compose.

C’est toute la différence, résumée 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ù --force-recreate est nécessaire.

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. Le délai d’attente par défaut est de 10 secondes et -t permet de le modifier. Rien n’est supprimé. Le conteneur conserve son ID, sa couche accessible en écriture, sa réservation d’adresse IP et ses journaux.

docker compose stop
docker compose ps -a

docker compose ps seul affiche uniquement les conteneurs en cours d’exécution. Après stop, il affiche donc un tableau vide, ce qui peut donner l’impression que les conteneurs ont été supprimés. ps -a inclut les conteneurs arrêtés. C’est là que vous verrez Exited (0) à côté de chaque service. Redémarrez-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 privilégier 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 décrit cette commande comme l’opération qui arrête les conteneurs et supprime les conteneurs, réseaux, volumes et images créés par up. Toutefois, les volumes et les images ne sont supprimé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 plus 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 passez -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 stocké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 voulez utiliser 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.

docker compose down supprime-t-il mes volumes ?

Non. Un volume nommé déclaré sous la clé de niveau supérieur volumes survit à down et au conteneur auquel il était attaché. C’est la crainte la plus fréquente concernant cette commande, mais le comportement est identique avec Compose v2.

Préparez une stack de test. Placez le contenu suivant 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 plus tard.

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 disparu, 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 différent et possède un autre ID, mais il est attaché au même volume. Pour aller plus loin, 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 down -v supprime exactement

-v (forme longue : --volumes) supprime les volumes nommés déclarés dans la section volumes du fichier Compose, ainsi que les volumes anonymes associé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, cela signifie que le volume a été supprimé. Votre table marker a disparu et la seule solution consiste à restaurer une sauvegarde.

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

Ce dernier cas piège souvent les administrateurs 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, et non après.

Dans quels cas utiliser réellement --force-recreate

docker compose up -d ne reconstruit pas tout à chaque exécution. Compose stocke un 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 presque toujours le comportement recherché, car up -d peut ainsi être exécuté plusieurs fois sans risque.

C’est aussi la raison pour laquelle certaines modifications semblent ne rien changer. Compose calcule le hash de la définition résolue du service, pas 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 du 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 touché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, puis up -d détecte que cet ID diffère de celui du conteneur en cours d’exécution et recrée automatiquement le conteneur. Ajouter --force-recreate sans pull vous donne un nouveau conteneur basé sur la même ancienne image. C’est pourquoi « j’ai effectué une recréation forcée, mais la version est toujours l’ancienne » est une plainte 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 un mapping de port modifié ne sera donc pas appliqué. 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 séparation. 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’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 avec POSTGRES_PASSWORD est lu uniquement 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, vous donne donc password authentication failed for user "postgres". Le conteneur est nouveau, mais le volume est ancien, et cet ancien volume contient toujours l’ancien mot de passe. Comment Compose résout les fichiers d’environnement et les secrets explique quelle couche est prioritaire lorsque la 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 connecté au réseau du projet. Il s’agit généralement d’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 encore le label du projet. docker compose down --remove-orphans les supprime. 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 multi-service montre combien de volumes un seul projet peut accumuler.

FAQ

Le fait d’exécuter docker compose down supprime-t-il 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 toujours 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 conservé. 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épannage, 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 tous les conteneurs qui portent encore le nom du projet dans leurs labels. Il ne modifie pas les bind mounts ni les volumes marqués external: true. Vérifiez ce qui va être supprimé 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 un 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 s’exécuter 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 utilisé. 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.