# Config Options

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

1. **Project** `.ddev/config.yaml` settings, with optional [environmental override](<#environmental-overrides>) 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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).

## Managing Configuration

### Setting Options

You can hand-edit the YAML files DDEV creates for you after running [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>), and you can also define most settings with equivalent CLI arguments:

```
php_version: "8.4"
```

```
ddev config --php-version 8.4
```

Run `ddev help config` to see all the available config 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](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>). For example, `config.python2.yaml` in [Python 2 add-on](<https://github.com/ddev/ddev-python2>) adds additional configuration related to Python 2.

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.

The global `$HOME/.ddev/global_config.yaml` can be extended the same way with `global_config.*.yaml` files in `$HOME/.ddev`, which is useful for keeping machine-specific or team-distributed settings out of the file DDEV rewrites.

For examples, see the [Extending and Customizing Environments](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#extending-configyaml-with-custom-configyaml-files>) page.

---

## `additional_fqdns`

An array of [extra fully-qualified domain names](<https://ddev.github.io/ddev/en/stable/users/extend/additional-hostnames/index.md>) 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!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) 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](<https://ddev.github.io/ddev/en/stable/users/extend/additional-hostnames/index.md>) 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)](<#use_dns_when_possible>) and connected to the internet and using `ddev.site` as your [`project_tld`](<#project_tld>).

See [Hostnames and Wildcards and DDEV, Oh My!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) 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](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/#exposing-a-host-port-and-providing-a-direct-url>).

| 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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>) command.

| Type | Default | Usage |
| --- | --- | --- |
| project | `2` | Can be `2` or empty (`""`) for latest major version at container build time.<br><br>Can also be the LTS version `2.2` (there’s no other `2.x` LTS), an explicit version like `2.9.3`, or a keyword like `stable`, `preview` or `snapshot`. See [Composer documentation](<https://getcomposer.org/doc/03-cli.md#self-update-selfupdate>). |

> [!WARNING]
>
> **Composer version is cached at container build time**
>
> DDEV installs Composer at container build time and caches it. If you use a non-specific version like `2`, `2.2`, `""` (empty), or `stable`, DDEV installs the latest available version in that range at build time.
>
> The next update of Composer will be done automatically when DDEV is upgraded. If you want to update Composer in the web container before then, [restart](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) with `--no-cache` or [rebuild](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-rebuild>):
>
> ```
> ddev restart --no-cache
> # or
> ddev utility rebuild
> ```
>
> See [Composer Self-Update Changes Do Not Persist](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#composer-self-update-changes-do-not-persist>) for details.

> [!TIP]
>
> **Using `vendor/bin/composer`**
>
> See the example in [Composer from `vendor/bin/composer`](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#composer-from-vendorbincomposer>).

## `corepack_enable`

Whether to run `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 `pnpm` and `yarn` package managers available.

Node.js 25 and later no longer include `corepack`. When it is missing, DDEV installs it from npm while building the web image, so that build needs access to the npm registry.

To set a specific version of `pnpm` for a project:

```
ddev config --corepack-enable && ddev restart
# pnpm@latest requires Node.js 22+
# use pnpm@latest-10 for Node.js 18 or 20
ddev exec corepack use pnpm@latest
ddev exec pnpm --version
```

To set a specific version of `yarn` for a project:

```
ddev config --corepack-enable && ddev restart
# yarn@stable is the latest stable release
# use yarn@4.9.1 to pin exactly
ddev exec corepack use yarn@stable
ddev yarn --version
```

`corepack use` pins the version by setting the `packageManager` field in `package.json`. To clear the global cache, run:

```
ddev exec corepack cache clear
```

## `database`

The type and version of the database engine the project should use.

| Type | Default | Usage |
| --- | --- | --- |
| project | `mariadb:11.8` | The following database types are currently supported:<br>\- MariaDB 5.5-10.8, 10.11, 11.4, 11.8, 12.3<br>\- MySQL 5.5-8.0, 8.4, 9.7<br>\- Postgres 9-18 |

See [Database Server Types](<https://ddev.github.io/ddev/en/stable/users/extend/database-types/index.md>) for examples (e.g. `ddev config --database=mariadb:11.8`) and caveats (e.g. how to migrate from one database version to another).

> [!TIP]
>
> **For very old database types, see [Using DDEV to spin up a legacy PHP application](<https://ddev.com/blog/legacy-projects-with-unsupported-php-and-mysql-using-ddev/>).**

## `dbimage`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it without Docker experience and a good reason. Typically, this means additions to the existing db image using a `.ddev/db-build/Dockerfile.*`.

The Docker image to use for the database server.

| Type | Default | Usage |
| --- | --- | --- |
| project | [`ddev/ddev-dbserver`](<https://hub.docker.com/u/ddev>) | Specify your own image based on the [ddev-dbserver](<https://github.com/ddev/ddev/tree/main/containers/ddev-dbserver>) image matching your project’s `database` type and version. |

DDEV images carry a `com.ddev.image-tag` label recording the image tag they were built as, and a derived image inherits it. When a pinned image was built from a different generation of DDEV images than the running DDEV expects, `ddev start` reports it as custom configuration, along with a note showing both tags. That’s the signal to rebuild your derived image against the current DDEV images. Images built before the label existed are not reported. See [DDEV Labels on Images](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#ddev-labels-on-images>) for how this differs from `com.ddev.webtag`.

## `dbimage_extra_packages`

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

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

Example: `dbimage_extra_packages: [netcat, telnet, sudo]` will add the `netcat`, `telnet`, and `sudo` packages when the database container is built.

## `ddev_version_constraint`

You can configure a [version constraint](<https://github.com/Masterminds/semver#checking-version-constraints>) 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'
```

| Type | Default | Usage |
| --- | --- | --- |
| project |  | `>= 1.24.8` |

## `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 be `true` or `false`. |

## `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](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen-and-user-generated-uploads>) for context on why DDEV avoids doing the Mutagen sync on `upload_dirs`.

## `docker_buildx_version`

> [!WARNING]
>
> **Advanced Usage**
>
> `docker_buildx_version` should only be changed for troubleshooting purposes or if you can’t install `docker-buildx` on your system.

Controls which `docker-buildx` plugin DDEV uses.

| Type | Default | Usage |
| --- | --- | --- |
| global | `system` | `system` or a version string like `0.33.0` |

When set to `system` (the default), DDEV uses whatever `docker-buildx` is already installed on your system and never downloads anything.

## `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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) should be interrupted by a failing [hook](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>), on a single project or for all projects if used globally.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `false` | Can be `true` or `false`. |

## `hooks`

DDEV-specific lifecycle [hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>) to be executed.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | \`\` | Global hooks in `global_config.yaml` run for every project, see [Global Hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/#global-hooks>). |

## `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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | ‌ |

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

## `instrumentation_opt_in`

Whether to allow [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `true` | Can be `true` or `false`. |

When `true`, anonymous usage information is collected via [Amplitude](<https://amplitude.com/>).

## `instrumentation_queue_size`

Maximum number of locally collected events for [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `100` | Can be any integer. |

## `instrumentation_reporting_interval`

Reporting interval in hours for [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `24` | Can be any integer. |

## `instrumentation_user`

Specific name identifier for [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| 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](<https://ddev.github.io/ddev/en/stable/users/usage/faq/index.md>) and [GitHub issue](<https://github.com/ddev/ddev/issues/2409#issuecomment-662448025>).

## `letsencrypt_email`

Email associated with Let’s Encrypt feature. (Works in conjunction with [`use_letsencrypt`](<#use_letsencrypt>).)

| Type | Default | Usage |
| --- | --- | --- |
| global | \`\` | ‌ |

Set with `ddev config global --letsencrypt-email=me@example.com`. Used with the [hosting](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>) feature.

## `mailpit_http_port`

Port for project’s Mailpit HTTP URL.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8025` | Can be changed to avoid a port conflict. |

## `mailpit_https_port`

Port for project’s Mailpit HTTPS URL.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>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 `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>))

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

| 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](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).)” |

## `no_bind_mounts`

Whether to not use Docker bind mounts.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `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`. |

> [!WARNING]
>
> **Advanced users only!**
>
> When `true`, project will not be mounted by DDEV into the web container. Enables experimentation with alternate file mounting strategies.

## `no_tui`

Whether to disable the TUI (terminal user interface) when running the `ddev` command without any arguments.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

## `nodejs_root`

The relative path, from the project root, to the directory containing the Node.js version file. (Requires [`nodejs_version`](<#nodejs_version>) `auto` or `engine`.)

| Type | Default | Usage |
| --- | --- | --- |
| project | ‌ | `nodejs_root: web/themes/custom/mytheme` |

## `nodejs_version`

Node.js version for the web container, managed by [`n`](<https://www.npmjs.com/package/n>).

| Type | Default | Usage |
| --- | --- | --- |
| project | current LTS version | Any [Node.js version](<https://www.npmjs.com/package/n#specifying-nodejs-versions>); see the table below for what each value does. |

What DDEV does depends on the value:

| Value | Result |
| --- | --- |
| `24` | Default version preinstalled in DDEV. |
| `""` (empty) | Uses the version already included in the image, with no download step (fastest for CI). Follows DDEV default behavior over time. |
| `v24` | Installs the newest `24.x` release when the image is built. Use the `v` prefix only to get the latest of the current default major. |
| any other version (`22`, `20.2`, `18.19.2`, etc.) | Installs that version when the image is built. A bare major like `22` already installs the newest `22.x`. |
| `auto`, `engine` | Reads the version from a file in your project (see below). |

> [!WARNING]
>
> **The Node.js version changes only when the image is rebuilt**
>
> A version installed by `n` is fixed at build time. It changes only when the `ddev-webserver` image is rebuilt, for example when you upgrade DDEV. You can also trigger a rebuild manually:
>
> ```
> ddev restart --no-cache
> # or
> ddev utility rebuild
> ```
>
> Example: you set `22`, and `n` installs the newest `22.x` available at build time, for example `22.14.0`. If `22.14.1` is released before the next rebuild, your project stays on `22.14.0` until then.

> [!TIP]
>
> **How to define the Node.js version using a file**
>
> Set `nodejs_version: auto` to read the version from a file in your project root ([`DDEV_APPROOT`](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#environment-variables-provided>)). `n` checks these in order: `.n-node-version`, `.node-version`, `.nvmrc`, then the `engines.node` field in `package.json`. Set `nodejs_version: engine` to use only `engines.node`. Either value fails validation if no such file exists. See [n’s documentation](<https://www.npmjs.com/package/n#specifying-nodejs-versions>) for details.
>
> If your version file is not in your project root, point [`nodejs_root`](<#nodejs_root>) at its directory. For example, if you have `frontend/.nvmrc`:
>
> ```
> nodejs_root: frontend
> nodejs_version: auto
> ```

> [!TIP]
>
> **Installing additional Node.js versions**
>
> To have multiple Node.js versions available, install additional ones via a [`post-start` hook](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>) using `n`:
>
> ```
> hooks:
>   post-start:
>     - exec: "n install 18 && n install 20"
> ```
>
> All installed versions are cached; the last one becomes active. Switch with `ddev exec n <version>`, clean up with `ddev exec n prune`.

## `omit_containers`

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

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `[]` | **For projects**, can include `db`, and `ddev-ssh-agent`.<br>**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 `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) 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.

## `omit_project_name_by_default`

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

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

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.

## `omit_snapshot_on_delete`

Determines whether to omit the database snapshot when running `ddev delete` by default.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

Snapshots are taken by default when running `ddev delete` to allow recovery of data if the deletion was accidental. Setting this to `true` will turn off that safety feature. You can also override this behavior on a per-command basis with `ddev delete --omit-snapshot=false`.

## `override_config`

Whether to override config values instead of merging.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `false` | Can be `true` or `false`. |

When `true`, the `config.*.yaml` or `global_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](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#extending-configyaml-with-custom-configyaml-files>).

## `performance_mode`

Defines the performance optimization mode to be used. Currently [Mutagen asynchronous caching](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen>) is supported. Mutagen is enabled by default on Mac and Traditional Windows.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | \`\` | Can be `global`, `none`, `mutagen`. |

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

## `php_version`

The PHP version the project should use.

| Type | Default | Usage |
| --- | --- | --- |
| project | `8.4` | Can be `5.6` through `8.6`. New versions are added when released upstream. |

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<br>global | `ddev.site` | Can be changed to any TLD you’d prefer. |

See [Hostnames and Wildcards and DDEV, Oh My!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) for more information on DDEV hostname resolution.

## `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](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>).

## `router_http_port`

Port for DDEV router’s HTTP traffic.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `80` | Usually changed only if there’s a conflicting process using that port. |

See the [Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#web-server-ports-already-occupied>) page for more on addressing port conflicts.

## `router_https_port`

Port for DDEV router’s HTTPS traffic.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `443` | Usually changed only if there’s a conflicting process using that port. |

See the [Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#web-server-ports-already-occupied>) page for more on addressing port conflicts.

## `share_default_provider`

The default share provider to use with the [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) command.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `ngrok` | Built-in providers: `ngrok`, `cloudflared`. Custom providers can be added to `.ddev/share-providers/`. Project config overrides global config. |

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](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>) with the [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) command.

| Type | Default | Usage |
| --- | --- | --- |
| project | \`\` | ‌ |

Example:

- [ngrok](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/#setting-up-a-stable-ngrok-domain>): `--basic-auth username:pass1234 --domain foo.ngrok-free.app`.
- [cloudflared](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/#setting-up-a-stable-cloudflared-domain>): `--tunnel my-tunnel --hostname mysite.example.com`.

> [!NOTE]
>
> **Replaces `ngrok_args`**
>
> This option replaces the deprecated `ngrok_args`. The old name still works for backward compatibility.

## `simple_formatting`

Whether to disable most [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) and [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) table formatting and implicitly set `NO_COLOR=1`.

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

When `true`, turns off most table formatting in [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) and [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) and suppresses colorized text everywhere.

## `skip_global_hooks`

Whether to skip the [global hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/#global-hooks>) in this project.

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. Project hooks still run. |

## `ssh_agent_upstream`

Make the `ddev-ssh-agent` container relay to an SSH agent you already run, such as the macOS agent, 1Password, or one forwarded with `ssh -A`, instead of running its own agent. See [Using an Existing SSH Agent](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#using-an-existing-ssh-agent>) for how this works with each Docker provider.

| Type | Default | Usage |
| --- | --- | --- |
| global | (empty) | Can be empty, `host`, or an absolute or `~/`-relative path of an agent socket. |

- Empty: `ddev-ssh-agent` runs its own agent, and [`ddev auth ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#auth-ssh>) adds key files to it.
- `host`: relay to the agent your Docker provider forwards (Docker Desktop on macOS or Linux, OrbStack, Colima with `--ssh-agent`, or Lima with `ssh.forwardAgent`), or on Linux and WSL2 to the socket in `$SSH_AUTH_SOCK` when a project starts.
- A socket path: relay to that socket. The Docker host must be able to reach it, so on macOS use `host` instead.

Traditional Windows doesn’t support this setting, because Windows SSH agents such as 1Password listen on a named pipe that Docker can’t reach. On WSL2, bridge that pipe to a socket path first, as [Using an Existing SSH Agent](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#using-an-existing-ssh-agent>) describes.

If DDEV can’t use the setting, for example `host` with a provider that doesn’t forward an agent, projects still start with DDEV’s own agent and a warning. With an upstream agent, `ddev auth ssh` lists the agent’s keys rather than adding keys.

## `table_style`

Style for [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) and [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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 global --simple-formatting=true`.

## `timezone`

Timezone for container and PHP configuration.

| Type | Default | Usage |
| --- | --- | --- |
| project | Automatic detection or `UTC` | Can be any [valid timezone](<https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>), like `Europe/Dublin` or `MST7MDT`. |

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 | Default | Usage |
| --- | --- | --- |
| global | `10999` | Can be any unused port below 65535. |

## `type`

The DDEV-specific project type.

| Type | Default | Usage |
| --- | --- | --- |
| project | `php` | Can be `asterios`, `backdrop`, `cakephp`, `codeigniter`, `craftcms`, `drupal`, `drupal6`, `drupal7`, `drupal8`, `drupal9`, `drupal10`, `drupal11`, `drupal12`, `generic`, `joomla`, `laravel`, `magento`, `magento2`, `maho`, `modx`, `php`, `shopware6`, `silverstripe`, `symfony`, `typo3`, `wordpress`, or `wp-bedrock`. |

The `php` type doesn’t attempt [CMS configuration](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>) 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 until the release of Drupal 12, `drupal` currently 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`](<#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](<https://ddev.github.io/ddev/en/stable/users/usage/offline/index.md>).

## `use_hardened_images`

Whether to use hardened images for internet deployment.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `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 [hosting](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>) feature.

## `use_letsencrypt`

Whether to enable Let’s Encrypt integration. (Works in conjunction with [`letsencrypt_email`](<#letsencrypt_email>).)

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `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 [hosting](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>) feature.

## `web_environment`

Additional [custom environment variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/#web_environment>) for a project’s web container. (Or for all projects if used globally.)

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `[]` | ‌ |

## `web_extra_daemons`

Additional daemons that should [automatically be started in the web container](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#running-extra-daemons-in-the-web-container>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

## `web_extra_exposed_ports`

Additional named sets of ports to [expose via `ddev-router`](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#exposing-extra-ports-via-ddev-router>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

For common front-end development tools like Vite, see the [Vite Integration](<https://ddev.github.io/ddev/en/stable/users/usage/vite/index.md>) documentation for complete configuration examples.

## `webimage`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, 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.*`.

The Docker image to use for the web server.

| Type | Default | Usage |
| --- | --- | --- |
| project | [`ddev/ddev-webserver`](<https://hub.docker.com/r/ddev/ddev-webserver>) | Specify your own image based on [ddev/ddev-webserver](<https://github.com/ddev/ddev/tree/main/containers/ddev-webserver>). |

## `webimage_extra_packages`

Extra Debian packages for the project’s web container.

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

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

## `webserver_type`

Which available [web server type](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#changing-web-server-type>) should be used.

| Type | Default | Usage |
| --- | --- | --- |
| project | `nginx-fpm` | Can be `nginx-fpm`, `apache-fpm`, `generic`. |

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`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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`](<#web_extra_daemons>) option.

> [!TIP]
>
> For generic web server configuration examples, see the [quickstart guide](<https://ddev.github.io/ddev/en/stable/users/quickstart/#generic>).

## `working_dir`

Working directories used by [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) and [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#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`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it. On Windows, it may prevent site access when using a custom [`project_tld`](<#project_tld>) or working [offline](<https://ddev.github.io/ddev/en/stable/users/usage/offline/index.md>).

(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 be `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](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>) or [profiling](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/xdebug-profiling/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Please leave this `false` in most cases. Most people use [`ddev xdebug`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xdebug>) and `ddev xdebug off` (or `ddev xdebug toggle`) commands. |

## `xdebug_ide_location`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it. Ask for help in one of our [support channels](<https://ddev.github.io/ddev/en/stable/users/support/index.md>) before changing it unless you understand its use completely.

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

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

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8143` | Can be changed to avoid a port conflict. |

## `xhgui_https_port`

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

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8142` | Can be changed to avoid a port conflict. |

## `xhprof_mode`

Whether XHProf should use `prepend` or `xhgui` mode.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `xhgui` | Can be `global`, `prepend` or `xhgui`. |