DDEV — Lokale PHP-Entwicklungsumgebung mit Docker

DDEV ist eine containerbasierte lokale Entwicklungsumgebung, die Webserver, Datenbank und PHP in Docker- oder Podman-Containern kapselt und über ein einheitliches CLI steuerbar macht. Statt jede Komponente von Hand zu installieren, beschreibst du dein Projekt in einer einzigen Konfigurationsdatei und startest die komplette Umgebung mit einem Befehl. Besonders im PHP- und CMS-Umfeld – Drupal, TYPO3, WordPress, Contao oder Shopware – hat sich das Werkzeug als Standard etabliert. Dieser Guide führt dich durch die wichtigsten Befehle für den Alltag, vom Anlegen eines Projekts über Datenbank-Im- und -Export bis zu Xdebug und Add-ons.

Projekt-Setup & Konfiguration

ddev config — Konfiguriert ein neues oder bestehendes DDEV-Projekt im aktuellen Verzeichnis interaktiv. Erstellt oder aktualisiert .ddev/config.yaml.

ddev config

ddev config --project-name <name> — Setzt den Projektnamen (wird für den Hostnamen verwendet: .ddev.site).

ddev config --project-name myshop

ddev config --project-type <type> — Setzt den Projekttyp. Optionen: php, wordpress, drupal, drupal6, drupal7, drupal10, drupal11, typo3, magento, magento2, laravel, craftcms, django4, python und mehr.

ddev config --project-type wordpress

ddev config --php-version <version> — Setzt die PHP-Version für das Projekt. Unterstützt: 5.6, 7.0 – 7.4, 8.0 – 8.4.

ddev config --php-version 8.3

ddev config --webserver-type <type> — Setzt den Webserver-Typ: nginx-fpm (Standard), apache-fpm oder nginx-gunicorn.

ddev config --webserver-type apache-fpm

ddev config --docroot <path> — Setzt das Document-Root relativ zum Projektverzeichnis.

ddev config --docroot web

ddev config --database <type>:<version> — Setzt Datenbanktyp und -version. Optionen: mysql:5.7, mysql:8.0, mariadb:10.6, mariadb:10.11, postgres:14 usw.

ddev config --database mariadb:10.11

ddev config --additional-hostnames <names> — Fügt zusätzliche Hostnamen (kommagetrennt) hinzu, die auf das Projekt zeigen.

ddev config --additional-hostnames api.myshop,cdn.myshop

ddev config --timezone <tz> — Setzt die Zeitzone des Containers.

ddev config --timezone Europe/Berlin

Projekt-Lebenszyklus

ddev start — Startet das DDEV-Projekt im aktuellen Verzeichnis. Lädt bei Bedarf Docker-Images herunter.

ddev start

ddev stop — Stoppt die Container des DDEV-Projekts, ohne sie zu entfernen.

ddev stop

ddev stop --all — Stoppt alle laufenden DDEV-Projekte auf dem Rechner.

ddev stop --all

ddev restart — Stoppt und startet das DDEV-Projekt. Übernimmt Konfigurationsänderungen.

ddev restart

ddev pause — Pausiert die Projekt-Container, um CPU/Speicher freizugeben, ohne den Zustand zu verlieren.

ddev pause

ddev poweroff — Stoppt alle DDEV-Projekte und den globalen Router. Vor dem Herunterfahren verwenden.

ddev poweroff

ddev delete — Entfernt das DDEV-Projekt (Container, Volumes). Löscht NICHT die Projektdateien.

ddev delete

ddev delete --omit-snapshot — Löscht das Projekt, ohne vorher einen Datenbank-Snapshot zu erstellen.

ddev delete --omit-snapshot

ddev delete images — Entfernt alle ungenutzten DDEV-Docker-Images, um Speicherplatz freizugeben.

ddev delete images

Status & Informationen

ddev describe — Zeigt detaillierten Status, URLs, Datenbank-Infos und Service-Details des aktuellen Projekts.

ddev describe

ddev list — Listet alle DDEV-Projekte auf dem Rechner mit ihrem Status auf.

ddev list

ddev list --active-only — Listet nur die aktuell laufenden DDEV-Projekte auf.

ddev list --active-only

ddev version — Zeigt die DDEV-Version und Systeminformationen an.

ddev version

