ddev drush config:export -y
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:Likewise, switch payment systems, webhooks, CRM connections, and other integrations to local or sandbox settings.Private files and remote object storage need separate handling. A successful public-file import does not mean every asset has been transferred.
What DDEV does for a Drupal project
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.A production deployment usually moves reviewed code and configuration forward while preserving live content and activity.Let DDEV manage these local connection settings rather than placing production database credentials into your local environment.ddev composer install
ddev drush status
Create a handoff directory outside the project’s web root:
Before you begin: understand the pieces you are moving
You can run PHP tools inside that environment:
| Component | What it contains | How it usually moves |
|---|---|---|
| Code | Custom modules, themes, Composer files, scripts | Git repository or reviewed source archive |
| Database | Content, users, active configuration, application data | SQL export |
| Uploaded files | Images, documents, and other managed assets | File archive or approved file transfer |
| Environment settings | DDEV configuration, local overrides, service connections | Shared configuration plus separately managed secrets |
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.Install the new site:Similarly, a DDEV environment does not supply production secrets, DNS configuration, backups, or operational monitoring.
Step 1: Install DDEV and a Docker provider
Follow DDEV’s Windows installer instructions. Its recommended WSL2 option can configure Docker CE inside your Linux environment.
On macOS
An export recreates a site at a particular point in time.DDEV normally creates settings.ddev.php and adds an include to Drupal’s settings.php.
On Windows
tar -czf ../drupal-handoff/files.tar.gz
-C web/sites/default/files .
mkdir -p ../drupal-handoff
ddev export-db
--file=../drupal-handoff/database.sql.gz
Commands use a macOS, Linux, or Windows WSL2 shell. Replace example paths and repository addresses with your own.Avoid changing PHP, database engines, dependencies, and Drupal configuration simultaneously while troubleshooting an import. First recreate the original environment, then make deliberate changes.drupal-handoff/
├── code.tar.gz
├── database.sql.gz
├── files.tar.gz
└── README.md
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.
Step 2: Create a new Drupal 11 project
For a quick local database checkpoint before experimenting, you can also use:For a Git-based project, replace this example URL:Create a directory and configure DDEV: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.A typical handoff directory now looks like this:ddev import-db --file=/path/to/database.sql.gz
The most useful verification is recreating the site from the exported files.From the project root, archive the public files:Once local settings and integrations are configured:
Step 3: Collect an existing project from another environment
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.
- The correct code revision, including
composer.jsonandcomposer.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.
mkdir -p ~/projects
git clone
https://example.com/your-team/your-drupal-project.git
~/projects/drupal-existing
cd ~/projects/drupal-existing
ddev composer create-project "drupal/recommended-project:^11"
ddev composer require drush/drush
Create a separate directory: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.
Step 4: Bring the code into DDEV
ddev mailpit
To bring in a site from a hosting provider, another developer, or a different local tool, obtain:ddev config --project-name=drupal-restored
ddev start
ddev composer install
ddev restart
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.Install and start a supported provider, then use Homebrew:brew install ddev/ddev/ddev
mkcert -install
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.If you made intended Drupal configuration changes, export them:Follow DDEV’s instructions for your distribution’s Docker and package-manager setup. Repository configuration differs between Debian-based and RPM-based systems.
Step 5: Check local settings before importing the database
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.For a team handoff, share the Git repository and the exact commit corresponding to the database export.If the recipient needs a source archive, create one from the committed revision:
| Setting | Value |
|---|---|
| Database host | db |
| Database name | db |
| Username | db |
| Password | db |
If you received a code archive, extract it into a project directory instead. Locate composer.json before continuing.ddev import-files
--source=/path/to/files.tar.gz
--extract-path=files
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.
Step 6: Import the database and uploaded files
mkdir -p ~/projects/drupal-restored
tar -xzf /path/to/drupal-handoff/code.tar.gz
-C ~/projects/drupal-restored
cd ~/projects/drupal-restored
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.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.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.This guide covers all three, including an easily missed detail: a Drupal project is more than its code folder.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
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 drush cache:rebuild
ddev drush status
ddev drush user:login
ddev launch
Check that the local settings load correctly, especially if the imported project has custom settings logic or references to hosting-specific files.
Step 7: Verify the imported website
A typical Drupal site has these components:If the project has no DDEV configuration, create one. For example, for a Drupal 11 site using PHP 8.3 and MariaDB 10.11:
- 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.
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.Include the intended, non-secret parts of:DDEV records the settings in .ddev/config.yaml. See DDEV’s configuration options.ddev snapshot --name=before-changes
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.The examples below assume a Composer-managed Drupal site with a web document root. Run project commands from the directory containing composer.json.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.Import the public files:DDEV provides the local environment. Your project may still need additional services, such as search, Redis, or a frontend build process.
Step 9: Export your uploaded files and configuration
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.If the archive did not include DDEV configuration, configure the correct project type, document root, PHP version, and database before starting.DDEV’s default database connection uses:DDEV needs a supported Docker provider. The installation route depends on your operating system.Use the local project to prepare and test the release. Treat the live deployment as its own controlled step.DDEV supports adding its configuration to an existing codebase before importing the application’s data. Read about starting a DDEV project.
Step 10: Export the code and environment definition
That makes it useful for starting a new Drupal site, taking over an existing project, or handing your work to another developer.Check that both tools respond:
composer.jsonandcomposer.lock.- Custom modules, themes, and other application code.
- Configuration exports.
.ddev/config.yamland required shared DDEV files.- Frontend build manifests and lock files.
- A README describing setup and additional services.
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
Use this section for a new, empty site. If you are importing an existing website, skip to Step 3.For local email testing, open Mailpit:Neither option is a complete project backup on its own.Download Drupal and add Drush:Keep database dumps and transfer archives outside the public document root.
Step 11: Restore the export into a second DDEV project
docker version
ddev version
ddev drush site:install standard
--account-name=admin
--site-name="Drupal Local"
-y
ddev drush user:login
ddev launch
ddev start
ddev composer install
ddev restart
Document the code revision, PHP and database versions, required services, and asset locations. Share credentials through your team’s approved secret-management process.Import the database from your transfer directory:Start the environment and install its locked dependencies:ddev import-files --source=/path/to/files.tar.gz
ddev import-files --source=/path/to/files
Use the official instructions for your platform rather than mixing installation methods from different tutorials. See DDEV’s installation guide and Docker provider setup.For that setup, run project commands inside WSL2 and keep project files in its Linux filesystem, such as ~/projects, rather than /mnt/c.Review and commit the intended files first.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.
Common problems and what to check
| Problem | First checks |
|---|---|
| DDEV cannot start | Docker provider is running; inspect ddev logs |
| Drupal files exist but the browser shows an error | Check docroot and whether Composer installation completed |
| Database connection fails | Confirm DDEV settings load and hosting-specific settings are overridden |
| Composer reports a PHP mismatch | Match DDEV’s PHP version to the project requirements |
| Images are missing | Check file-import location and nested archive folders |
| Site redirects to production | Inspect local overrides, domain modules, redirects, and custom code |
| Imported database reports collation errors | Check source and target database compatibility |
| Local forms send real email | Inspect SMTP and API integrations; verify Mailpit routing |
| A restored project is incomplete | Check uncommitted files, private assets, submodules, and external services |
If .ddev/config.yaml already exists, review and reuse it. Check project-specific instructions and hooks before starting the environment.
Everyday DDEV commands worth keeping nearby
| Task | Command |
|---|---|
| Start this project | ddev start |
| Stop this project | ddev stop |
| List local projects | ddev list |
| Show project URLs and connection details | ddev describe |
| Open the website | ddev launch |
| Open a container shell | ddev ssh |
| Rebuild Drupal caches | ddev drush cr |
| Inspect Drupal status | ddev drush status |
| Open captured email | ddev mailpit |
ddev config
--project-name=drupal-existing
--project-type=drupal11
--docroot=web
--php-version=8.3
--database=mariadb:10.11
Use backups and exports from the same site, matched to a compatible code 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.
