DDEV — Local PHP Development Environments with Docker

DDEV is a container-based local development environment that wraps your web server, database and PHP into Docker (or Podman) containers, all driven through a single, consistent CLI. Instead of installing each component by hand, you describe your project in one configuration file and spin up the whole stack with a single command. It has become a de-facto standard in the PHP and CMS world – Drupal, TYPO3, WordPress, Contao and Shopware among them. This guide walks you through the commands you reach for daily, from creating a project to database import and export, Xdebug and add-ons.

Project Setup & Configuration

ddev config — Interactively configure a new or existing DDEV project in the current directory. Creates or updates .ddev/config.yaml.

ddev config

ddev config --project-name <name> — Set the project name (used for the hostname: .ddev.site).

ddev config --project-name myshop

ddev config --project-type <type> — Set the project type. Options: php, wordpress, drupal, drupal6, drupal7, drupal10, drupal11, typo3, magento, magento2, laravel, craftcms, django4, python, and more.

ddev config --project-type wordpress

ddev config --php-version <version> — Set the PHP version for the project. Supported: 5.6, 7.0 – 7.4, 8.0 – 8.4.

ddev config --php-version 8.3

ddev config --webserver-type <type> — Set the web server type: nginx-fpm (default), apache-fpm, or nginx-gunicorn.

ddev config --webserver-type apache-fpm

ddev config --docroot <path> — Set the document root relative to the project directory.

ddev config --docroot web

ddev config --database <type>:<version> — Set the database type and version. Options: mysql:5.7, mysql:8.0, mariadb:10.6, mariadb:10.11, postgres:14, etc.

ddev config --database mariadb:10.11

ddev config --additional-hostnames <names> — Add extra hostnames (comma-separated) that resolve to the project.

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

ddev config --timezone <tz> — Set the container timezone.

ddev config --timezone Europe/Berlin

Project Lifecycle

ddev start — Start the DDEV project in the current directory. Pulls Docker images if needed.

ddev start

ddev stop — Stop the DDEV project containers without removing them.

ddev stop

ddev stop --all — Stop all running DDEV projects on the machine.

ddev stop --all

ddev restart — Stop and start the DDEV project. Applies config changes.

ddev restart

ddev pause — Pause the project containers to free CPU/memory without losing state.

ddev pause

ddev poweroff — Stop all DDEV projects and the global router. Use before shutting down.

ddev poweroff

ddev delete — Remove the DDEV project (containers, volumes). Does NOT delete project files.

ddev delete

ddev delete --omit-snapshot — Delete the project without creating a database snapshot first.

ddev delete --omit-snapshot

ddev delete images — Remove all unused DDEV Docker images to free disk space.

ddev delete images

Status & Information

ddev describe — Show detailed status, URLs, database info, and service details for the current project.

ddev describe

ddev list — List all DDEV projects on the machine with their status.

ddev list

ddev list --active-only — List only currently running DDEV projects.

ddev list --active-only

ddev version — Show the DDEV version and system information.

ddev version

ddev launch — Open the project URL in the default browser.

ddev launch

ddev launch /path — Open a specific path on the project URL in the browser.

ddev launch /wp-admin

ddev status — Show the status of the current project's containers.

ddev status

Shell & Command Execution

ddev ssh — SSH into the web container of the current project as the www-data user.

ddev ssh

ddev ssh -s db — SSH into the database container.

ddev ssh -s db

ddev exec <command> — Execute a command inside the web container.

ddev exec ls -la /var/www/html

ddev exec -s db <command> — Execute a command inside the database container.

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

ddev exec --raw <command> — Execute a command without the default environment setup (raw Docker exec).

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

ddev . <command> — Shorthand for ddev exec. Run a command in the web container.

ddev . php -v

Database

ddev mysql — Open an interactive MySQL/MariaDB shell connected to the project database.

ddev mysql

ddev mysql -e "<query>" — Execute a SQL query directly from the shell.

ddev mysql -e "SHOW TABLES;"

