Getting a Drupal site running locally should not require an afternoon of negotiating with PHP versions, database settings, and a web server that worked perfectly yesterday.

DDEV helps by giving each project a configurable development environment. You work with familiar commands while it manages the containers running the application and database.

That makes it useful for starting a new Drupal site, taking over an existing project, or handing your work to another developer.

This guide covers all three, including an easily missed detail: a Drupal project is more than its code folder.

DDEV uses containers to provide the services your application needs. Project settings live in a .ddev directory, allowing a team to share the environment configuration alongside its code.

You can run PHP tools inside that environment:

ddev composer install
ddev drush status

This helps avoid situations where one developer runs Composer against a different PHP version from everyone else.

Your project files remain available to your editor on your computer. The database lives in a container-managed volume, so copying the code directory alone does not copy the database. Read how DDEV works (opens in a new tab).

DDEV provides the local environment. Your project may still need additional services, such as search, Redis, or a frontend build process.

A typical Drupal site has these components:

Drupal configuration exports are another important part of the workflow. They describe settings such as fields, content types, and Views. They do not replace a database export containing your content and users. Read about Drupal configuration management (opens in a new tab).

The examples below assume a Composer-managed Drupal site with a web document root. Run project commands from the directory containing composer.json.

Commands use a macOS, Linux, or Windows WSL2 shell. Replace example paths and repository addresses with your own.

DDEV needs a supported Docker provider. The installation route depends on your operating system.

Install and start a supported provider, then use Homebrew:

brew install ddev/ddev/ddev
mkcert -install

The certificate setup allows browsers to trust local HTTPS sites.

Follow DDEV’s Windows installer instructions. Its recommended WSL2 option can configure Docker CE inside your Linux environment.

For that setup, run project commands inside WSL2 and keep project files in its Linux filesystem, such as ~/projects, rather than /mnt/c.

Follow DDEV’s instructions for your distribution’s Docker and package-manager setup. Repository configuration differs between Debian-based and RPM-based systems.

Use the official instructions for your platform rather than mixing installation methods from different tutorials. See DDEV’s installation guide (opens in a new tab) and Docker provider setup (opens in a new tab).

Check that both tools respond:

docker version
ddev version

If Docker reports that it cannot connect to the server, resolve that before creating a project.

Use this section for a new, empty site. If you are importing an existing website, skip to Step 3.

Create a directory and configure DDEV:

mkdir -p ~/projects/drupal-local
cd ~/projects/drupal-local

ddev config \
  --project-type=drupal11 \
  --docroot=web \
  --php-version=8.3 \
  --database=mariadb:10.11

ddev start

These PHP and database versions are an example environment. For a team project, choose supported versions that match its requirements.

DDEV records the settings in .ddev/config.yaml. See DDEV’s configuration options (opens in a new tab).

Download Drupal and add Drush:

ddev composer create-project "drupal/recommended-project:^11"
ddev composer require drush/drush

This follows DDEV’s Drupal quickstart approach while explicitly selecting the Drupal 11 release series. See DDEV’s Drupal quickstart (opens in a new tab).

Install the new site:

ddev drush site:install standard \
  --account-name=admin \
  --site-name="Drupal Local" \
  -y

ddev drush user:login
ddev launch

Open the one-time login URL printed by Drush to access the local administration interface. Treat that URL as a login credential.

Do not run site:install against an existing site you intend to preserve. It initializes a Drupal database; it is not an import command. Read Drush’s site:install documentation (opens in a new tab).

To bring in a site from a hosting provider, another developer, or a different local tool, obtain:

• The correct code revision, including composer.json and composer.lock.
• A database dump, commonly database.sql.gz.
• The public uploaded files, commonly from web/sites/default/files.
• Any private files or externally stored assets the project needs.
• Its PHP version, database engine and version, and additional service requirements.

Use backups and exports from the same site, matched to a compatible code revision.

Get the database and files through your hosting provider’s backup tools or your team’s established export process. A ZIP containing website code usually does not include the database.

Keep database dumps and transfer archives outside the public document root.

