Docker Compose im falschen Verzeichnis: So findest du heraus, was dein Befehl wirklich trifft

Ein schnell getippter Compose-Befehl kann den falschen Stack treffen. Ich zeige dir, wie du vor dem Neustart prüfst, welches Projekt du gerade ansprichst.

· Martin Ehrentraut · ca. 7 Minuten · KI-unterstützt

Du willst nur schnell einen der vielen Container in deinem Homelab neu starten. Also wechselst du in den Ordner, der zu dem Dienst gehört, und tippst docker compose restart. Und dann passiert etwas, das du nicht erwartet hast: Es starten viele andere Container mit neu, obwohl du nur einen Dienst gemeint hast. Bei docker compose down wäre der Irrtum noch unangenehmer: Der Befehl stoppt und entfernt Container und räumt die zugehörigen, nicht externen Netzwerke auf. Volumes bleiben ohne -v erhalten.

Das folgt aus den Regeln, nach denen Docker Compose eine Konfiguration und ein Projekt auswählt. Vor dem nächsten Neustart lohnt sich deshalb ein Blick darauf, was Compose gefunden hat.

Ein Terminal im Unterordner zeigt über einen orangefarbenen Pfad auf die Compose-Datei eines übergeordneten Stacks.
KI-generierte Symbolillustration, kein Screenshot.

Was Compose bei jedem Befehl zuerst tut

Für up, restart oder down muss Compose wissen, welche Konfiguration und welches Projekt du meinst. Das aktuelle Verzeichnis spielt dabei eine Rolle. Optionen und Umgebungsvariablen können die Auswahl aber überschreiben:

  1. Welche Compose-Dateien werden geladen?
  2. Welchen Projektnamen bekommt das Ganze?
  3. Welche Dienste werden angesprochen?

Ohne -f und ohne eine Dateivorgabe über COMPOSE_FILE sucht Compose zuerst im aktuellen Verzeichnis. Die Standardnamen haben diese Reihenfolge: compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml. Liegen mehrere davon im selben Ordner, verwendet Compose die erste nach dieser Reihenfolge. Findet es dort keine, prüft es das nächste übergeordnete Verzeichnis und geht so weiter bis zur Wurzel. Die Suche endet im ersten Ordner mit einer passenden Datei. Dort kann zusätzlich eine automatisch erkannte Override-Datei geladen werden, etwa compose.override.yaml. Sie ergänzt oder überschreibt Teile der Basiskonfiguration. Quelle: Docker Compose CLI-Dokumentation.

Das ist praktisch für Projekte, deren Compose-Datei oberhalb des aktuellen Unterordners liegt. Es wird zur Falle, wenn dort eine compose.yml liegt, die du gar nicht meintest.

Der Projektname hat eine eigene Rangfolge: -p gewinnt vor COMPOSE_PROJECT_NAME, danach folgt ein name: auf der obersten Ebene der Compose-Datei. Bei mehreren Dateien zählt das zuletzt gesetzte name:. Erst wenn nichts davon gesetzt ist, nimmt Compose den Namen des Projektverzeichnisses. Das ist normalerweise der Ordner der Compose-Datei, bei mehreren Dateien der Ordner der ersten. Mit --project-directory lässt er sich ändern. Der Projektname fließt in die automatisch vergebenen Container- und Netzwerknamen ein. Docker erklärt die Projektnamensregeln in der Dokumentation.

Eine Datei ist dabei kein eigener Namensraum: Verschiedene Compose-Dateien können denselben Projektnamen ergeben und damit dieselben Ressourcen ansprechen. Welche Dienste ein Befehl erfasst, hängt außerdem von der geladenen Konfiguration, angegebenen Dienstnamen und gegebenenfalls aktivierten Profilen ab. Profile schalten optionale Dienste zu. up und restart lassen sich auf bestimmte Dienste beschränken; Abhängigkeiten können weitere Dienste einbeziehen. Ohne solche Einschränkungen betrifft der Befehl die dafür ausgewählten Dienste des Projekts.

Die erste Falle: die Suche nach oben

Ein Beispiel, das so ähnlich in vielen Homelabs vorkommt. Dein Setup hat eine Struktur wie diese:

~/containers/
├── compose.yml
├── webseite/
├── datenbank/
└── monitoring/

Du willst nur den Dienst in datenbank/ neu starten. Dort liegt aber keine eigene Compose-Datei mit Standardnamen, sondern die Datei heißt zum Beispiel datenbank-compose.yml. Weiter oben im Baum liegt eine compose.yml, nämlich die mit dem kompletten Stack. Ohne -f oder COMPOSE_FILE wählt dein docker compose restart aus datenbank/ deshalb diese Datei und startet die darüber ausgewählten Dienste neu. Gleiches gilt für docker compose down: Es fährt dann deutlich mehr herunter, als du vorhattest, und entfernt die betroffenen Container.

Mit einer expliziten Dateiangabe kannst du diese Suche umgehen.

Die zweite Falle: Datei geändert, aber nichts passiert

Die zweite Verwirrung kommt von restart selbst. Angenommen, du stehst im richtigen Verzeichnis und änderst in der compose.yml eine Umgebungsvariable, einen Port oder ein Volume. Anschließend tippst du docker compose restart, weil du den Dienst „neu starten“ willst. Ergebnis nach dem Neustart: Die Änderung ist nicht wirksam.

