Docker Compose: down vs. stop und Volumes erklärt

Die kurze Antwort

docker compose stop stoppt die Container und lässt sie auf dem Datenträger bestehen. docker compose down stoppt die Container und löscht anschließend die Container sowie das Netzwerk, das Compose für das Projekt erstellt hat. Keiner der beiden Befehle greift auf ein benanntes Volume zu. Ihre Datenbank wird erst gelöscht, wenn Sie -v ergänzen, wie in docker compose down -v. Dadurch werden die im Abschnitt volumes der Compose-Datei deklarierten benannten Volumes entfernt.

Das ist der gesamte Unterschied in einem Absatz. Der restliche Leitfaden belegt ihn anhand eines Postgres-Volumes. Sie können beobachten, wie es einen down übersteht und durch einen down -v verschwindet. Außerdem werden die beiden Fälle erklärt, in denen Sie --force-recreate benötigen.

docker compose stop: Die Container bleiben erhalten

stop sendet SIGTERM an den Hauptprozess in jedem Container und wartet anschließend. Wenn der Prozess weiterhin ausgeführt wird, sendet der Befehl SIGKILL. Die Standardwartezeit beträgt 10 Sekunden. -t ändert diese Wartezeit. Es wird nichts gelöscht. Der Container behält seine ID, seine beschreibbare Schicht, seine IP-Reservierung und seine Logs.

docker compose stop
docker compose ps -a

docker compose ps zeigt standardmäßig nur ausgeführte Container. Nach stop wird daher eine leere Tabelle ausgegeben, und es entsteht der Eindruck, die Container seien gelöscht. ps -a schließt angehaltene Container ein. Dort sehen Sie neben jedem Dienst Exited (0). Starten Sie die Container mit docker compose start erneut. Dabei werden genau dieselben Container wiederverwendet.

Da die Container weiterhin vorhanden sind, bleiben alle Daten erhalten, die darin außerhalb eines Volumes geschrieben wurden. Dazu gehören ein Paket, das Sie manuell mit docker compose exec installiert haben, und eine Konfigurationsdatei, die Sie im Container bearbeitet haben. Deshalb sollten Sie beim Debuggen stop bevorzugen: Sie können im selben Zustand neu starten.

docker compose down: Container und Netzwerke werden entfernt

down stoppt die Container und entfernt sie anschließend zusammen mit dem Standardnetzwerk, das Compose für das Projekt erstellt hat. Die Docker-Dokumentation beschreibt den Befehl als Stoppen der Container und Entfernen der von up erstellten Container, Netzwerke, Volumes und Images. Die Teile für Volumes und Images werden jedoch nur ausgeführt, wenn Sie sie mit -v und --rmi anfordern.

docker compose down
docker compose ps -a
docker network ls

Nach down gibt ps -a für das Projekt nichts aus, und das Netzwerk <project>_default ist nicht mehr vorhanden. Der Projektname wird aus dem Verzeichnisnamen übernommen, sofern Sie nicht name: in der Compose-Datei setzen oder -p übergeben. Alle Änderungen, die Sie innerhalb der beschreibbaren Ebene eines Containers vorgenommen haben, sind jetzt nicht wiederherstellbar. Behandeln Sie down daher als Befehl, der den Container verwirft und die in Volumes gespeicherten Daten beibehält.

Wenn Sie den Befehl im falschen Verzeichnis ausführen, erhalten Sie no configuration file provided: not found. Compose weiß nicht, welches Projekt Sie meinen, und verweigert daher die Ausführung. Verwenden Sie docker compose -f /srv/myapp/compose.yaml down, wenn Sie sich nicht im Projektverzeichnis befinden.

Löscht docker compose down meine Volumes?

Nein. Ein benanntes Volume, das unter dem Schlüssel volumes der obersten Ebene deklariert ist, bleibt über down hinaus bestehen. Es bleibt auch nach dem Löschen des Containers bestehen, an den es angehängt war. Das ist die häufigste Sorge bei diesem Befehl. Die Antwort gilt unverändert für Compose v2.

Richten Sie einen Stack ein, den Sie testen können. Speichern Sie Folgendes in compose.yaml in einem leeren Verzeichnis namens voltest.

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

volumes:
  pgdata:

Starten Sie den Stack und schreiben Sie eine Zeile, die Sie später wiedererkennen.

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');"

Löschen Sie nun den Container und prüfen Sie das Volume.

docker compose down
docker volume ls

Die Ausgabe enthält weiterhin voltest_pgdata. Der Container ist gelöscht, die Daten sind jedoch noch vorhanden. Starten Sie den Stack erneut und lesen Sie die Zeile aus.

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

Sie erhalten eine Zeile mit survived. Der neue Container ist ein anderer Container mit einer anderen ID, der an dasselbe Volume angehängt ist. Eine umfassendere Übersicht finden Sie im Leitfaden zu den Compose-Grundlagen. Dort werden benannte Volumes mit Bind-Mounts verglichen und die Speicherorte der jeweiligen Daten auf dem Host erläutert.