ddev import-db --file=<file> — Import a database dump (.sql, .sql.gz, .sql.bz2, .tar, .zip) into the project database.

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

ddev import-db --database=<name> --file=<file> — Import a dump into a specific named database.

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

ddev export-db --file=<file> — Export the project database to a compressed SQL file.

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

ddev export-db --gzip=false --file=<file> — Export the database as a plain (uncompressed) SQL file.

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

ddev export-db | gzip > backup.sql.gz — Export the database to stdout and pipe it to gzip.

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

ddev tableplus — Open the database in TablePlus GUI (if installed).

ddev tableplus

Snapshots

ddev snapshot — Create a snapshot of the current database state. Can be restored later.

ddev snapshot

ddev snapshot --name <name> — Create a named database snapshot for easy identification.

ddev snapshot --name before-migration

ddev snapshot restore — Restore the most recent database snapshot.

ddev snapshot restore

ddev snapshot restore <name> — Restore a specific named snapshot.

ddev snapshot restore before-migration

ddev snapshot restore --latest — Restore the latest snapshot without prompting.

ddev snapshot restore --latest

ddev snapshot list — List all available snapshots for the current project.

ddev snapshot list

ddev snapshot delete <name> — Delete a specific named snapshot.

ddev snapshot delete before-migration

ddev snapshot delete --all — Delete all snapshots for the current project.

ddev snapshot delete --all

Composer, PHP & Node

ddev composer <args> — Run Composer inside the web container with the correct PHP version.

ddev composer install

ddev composer require <package> — Require a Composer package inside the container.

ddev composer require monolog/monolog

ddev composer update — Update all Composer dependencies inside the container.

ddev composer update

ddev php <args> — Run PHP CLI inside the web container.

ddev php -v

ddev php artisan <command> — Run a Laravel Artisan command inside the container.

ddev php artisan migrate

ddev npm <args> — Run npm inside the web container.

ddev npm install

ddev npm run <script> — Run an npm script inside the container.

ddev npm run build

ddev node <args> — Run Node.js inside the web container.

ddev node --version

ddev yarn <args> — Run Yarn inside the web container (if Yarn is installed).

ddev yarn install

Logs

ddev logs — Show the web container logs (stdout/stderr from nginx/apache + PHP).

ddev logs

ddev logs -f — Follow (tail) the web container logs in real-time.

ddev logs -f

ddev logs -s db — Show logs from the database container.

ddev logs -s db

ddev logs -s db -f — Follow the database container logs in real-time.

ddev logs -s db -f

ddev logs --tail <n> — Show only the last N lines of container logs.

ddev logs --tail 100

Add-ons & Services

ddev add-on get <addon> — Install a DDEV add-on (formerly 'ddev get'). Add-ons provide extra services like Redis, Solr, Memcached, Mailpit, etc.

ddev add-on get ddev/ddev-redis

ddev add-on list --all — List all available official DDEV add-ons from the registry.

ddev add-on list --all

ddev add-on list — List add-ons currently installed in the project.

ddev add-on list

ddev add-on remove <addon> — Remove an installed add-on from the project.

ddev add-on remove ddev-redis

ddev add-on get ddev/ddev-mailpit — Install Mailpit for local email testing (replaces Mailhog).

ddev add-on get ddev/ddev-mailpit

ddev add-on get ddev/ddev-phpmyadmin — Install phpMyAdmin for database management.

ddev add-on get ddev/ddev-phpmyadmin

ddev add-on get ddev/ddev-adminer — Install Adminer as a lightweight database management UI.

ddev add-on get ddev/ddev-adminer

File Management

ddev import-files --source=<path> — Import files (tar.gz archive or directory) into the project's upload/files directory.

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

ddev export-files --destination=<path> — Export the project's upload/files directory to a tar.gz archive.

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

ddev exec scp <remote>:<path> <local> — Copy files from a remote server into the container using SCP via SSH agent forwarding.

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

Global Configuration

ddev config global — Show and edit global DDEV configuration (applies to all projects).

ddev config global

ddev config global --instrumentation-opt-in=false — Opt out of anonymous usage statistics collection.

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