ddev launch — Öffnet die Projekt-URL im Standardbrowser.

ddev launch

ddev launch /path — Öffnet einen bestimmten Pfad der Projekt-URL im Browser.

ddev launch /wp-admin

ddev status — Zeigt den Status der Container des aktuellen Projekts an.

ddev status

Shell & Befehlsausführung

ddev ssh — Öffnet eine SSH-Sitzung im Web-Container des aktuellen Projekts als Benutzer www-data.

ddev ssh

ddev ssh -s db — Öffnet eine SSH-Sitzung im Datenbank-Container.

ddev ssh -s db

ddev exec <command> — Führt einen Befehl im Web-Container aus.

ddev exec ls -la /var/www/html

ddev exec -s db <command> — Führt einen Befehl im Datenbank-Container aus.

ddev exec -s db mysql -u root -proot mydb

ddev exec --raw <command> — Führt einen Befehl ohne das Standard-Environment-Setup aus (roher Docker-exec).

ddev exec --raw cat /etc/os-release

ddev . <command> — Kurzform für ddev exec. Führt einen Befehl im Web-Container aus.

ddev . php -v

Datenbank

ddev mysql — Öffnet eine interaktive MySQL-/MariaDB-Shell, verbunden mit der Projektdatenbank.

ddev mysql

ddev mysql -e "<query>" — Führt eine SQL-Abfrage direkt aus der Shell aus.

ddev mysql -e "SHOW TABLES;"

ddev import-db --file=<file> — Importiert einen Datenbank-Dump (.sql, .sql.gz, .sql.bz2, .tar, .zip) in die Projektdatenbank.

ddev import-db --file=dump.sql.gz

ddev import-db --database=<name> --file=<file> — Importiert einen Dump in eine bestimmte benannte Datenbank.

ddev import-db --database=staging --file=staging.sql

ddev export-db --file=<file> — Exportiert die Projektdatenbank in eine komprimierte SQL-Datei.

ddev export-db --file=backup.sql.gz

ddev export-db --gzip=false --file=<file> — Exportiert die Datenbank als unkomprimierte SQL-Datei.

ddev export-db --gzip=false --file=backup.sql

ddev export-db | gzip > backup.sql.gz — Exportiert die Datenbank nach stdout und leitet sie an gzip weiter.

ddev export-db | gzip > backup.sql.gz

ddev tableplus — Öffnet die Datenbank in der TablePlus-GUI (falls installiert).

ddev tableplus

Snapshots

ddev snapshot — Erstellt einen Snapshot des aktuellen Datenbankzustands. Kann später wiederhergestellt werden.

ddev snapshot

ddev snapshot --name <name> — Erstellt einen benannten Datenbank-Snapshot zur leichteren Identifikation.

ddev snapshot --name before-migration

ddev snapshot restore — Stellt den neuesten Datenbank-Snapshot wieder her.

ddev snapshot restore

ddev snapshot restore <name> — Stellt einen bestimmten benannten Snapshot wieder her.

ddev snapshot restore before-migration

ddev snapshot restore --latest — Stellt den neuesten Snapshot ohne Rückfrage wieder her.

ddev snapshot restore --latest

ddev snapshot list — Listet alle verfügbaren Snapshots des aktuellen Projekts auf.

ddev snapshot list

ddev snapshot delete <name> — Löscht einen bestimmten benannten Snapshot.

ddev snapshot delete before-migration

ddev snapshot delete --all — Löscht alle Snapshots des aktuellen Projekts.

ddev snapshot delete --all

Composer, PHP & Node

ddev composer <args> — Führt Composer im Web-Container mit der passenden PHP-Version aus.

ddev composer install

ddev composer require <package> — Fügt ein Composer-Paket im Container hinzu.

ddev composer require monolog/monolog

ddev composer update — Aktualisiert alle Composer-Abhängigkeiten im Container.

ddev composer update

ddev php <args> — Führt die PHP-CLI im Web-Container aus.

ddev php -v

ddev php artisan <command> — Führt einen Laravel-Artisan-Befehl im Container aus.

ddev php artisan migrate

ddev npm <args> — Führt npm im Web-Container aus.

ddev npm install

ddev npm run <script> — Führt ein npm-Skript im Container aus.

ddev npm run build

ddev node <args> — Führt Node.js im Web-Container aus.