Was down -v genau löscht

-v (Langform --volumes) entfernt die benannten Volumes, die im Abschnitt volumes der Compose-Datei deklariert sind, sowie an die Container angehängte anonyme Volumes. Führen Sie den Befehl für denselben Stack aus.

docker compose down -v
docker volume ls

voltest_pgdata wird nicht mehr aufgeführt. Starten Sie den Stack erneut. Der Postgres-Entrypoint findet dann ein leeres Datenverzeichnis und initialisiert einen neuen Cluster. Das Container-Log bestätigt dies eindeutig.

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

Wenn dieser Block bei einem Stack erscheint, der seit Monaten ausgeführt wird, wurde das Volume entfernt. Ihre marker-Tabelle ist verloren. Der einzige Wiederherstellungsweg ist ein Backup.

Einige Speicherbereiche werden von -v nie entfernt. Ein Bind-Mount verweist auf einen Host-Pfad. Docker hebt daher nur den Mount auf, und Ihre Dateien bleiben erhalten. Ein mit external: true markiertes Volume ist als zu einer externen Ressource gehörig deklariert. Compose entfernt es daher nie. Wenn Sie ein benanntes Volume vor der Ausführung von down -v aus der Compose-Datei löschen, ist es nicht mehr deklariert. Compose weiß dann nicht, dass es entfernt werden soll, und lässt es als verwaistes Volume für docker volume prune zurück.

Dieser letzte Fall tritt bei einer Umstrukturierung häufig auf. Wenn Sie einen Service und dessen Volume aus der Datei entfernen und anschließend down -v ausführen, bleibt das Volume erhalten, weil es in der Datei nicht mehr erwähnt wird. Führen Sie down -v aus, bevor Sie die Datei bearbeiten, nicht danach.

Wann Sie --force-recreate tatsächlich benötigen

docker compose up -d erstellt nicht jedes Mal alles neu. Compose speichert einen Hash der aufgelösten Konfiguration jedes Dienstes als Label am Container. Stimmen der Hash und die Image-ID überein, bleibt der Container unverändert, und Sie erhalten Container voltest-db-1 Running statt Recreated. Dieses Verhalten ist fast immer erwünscht, weil up -d dadurch wiederholt sicher ausgeführt werden kann.

Das erklärt auch, warum manche Änderungen scheinbar keine Wirkung haben. Compose hasht die aufgelöste Dienstdefinition, nicht den Inhalt der Dateien, auf die diese Definition verweist. Eine in den Container eingebundene und nur beim Start gelesene Konfigurationsdatei löst beim Bearbeiten keine Neuerstellung aus, weil sich der Einbindungspfad nicht geändert hat. Der Dienst läuft mit den Werten weiter, die er beim Start eingelesen hat.

docker compose up -d --force-recreate

Dieser Befehl stoppt und entfernt jeden Container und erstellt anhand derselben Definition einen neuen. Verwenden Sie ihn nach einer Änderung an einer eingebundenen Konfigurationsdatei sowie dann, wenn ein Container in einen Zustand geraten ist, den Sie nicht erklären können. Volumes bleiben unverändert. Daher bleibt eine Datenbank bei einer erzwungenen Neuerstellung erhalten. Um ein neueres Image unter demselben Tag zu übernehmen, müssen Sie zusätzlich das Image abrufen.

docker compose pull
docker compose up -d

pull ruft die neue Image-ID ab. up -d erkennt anschließend, dass sich die Image-ID vom laufenden Container unterscheidet, und erstellt den Container selbstständig neu. Wenn Sie --force-recreate ohne pull hinzufügen, erhalten Sie einen neuen Container aus demselben alten Image. Deshalb lautet eine häufige Beschwerde: „Ich habe eine erzwungene Neuerstellung durchgeführt, aber es ist immer noch die alte Version.“

docker compose restart führt nichts davon aus. Der Befehl startet die vorhandenen Container neu und liest die Compose-Datei überhaupt nicht erneut ein. Daher werden eine geänderte Umgebungsvariable oder eine geänderte Portzuordnung nicht übernommen. Wenn Sie die Datei bearbeitet haben, verwenden Sie up -d.

Das mentale Modell, das Sie beibehalten sollten

Container sind ersetzbar. Ein Container besteht aus einem Prozess und einer dünnen beschreibbaren Schicht. Compose kann anhand der Datei in etwa einer Sekunde einen identischen Container erstellen. Volumes sind nicht ersetzbar. Sie enthalten die einzige Kopie des Zustands, die keine Datei in Ihrem Repository neu erzeugen kann.

Jedes Compose-Verb entspricht dieser Trennung. stop und start behalten den Container bei. down und up ersetzen den Container und behalten das Volume bei. down -v ist der einzige routinemäßige Befehl, der den Zustand entfernt. Deshalb ist dafür ein expliziter Flag erforderlich. Bevor Sie den Befehl auf einem produktiven System eingeben, bestätigen Sie, dass Sie über ein Backup verfügen, das Sie mindestens einmal wiederhergestellt haben.

