Skip to content

.ddev/config.yaml Options

Each project’s hidden .ddev directory contains a .ddev/config.yaml file with its primary configuration.

  • You can override the config.yaml with extra files named config.*.yaml. For example, many teams use config.local.yaml for configuration that is specific to one environment, and not checked into the team’s default config.yaml.
  • Most configuration options take effect on ddev start.
  • Nearly all configuration options have equivalent ddev config flags, so you can use ddev config instead of editing config.yaml. See ddev help config to see all the flags.
Option Description Notes
name Project name Must be unique on the host—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.
type Project type Can be backdrop, craftcms, drupal6, drupal7, drupal8, drupal9, drupal10, laravel, magento, magento2, php, shopware6, typo3, or wordpress. The php type doesn’t attempt CMS configuration or settings file management and can work with any project.
docroot Relative path to docroot containing index.php / index.html
php_version 5.6, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2 You can only specify the major version (7.3), not a minor version (7.3.2), from those explicitly available.
webimage Docker image to use for web server It’s unusual and not recommended to change the default, but the web image can be overridden with a correctly-crafted image, probably based on drud/ddev-webserver—typically, this means additions to the existing web image using a .ddev/web-build/Dockerfile.*.
database Database type and version to be used Defaults to MariaDB 10.3.

MariaDB 5.5–10.7, MySQL 5.5–8.0, and PostgreSQL 9–14 are available. See Database Server Types for details and caveats.

DDEV v1.18 and earlier used mariadb_version and mysql_version, which are now automatically converted to the database format.
router_http_port Port for router’s HTTP traffic Defaults to 80. Can be changed if there’s a conflict on the host with that port.
router_https_port Port for router’s HTTPS traffic Defaults to 443. Usually changed only if there’s a conflicting process using that port.
xdebug_enabled true enables Xdebug Can be true or false. Most people use ddev xdebug and ddev xdebug off commands instead of configuring this, because Xdebug has a significant performance impact.
webserver_type nginx-fpm or apache-fpm Defaults to nginx-fpm, which works best for many projects.
timezone Timezone for container and PHP configuration Defaults to UTC and can be set to any valid timezone. (e.g. Europe/Dublin or MST7MDT.)
composer_root Relative path to Composer root directory from project root The directory containing composer.json, where all Composer-related commands are executed.
composer_version Composer version for web container and ddev composer Defaults to 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.
nodejs_version Node.js version for web container as “system” version Defaults to current LTS version. Can be 14, 16, or 18. nvm is also available inside the container and via ddev nvm, and can be set to any valid version including much older ones.
additional_hostnames Array of extra hostnames 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 (*) setting only works if you’re using DNS to resolve hostnames (default) and connected to the internet.
additional_fqdns Extra fully-qualified domain names Example: additional_fqdns: ["example.com", "sub1.example.com"] would provide HTTP and HTTPS URLs for example.com and sub1.example.com. Take care with this because it can cause great confusion and adds extraneous items to your /etc/hosts file.
upload_dir Path from docroot to the user-generated-files directory targeted by ddev import-files
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.
omit_containers Containers the project should not load Can include db, dba, and ddev-ssh-agent.

Example: omit_containers: [db, dba, ddev-ssh-agent] starts the project without a db container, phpMyAdmin, 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.

