Upgrade Debian 12 to 13 with Docker: docker-compose vs. docker compose

Complete practical guide to Docker on Debian 12 → 13: Compose V1 vs. V2, docker-compose vs. docker compose, packages, scripts, backups and safe migration.

Why this difference matters during a Debian upgrade

When moving from Debian 12 Bookworm to Debian 13 Trixie, Docker itself can continue working while the Compose command and installation source change. A common surprise is that `docker-compose` worked before, while the upgraded system provides `docker compose` or old scripts can no longer find the command.

The short answer: Docker Compose is now a Docker plugin

Current Docker installations integrate Compose V2 as a CLI plugin. The modern syntax is `docker compose`. Debian 13 Trixie also provides a `docker-compose` package containing Compose V2, so the package name should not be confused with historical Compose V1.

docker-compose vs. docker compose – was ist der Unterschied?

Historisch war `docker-compose` ein eigenständiges Programm. Compose V1 wurde als separates Python-Tool ausgeliefert. Compose V2 wurde in Go neu implementiert und als Docker-CLI-Plugin integriert. Deshalb ist `docker compose` heute die bevorzugte Form. Der sichtbare Unterschied ist nur ein Leerzeichen, technisch steckt aber eine andere Architektur dahinter.

Warum Debian 12 → Debian 13 so eine Falle sein kann

Auf Debian 12 können ältere Installationen noch aus einem Paket, einer manuellen Installation oder einem früher eingerichteten Docker-Repository stammen. Debian 13 bringt eine andere Paketlandschaft mit. Wer nach dem Upgrade nur `docker --version` prüft, kann übersehen, dass ein separates `docker-compose`-Binary verschwunden ist.

Vor dem Upgrade: zuerst den Ist-Zustand dokumentieren

Bevor du Debian aktualisierst, solltest du festhalten, wie Docker installiert ist und welche Compose-Variante tatsächlich verwendet wird.

docker --version
docker compose version
docker-compose --version
which docker
which docker-compose
docker compose ls
docker ps -a
dpkg -l | grep -E 'docker|containerd|compose'

Der wichtigste Test: beide Compose-Befehle prüfen

Führe vor dem Upgrade bewusst beide Varianten aus. Wenn `docker compose version` eine Version liefert, ist Compose V2 vorhanden. Wenn zusätzlich `docker-compose --version` funktioniert, existiert noch ein separates Kommando. Genau diese Information entscheidet darüber, ob alte Skripte und Cronjobs angepasst werden müssen.

Compose-Dateien müssen meistens nicht neu geschrieben werden

Der Wechsel von Compose V1 zu V2 bedeutet nicht automatisch, dass deine `compose.yml` neu geschrieben werden muss. Compose V2 verwendet weiterhin das Compose-Dateiformat. Ein sehr nützlicher Test ist `docker compose config`, weil Docker dabei die Datei einliest und die aufgelöste Konfiguration ausgibt.

Der Klassiker: Skripte mit docker-compose

Besonders gefährlich sind Shell-Skripte, systemd-Units, Cronjobs, Deployment-Skripte und Backups, in denen hart `docker-compose` steht. Nach dem Upgrade kann `docker compose up -d` funktionieren, während ein automatisches Skript mit `docker-compose: command not found` scheitert.

So findest du alte Aufrufe

Für ein Projektverzeichnis reicht beispielsweise `grep -RIn --exclude-dir=.git 'docker-compose' /pfad/zum/projekt`. Nicht blind jede Fundstelle ersetzen: Prüfe zuerst, ob es ein echtes Kommando, Dokumentation oder ein Dateiname ist.

grep -RIn --exclude-dir=.git 'docker-compose' /pfad/zum/projekt

Migration: docker-compose durch docker compose ersetzen

Die üblichen Befehle lassen sich direkt umstellen: `docker-compose up -d` wird zu `docker compose up -d`, `docker-compose down` zu `docker compose down`, `docker-compose pull` zu `docker compose pull`, `docker-compose logs -f` zu `docker compose logs -f` und `docker-compose exec web bash` zu `docker compose exec web bash`. Die Compose-Datei bleibt normalerweise unverändert.

Was ist mit docker-compose.yml?