ddev config global --use-hardened-images=true — Use hardened (security-focused) Docker images globally.

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

ddev config global --router-bind-all-interfaces=true — Bind the DDEV router to all network interfaces (for LAN access from other devices).

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

ddev config global --performance-mode=mutagen — Enable Mutagen file sync for significantly faster file performance on macOS/Windows.

ddev config global --performance-mode=mutagen

ddev config global --simple-formatting=true — Disable colorized/boxed table output for simpler terminal logging.

ddev config global --simple-formatting=true

ddev hostname --list — List all hostnames currently managed by DDEV in /etc/hosts.

ddev hostname --list

SSL & HTTPS

mkcert -install — Install the mkcert root CA. Run once after installing mkcert. Required for trusted HTTPS in DDEV.

mkcert -install

ddev config --use-dns-when-possible=true — Use DNS for hostname resolution instead of /etc/hosts (requires internet access).

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

ddev exec curl -sI https://localhost — Test the HTTPS connection inside the container.

ddev exec curl -sI https://localhost

ddev debug router-nginx-config — Show the generated nginx router configuration for debugging HTTPS/routing issues.

ddev debug router-nginx-config

Debugging & Profiling

ddev xdebug on — Enable Xdebug inside the web container for step debugging.

ddev xdebug on

ddev xdebug off — Disable Xdebug (re-enables when container restarts, unless set in config).

ddev xdebug off

ddev xdebug status — Show whether Xdebug is currently enabled or disabled.

ddev xdebug status

ddev config --xdebug-enabled=true — Permanently enable Xdebug for this project (persists across restarts).

ddev config --xdebug-enabled=true

ddev xhprof on — Enable xhprof PHP profiler. Access the profiler UI via the DDEV URL.

ddev xhprof on

ddev xhprof off — Disable the xhprof profiler.

ddev xhprof off

ddev debug nfsmount — Test whether NFS is working correctly (macOS NFS performance mode).

ddev debug nfsmount

ddev debug test — Run a series of self-tests to check DDEV's configuration and environment.

ddev debug test

Custom Commands & Hooks

ddev <custom-command> — Run a custom command defined in .ddev/commands/web/ or .ddev/commands/host/.

ddev deploy

ddev artisan <command> — Run Laravel Artisan via a custom DDEV command (if configured as add-on).

ddev artisan migrate:fresh --seed

ddev craft <command> — Run Craft CMS CLI commands inside the container.

ddev craft migrate/all

ddev drush <command> — Run Drush (Drupal CLI) inside the container.

ddev drush cr

ddev wp <command> — Run WP-CLI commands inside the container (if WordPress project type).

ddev wp plugin list

ddev typo3 <command> — Run TYPO3 Console commands inside the container.

ddev typo3 cache:flush

Cleanup & Maintenance

ddev clean — Remove temporary Docker images and containers not associated with any project.

ddev clean

ddev clean --all — Remove all DDEV Docker images, containers, and networks. Full cleanup.

ddev clean --all

ddev self-upgrade — Upgrade DDEV to the latest version (if installed via the self-upgrade method).

ddev self-upgrade

ddev pull <provider> — Pull database and/or files from a configured remote provider (e.g. Pantheon, Acquia, Platform.sh).

ddev pull pantheon

ddev push <provider> — Push database and/or files to a configured remote provider.

ddev push acquia

ddev mutagen reset — Reset the Mutagen sync session (macOS/Windows performance mode). Use if sync gets out of sync.

ddev mutagen reset

ddev mutagen monitor — Monitor the Mutagen sync status in real-time.

ddev mutagen monitor

Conclusion

DDEV takes the tedium out of setting up local development environments: one ddev config, one ddev start, and your web server, database and PHP run reproducibly in containers. Because the entire configuration lives inside the project under .ddev/, your whole team works with identical versions and new contributors are up and running in minutes. As you go deeper, add-ons, Mutagen sync and custom commands combine into a workflow that meaningfully narrows the gap between your local machine and production.