Omitting the db container will cause database-dependent DDEV features to be unstable.
web_environment Additional custom environment variables for the project’s web container Example: web_environment: ["SOMEENV=someval", "SOMEOTHERENV=someotherval"].
nfs_mount_enabled Whether to use NFS to mount the project into the container for performance Can be true or false, and requires host configuration before it can be used. See nfs_mount_enabled documentation. Project-level configuration of this option is unusual, and when true in the global config it overrides the project-specific value. (Not commonly used now that much-faster Mutagen is available.)
fail_on_hook_fail Whether ddev start should be interrupted by a failing hook Can be true or false (default).
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 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_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 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_db_port Port for binding database server to localhost interface 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 sequelpro, etc., which handle changing ports automatically, as does the sample command ddev mysqlworkbench.)
phpmyadmin_port Port for project’s phpMyAdmin HTTP URL Defaults to 8036. Can be changed to avoid a port conflict.
phpmyadmin_https_port Port for project’s phpMyAdmin HTTPS URL Defaults to 8037. Can be changed to avoid a port conflict.
mailhog_port Port for project’s MailHog HTTP URL Defaults to 8025. Can be changed to avoid a port conflict.
mailhog_https_port Port for project’s MailHog HTTPS URL Defaults to 8026. Can be changed to avoid a port conflict.
webimage_extra_packages Extra Debian packages for the project’s web container Example: webimage_extra_packages: [php-yaml, php-bcmath] will add the php-yaml and php-bcmath packages when the web container is built.
dbimage_extra_packages Extra Debian packages for the project’s database container Example: dbimage_extra_packages: ["less"] will add the less package when the database container is built.
use_dns_when_possible Whether to use DNS instead of editing /etc/hosts Defaults to true. When false, DDEV will always update the /etc/hosts file with the project hostname instead of using DNS for name resolution.
project_tld Default TLD used for project domains Defaults to ddev.site. Can be changed to anything that works for you.
ngrok_args Extra flags for ngrok when using the ddev share command Example: --basic-auth username:pass1234. See ngrok docs.
disable_settings_management Whether to disable CMS-specific settings file management Defaults to false. When true, DDEV will not create or update CMS-specific settings files.
hooks DDEV-specific lifecycle hooks to be executed See hooks for more information.
no_project_mount Whether to skip mounting project into web container Defaults to false. Advanced users only! When true, project will not be mounted by DDEV into the web container. Enables experimentation with alternate file mounting strategies.
default_container_timeout Seconds DDEV will wait for all containers to become ready Defaults to 120. Not usually changed, but can be adjusted to avoid timeouts on slower systems or for huge snapshot restores.
override_config Whether to override config values instead of merging Defaults to false. When true, the config.*.yaml file with the option will have its settings override rather than merge with others. Allows statements like nfs_mount_enabled: false or additional_hostnames: [] to work.

global_config.yaml Options

The $HOME/.ddev/global_config.yaml file has a few key global config options.

Option Description Notes
nfs_mount_enabled Whether to globally enable NFS mounting for all projects Only true has any effect. When true, NFS will be used on all projects, regardless of any settings in the individual projects. (Rarely used since Mutagen is widely used and much faster.)
project_tld Set global project_tld. Defaults to ddev.site so project URLs are normally someproject.ddev.site Can be changed to anything that works for you.
mutagen_enabled Whether to globally enable Mutagen asynchronous caching for all projects When true, Mutagen will be used on all projects. This overrides NFS mounting as it’s incompatible with NFS.
table-style Style for ddev list and ddev describe output Can be default, bold, and bright. bright is a pleasant, colorful output some people may prefer.
simple-formatting Whether to disable most ddev list and ddev describe table formatting Defaults to false. When true, turns off most table formatting in ddev list and ddev describe and suppresses colorized text everywhere.
fail_on_hook_fail Whether to interrupt ddev start hook failure globally for all projects Defaults to false. When true, enables ddev start interruption globally for all projects when a hook fails.
omit_containers Containers every project should not load Can include dba and ddev-ssh-agent. Example: omit_containers: [ "dba", "ddev-ssh-agent"]. You cannot omit the db container in the global configuration, only the per-project .ddev/config.yaml.
web_environment Additional custom environment variables for every project’s web container Example: web_environment: ["SOMEENV=someval", "SOMEOTHERENV=someotherval"].
instrumentation_opt_in Whether to allow instrumentation reporting When true (default), anonymous usage information is collected via Segment.
router_bind_all_interfaces Whether to bind on all network interfaces Defaults to false. When true, ddev-router will bind on all network interfaces instead of only localhost, exposing DDEV projects to your local network. If you set this to true, consider setting omit_containers: ["dba"] so phpMyAdmin is not available.
disable_http2 Whether to disable http/2 listen in ddev-router Defaults to false. When true, nginx will not listen for http/2, but just use http/1.1 SSL. (Some browsers don’t work well with http/2.)
internet_detection_timeout_ms Internet detection timeout in milliseconds Defaults to 1000 (1 second). 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.
use_hardened_images Whether to use hardened images for internet deployment Defaults to 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 experimental casual hosting feature.
use_letsencrypt Whether to enable Let’s Encrypt integration Defaults to false and may also be set via ddev global --use-letsencrypt or ddev global --use-letsencrypt=false. When true, letsencrypt_email must also be set and the system must be available on the internet. Used with casual web hosting feature.
letsencrypt_email Email associated with Let’s Encrypt feature Set with ddev global --letsencrypt-email=me@example.com. Used with experimental casual hosting feature.
developer_mode Whether to enable developer mode Not currently used.
required_docker_compose_version Specific docker-compose version for download If set to v2.8.0, for example, it will download and use that version instead of the expected version for docker-compose.
use_docker_compose_from_path Whether to use the system-installed docker-compose Defaults to 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.
no_bind_mounts Whether to not use Docker bind mounts Defaults to 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.

Last update: October 6, 2022