ddev node --version

ddev yarn <args> — Führt Yarn im Web-Container aus (falls Yarn installiert ist).

ddev yarn install

Logs

ddev logs — Zeigt die Logs des Web-Containers (stdout/stderr von nginx/apache + PHP).

ddev logs

ddev logs -f — Folgt den Logs des Web-Containers in Echtzeit (tail).

ddev logs -f

ddev logs -s db — Zeigt die Logs des Datenbank-Containers.

ddev logs -s db

ddev logs -s db -f — Folgt den Logs des Datenbank-Containers in Echtzeit.

ddev logs -s db -f

ddev logs --tail <n> — Zeigt nur die letzten N Zeilen der Container-Logs.

ddev logs --tail 100

Add-ons & Services

ddev add-on get <addon> — Installiert ein DDEV-Add-on (früher 'ddev get'). Add-ons liefern zusätzliche Dienste wie Redis, Solr, Memcached, Mailpit usw.

ddev add-on get ddev/ddev-redis

ddev add-on list --all — Listet alle verfügbaren offiziellen DDEV-Add-ons aus der Registry auf.

ddev add-on list --all

ddev add-on list — Listet die im Projekt installierten Add-ons auf.

ddev add-on list

ddev add-on remove <addon> — Entfernt ein installiertes Add-on aus dem Projekt.

ddev add-on remove ddev-redis

ddev add-on get ddev/ddev-mailpit — Installiert Mailpit zum lokalen Testen von E-Mails (ersetzt Mailhog).

ddev add-on get ddev/ddev-mailpit

ddev add-on get ddev/ddev-phpmyadmin — Installiert phpMyAdmin zur Datenbankverwaltung.

ddev add-on get ddev/ddev-phpmyadmin

ddev add-on get ddev/ddev-adminer — Installiert Adminer als schlanke UI zur Datenbankverwaltung.

ddev add-on get ddev/ddev-adminer

Dateiverwaltung

ddev import-files --source=<path> — Importiert Dateien (tar.gz-Archiv oder Verzeichnis) in das Upload-/Dateiverzeichnis des Projekts.

ddev import-files --source=files.tar.gz

ddev export-files --destination=<path> — Exportiert das Upload-/Dateiverzeichnis des Projekts in ein tar.gz-Archiv.

ddev export-files --destination=files-backup.tar.gz

ddev exec scp <remote>:<path> <local> — Kopiert Dateien von einem Remote-Server in den Container per SCP über SSH-Agent-Weiterleitung.

ddev exec scp user@prod:/var/www/html/files ./files

Globale Konfiguration

ddev config global — Zeigt und bearbeitet die globale DDEV-Konfiguration (gilt für alle Projekte).

ddev config global

ddev config global --instrumentation-opt-in=false — Deaktiviert die Erhebung anonymer Nutzungsstatistiken.

ddev config global --instrumentation-opt-in=false

ddev config global --use-hardened-images=true — Verwendet global gehärtete (sicherheitsoptimierte) Docker-Images.

ddev config global --use-hardened-images=true

ddev config global --router-bind-all-interfaces=true — Bindet den DDEV-Router an alle Netzwerkschnittstellen (für LAN-Zugriff von anderen Geräten).

ddev config global --router-bind-all-interfaces=true

ddev config global --performance-mode=mutagen — Aktiviert Mutagen-Dateisynchronisation für deutlich bessere Datei-Performance unter macOS/Windows.

ddev config global --performance-mode=mutagen

ddev config global --simple-formatting=true — Deaktiviert farbige/gerahmte Tabellenausgabe für einfacheres Terminal-Logging.

ddev config global --simple-formatting=true

ddev hostname --list — Listet alle aktuell von DDEV in /etc/hosts verwalteten Hostnamen auf.

ddev hostname --list

SSL & HTTPS

mkcert -install — Installiert die mkcert-Root-CA. Einmalig nach der Installation von mkcert ausführen. Für vertrauenswürdiges HTTPS in DDEV erforderlich.

mkcert -install

ddev config --use-dns-when-possible=true — Nutzt DNS zur Hostnamen-Auflösung statt /etc/hosts (erfordert Internetzugang).

ddev config --use-dns-when-possible=true

ddev exec curl -sI https://localhost — Testet die HTTPS-Verbindung im Container.

