This guide walks you through setting up a Drupal development environment using DDEV. For AI agent instructions, see AGENTS.md.
Before you begin, make sure you have the following installed:
- Docker Desktop — Download Docker Desktop
- DDEV — DDEV Installation Guide
macOS (Homebrew):
brew install ddev/ddev/ddevWindows / Linux: Follow the official installation instructions at https://ddev.readthedocs.io/en/stable/users/installation/
Verify your installation:
ddev --versionmkdir my-drupal-project
cd my-drupal-projectddev config --project-type=drupal --docroot=web --php-version=8.3This creates a .ddev/config.yaml file with your project settings.
ddev startDDEV will pull the required Docker images and start your containers. This may take a few minutes the first time.
ddev composer create drupal/recommended-projectddev composer require drush/drushddev exec drush site:install standard \
--db-url=mysql://db:db@db/db \
--account-name=admin \
--account-pass=admin \
--yesddev launchYour Drupal site is now running! Log in at /user/login with admin / admin.
| Command | Description |
|---|---|
ddev start |
Start the development environment |
ddev stop |
Stop the environment |
ddev restart |
Restart the environment |
ddev launch |
Open the site in your browser |
ddev exec drush cr |
Clear all Drupal caches |
ddev snapshot |
Create a database snapshot |
ddev restore-snapshot |
Restore a database snapshot |
ddev ssh |
SSH into the web container |
ddev describe |
Show environment details |
ddev poweroff |
Stop all DDEV projects |
These modules are helpful during development:
ddev composer require drupal/devel drupal/admin_toolbar
ddev exec drush pm:enable devel admin_toolbar admin_toolbar_tools -y
ddev exec drush crThe Examples for Developers module provides well-documented, working code samples that demonstrate how to use Drupal's core APIs. It is an excellent reference for learning hooks, plugins, forms, render arrays, and more.
Install it as a dev dependency so it is available locally but excluded from production:
ddev composer require --dev drupal/examplesOnce installed, the example modules are located at web/modules/contrib/examples/. You do not need to enable all of them — browse the directory and enable only the examples relevant to what you are working on:
# List available example modules
ls web/modules/contrib/examples/
# Enable a specific example (e.g., block_example)
ddev exec drush pm:enable block_example -yFor more information, see the Examples project page and the included README files within each example module.
# Export configuration
ddev exec drush config:export
# Import configuration
ddev exec drush config:import
# Run database updates
ddev exec drush updatedbOnce installed, your project will follow this structure:
| Path | Contents |
|---|---|
web/modules/custom/ |
Your custom modules |
web/modules/contrib/examples/ |
Examples for Developers reference modules |
web/themes/custom/ |
Your custom themes |
web/profiles/custom/ |
Your custom install profiles |
config/sync/ |
Exported configuration (after first export) |
.ddev/ |
DDEV configuration files |
DDEV won't start:
ddev poweroff && ddev startPort conflicts: Edit .ddev/config.yaml and change the port settings:
router_http_port: "8080"
router_https_port: "8443"Composer memory issues:
ddev exec php -d memory_limit=-1 /usr/local/bin/composer installCheck environment status:
ddev describe- DDEV Documentation — https://ddev.readthedocs.io
- DDEV Drupal Quick Start — https://ddev.readthedocs.io/en/stable/users/topics/drupal/
- Drupal API Reference — https://api.drupal.org
- Drupal Developer Guide — https://www.drupal.org/docs/develop
- Drupal Coding Standards — https://www.drupal.org/docs/develop/standards
- Drupal at Your Fingertips — https://www.drupalatyourfingertips.com
- Drupal Slack — https://drupal.slack.com