Config Options¶

DDEV configuration is stored in YAML files that come in two flavors:

1. Project .ddev/config.yaml settings, with optional environmental override variants.
2. 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:

php_version: "8.4"

ddev config --php-version 8.4

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. For example, you might enable performance_mode: mutagen only on your machine. Or you could 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.

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.

additional_hostnames¶

An array of extra hostnames to be used for a 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.

composer_root¶

The relative path, from the project root, to the directory containing composer.json. (This is where all Composer-related commands are executed.)

composer_version¶

Composer version for the web container and the ddev composer command.

ddev utility rebuild

corepack_enable¶

Whether to run corepack enable on Node.js configuration.

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.

dbimage_extra_packages¶

Extra Debian packages for the project’s database container. (This is rarely used.)

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:

ddev_version_constraint: '>= v1.24.0-alpha1'

default_container_timeout¶

Seconds DDEV will wait for all containers to become ready.

developer_mode¶

Not currently used.

disable_settings_management¶

Whether to disable CMS-specific settings file management.

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.

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.

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.

hooks¶

DDEV-specific lifecycle hooks to be executed.

host_db_port¶

Port for binding database server to localhost interface.

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.

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.

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.

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.

host_xhgui_port¶

Specific, persistent XHGui port for direct binding to localhost interface.

Very rarely used. Can be a specific port number for a fixed XHGui URL.

instrumentation_opt_in¶

Whether to allow instrumentation reporting.

When true, anonymous usage information is collected via Amplitude.

instrumentation_queue_size¶

Maximum number of locally collected events for instrumentation reporting.

instrumentation_reporting_interval¶

Reporting interval in hours for instrumentation reporting.

instrumentation_user¶

Specific name identifier for instrumentation reporting.

internet_detection_timeout_ms¶

Internet detection timeout in milliseconds.

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.)

Set with ddev config global --letsencrypt-email=me@example.com. Used with the hosting feature.

mailpit_http_port¶

Port for project’s Mailpit HTTP URL.

mailpit_https_port¶

Port for project’s Mailpit HTTPS URL.

messages¶

Configure messages like the Tip of the Day.

Example: Disable the “Tip of the Day” ticker in $HOME/.ddev/global_config.yaml (see global configuration directory)

messages:
  ticker_interval: -1

Example: Show the “Tip of the Day” ticket every two hours:

messages:
  ticker_interval: 2

name¶

The URL-friendly name DDEV should use to reference the project.

no_bind_mounts¶

Whether to not use Docker bind mounts.

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.

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.

Note that specifying any non-default Node.js version will cause DDEV to download and install that version when running ddev start the first time on a project. If optimizing first-time startup speed (as in Continuous Integration) is your biggest concern, consider using the default version of Node.js.

ddev config --nodejs-version=auto

RUN ln -sf /var/www/html/frontend/.nvmrc /var/www/.nvmrc

omit_containers¶

Containers that should not be loaded automatically for one or more projects.

Example: omit_containers: [db, ddev-ssh-agent] starts the project without a db container and SSH agent. Some containers can be omitted globally in $HOME/.ddev/global_config.yaml (see global configuration directory) and the result is additive; all containers named in both places will be omitted.

omit_project_name_by_default¶

Determines whether ddev config updates the name field in the .ddev/config.yaml by default.

When the name field is omitted in .ddev/config.yaml, DDEV gets the project name from the directory the project is in. If this option is set to true, ddev config will not update the name field unless you use ddev config --project-name=<name> to explicitly set the project name. People using git worktree often prefer to omit the project name so they can work on multiple projects at the same time in different worktrees.

override_config¶

Whether to override config values instead of merging.

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 is supported. Mutagen is enabled by default on Mac and Traditional Windows.

This is typically a global setting. The project-specific value will override global config.

php_version¶

The PHP version the project should use.

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.

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.

If set to v2.8.3, for example, it will download and use that version instead of the expected version for docker-compose.

router_bind_all_interfaces¶

Whether to bind ddev-router’s ports on all network interfaces.

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.

See the Troubleshooting page for more on addressing port conflicts.

router_https_port¶

Port for DDEV router’s HTTPS traffic.

See the Troubleshooting page for more on addressing port conflicts.

share_default_provider¶

The default share provider to use with the ddev share command.

Set globally with ddev config global --share-default-provider=cloudflared or per-project with ddev config --share-default-provider=cloudflared. Can also be overridden with the --provider flag when running ddev share.

share_provider_args¶

Extra flags for configuring provider when sharing projects with the ddev share command.

Example:

• ngrok: --basic-auth username:pass1234 --domain foo.ngrok-free.app.
• cloudflared: --tunnel my-tunnel --hostname mysite.example.com.

simple_formatting¶

Whether to disable most ddev list and ddev describe table formatting and implicitly set NO_COLOR=1.

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.

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 global --simple-formatting=true.

timezone¶

Timezone for container and PHP configuration.

If timezone is unset, DDEV will attempt to derive it from the host system timezone using the $TZ environment variable or the /etc/localtime symlink.

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¶

The DDEV-specific project type.

The php type doesn’t attempt CMS configuration or settings file management and can work with any project.

The many versions of the Drupal project types can be used, for example drupal11 or drupal6. There is also a special drupal type that is interpreted as “latest stable Drupal version”, so in 2025, drupal means drupal11.

The special generic project type does nothing and implies nothing. It is normally used with webserver_type: generic.

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.

use_dns_when_possible¶

Whether to use DNS instead of editing /etc/hosts.

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.

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.

use_hardened_images¶

Whether to use hardened images for internet deployment.

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 hosting feature.

use_letsencrypt¶

Whether to enable Let’s Encrypt integration. (Works in conjunction with letsencrypt_email.)

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 hosting feature.

web_environment¶

Additional custom environment variables for a project’s web container. (Or for all projects if used globally.)

web_extra_daemons¶

Additional daemons that should automatically be started in the web container.

web_extra_exposed_ports¶

Additional named sets of ports to expose via ddev-router.

For common front-end development tools like Vite, see the Vite Integration documentation for complete configuration examples.

webimage¶

The Docker image to use for the web server.

webimage_extra_packages¶

Extra Debian packages for the project’s web container.

Example: webimage_extra_packages: [php${DDEV_PHP_VERSION}-yac, php${DDEV_PHP_VERSION}-bcmath] will add the php-yac and php-bcmath packages when the web container is built.

webserver_type¶

Which available web server type should be used.

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:

webserver_type: apache-fpm

This is the same as ddev config --webserver-type=apache-fpm.

Then run ddev restart to have the change take effect.

The generic type is special: It tells DDEV not to run any web server daemons, and the user can configure their own with the web_extra_daemons option.

working_dir¶

Working directories used by ddev exec and ddev ssh.

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.

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.

xdebug_ide_location¶

Adjust Xdebug listen location for WSL2 or in-container. This is used very rarely.

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 the ddev-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.

xhgui_http_port¶

Port for project’s XHGui HTTP URL (for router). Only changed when there are port conflicts on the default port 8143.

xhgui_https_port¶

Port for project’s XHGui HTTPS URL (for router). Only changed when there are port conflicts on the default port 8142.

xhprof_mode¶

Whether XHProf should use prepend or xhgui mode.