# DDEV — Local PHP Development Environments with Docker

> Practical guide to DDEV — a container-based local development environment for PHP projects like Drupal, TYPO3 and WordPress, driven by a single CLI.

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

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

## Project Setup & Configuration

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

```bash
ddev config
```

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

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

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

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

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

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

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

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

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

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

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

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

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

## Project Lifecycle

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

```bash
ddev start
```

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

```bash
ddev stop
```

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

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

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

```bash
ddev restart
```

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

```bash
ddev pause
```

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

```bash
ddev poweroff
```

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

```bash
ddev delete
```

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

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

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

```bash
ddev delete images
```

## Status & Information

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

```bash
ddev describe
```

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

```bash
ddev list
```

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

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

`ddev version` — Show the DDEV version and system information.

```bash
ddev version
```

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

```bash
ddev launch
```

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

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

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

```bash
ddev status
```

## Shell & Command Execution

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

```bash
ddev ssh
```

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

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

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

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

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

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

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

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

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

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

## Database

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

```bash
ddev mysql
```

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

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

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

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

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

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

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

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

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

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

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

```bash
ddev tableplus
```

## Snapshots

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

```bash
ddev snapshot
```

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

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

`ddev snapshot restore` — Restore the most recent database snapshot.

```bash
ddev snapshot restore
```

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

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

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

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

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

```bash
ddev snapshot list
```

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

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

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

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

## Composer, PHP & Node

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

```bash
ddev composer install
```

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

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

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

```bash
ddev composer update
```

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

```bash
ddev php -v
```

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

```bash
ddev php artisan migrate
```

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

```bash
ddev npm install
```

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

```bash
ddev npm run build
```

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

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

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

```bash
ddev yarn install
```

## Logs

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

```bash
ddev logs
```

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

```bash
ddev logs -f
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
ddev config global
```

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

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

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

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

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

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

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

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

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

```bash
ddev hostname --list
```

## SSL & HTTPS

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

```bash
mkcert -install
```

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

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

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

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

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

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

## Debugging & Profiling

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

```bash
ddev xdebug on
```

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

```bash
ddev xdebug off
```

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

```bash
ddev xdebug status
```

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

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

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

```bash
ddev xhprof on
```

`ddev xhprof off` — Disable the xhprof profiler.

```bash
ddev xhprof off
```

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

```bash
ddev debug nfsmount
```

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

```bash
ddev debug test
```

## Custom Commands & Hooks

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

```bash
ddev deploy
```

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

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

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

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

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

```bash
ddev drush cr
```

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

```bash
ddev wp plugin list
```

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

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

## Cleanup & Maintenance

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

```bash
ddev clean
```

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

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

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

```bash
ddev self-upgrade
```

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

```bash
ddev pull pantheon
```

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

```bash
ddev push acquia
```

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

```bash
ddev mutagen reset
```

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

```bash
ddev mutagen monitor
```

<!-- PROSE:outro -->
## 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.

## Further Reading

- [DDEV – official website](https://ddev.com/) – overview, downloads and blog
- [DDEV documentation](https://docs.ddev.com/en/stable/) – full reference and guides
- [DDEV on GitHub](https://github.com/ddev/ddev) – source code, releases and issue tracker
<!-- PROSE:outro:end -->

## Related Commands

- [docker](https://www.jpkc.com/db/en/cheatsheets/containers/docker/) – the container engine DDEV builds on
- [docker-compose](https://www.jpkc.com/db/en/cheatsheets/containers/docker-compose/) – define multi-container setups declaratively
- [helm](https://www.jpkc.com/db/en/cheatsheets/containers/helm/) – package manager for Kubernetes deployments