# DDEV — Lokale PHP-Entwicklungsumgebung mit Docker

> Praxis-Guide zu DDEV — containerbasierte lokale Entwicklungsumgebung für PHP-Projekte wie Drupal, TYPO3 und WordPress, gesteuert über ein einheitliches CLI.

Source: https://www.jpkc.com/db/cheatsheets/containers/ddev/

<!-- PROSE:intro -->
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.
<!-- PROSE:intro:end -->

## Projekt-Setup & Konfiguration

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

```bash
ddev config
```

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

```bash
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.

```bash
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.

```bash
ddev config --php-version 8.3
```

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

```bash
ddev config --webserver-type apache-fpm
```

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

```bash
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.

```bash
ddev config --database mariadb:10.11
```

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

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

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

```bash
ddev config --timezone Europe/Berlin
```

## Projekt-Lebenszyklus

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

```bash
ddev start
```

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

```bash
ddev stop
```

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

```bash
ddev stop --all
```

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

```bash
ddev restart
```

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

```bash
ddev pause
```

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

```bash
ddev poweroff
```

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

```bash
ddev delete
```

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

```bash
ddev delete --omit-snapshot
```

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

```bash
ddev delete images
```

## Status & Informationen

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

```bash
ddev describe
```

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

```bash
ddev list
```

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

```bash
ddev list --active-only
```

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

```bash
ddev version
```

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

```bash
ddev launch
```

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

```bash
ddev launch /wp-admin
```

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

```bash
ddev status
```

## Shell & Befehlsausführung

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

```bash
ddev ssh
```

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

```bash
ddev ssh -s db
```

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

```bash
ddev exec ls -la /var/www/html
```

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

```bash
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).

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

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

```bash
ddev . php -v
```

## Datenbank

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

```bash
ddev mysql
```

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

```bash
ddev mysql -e "SHOW TABLES;"
```

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

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

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

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

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

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

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

```bash
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.

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

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

```bash
ddev tableplus
```

## Snapshots

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

```bash
ddev snapshot
```

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

```bash
ddev snapshot --name before-migration
```

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

```bash
ddev snapshot restore
```

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

```bash
ddev snapshot restore before-migration
```

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

```bash
ddev snapshot restore --latest
```

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

```bash
ddev snapshot list
```

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

```bash
ddev snapshot delete before-migration
```

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

```bash
ddev snapshot delete --all
```

## Composer, PHP & Node

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

```bash
ddev composer install
```

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

```bash
ddev composer require monolog/monolog
```

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

```bash
ddev composer update
```

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

```bash
ddev php -v
```

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

```bash
ddev php artisan migrate
```

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

```bash
ddev npm install
```

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

```bash
ddev npm run build
```

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

```bash
ddev node --version
```

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

```bash
ddev yarn install
```

## Logs

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

```bash
ddev logs
```

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

```bash
ddev logs -f
```

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

```bash
ddev logs -s db
```

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

```bash
ddev logs -s db -f
```

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

```bash
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.

```bash
ddev add-on get ddev/ddev-redis
```

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

```bash
ddev add-on list --all
```

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

```bash
ddev add-on list
```

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

```bash
ddev add-on remove ddev-redis
```

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

```bash
ddev add-on get ddev/ddev-mailpit
```

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

```bash
ddev add-on get ddev/ddev-phpmyadmin
```

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

```bash
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.

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

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

```bash
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.

```bash
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).

```bash
ddev config global
```

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

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

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

```bash
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).

```bash
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.

```bash
ddev config global --performance-mode=mutagen
```

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

```bash
ddev config global --simple-formatting=true
```

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

```bash
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.

```bash
mkcert -install
```

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

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

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

```bash
ddev exec curl -sI https://localhost
```

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

```bash
ddev debug router-nginx-config
```

## Debugging & Profiling

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

```bash
ddev xdebug on
```

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

```bash
ddev xdebug off
```

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

```bash
ddev xdebug status
```

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

```bash
ddev config --xdebug-enabled=true
```

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

```bash
ddev xhprof on
```

`ddev xhprof off` — Deaktiviert den xhprof-Profiler.

```bash
ddev xhprof off
```

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

```bash
ddev debug nfsmount
```

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

```bash
ddev debug test
```

## Eigene Befehle & Hooks

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

```bash
ddev deploy
```

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

```bash
ddev artisan migrate:fresh --seed
```

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

```bash
ddev craft migrate/all
```

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

```bash
ddev drush cr
```

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

```bash
ddev wp plugin list
```

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

```bash
ddev typo3 cache:flush
```

## Aufräumen & Wartung

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

```bash
ddev clean
```

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

```bash
ddev clean --all
```

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

```bash
ddev self-upgrade
```

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

```bash
ddev pull pantheon
```

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

```bash
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.

```bash
ddev mutagen reset
```

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

```bash
ddev mutagen monitor
```

<!-- PROSE:outro -->
## 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](https://ddev.com/) – Überblick, Download und Blog (englisch)
- [DDEV-Dokumentation](https://docs.ddev.com/en/stable/) – vollständige Referenz und Anleitungen (englisch)
- [DDEV auf GitHub](https://github.com/ddev/ddev) – Quellcode, Releases und Issue-Tracker (englisch)
<!-- PROSE:outro:end -->

## Verwandte Kommandos

- [docker](https://www.jpkc.com/db/cheatsheets/containers/docker/) – die Container-Engine, auf der DDEV aufsetzt
- [docker-compose](https://www.jpkc.com/db/cheatsheets/containers/docker-compose/) – Multi-Container-Setups deklarativ definieren
- [helm](https://www.jpkc.com/db/cheatsheets/containers/helm/) – Paketmanager für Kubernetes-Deployments