Auch das ist korrektes Verhalten. restart startet die vorhandenen Container nur neu, es erstellt sie nicht aus der aktuellen Datei. Mit docker compose up -d übernimmt Compose Änderungen an der Containerkonfiguration und erzeugt betroffene Container bei Bedarf neu. Das -d lässt sie im Hintergrund laufen. Docker beschreibt das im Compose-CLI-Referenzteil zu up.

  • Datei geändert, Image getauscht, neues Label gesetzt: docker compose up -d.
  • Nur die vorhandenen Container ohne Konfigurationsänderung neu starten: docker compose restart.

Ein neues Image unter demselben Tag wird dabei nicht grundsätzlich heruntergeladen. Dafür ist gegebenenfalls ein Pull nötig; Änderungen am eigenen Build brauchen gegebenenfalls einen neuen Build.

Eine Lupe hebt einen Projektordner mit Konfigurationsdatei hervor; orange Verbindungen führen zu den zugeordneten Diensten.
KI-generierte Symbolillustration, kein Screenshot.

Drei Befehle, die Klarheit schaffen

Bevor du up, restart oder down ausführst, kannst du die geladene Konfiguration und die vorhandenen Container prüfen. Verwende dabei dieselben Optionen und Umgebungsvariablen wie beim anschließenden Befehl.

  1. Zeige die effektive Konfiguration an:
    docker compose config

    Dieser Befehl führt die geladenen Dateien zusammen, setzt Variablen ein und zeigt die aufgelöste Konfiguration. Du siehst darin auch den Projektnamen. Die Ausgabe beschreibt die Konfiguration, nicht den tatsächlichen Zustand der Container und auch keine vollständige Vorschau auf down. Mit einer Option kannst du die Dienstnamen einzeln auflisten:

    docker compose config --services
  2. Zeige die laufenden Projekte:
    docker compose ls

    Die Ausgabe listet die laufenden Projekte mit Projektnamen, Compose-Dateien und Status. Sie zeigt vorhandene Projekte im angesprochenen Docker-Daemon, nicht die Dateiauswahl deines nächsten Befehls. Ein unerwarteter Dateipfad ist ein Anlass zum Nachsehen, aber kein Beweis für ein falsches Arbeitsverzeichnis. Mit docker compose ls --all siehst du auch Projekte mit gestoppten Containern.

  3. Liste die Container des aktuellen Projekts:
    docker compose ps

    Damit siehst du standardmäßig die laufenden Container des ausgewählten Projekts. Für die gestoppten nimmst du docker compose ps --all.

Dem Befehl den Weg zeigen

Bei einem abweichenden Dateinamen wie datenbank-compose.yml gibst du die Datei explizit an. Die folgenden Befehle gehen davon aus, dass du in ~/containers/ stehst:

docker compose -f datenbank/datenbank-compose.yml ps
docker compose -f datenbank/datenbank-compose.yml up -d

Das Flag -f ersetzt die automatische Dateisuche und hat Vorrang vor COMPOSE_FILE. Der relative Pfad im Beispiel hängt weiterhin von deinem aktuellen Verzeichnis ab. Mit einem absoluten Pfad kannst du die Datei von überall aus eindeutig angeben. Mehrere -f laden die Dateien in der angegebenen Reihenfolge; spätere Einträge ergänzen oder überschreiben frühere. Eine automatisch gefundene Override-Datei wird bei expliziter Dateiauswahl nicht zusätzlich geladen.

Auch einen Projektnamen kannst du setzen, falls zwei Dateien sonst denselben ergeben würden:

docker compose -p webseite up -d

-p setzt nur den Projektnamen, die Compose-Datei musst du weiterhin passend auswählen. Verwende für einen bestehenden Stack dessen bisherigen Namen: Ein anderer Name kann ein zusätzliches Projekt erzeugen. Erlaubt sind Kleinbuchstaben von a bis z, Ziffern sowie Bindestriche und Unterstriche. Der Name muss mit einem Kleinbuchstaben oder einer Ziffer beginnen.

In Umgebungen mit vielen Diensten lohnt sich zusätzlich ein Blick auf COMPOSE_FILE. Die Variable kann eine oder mehrere Dateien vorgeben und damit die automatische Suche ersetzen. Ein env | grep COMPOSE_FILE zeigt, ob sie in deiner Shell exportiert ist. Compose kann sie aber auch aus einer .env-Datei laden, die dieser Shell-Befehl nicht erfasst. Eine leere Ausgabe schließt eine Dateivorgabe deshalb nicht aus.

Die kurze Regel für den Alltag

Vor jedem Compose-Befehl, der etwas verändert oder beendet:

  1. Steh im richtigen Verzeichnis oder nenne die Datei mit -f.
  2. Prüfe mit config die Konfiguration samt Projektname. Vergleiche sie mit den Projekten aus docker compose ls und den Containern aus ps.
  3. Bei geänderter Konfiguration up -d, nicht restart.

Wie hältst du das in deinem Setup auseinander?

Redaktionsstand: 8. November 2026. Die verlinkten Primärquellen der Docker-Dokumentation belegen Dateisuche, Projektnamen und Befehlsverhalten. Bilder: KI-generierte Symbolillustrationen, keine Screenshots.