Frequently-asked questions organized into high-level functionality, investigating issues, daily usage, and connecting with our community.
Features & Requirements¶
What operating systems will DDEV work with?¶
DDEV works nearly anywhere Docker will run, including macOS, Windows 10/11 Pro/Enterprise and Home, and every Linux variant we’ve ever tried. It also runs in many Linux-like environments, like ChromeOS (in Linux machine) and Windows 10/11’s WSL2. DDEV works the same on each of these platforms since the important work is done inside identical Docker containers.
Why do you recommend Colima over Docker Desktop on macOS?¶
Colima (with its bundled Lima) is similar to what Docker Desktop provides, with a great DDEV experience on Intel and Apple Silicon machines. We specifically recommend Colima because of some important differences:
- It’s open source software with an MIT license, unlike Docker Desktop which is proprietary software. No license fee to Docker, Inc. and no paid Docker plan required for larger organizations.
- It’s CLI-focused, unlike Docker Desktop’s GUI.
- It’s focused directly on running containers.
- It’s fast and stable.
Do I need to install PHP, Composer, nginx, or Node.js/npm on my workstation?¶
No. These tools live inside DDEV’s Docker containers, so you only need to install Docker and install DDEV. This is especially handy for Windows users where there’s more friction getting these things installed.
Do I lose data when I run
ddev stop, or
No. Your code continues to live on your workstation, and your database is safely stored on a Docker volume—both unaffected by these commands.
How can I connect to my database?¶
The answer depends on where you’re connecting from.
ddev describe command includes database connection details in a row like this:
Inside your project container, where the app itself is running, the database hostname is
127.0.0.1) and the port is the default for your database engine—
3306 for MySQL/MariaDB,
5432 for PostgreSQL.
Outside your project’s web container, for example a database GUI on your workstation, the hostname is
localhost and the port is unique to that project. In the example above, it’s
The username, password, and database are each
db regardless of how you connect.
Can I use additional databases with DDEV?¶
Yes, you can create additional databases and manually do whatever you need on them. They’re created automatically if you use
ddev import-db with the
--target-db option. In this example,
extradb.sql.gz is extracted and imported to a newly-created database named
Can different projects communicate with each other?¶
Yes, this is commonly required for situations like Drupal migrations. For the
web container to access the
db container of another project, use
ddev-<projectname>-db as the hostname of the other project.
Let’s say we have two projects, for example: project A, and project B. In project A, use
mysql -h ddev-projectb-db to access the database server of project B. For HTTP/S communication you can 1) access the web container of project B directly with the hostname
ddev-<projectb>-web and port 80 or 443:
curl https://ddev-projectb-web or 2) Add a
.ddev/docker-compose.communicate.yaml for accessing the other project via the official FQDN.
Can I run DDEV with other development environments at the same time?¶
Yes, as long as they’re configured with different ports. It doesn’t matter whether your other environments use Docker or not, it should only be a matter of avoiding port conflicts.
It’s probably easiest, however, to shut down one before using the other.
For example, if you use Lando for one project, do a
lando poweroff before using DDEV, and then run
ddev poweroff before using Lando again. If you run nginx or Apache locally, stop them before using DDEV. The troubleshooting section goes into more detail about identifying and resolving port conflicts.
Performance & Troubleshooting¶
How can I get the best performance?¶
Docker’s normal mounting can be slow, especially on macOS. See the Performance section for speed-up options including Mutagen and NFS mounting.
How can I troubleshoot what’s going wrong?¶
How can I check that Docker is working?¶
See the troubleshooting section on the Docker Installation page.
Why do I get a 403 or 404 on my project after
Most likely because the docroot is misconfigured, or there’s no
index.html in it. Open your
.ddev/config.yaml file and check the
docroot value, which should be a relative path to the directory containing your project’s
Why do I see nginx headers when I’ve set
Apache runs in the web container, but when you use the
https://*.ddev.site URL, it goes through
ddev-router, which is an nginx reverse proxy. That’s why you see nginx headers even though your web container’s using Apache. Read more in this Stack Overflow answer.
ddev start fail with “error while mounting volume, Permission denied”?¶
This almost always means NFS is enabled in your project, but NFS isn’t working on your machine.
Start by completely turning NFS off for your projects with
ddev config --nfs-mount-enabled=false && ddev config global --nfs-mount-enabled=false. Then later, get NFS working. NFS can be a big performance help on macOS and traditional Windows, and not needed on Linux or Windows WSL2. Most people on macOS and Windows use Mutagen instead of NFS because of its vastly improved performance, so instead of trying to fix this you can disable NFS and enable Mutagen by running
ddev config --nfs-mount-enabled=false --mutagen-enabled.
How can I update/upgrade DDEV?¶
You’ll want to update DDEV using the same method you chose to install it. Since upgrading is basically the same as installing, you can follow DDEV Installation to upgrade.
You can use the
self-upgrade command for getting instructions tailored to your installation.
- On macOS you likely installed via Homebrew; run
brew update && brew upgrade ddev.
- On Linux + WSL2 using Debian/Ubuntu’s
apt installtechnique, run
sudo apt update && sudo apt upgrade ddevlike any other package on your system.
- On Linux + WSL2 with a Homebrew install, run
brew update && brew upgrade ddev.
- On macOS or Linux (including WSL2) if you installed using the install_ddev.sh script you just run it again:
- On traditional Windows, you likely installed with Chocolatey or by downloading the installer package. You can upgrade with
choco upgrade ddevor by visiting the releases page and downloading the installer. Both techniques will work.
- On Arch-Linux based systems, use the standard upgrade techniques, e.g.
How can I install a specific version of DDEV?¶
If you’re using Homebrew, first run
brew unlink ddev to get rid of the version you have there. Then use one of these options:
- Download the version you want from the releases page and place it in your
- Use the install_ddev.sh script with the version number argument. For example, if you want v1.18.3-alpha1, run
curl -fsSL https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh | bash -s v1.18.3-alpha1.
- On Debian/Ubuntu/WSL2 with DDEV installed via apt, you can run
sudo apt update && sudo apt install ddev=<version>, for example
sudo apt install ddev=1.21.1.
- If you want the very latest, unreleased version of DDEV, run
brew unlink ddev && brew install drud/ddev/ddev --HEAD.
How can I back up or restore all project databases?¶
You can back up all projects that show in
ddev list with
ddev snapshot -a. This only snapshots projects displayed in
ddev list; any projects not shown there will need to be started so they’re be registered in
How can I share my local project with someone?¶
See Sharing Your Project.
How do I make DDEV match my production environment?¶
You can change the major PHP version and choose between nginx+fpm (default) and Apache+fpm and choose the MariaDB/MySQL/PostgreSQL version add extra services like Solr and Memcached. You won’t be able to make every detail match your production server, but with database server type and version, PHP version and web server type you’ll be close.
How do I completely destroy a project?¶
ddev delete <project> to destroy a project. By default, a
ddev snapshot of your database is taken, but you can skip this using
ddev delete --omit-snapshot or
ddev delete --omit-snapshot -y. See
ddev delete -h for options. It’s up to you to then delete the code directory.
What if I don’t like the settings files or gitignores DDEV creates?¶
You have several options:
- Use the
disable_settings_management: trueoption in the project’s
.ddev/config.yamlfile. This disables DDEV from updating CMS-related settings files.
- Use the more generic “php” project type rather than a CMS-specific one; it basically means “don’t try to create settings files for me”. The “php” type works great for experienced developers.
- Take over the settings file or
.gitignoreby deleting the line
#ddev-generatedin it, then check in the file. If that line is removed, DDEV will not try to replace or change the file.
How can I change a project’s name?¶
Delete it and migrate it to a new project with your preferred name:
- Export the project’s database:
ddev export-db --file=/path/to/db.sql.gz.
- Delete the project:
ddev delete <project>. (This takes a snapshot by default for safety.)
- Rename the project:
ddev config --project-name=<new_name>.
- Start thew new project with
- Import the database dump from step one:
ddev import-db --src=/path/to/db.sql.gz.
How can I move a project to another directory?¶
How can I move a project to another workstation?¶
Take a snapshot, move the project files, and restore the snapshot in a new project on the target workstation:
ddev start && ddev snapshot.
ddev stop --unlist.
- Move the project directory to another computer any way you want.
- On the new computer, run
ddev start && ddev snapshot restore --latest.
- Optionally, on the old computer, run
ddev delete --omit-snapshotto remove its copy of the database.
How can I move a project from traditional Windows to WSL2?¶
This is exactly the same as moving a project from one computer to another described above. Make sure you move the project into a native filesystem in WSL2, most likely
Why does DDEV want to edit
If you see “The hostname
ping <hostname>, it may be that DNS resolution is slow.
DDEV doesn’t have control over your computer’s name resolution, so it doesn’t have any way to influence how your browser gets an IP address from a hostname. It knows you have to be connected to the internet to do that, and uses a test DNS lookup of
<somethingrandom>.ddev.site as a way to guess whether you’re connected to the internet. If it’s unable to do a name lookup, or if the hostname associated with your project is not
*.ddev.site, it will try to create entries in
/etc/hosts, since it’s assuming you can’t look up your project’s hostname(s) via DNS. If your internet (and name resolution) is actually working, but DNS is slow, run
ddev config global --internet-detection-timeout-ms=3000 to set the timeout to 3 seconds (or higher). See this GitHub issue for more. (If DNS rebinding is disallowed on your network/router, this won’t be solvable without network/router changes. Help here and here.) For more detailed troubleshooting information, please see the troubleshooting section.
How can I configure a project with the defaults without hitting RETURN a bunch of times?¶
ddev config --auto to set the docroot and project type based on the discovered code.
If anything in
.ddev/config.yaml is wrong, you can edit that directly or use
ddev config commands to update settings.
How do I get support?¶
How can I contribute to DDEV?¶
We love and welcome contributions of knowledge, support, docs, and code:
- Submit an issue or pull request to the main repo.
- Add your external resource to awesome-ddev.
- Add your recipe or HOWTO to ddev-contrib.
- Help others in Discord and on Stack Overflow.
- Contribute financially via GitHub Sponsors.
- Get involved with DDEV governance and the Advisory Group.