ddev exec curl -sI https://localhost

ddev debug router-nginx-config — Zeigt die generierte nginx-Router-Konfiguration zur Fehlersuche bei HTTPS/Routing-Problemen.

ddev debug router-nginx-config

Debugging & Profiling

ddev xdebug on — Aktiviert Xdebug im Web-Container für Step-Debugging.

ddev xdebug on

ddev xdebug off — Deaktiviert Xdebug (wird beim Container-Neustart wieder aktiv, sofern nicht in der Konfiguration gesetzt).

ddev xdebug off

ddev xdebug status — Zeigt an, ob Xdebug derzeit aktiviert oder deaktiviert ist.

ddev xdebug status

ddev config --xdebug-enabled=true — Aktiviert Xdebug dauerhaft für dieses Projekt (bleibt über Neustarts hinweg erhalten).

ddev config --xdebug-enabled=true

ddev xhprof on — Aktiviert den xhprof-PHP-Profiler. Die Profiler-UI ist über die DDEV-URL erreichbar.

ddev xhprof on

ddev xhprof off — Deaktiviert den xhprof-Profiler.

ddev xhprof off

ddev debug nfsmount — Testet, ob NFS korrekt funktioniert (macOS-NFS-Performance-Modus).

ddev debug nfsmount

ddev debug test — Führt eine Reihe von Selbsttests aus, um DDEVs Konfiguration und Umgebung zu prüfen.

ddev debug test

Eigene Befehle & Hooks

ddev <custom-command> — Führt einen eigenen Befehl aus, definiert in .ddev/commands/web/ oder .ddev/commands/host/.

ddev deploy

ddev artisan <command> — Führt Laravel Artisan über einen eigenen DDEV-Befehl aus (falls als Add-on konfiguriert).

ddev artisan migrate:fresh --seed

ddev craft <command> — Führt Craft-CMS-CLI-Befehle im Container aus.

ddev craft migrate/all

ddev drush <command> — Führt Drush (Drupal-CLI) im Container aus.

ddev drush cr

ddev wp <command> — Führt WP-CLI-Befehle im Container aus (bei WordPress-Projekttyp).

ddev wp plugin list

ddev typo3 <command> — Führt TYPO3-Console-Befehle im Container aus.

ddev typo3 cache:flush

Aufräumen & Wartung

ddev clean — Entfernt temporäre Docker-Images und -Container, die zu keinem Projekt gehören.

ddev clean

ddev clean --all — Entfernt alle DDEV-Docker-Images, -Container und -Netzwerke. Vollständige Bereinigung.

ddev clean --all

ddev self-upgrade — Aktualisiert DDEV auf die neueste Version (bei Installation per self-upgrade-Methode).

ddev self-upgrade

ddev pull <provider> — Holt Datenbank und/oder Dateien von einem konfigurierten Remote-Provider (z. B. Pantheon, Acquia, Platform.sh).

ddev pull pantheon

ddev push <provider> — Überträgt Datenbank und/oder Dateien an einen konfigurierten Remote-Provider.

ddev push acquia

ddev mutagen reset — Setzt die Mutagen-Sync-Sitzung zurück (macOS/Windows-Performance-Modus). Nutzen, wenn die Synchronisation aus dem Tritt gerät.

ddev mutagen reset

ddev mutagen monitor — Überwacht den Mutagen-Sync-Status in Echtzeit.

ddev mutagen monitor

Fazit

DDEV nimmt dir die mühsame Einrichtung lokaler Entwicklungsumgebungen ab: Ein ddev config, ein ddev start – und Webserver, Datenbank und PHP laufen reproduzierbar im Container. Weil die komplette Konfiguration im Projekt unter .ddev/ liegt, arbeitet dein ganzes Team mit identischen Versionen, und neue Projektmitglieder sind in Minuten startklar. Wer tiefer einsteigt, kombiniert Add-ons, Mutagen-Sync und eigene Befehle zu einem Workflow, der die Lücke zwischen lokaler Maschine und Produktion spürbar verkleinert.

Weiterführende Links

DDEV – offizielle Website – Überblick, Download und Blog (englisch)
DDEV-Dokumentation – vollständige Referenz und Anleitungen (englisch)
DDEV auf GitHub – Quellcode, Releases und Issue-Tracker (englisch)