Built-in Developer Tools¶
ddev describe to see the project information and services available for your project and how to access them.
Command-line Tools in the Containers¶
Hundreds of useful developer tools are included inside the containers and can be used via
ddev exec or
ddev ssh. Some of those include:
- MySQL client (
mysql) - Command-line interface for interacting with MySQL/MariaDB.
- PostgreSQL client (
psql) - Command-line tool for PostgreSQL.
- Drush - Command-line shell and Unix scripting interface for Drupal.
- PHIVE - Command line tool for “PHAR Installation and Verification Environment”.
- WP-CLI - Command-line tools for managing WordPress installations, available both as
yarn(these also have
These tools can be accessed for single commands using
ddev exec <command> or
ddev ssh for an interactive
You can also add tools that are not provided by default using
webimage_extra_packages or a custom Dockerfile.
DDEV and Composer¶
DDEV provides a built-in command to simplify use of PHP’s dependency manager, Composer, without requiring it to be installed on the host machine. Generally, executing any Composer command through DDEV is as simple as prepending the command with
ddev. DDEV will execute the command at the project root in the web container, passing (almost) all arguments and flags to Composer. To execute Composer in other directories within the container, use
ddev ssh or
ddev exec -d <dir>. For example:
ddev composer helpruns Composer’s help command to learn more about what’s available.
ddev composer require <package>tells Composer to require a specific PHP package for the current project.
Additionally, Composer can be used to initialize new projects with
ddev composer create. This command supports limited argument and flag options, and will install a new project to the project root in
/var/www/html. The package and version arguments are required:
ddev composer create [<flags>] "<package>:<version>"
ddev composer create --no-dev "typo3/cms-base-distribution:^9"
To execute a fully-featured
composer create-project command, you can execute the command from within the container after executing
ddev ssh, or pass the full command to
ddev exec, like so:
ddev exec composer create-project ...
DDEV uses Composer 2 by default. Use the
--composer-version option to roll back to version 1:
ddev config --composer-version=1 && ddev start.
composer.json Location: It’s most common for
composer.json to be in the project root, but you can specify an alternate Composer root using DDEV’s
composer_root option in
ddev config --composer-root <dir>. The
composer_root value is the relative path from the project root to the directory containing
composer.json. If yours is at
docroot/composer.json, for example, the
composer_root value should be
Careful with Global Requirements!
If you run
ddev composer global require (or
composer global require inside the web container), global packages will be installed at the home directory within the container (
~/.composer) and will disappear when the container restarts—meaning you’ll need to re-run the command.
You may want to synchronize created Composer configuration and installed packages with the DDEV’s
homeadditions directory on your host machine.
Windows OS and
DDEV attempts to help with Composer and some configurations of Docker Desktop for Windows that introduce complex filesystem workarounds.
ddev composer (Composer inside the container) instead of using
composer on the host side, because it uses the right version of PHP and all its extensions for your project:
- On some older configurations of Docker Desktop for Windows, symlinks are created in the container as “simulated symlinks”, or XSym files. These special text files behave as symlinks inside the container (on CIFS filesystem), but appear as simple text files on the Windows host. (On the CIFS filesystem used by Docker for Windows, inside the container, there is no capability to create real symlinks even though Windows now has this capability.)
- DDEV attempts to clean up for this situation. Since Windows 10/11+ (in developer mode) can create real symlinks, DDEV scans your repository after a
ddev composercommand and attempts to convert XSym files into real symlinks. On older versions of Windows 10, it can only do this if your Windows 10 workstation is set to “Developer Mode”.
- To enable developer mode on Windows 10/11+, search for “developer” in settings:
Email Capture and Review (MailHog)¶
MailHog is a mail catcher that’s configured to capture and display emails sent by PHP in the development environment.
After your project is started, access the MailHog web interface at
https://mysite.ddev.site:8026, or run
ddev launch -m to launch it in your default browser.
MailHog will not intercept emails if your application is configured to use SMTP or a third-party ESP integration.
If you’re using SMTP for outgoing mail—with Symfony Mailer or SMTP modules, for example—update your application’s SMTP server configuration to use
localhost and MailHog’s port
For Drupal 9+
settings.ddev.php overrides the Symfony Mailer sendmail configuration to use MailHog.
For Drupal 8/9
settings.ddev.php overrides the Swift Mailer transport configuration to use MailHog.
For Laravel projects, MailHog will capture Swift messages via SMTP. Update your
.env to use Mailhog with the following settings:
MAIL_MAILER=smtp MAIL_HOST=localhost MAIL_PORT=1025 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=null
Using Development Tools on the Host Machine¶
It’s possible in many cases to use development tools installed on your host machine on a project provisioned by DDEV. Tools that interact with files and require no database connection, such as Git or Composer, can be run from the host machine against the code base for a DDEV project with no additional configuration necessary.
Database Connections from the Host¶
If you need to connect to your project’s database from your workstation, run
ddev describe to show the database connection information, like
Each project’s database port is unique, and randomly chosen from available ports on your system when you run
You can force this port to be the same on every
ddev start by setting
host_db_port in the project’s
.ddev/config.yaml. For example,
host_db_port: "49156" or
ddev config --host-db-port=49156. This value needs to be different on each running DDEV project, and unless it is set, the database port will change on every
You can use this port with various tools that need a direct port, like
psql clients, but it’s usually easiest to use
ddev tableplus, etc, which set everything up for you.
(If you use PhpStorm and its integrated database browser, use the DDEV Integration Plugin to manage all of this for you.)
Using Drush 8 Installation on Your Host Machine¶
We don’t recommend using
drush on your host machine. It’s also mostly irrelevant for Drupal 9+, as you should be using Composer-installed, project-level
If you have PHP and Drush installed on your host system and the environment variable
IS_DDEV_PROJECT=true, you can use Drush to interact with a DDEV project. On the host machine, extra host-side configuration for the database and port in
settings.ddev.php allow Drush to access the database server. This may not work for all Drush commands because the actual web server environment is not available.
On Drupal 8+, if you want to use
drush uli on the host (or other Drush commands that require a default URI), you’ll need to set
DRUSH_OPTIONS_URI on the host. For example,
DDEV and Terminus¶
Terminus is a command line tool providing advanced interaction with Pantheon services.
terminus is available inside the project’s container, allowing users to get information from, or issue commands to their Pantheon-hosted sites. This is an especially helpful feature for Windows users since Terminus is only officially supported on Unix-based systems.
To use Terminus, you’ll first need to:
- Use a machine token. (See Pantheon provider discussion.)
ddev sshto tunnel into your container.
- Issue a command using the keyword
terminus. For help using Terminus, try
terminus listto get a list of possible commands.
Terminus also allows you to issue Drush, WP-CLI, and Composer commands to your Pantheon server. These are all usable from within the container as well, but will require authentication via either your Pantheon password or an SSH key. To use your host machine’s SSH key, you can use the
ddev auth ssh command described here.