Config Options¶
DDEV configuration is stored in YAML files that come in two flavors:
- Project
.ddev/config.yaml
settings, with optional environmental override variants. - Global
$HOME/.ddev/global_config.yaml
settings that can apply to all projects.
Most of these settings take effect when you run ddev start
.
Managing Configuration¶
Setting Options¶
You can hand-edit the YAML files DDEV creates for you after running ddev config
, and you can also define most settings with equivalent CLI arguments:
Environmental Overrides¶
You can override the per-project config.yaml
with files named config.*.yaml
, and files like this are often created by DDEV add-ons. For example, config.elasticsearch.yaml
in Elasticsearch add-on adds additional configuration related to Elasticsearch.
Many teams use config.local.yaml
for configuration that is specific to one environment, and not checked into the team’s default config.yaml
. You might enable Mutagen or enable NFS for the project, for example, only on your machine. Or maybe use a different database type. The file config.local.yaml
is gitignored by default.
For examples, see the Extending and Customizing Environments page.
additional_fqdns
¶
An array of extra fully-qualified domain names to be used for a project.
Type | Default | Usage |
---|---|---|
project | [] | |
Example: additional_fqdns: ["example.com", "sub1.example.com"]
would provide HTTP and HTTPS URLs for example.com
and sub1.example.com
.
See Hostnames and Wildcards and DDEV, Oh My! for more information on DDEV hostname resolution.
Warning
Take care with additional_fqdns
; it adds items to your /etc/hosts
file which can cause confusion.
additional_hostnames
¶
An array of extra hostnames to be used for a project.
Type | Default | Usage |
---|---|---|
project | [] | |
Example: additional_hostnames: ["somename", "someothername", "*.thirdname"]
would provide HTTP and HTTPS URLs for somename.ddev.site
, someothername.ddev.site
, and one.thirdname.ddev.site
+ two.thirdname.ddev.site
.
The wildcard (*.<whatever>
) setting only works if you’re using DNS to resolve hostnames (default) and connected to the internet and using ddev.site
as your project_tld
.
See Hostnames and Wildcards and DDEV, Oh My! for more information on DDEV hostname resolution.
bind_all_interfaces
¶
When the network interfaces of a project should be exposed to the local network, you can specify bind_all_interfaces: true
to do that. This is an unusual application, sometimes used to share projects on a local network.
Type | Default | Usage |
---|---|---|
project | false | Can be true or false . |
composer_root
¶
The relative path, from the project root, to the directory containing composer.json
. (This is where all Composer-related commands are executed.)
Type | Default | Usage |
---|---|---|
project | | |
composer_version
¶
Composer version for the web container and the ddev composer
command.
Type | Default | Usage |
---|---|---|
project | 2 | Can be 2 , 1 , or empty ("" ) for latest major version at container build time.Can also be a minor version like 2.2 for the latest release of that branch, an explicit version like 1.0.22 , or a keyword like stable , preview or snapshot . See Composer documentation. |
corepack_enable
¶
Whether to corepack enable
on Node.js configuration.
Type | Default | Usage |
---|---|---|
project | false | Can be true or false . |
When true
, corepack_enable
will be executed, making latest yarn
and pnpm
package managers available.
database
¶
The type and version of the database engine the project should use.
Type | Default | Usage |
---|---|---|
project | MariaDB 10.11 | Can be MariaDB 5.5–10.8, 10.11, or 11.4, MySQL 5.5–8.0, or PostgreSQL 9–15. See Database Server Types for examples and caveats. |
dbimage_extra_packages
¶
Extra Debian packages for the project’s database container. (This is rarely used.)
Type | Default | Usage |
---|---|---|
project | [] | |
Example: dbimage_extra_packages: ["less"]
will add the less
package when the database container is built.
ddev_version_constraint
¶
You can configure a version constraint for DDEV that will be validated against the running DDEV executable and prevent ddev start
from running if it doesn’t validate. For example:
This is only supported with DDEV versions above v1.22.4; older DDEV versions will ignore this setting.
Type | Default | Usage |
---|---|---|
project | >= 1.22.4 |
default_container_timeout
¶
Seconds DDEV will wait for all containers to become ready.
Type | Default | Usage |
---|---|---|
project | 120 | Can be adjusted to avoid timeouts on slower systems or for huge snapshot restores. |
developer_mode
¶
Not currently used.
Type | Default | Usage |
---|---|---|
global | false | Can true or false . |
disable_http2
¶
Whether to disable HTTP/2 listen in ddev-router
.
Type | Default | Usage |
---|---|---|
global | false | Can be true or false . |
Only available with legacy router: nginx-proxy
, not the default router: traefik
. When true
, the router will not listen for HTTP/2, but use HTTP/1.1 SSL. (Some browsers don’t work well with HTTP/2.)
disable_settings_management
¶
Whether to disable CMS-specific settings file management.
Type | Default | Usage |
---|---|---|
project | false | Can be true or false . |
When true
, DDEV will not create or update CMS-specific settings files.
disable_upload_dirs_warning
¶
Whether to disable the standard warning issued when a project is using performance_mode: mutagen
but upload_dirs
is not configured.
Type | Default | Usage |
---|---|---|
project | false | Can be true or false . |
When true
, DDEV will not issue the normal warning on ddev start
: “You have Mutagen enabled and your ‘php’ project type doesn’t have upload_dirs
set”. See Mutagen and User-Generated Uploads for context on why DDEV avoids doing the Mutagen sync on upload_dirs
.
docroot
¶
Relative path to the document root containing index.php
or index.html
.
Type | Default | Usage |
---|---|---|
project | automatic | DDEV will attempt to detect this and set it for you, otherwise falling back to the current directory. |
fail_on_hook_fail
¶
Whether ddev start
should be interrupted by a failing hook, on a single project or for all projects if used globally.
Type | Default | Usage |
---|---|---|
project global | false | Can be true or false . |
hooks
¶
DDEV-specific lifecycle hooks to be executed.
Type | Default | Usage |
---|---|---|
project | `` | |
host_db_port
¶
Port for binding database server to localhost interface.
Type | Default | Usage |
---|---|---|
project | automatic | |
Not commonly used. Can be a specific port number for a fixed database port. If unset, the port will be assigned automatically and change each time ddev start
is run.
Can be a specific port number for a fixed database port, which can be useful for configuration of host-side database clients. (May still be easier to use ddev mysql
, ddev psql
, ddev sequelace
, etc., which handle changing ports automatically, as does the sample command ddev mysqlworkbench
.)
host_https_port
¶
Specific, persistent HTTPS port for direct binding to localhost interface.
Type | Default | Usage |
---|---|---|
project | automatic | |
Not commonly used. Can be a specific port number for a fixed HTTPS URL. If unset, the port will be assigned automatically and change each time ddev start
is run.
Example: 59001
will have the project always use https://127.0.0.1:59001
for the localhost URL—used less commonly than the named URL which is better to rely on.
host_mailpit_port
¶
Specific, persistent Mailpit port for direct binding to localhost interface.
Type | Default | Usage |
---|---|---|
project | automatic | |
Not commonly used. Can be a specific port number for a fixed Mailpit URL. If unset, the port will be assigned automatically and change each time ddev start
is run.
host_webserver_port
¶
Specific, persistent HTTP port for direct binding to localhost interface.
Type | Default | Usage |
---|---|---|
project | automatic | |
Not commonly used. Can be a specific port number for a fixed HTTP URL. If unset, the port will be assigned automatically and change each time ddev start
is run.
Example: 59000
will have the project always use http://127.0.0.1:59000
for the localhost URL—used less commonly than the named URL which is better to rely on.
instrumentation_opt_in
¶
Whether to allow instrumentation reporting.
Type | Default | Usage |
---|---|---|
global | true | Can be true or false . |
When true
, anonymous usage information is collected via Amplitude.
instrumentation_queue_size
¶
Maximum number of locally collected events for instrumentation reporting.
Type | Default | Usage |
---|---|---|
global | 100 | Can be any integer. |
instrumentation_reporting_interval
¶
Reporting interval in hours for instrumentation reporting.
Type | Default | Usage |
---|---|---|
global | 24 | Can be any integer. |
instrumentation_user
¶
Specific name identifier for instrumentation reporting.
Type | Default | Usage |
---|---|---|
global | `` | |
internet_detection_timeout_ms
¶
Internet detection timeout in milliseconds.
Type | Default | Usage |
---|---|---|
global | 3000 (3 seconds) | Can be any integer. |
DDEV must detect whether the internet is working to determine whether to add hostnames to /etc/hosts
. In rare cases, you may need to increase this value if you have slow but working internet. See FAQ and GitHub issue.
letsencrypt_email
¶
Email associated with Let’s Encrypt feature. (Works in conjunction with use_letsencrypt
.)
Type | Default | Usage |
---|---|---|
global | `` | |
Set with ddev config global --letsencrypt-email=me@example.com
. Used with the casual hosting feature.
mailpit_http_port
¶
Port for project’s Mailpit HTTP URL.
Type | Default | Usage |
---|---|---|
project global | 8025 | Can be changed to avoid a port conflict. |
mailpit_https_port
¶
Port for project’s Mailpit HTTPS URL.
Type | Default | Usage |
---|---|---|
project global | 8026 | Can be changed to avoid a port conflict. |
messages
¶
Configure messages like the Tip of the Day.
Type | Default | Usage |
---|---|---|
global | ticker_interval: | hours between ticker messages. |
Example: Disable the “Tip of the Day” ticker in ~/.ddev/global_config.yaml
Example: Show the “Tip of the Day” ticket every two hours:
name
¶
The URL-friendly name DDEV should use to reference the project.
Type | Default | Usage |
---|---|---|
project | enclosing directory name | Must be unique; no two projects can have the same name. It’s best if this matches the directory name. If this option is omitted, the project will take the name of the enclosing directory. This value may also be set via ddev config --project-name=<name> . (The ddev config flag is project-name , not name , see ddev config docs.)” |
ngrok_args
¶
Extra flags for configuring ngrok when sharing projects with the ddev share
command.
Type | Default | Usage |
---|---|---|
project | `` | |
Example: --basic-auth username:pass1234 --domain foo.ngrok-free.app
.
no_bind_mounts
¶
Whether to not use Docker bind mounts.
Type | Default | Usage |
---|---|---|
global | false | Can true or false . |
Some Docker environments (like remote Docker) do not allow bind mounts, so when true
this turns those off, turns on Mutagen, and uses volume copies to do what bind mounts would otherwise do.
no_project_mount
¶
Whether to skip mounting project into web container.
Type | Default | Usage |
---|---|---|
project | false | Can be true or false . |
Advanced users only!
When true
, project will not be mounted by DDEV into the web container. Enables experimentation with alternate file mounting strategies.
nodejs_version
¶
Node.js version for the web container’s “system” version. n
tool is under the hood.
There is no need to reconfigure nodejs_version
unless you want a version other than the version already specified, which will be the default version at the time the project was configured.
Type | Default | Usage |
---|---|---|
project | current LTS version | any node version, like 16 , 18.2 , 18.19.2 , etc. |
How to install the Node.js version from a file
Your project team may specify the Node.js version in a more general way than in the .ddev/config.yaml
. For example, you may use a .nvmrc
file, the package.json
, or a similar technique. In that case, DDEV can use the external configuration provided by that file.
There is an auto
label (see full documentation):
It reads the target version from a file in the DDEV_APPROOT directory, or any parent directory.
n
looks for in order:
.n-node-version
: version on single line. Custom ton
..node-version
: version on single line. Used by multiple tools..nvmrc
: version on single line. Used bynvm
.- if no version file found, look for
engine
as below.
The engine
label looks for a package.json
file and reads the engines field to determine compatible Node.js.
If your file is not in the DDEV_APPROOT
directory, you can create a link to the parent folder, so that n
can find it. For example, if you have frontend/.nvmrc
, create a .ddev/web-build/Dockerfile.nvmrc
file:
Switching from nvm
to nodejs_version
If switching from using nvm
to using nodejs_version
, you may find that the container continues to use the previously specified version. If this happens, use ddev nvm alias default system
or ddev ssh
into the container (ddev ssh
) and run rm -rf /mnt/ddev-global-cache/nvm_dir/${DDEV_PROJECT}-web
, then ddev restart
.
omit_containers
¶
Containers that should not be loaded automatically for one or more projects.
Type | Default | Usage |
---|---|---|
project global | [] | For projects, can include db , and ddev-ssh-agent .Globally, can include ddev-router , and ddev-ssh-agent . |
Example: omit_containers: [db, ddev-ssh-agent]
starts the project without a db
container and SSH agent. Some containers can be omitted globally in ~/.ddev/global_config.yaml
and the result is additive; all containers named in both places will be omitted.
Warning
Omitting the db
container will cause database-dependent DDEV features to be unstable.
override_config
¶
Whether to override config values instead of merging.
Type | Default | Usage |
---|---|---|
project | false | Can be true or false . |
When true
, the config.*.yaml
file with the option will have its settings override rather than merge with others. Allows statements like use_dns_when_possible: false
or additional_hostnames: []
to work.
See Extending config.yaml
with Custom config.*.yaml
Files.
performance_mode
¶
Defines the performance optimization mode to be used. Currently Mutagen asynchronous caching and NFS are supported. Mutagen is enabled by default on Mac and Windows.
Type | Default | Usage |
---|---|---|
project global | `` | Can be global , none , mutagen , or nfs . |
This is typically a global setting. The project-specific value will override global config.
Workstation configuration is required to use NFS!
See the NFS section on the Performance page.
php_version
¶
The PHP version the project should use.
Type | Default | Usage |
---|---|---|
project | 8.2 | Can be 5.6 , 7.0 , 7.1 , 7.2 , 7.3 , 7.4 , 8.0 , 8.1 , 8.2 , ‘8.3’, or 8.4 . |
You can only specify the major version (7.3
), not a minor version (7.3.2
), from those explicitly available.
project_tld
¶
Default Top-Level-Domain (TLD
) to be used for a project’s domains, or globally for all project domains. This defaults to ddev.site
and it’s easiest to work with DDEV using the default setting.
Type | Default | Usage |
---|---|---|
project global | ddev.site | Can be changed to any TLD you’d prefer. |
See Hostnames and Wildcards and DDEV, Oh My! for more information on DDEV hostname resolution.
required_docker_compose_version
¶
Specific docker-compose version for download.
Type | Default | Usage |
---|---|---|
global | | |
If set to v2.8.0
, for example, it will download and use that version instead of the expected version for docker-compose.
Troubleshooting Only!
This should only be used in specific cases like troubleshooting. Please don’t experiment with it unless directed to do so.
router
¶
Whether to enable the default Traefik router or the deprecated “nginx-proxy” router.
Type | Default | Usage |
---|---|---|
global | traefik | Can traefik or nginx-proxy (deprecated). |
May also be set via ddev config global --router=traefik
or ddev config global --router=nginx-proxy
.
router_bind_all_interfaces
¶
Whether to bind ddev-router
’s ports on all network interfaces.
Type | Default | Usage |
---|---|---|
global | false | Can be true or false . |
When true
, the router will bind on all network interfaces instead of only localhost
, exposing DDEV projects to your local network. This is sometimes used to share projects on a local network, see Sharing Your Project.
router_http_port
¶
Port for DDEV router’s HTTP traffic.
Type | Default | Usage |
---|---|---|
project global | 80 | Usually changed only if there’s a conflicting process using that port. |
See the Troubleshooting page for more on addressing port conflicts.
router_https_port
¶
Port for DDEV router’s HTTPS traffic.
Type | Default | Usage |
---|---|---|
project global | 443 | Usually changed only if there’s a conflicting process using that port. |
See the Troubleshooting page for more on addressing port conflicts.
simple_formatting
¶
Whether to disable most ddev list
and ddev describe
table formatting.
Type | Default | Usage |
---|---|---|
global | false | Can be true or false . If you don’t like the table lines in ddev list or ddev describe , you can completely turn them off with ddev config --simple-formatting=true . |
When true
, turns off most table formatting in ddev list
and ddev describe
and suppresses colorized text everywhere.
table_style
¶
Style for ddev list
and ddev describe
.
Type | Default | Usage |
---|---|---|
global | default | Can be default , bold , and bright . |
bright
is a pleasant, colorful output some people may prefer. If you don’t like the table lines at all, you can remove them with ddev config --simple-formatting=true
.
timezone
¶
Timezone for container and PHP configuration.
Type | Default | Usage |
---|---|---|
project | UTC | Can be any valid timezone, like Europe/Dublin or MST7MDT . |
traefik_monitor_port
¶
Specify an alternate port for the Traefik (ddev-router) monitor port. This defaults to 10999 and rarely needs to be changed, but can be changed in cases of port conflicts.
Type | Default | Usage |
---|---|---|
global | 10999 | Can be any unused port below 65535. |
type
¶
The DDEV-specific project type.
Type | Default | Usage |
---|---|---|
project | php | Can be backdrop , craftcms , django4 , drupal6 , drupal7 , drupal , laravel , magento , magento2 , php , python , shopware6 , silverstripe , typo3 , or wordpress . |
The php
and python
types don’t attempt CMS configuration or settings file management and can work with any project.
The former DDEV project types drupal8
, drupal9
, and drupal10
can still be manually specified; by using drupal
instead, DDEV will autodetect the correct type and its corresponding settings.
upload_dirs
¶
Paths from the project’s docroot to the user-generated files directory targeted by ddev import-files
. Can be outside the docroot but must be within the project directory e.g. ../private
. Some CMSes and frameworks have default upload_dirs
, like Drupal’s sites/default/files
; upload_dirs
will override the defaults, so if you want Drupal to use both sites/default/files
and ../private
you would list both, upload_dirs: ["sites/default/files", "../private"]
. upload_dirs
is used for targeting ddev import-files
and also, when Mutagen is enabled, to bind-mount those directories so their contents does not need to be synced into Mutagen.
If you do not have directories of static assets of this type, or they are small and you don’t care about them, you can disable the warning You have Mutagen enabled and your 'php' project type doesn't have upload_dirs set.
by setting disable_upload_dirs_warning
with ddev config --disable-upload-dirs-warning
.
Type | Default | Usage |
---|---|---|
project | A list of directories. |
use_dns_when_possible
¶
Whether to use DNS instead of editing /etc/hosts
.
Type | Default | Usage |
---|---|---|
project | true | Can be true or false . |
When false
, DDEV will always update the /etc/hosts
file with the project hostname instead of using DNS for name resolution.
See Using DDEV Offline.
use_docker_compose_from_path
¶
Whether to use the system-installed docker-compose. You can otherwise use required_docker_compose_version
to specify a version for download.
Type | Default | Usage |
---|---|---|
global | false | Can true or false . |
When true
, DDEV will use the docker-compose found in on your system’s path instead of using its private, known-good, docker-compose version.
Troubleshooting Only!
This should only be used in specific cases like troubleshooting. (It is used in the Docker Compose automated tests.)
use_hardened_images
¶
Whether to use hardened images for internet deployment.
Type | Default | Usage |
---|---|---|
global | false | Can true or false . |
When true
, more secure hardened images are used for an internet deployment. These do not include sudo in the web container, and the container is run without elevated privileges. Generally used with the casual hosting feature.
use_letsencrypt
¶
Whether to enable Let’s Encrypt integration. (Works in conjunction with letsencrypt_email
.)
Type | Default | Usage |
---|---|---|
global | false | Can true or false . |
May also be set via ddev config global --use-letsencrypt
or ddev config global --use-letsencrypt=false
. When true
, letsencrypt_email
must also be set and the system must be available on the internet. Used with the casual hosting feature.
web_environment
¶
Additional custom environment variables for a project’s web container. (Or for all projects if used globally.)
Type | Default | Usage |
---|---|---|
project global | [] | |
web_extra_daemons
¶
Additional daemons that should automatically be started in the web container.
Type | Default | Usage |
---|---|---|
project | [] | |
web_extra_exposed_ports
¶
Additional named sets of ports to expose via ddev-router
.
Type | Default | Usage |
---|---|---|
project | [] | |
webimage
¶
The Docker image to use for the web server.
Type | Default | Usage |
---|---|---|
project | ddev/ddev-webserver | Specify your own image based on ddev/ddev-webserver. |
Proceed with caution
It’s unusual to change this, and we don’t recommend it without Docker experience and a good reason. Typically, this means additions to the existing web image using a .ddev/web-build/Dockerfile.*
.
webimage_extra_packages
¶
Extra Debian packages for the project’s web container.
Type | Default | Usage |
---|---|---|
project | [] | |
Example: webimage_extra_packages: [php-yaml, php-bcmath]
will add the php-yaml
and php-bcmath
packages when the web container is built.
webserver_type
¶
Which available web server type should be used.
Type | Default | Usage |
---|---|---|
project | nginx-fpm | Can be nginx-fpm , apache-fpm , or nginx-gunicorn . |
To change from the default nginx-fpm
to apache-fpm
, for example, you would need to edit your project’s .ddev/config.yaml
to include the following:
Then run the ddev restart
command to have the change take effect.
working_dir
¶
Working directories used by ddev exec
and ddev ssh
.
Type | Default | Usage |
---|---|---|
project | | |
Example: working_dir: { web: "/var/www", db: "/etc" }
sets the working directories for the web
and db
containers.
wsl2_no_windows_hosts_mgt
¶
(WSL2 only) Whether to disable the management and checking of the Windows hosts file. By default, when using WSL2, DDEV manages the system-wide hosts file on the Windows side (normally C:\Windows\system32\drivers\etc\hosts
) by using ddev.exe
installed on the Windows side. This normally works better for all applications, including browsers and IDEs. However, this behavior can be disabled by setting wsl_no_windows_hosts_mgt: true
.
Type | Default | Usage |
---|---|---|
global | false | Can true or false . |
May also be set via ddev config global --wsl2-no-windows-hosts-mgt
or ddev config global --wsl2-no-windows-hosts-mgt=false
.
xdebug_enabled
¶
Whether Xdebug should be enabled for step debugging or profiling.
Type | Default | Usage |
---|---|---|
project | false | Please leave this false in most cases. Most people use ddev xdebug and ddev xdebug off (or ddev xdebug toggle ) commands. |
xdebug_ide_location
¶
Adjust Xdebug listen location for WSL2 or in-container. This is used very rarely. Ask for help in one of our support channels before changing it unless you understand its use completely.
Type | Default | Usage |
---|---|---|
global | "" | Can be empty ("" ), "wsl2" , "container" , or an explicit IP address. |
For PhpStorm running inside WSL2 (or JetBrains Gateway), use "wsl2"
. For in-container like VS Code Language Server, set to "container"
. It can also be set to an explicit IP address.
Examples:
xdebug_ide_location: 172.16.0.2
when you need to provide an explicit IP address where the IDE is listening. This is very unusual.xdebug_ide_location: container
when the IDE is actually listening inside theddev-webserver
container. This is only done very occasionally with obscure Visual Studio Code setups like VS Code Language Server.xdebug_ide_location: wsl2
when an IDE is running (or listening) in WSL2. This is the situation when running an IDE directly inside WSL2 instead of running it on Windows.