If the source contains customer information, use an approved sanitized dataset where possible. Also arrange local credentials, or disable integrations, before bootstrapping the imported application.

For a Git-based project, replace this example URL:

mkdir -p ~/projects

git clone \
  https://example.com/your-team/your-drupal-project.git \
  ~/projects/drupal-existing

cd ~/projects/drupal-existing

Check out the branch or commit that matches the database backup.

If you received a code archive, extract it into a project directory instead. Locate composer.json before continuing.

If .ddev/config.yaml already exists, review and reuse it. Check project-specific instructions and hooks before starting the environment.

If the project has no DDEV configuration, create one. For example, for a Drupal 11 site using PHP 8.3 and MariaDB 10.11:

ddev config \
  --project-name=drupal-existing \
  --project-type=drupal11 \
  --docroot=web \
  --php-version=8.3 \
  --database=mariadb:10.11

Use drupal10 for a Drupal 10 project, and match the source environment’s supported database engine and version. Do not treat MySQL and MariaDB as automatically interchangeable.

Start the environment and install its locked dependencies:

ddev start
ddev composer install
ddev restart

Use composer install to reproduce the versions recorded in composer.lock. Running composer update would introduce dependency changes while you are trying to recreate the existing site. Read about Composer’s lock-file workflow (opens in a new tab).

DDEV supports adding its configuration to an existing codebase before importing the application’s data. Read about starting a DDEV project (opens in a new tab).

DDEV normally creates settings.ddev.php and adds an include to Drupal’s settings.php.

Check that the local settings load correctly, especially if the imported project has custom settings logic or references to hosting-specific files.

DDEV’s default database connection uses:

Let DDEV manage these local connection settings rather than placing production database credentials into your local environment.

Keep local-only overrides separate from shared production settings. The generated settings.ddev.php file is normally Git-ignored. Read about DDEV’s CMS settings management (opens in a new tab).

If the site depends on Redis, Solr, or another service, configure its local equivalent or the project’s documented local fallback. DDEV offers add-ons for additional services. See DDEV services and add-ons (opens in a new tab).

Import the database from your transfer directory:

ddev import-db --file=/path/to/database.sql.gz

This replaces the current local database by default. Export anything you need from that local database before proceeding. Read about DDEV database imports (opens in a new tab).

Import the public files:

ddev import-files --source=/path/to/files.tar.gz

You can also import from an existing directory:

ddev import-files --source=/path/to/files

Use the directory containing the uploaded files, not the entire Drupal codebase.

For an archive, its root should contain the contents of the files directory. If it instead contains a top-level files folder, select that path:

ddev import-files \
  --source=/path/to/files.tar.gz \
  --extract-path=files

This avoids accidentally producing sites/default/files/files. Read DDEV’s file import guidance (opens in a new tab).

Check your destination files before importing into a populated project. DDEV empties the destination directory before it imports, so treat imports as replacements, not a way to merge different sets of uploads.

Private files and remote object storage need separate handling. A successful public-file import does not mean every asset has been transferred.

Once local settings and integrations are configured:

ddev drush cache:rebuild
ddev drush status
ddev drush user:login
ddev launch

Verify more than the homepage:

• Log in and open the administration interface.
• Inspect several content pages.
• Check images and downloadable files.
• Create or edit test content.
• Test a form.
• Check search and custom functionality.
• Review Drupal’s status report and logs.

If the checked-out code intentionally requires database updates, follow the project’s update process after backing up the local database. Do not run updates or import configuration merely because you copied a site.

For local email testing, open Mailpit:

ddev mailpit

DDEV captures normal PHP mail, but direct SMTP or external email APIs can bypass that capture. Verify your project’s mail configuration before submitting forms or triggering notifications. Read about DDEV email capture (opens in a new tab).

Likewise, switch payment systems, webhooks, CRM connections, and other integrations to local or sandbox settings.

Create a handoff directory outside the project’s web root:

mkdir -p ../drupal-handoff

ddev export-db \
  --file=../drupal-handoff/database.sql.gz