Der Dateiname `docker-compose.yml` kann in bestehenden Projekten weiterhin vorkommen. Das ist nicht dasselbe Problem wie der alte Befehl. Moderne Compose-Projekte verwenden häufig `compose.yaml` oder `compose.yml`; bestehende Dateien mit älteren Namen können weiterhin funktionieren.

Installation auf Debian 13

Wenn Docker aus dem offiziellen Docker-Repository installiert wird, dokumentiert Docker für Debian die Installation von `docker-ce`, `docker-ce-cli`, `containerd.io`, `docker-buildx-plugin` und `docker-compose-plugin`. Debian 13 selbst bietet außerdem ein Paket `docker-compose`, das Compose V2 enthält. Bei einer bestehenden Serverinstallation sollte man sich bewusst für eine Paketquelle entscheiden und nicht mehrere Installationswege vermischen.

Achtung bei docker.io und Docker CE

Docker weist ausdrücklich darauf hin, dass Pakete wie `docker.io`, `docker-compose`, `docker-doc`, `docker-buildx` oder `podman-docker` mit den offiziellen Docker-Paketen kollidieren können. Vor einer Neuinstallation oder Migration sollte deshalb geprüft werden, welche Variante tatsächlich installiert ist.

Was passiert mit Containern, Images und Volumes?

Das Ändern oder Entfernen der Compose-Installation bedeutet nicht automatisch, dass Docker-Daten verschwinden. Docker dokumentiert, dass beim Entfernen der Docker-Pakete Images, Container und Volumes unter `/var/lib/docker/` nicht automatisch gelöscht werden. Trotzdem sollte vor einem Betriebssystem-Upgrade immer ein echtes Backup wichtiger Volumes und Konfigurationsdateien vorhanden sein.

Der sichere Ablauf für Debian 12 → Debian 13

Ein pragmatischer Ablauf: 1. Docker- und Compose-Versionen dokumentieren. 2. Container und Volumes erfassen. 3. Compose-Dateien und `.env` sichern. 4. Skripte auf `docker-compose` prüfen. 5. Docker-Paketquelle dokumentieren. 6. Debian-Upgrade durchführen. 7. Docker-Dienst prüfen. 8. `docker compose version` testen. 9. Projekte mit `docker compose config` validieren. 10. Erst danach Container mit `docker compose up -d` starten.

Nach dem Upgrade: die wichtigsten Prüfungen

Prüfe `systemctl status docker`, danach `docker info`, `docker compose version`, `docker ps -a` und für jedes Projekt `docker compose config`. Anschließend Logs kontrollieren. Ein Container mit Status `Up` ist noch kein Beweis, dass die Anwendung funktioniert.

systemctl status docker
docker info
docker compose version
docker ps -a
docker compose config

systemd, Cron und Automatisierung nicht vergessen

Viele Serverprobleme entstehen erst bei Automatisierungen. Prüfe systemd-Units, Timer, Cronjobs, Backupskripte und Monitoring-Skripte. Ein Dienst, der bisher `/usr/bin/docker-compose` aufgerufen hat, kann nach der Umstellung ins Leere zeigen.

Was ich heute verwenden würde

Auf einem neuen Debian-13-Server würde ich grundsätzlich `docker compose` verwenden und die Compose-Integration über das Docker-Compose-Plugin beziehungsweise eine konsistente Paketquelle installieren. Bei bestehenden Systemen würde ich zuerst den Ist-Zustand prüfen und dann kontrolliert auf Compose V2 umstellen.

Meine Debian-Upgrade-Checkliste

Vor dem Upgrade: `docker --version`, `docker compose version`, `docker-compose --version`, `docker ps -a`, `docker volume ls`, `docker network ls`, `dpkg -l | grep -E 'docker|containerd|compose'`, Suche nach `docker-compose` in Skripten und Backup der Compose-Dateien und wichtigen Volumes. Danach Docker-Dienst, Compose, Konfiguration, Container und Logs prüfen.

Conclusion

The main Docker stumbling block when moving from Debian 12 to Debian 13 is not that Docker suddenly stops working. More often, the Compose installation changes: the old standalone `docker-compose` becomes the modern `docker compose` Docker CLI plugin. Checking versions, package sources, scripts and automation before the upgrade prevents the classic post-reboot surprise.

docker --version
docker compose version
docker-compose --version
docker ps -a
docker volume ls
docker network ls
dpkg -l | grep -E 'docker|containerd|compose'