Dieselbe Logik gilt für Secrets. Ein über POSTGRES_PASSWORD gesetztes Passwort wird nur beim ersten Initialisieren der Datenbank gelesen. Wenn Sie es in Ihrer Umgebungsdatei ändern und up -d ausführen, erhalten Sie password authentication failed for user "postgres". Der Container ist neu, das Volume ist alt, und im alten Volume steht weiterhin das alte Passwort. So löst Compose Env-Dateien und Secrets auf erklärt, welche Ebene gewinnt, wenn dieselbe Variable zweimal gesetzt ist.

Fehlerbilder und die angezeigten Meldungen

no configuration file provided: not found bedeutet, dass Compose in einem Verzeichnis ohne compose.yaml und ohne docker-compose.yml ausgeführt wird. Übergeben Sie -f mit dem vollständigen Pfad.

network voltest_default has active endpoints bei down bedeutet, dass ein Container außerhalb dieses Projekts mit dem Projektnetzwerk verbunden ist. Meist wurde er manuell mit docker run --network gestartet. Entfernen Sie diesen Container und führen Sie anschließend down erneut aus.

Found orphan containers ([voltest-old-1]) for this project wird angezeigt, nachdem Sie einen Service umbenannt oder gelöscht haben. Der alte Container trägt weiterhin das Projektlabel. docker compose down --remove-orphans entfernt diese Container. Der Befehl kann sicher auf einem fehlerfreien Stack ausgeführt werden.

Error response from daemon: remove voltest_pgdata: volume is in use bei einem manuellen docker volume rm bedeutet, dass noch ein Container auf das Volume verweist. Dazu kann auch ein beendeter Container gehören. Führen Sie zuerst docker compose down aus und entfernen Sie anschließend das Volume, oder verwenden Sie einfach down -v. Bei einem größeren Projekt zeigt ein Compose-Stack mit mehreren Services, wie viele Volumes sich in einem Projekt ansammeln können.

FAQ

Löscht docker compose down meine Datenbank?

Nicht, wenn sich die Datenbank in einem benannten Volume oder einem Bind-Mount befindet. down entfernt die Container und das Projektnetzwerk. Das Volume bleibt mit den unveränderten Daten auf dem Datenträger. Beim nächsten docker compose up -d wird ein neuer Container an dasselbe Volume angebunden, und die Daten sind wieder vorhanden. Nur docker compose down -v entfernt benannte Volumes, und zwar nur die Volumes, die im Abschnitt volumes der Compose-Datei deklariert sind.

Was ist der Unterschied zwischen stop und down, wenn ich einen Container später wieder verwenden möchte?

stop behält den Container bei. Mit docker compose start verwenden Sie denselben Container mit derselben beschreibbaren Schicht weiter. Alles, was Sie manuell im Container installiert oder geändert haben, bleibt erhalten. down löscht den Container. Der nächste up -d erstellt dann aus dem Image einen neuen Container, und diese manuellen Änderungen gehen verloren. Verwenden Sie beim Debuggen stop.

Wie entferne ich alles, was ein Compose-Projekt erstellt hat?

docker compose down -v --rmi all --remove-orphans entfernt die Container, das Projektnetzwerk, die in der Datei deklarierten benannten Volumes, die von den Services verwendeten Images und alle Container, die noch mit dem Projektnamen gekennzeichnet sind. Bind-Mounts und mit external: true markierte Volumes werden nicht verändert. Prüfen Sie mit docker volume ls, was Sie vor der Ausführung verlieren werden.

Warum übernimmt mein Container die Änderung an einer eingebundenen Konfigurationsdatei nicht?

Compose entscheidet anhand eines Hashes der aufgelösten Service-Definition, ob ein Container neu erstellt werden muss. Der Inhalt einer eingebundenen Datei ist nicht Bestandteil dieses Hashes. Der Pfad hat sich nicht geändert. Deshalb lässt Compose den Container mit den beim Start gelesenen Werten weiterlaufen. Führen Sie docker compose up -d --force-recreate aus, um einen neuen Container zu erstellen, der die Datei erneut einliest.

Warum funktioniert mein neues POSTGRES_PASSWORD nach der Änderung nicht?

Das Postgres-Image liest POSTGRES_PASSWORD nur ein, wenn es ein leeres Datenverzeichnis initialisiert. Ihr Volume enthält bereits einen initialisierten Cluster. Deshalb wird die Variable ignoriert, und das alte Passwort bleibt gültig. Sie sehen password authentication failed for user "postgres". Ändern Sie das Passwort mit ALTER USER in der laufenden Datenbank. Wenn Sie den Datenverlust akzeptieren, beginnen Sie mit docker compose down -v von vorn.