This creates a compressed SQL export. It contains database data, not your custom code or uploaded files. See the DDEV export command (opens in a new tab).

For a quick local database checkpoint before experimenting, you can also use:

ddev snapshot --name=before-changes

Snapshots are useful for local recovery, but database type and version matter when restoring them. A SQL export is generally the clearer handoff format between environments. Read about DDEV database management (opens in a new tab).

Neither option is a complete project backup on its own.

From the project root, archive the public files:

tar -czf ../drupal-handoff/files.tar.gz \
  -C web/sites/default/files .

The -C option changes the source directory for the archive. The final dot includes its contents, producing the layout expected by ddev import-files.

If the project uses private files, create a separate archive from the configured private directory. Keep those files outside the public web root when restoring them.

If you made intended Drupal configuration changes, export them:

ddev drush config:export -y

Use the project’s existing configuration-sync directory. If a new project does not have an appropriate shared directory configured, establish one outside the public document root before adopting the configuration workflow.

Review the exported changes before committing them. Local-only service settings and development modules should not accidentally become production configuration. Read Drush’s config:export documentation (opens in a new tab).

For a team handoff, share the Git repository and the exact commit corresponding to the database export.

Include the intended, non-secret parts of:

• composer.json and composer.lock.
• Custom modules, themes, and other application code.
• Configuration exports.
• .ddev/config.yaml and required shared DDEV files.
• Frontend build manifests and lock files.
• A README describing setup and additional services.

Review and commit the intended files first.

If the recipient needs a source archive, create one from the committed revision:

git archive \
  --format=tar.gz \
  --output=../drupal-handoff/code.tar.gz \
  HEAD

This includes committed files only. Uncommitted work, ignored files, and untracked assets will not appear in the archive. Git submodules also require separate attention.

A typical handoff directory now looks like this:

drupal-handoff/
├── code.tar.gz
├── database.sql.gz
├── files.tar.gz
└── README.md

Add private-file archives or other required assets separately.

Document the code revision, PHP and database versions, required services, and asset locations. Share credentials through your team’s approved secret-management process.

The most useful verification is recreating the site from the exported files.

Create a separate directory:

mkdir -p ~/projects/drupal-restored

tar -xzf /path/to/drupal-handoff/code.tar.gz \
  -C ~/projects/drupal-restored

cd ~/projects/drupal-restored

Assuming the archive includes the project’s DDEV configuration, give this copy a distinct name:

ddev config --project-name=drupal-restored

ddev start
ddev composer install
ddev restart

Import the database and files:

ddev import-db \
  --file=/path/to/drupal-handoff/database.sql.gz

ddev import-files \
  --source=/path/to/drupal-handoff/files.tar.gz

ddev drush cache:rebuild
ddev drush status
ddev launch

Restore any private files and additional services described in the README.

If the archive did not include DDEV configuration, configure the correct project type, document root, PHP version, and database before starting.

Repeat the functional checks from Step 7. Missing custom code, incorrect archive layouts, and undocumented services are much easier to fix now than after someone else receives the handoff.

An export recreates a site at a particular point in time.

A production deployment usually moves reviewed code and configuration forward while preserving live content and activity.

Uploading your local database over an active production database can overwrite newer submissions, users, orders, or editorial changes. Use your hosting platform’s deployment process and your team’s release plan.

Similarly, a DDEV environment does not supply production secrets, DNS configuration, backups, or operational monitoring.

Use the local project to prepare and test the release. Treat the live deployment as its own controlled step.

Avoid changing PHP, database engines, dependencies, and Drupal configuration simultaneously while troubleshooting an import. First recreate the original environment, then make deliberate changes.

Use ddev stop when you finish working. It preserves your local database. Removing a DDEV project is a different operation and can delete its database. Read about managing DDEV projects (opens in a new tab).

A useful local environment should be repeatable: another developer can obtain the code, import the data and files, follow the README, and reach the same working site.

What usually takes the longest when you set up a Drupal project locally: dependencies, database imports, missing files, or reproducing the hosting environment? Share your experience in the comments.