# Commands You can tell DDEV what to do by running its commands. This page details each of the available commands and their options, or flags. > [!TIP] > > **Using TUI (Terminal UI)** > > Running `ddev` without any arguments will launch the [interactive dashboard]() in your terminal. > > To disable the dashboard and show the classic help text instead, set [`no_tui: true`]() in your global configuration (`$HOME/.ddev/global_config.yaml`), or set the environment variable `DDEV_NO_TUI=true`. Type `ddev help` or `ddev --help` or `ddev -h` to see this list in your terminal: ``` → ddev help Create and maintain a local web development environment. Docs: https://docs.ddev.com Support: https://docs.ddev.com/en/stable/users/support Usage: ddev [command] Available Commands: auth A collection of authentication commands blackfire Enable or disable blackfire.io profiling (global shell web container command) clean Removes items ddev has created composer Executes a composer command within the web container ... ``` Use [`ddev help`](<#help>) to learn more about a specific command, like this example for [`ddev describe`](<#describe>): ``` → ddev help describe Get a detailed description of a running ddev project. Describe provides basic information about a ddev project, including its name, location, url, and status. It also provides details for MySQL connections, and connection information for additional services like Mailpit. You can run 'ddev describe' from a project directory to describe that project, or you can specify a project to describe by running 'ddev describe '. Usage: ddev describe [projectname] [flags] Aliases: describe, status, st, desc Examples: ddev describe ddev describe ddev status ddev st Flags: -h, --help help for describe Global Flags: -j, --json-output If true, user-oriented output will be in JSON format. ``` ## Global Flags Two flags are available for every command: - `--help` or `-h`: Outputs more information about a command rather than executing it. - `--json-output` or `-j`: Format user-oriented output in JSON. --- ## `add-on` *Aliases: `addon`, `add-ons`, `addons`.* [Add-on]() commands. Environment variables: - `DDEV_GITHUB_TOKEN`: [GitHub token]() for `ddev add-on` requests to avoid rate limiting. No privileges required for public repositories, scopes are only needed for [private repositories](). ``` export DDEV_GITHUB_TOKEN= ddev add-on list ``` - `GH_TOKEN`: Alternative GitHub token variable (lower priority than `DDEV_GITHUB_TOKEN`). - `GITHUB_TOKEN`: Alternative GitHub token variable (lowest priority). ### `add-on get` *Alias: `add-on install`.* Download an add-on (service, provider, etc.). Dependencies declared in the add-on’s `install.yaml` are installed automatically unless `--skip-deps` is used. Flags: - `--skip-deps`: Skip installing add-on dependencies (default `false`) - `--project `: Specify a project to install the add-on into. Defaults to checking for a project in the current directory. - `--version `: Specify a version, branch name, or commit SHA to download - `--default-branch`: Install from the last commit in the default branch (default `false`) - `--pr `: Install from a pull request number - `--verbose`, `-v`: Output verbose error information with Bash `set -x` (default `false`) Note: The `--version`, `--default-branch`, and `--pr` flags are mutually exclusive. Example: ``` # Download the official Redis add-on ddev add-on get ddev/ddev-redis # Get debug info about `ddev add-on get` failure ddev add-on get ddev/ddev-redis --verbose # Download the official Redis add-on, version v1.0.4 ddev add-on get ddev/ddev-redis --version v1.0.4 # Download the official Redis add-on from the main branch ddev add-on get ddev/ddev-redis --version main # Download the official Redis add-on from a specific commit SHA ddev add-on get ddev/ddev-redis --version b50ac77 # Download the official Redis add-on from the latest commit in the default branch ddev add-on get ddev/ddev-redis --default-branch # Download the official Redis add-on from pull request #54 ddev add-on get ddev/ddev-redis --pr 54 # Download the Drupal Solr add-on from its v1.2.3 release tarball ddev add-on get https://github.com/ddev/ddev-drupal-solr/archive/refs/tags/v1.2.3.tar.gz # Download the Drupal Contrib add-on from its main branch tarball ddev add-on get https://github.com/ddev/ddev-drupal-contrib/tarball/main # Download the OpenSearch add-on from a pull request #15 tarball ddev add-on get https://github.com/ddev/ddev-opensearch/tarball/refs/pull/15/head # Copy an add-on available in another directory ddev add-on get /path/to/package # Copy an add-on from a tarball in another directory ddev add-on get /path/to/tarball.tar.gz # Download the official Redis add-on and install it into a project named "my-project" ddev add-on get ddev/ddev-redis --project my-project # Install an add-on without installing its dependencies ddev add-on get ddev/ddev-redis-insight --skip-deps ``` **Automatic Dependency Installation:** When an add-on declares dependencies in its `install.yaml`, DDEV will automatically install any missing dependencies before installing the add-on itself. Dependencies support the same formats as `ddev add-on get`: - GitHub repositories: `ddev/ddev-redis` - Direct URLs: `https://example.com/addon.tar.gz` DDEV will detect and prevent circular dependencies with clear error messages. In general, you can run `ddev add-on get` multiple times without doing any damage. Updating an add-on can be done by running `ddev add-on get `, or use `ddev add-on update` to update every installed add-on at once. If you have changed an add-on file and removed the `#ddev-generated` marker in the file, that file will not be touched and DDEV will let you know about it. > [!TIP] > > **How to install add-ons from private repositories?** > > See [Private Add-ons]() for details. ### `add-on update` Check installed add-ons for a newer release and install it. If no add-on names are provided, all installed add-ons are checked. Add-ons installed from a local directory or from a non-GitHub tarball URL can’t be checked automatically and are skipped. Flags: - `--dry-run`: Show which add-ons would be updated without installing anything (default `false`) - `--project `: Specify a project to update the add-ons for. Defaults to checking for a project in the current directory. - `--verbose`, `-v`: Output verbose error information with Bash `set -x` (default `false`) - `--yes`, `-y`: Skip confirmation prompt. Example: ``` # Check and update all installed add-ons ddev add-on update # Update a single installed add-on ddev add-on update redis ddev add-on update ddev/ddev-redis # See what would be updated without installing anything ddev add-on update --dry-run # Update add-ons for a specific project ddev add-on update --project my-project ``` ### `add-on remove` Remove an installed add-on. Accepts the full add-on name, the short name of the repository, or with owner/repository format. Flags: - `--project `: Specify a project to remove the add-on from. Defaults to checking for a project in the current directory. - `--verbose`, `-v`: Output verbose error information with Bash `set -x` (default `false`) Example: ``` ddev add-on remove redis ddev add-on remove ddev-redis ddev add-on remove ddev/ddev-redis ddev add-on remove ddev/ddev-redis --project my-project ``` ### `add-on list` List available or installed DDEV add-ons. Flags: - `--installed`: List installed add-ons - `--project `: Specify the project for which to list add-ons. Can only be used with the `--installed` flag. Defaults to checking for a project in the current directory. - `--wrap-table`, `-W`: Display table with wrapped text instead of truncating. Example: ``` # List all available add-ons ddev add-on list # List installed add-ons ddev add-on list --installed # List installed add-ons for a specific project ddev add-on list --installed --project my-project # List with full untruncated add-on names and descriptions ddev add-on list --wrap-table ``` ### `add-on search` Search available DDEV add-ons by name or description. Flags: - `--wrap-table`, `-W`: Display table with wrapped text instead of truncating. Example: ``` # Search for Redis-related add-ons ddev add-on search redis # Search for database-related add-ons ddev add-on search database # Search with multiple terms (all must be present) ddev add-on search redis web # Search with multiple terms using quotes (currently same behavior) ddev add-on search "redis insight" # Search with full untruncated output ddev add-on search redis --wrap-table ``` ## `aliases` Shows all aliases for each command in the current context (global or project). ``` # Print a list of all available command aliases ddev aliases ``` ## `artisan` *Alias: `art`.* Run the `artisan` command; available only in projects of type `laravel`, and only available if `artisan` is in the project root. ``` # Show all artisan subcommands ddev artisan list ``` ## `asterios` *Alias: `ast`.* Run the `asterios` command; available only in projects of type `asterios`, and only available if `asterios` is in the project root. ``` # Show all asterios subcommands ddev asterios list ``` ## `auth` Authentication commands. ### `auth ssh` Add [SSH key authentication]() to the `ddev-ssh-agent` container. The command can be executed multiple times to add more keys, or you can use the `-f` flag for several individual keys for example `ddev auth ssh -f /path/to/first_id_rsa -f /path/to/second_id_rsa`. If [`ssh_agent_upstream`]() is set, `ddev auth ssh` without flags lists the keys in that agent instead of adding keys. To add a key held in a secret manager or CI variable without writing it to a file, pipe it in with `-f -`. The key must not have a passphrase. On traditional Windows, where `ssh_agent_upstream` isn’t available, this is how to use a key stored in 1Password; see [Using an Existing SSH Agent](). Example: ``` # Add your SSH keys to the SSH agent container ddev auth ssh # Add your SSH keys from ~/custom/path/to/ssh directory ddev auth ssh -d ~/custom/path/to/ssh # Add your SSH keys from ~/.ssh/id_ed25519 and ~/.ssh/id_rsa files ddev auth ssh -f ~/.ssh/id_ed25519 -f ~/.ssh/id_rsa # Add a key from 1Password's CLI, or any command that prints a private key op read "op://Private/deploy key/private key?ssh-format=openssh" | ddev auth ssh -f - ``` Flags: - `--ssh-key-file`, `-f`: Path to SSH private key file, use the flag multiple times to add more keys, or `-` to read one key without a passphrase from stdin. - `--ssh-key-path`, `-d`: Path to directory with SSH private key(s), use the flag multiple times to add more directories. ## `blackfire` Enable or disable [Blackfire profiling]() (global shell web container command). ``` # Display Blackfire profiling status ddev blackfire status # Start Blackfire profiling ddev blackfire on # Stop Blackfire profiling ddev blackfire off ``` > [!TIP] > > There are synonyms for the `on` and `off` arguments that have the exact same effect: > > - `on`: `start`, `enable`, `true` > - `off`: `stop`, `disable`, `false` ## `cake` Run the `cake` command; available only in projects of type `cakephp`, and only available if `cake.php` is in bin folder. ``` # Show all cake subcommands ddev cake ``` ## `clean` Removes items DDEV has created. (See [Uninstalling DDEV]().) Flags: - `--all`, `-a`: Clean all DDEV projects. - `--dry-run`: Run the clean command without deleting. - `--yes`, `-y`: Skip confirmation prompt. Example: ``` # Preview cleaning all projects without actually removing anything ddev clean --dry-run --all # Clean all projects ddev clean --all # Clean my-project and my-other-project ddev clean my-project my-other-project ``` ## `composer` *Alias: `co`.* Executes a [Composer command]() within the web container. `ddev composer create-project` is a special command that is an adaptation of `composer create-project`. See [DDEV and Composer]() for more information. Example: ``` # Install Composer packages ddev composer install ``` Example of `ddev composer create-project`: ``` # Create a new Drupal project in the current directory ddev composer create-project drupal/recommended-project . ``` ## `config` Create or modify a DDEV project’s configuration in the current directory. By default, `ddev config` will not change configuration that already exists in your `.ddev/config.yaml`, it will only make changes you specify with flags. However, if you want to autodetect everything, `ddev config --update` will usually do everything you need. > [!TIP] > > **You can also set these via YAML!** > > These settings, plus a few more, can be set by editing stored [Config Options](). Example: ``` # Start interactive project configuration ddev config # Accept defaults on a new project. This is the same as hitting # on every question in `ddev config` ddev config --auto # Detect docroot, project type (except for `generic` type), # and expected defaults for an existing project ddev config --update # Configure a Drupal project with a `web` document root ddev config --docroot=web --project-type=drupal # Switch the project’s default `nginx-fpm` to `apache-fpm` ddev config --webserver-type=apache-fpm ``` Flags: - `--additional-fqdns`: Comma-delimited list of project FQDNs or `--additional-fqdns=""` to remove any configured FQDNs. - `--additional-hostnames`: Comma-delimited list of project hostnames or `--additional-hostnames=""` to remove any configured additional hostnames. - `--auto`: Automatically run config without prompting. - `--bind-all-interfaces`: Bind host ports on all interfaces, not only on the localhost network interface. - `--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-root-default`: Unset a `web` service Composer root directory override, the same as `--composer-root=""`. - `--composer-version`: Specify override for Composer version in the web container. This may be `""`, `"2"`, `"2.2"`, `"stable"`, `"preview"`, `"snapshot"`, or a specific version. - `--corepack-enable`: Whether to run `corepack enable` on Node.js configuration. - `--database`: Specify the database `type:version` to use (see [default]()). - `--db-image`: Set the `db` container image ([for advanced use only]()). - `--db-image-default`: Set the default `db` container image, the same as `--db-image=""`. - `--db-working-dir`: Override the default working directory for the `db` service. - `--db-working-dir-default`: Unset a `db` service working directory override, the same as `--db-working-dir=""`. - `--dbimage-extra-packages`: Comma-delimited list of Debian packages that should be added to `db` container when the project is started or `--dbimage-extra-packages=""` to remove previously configured packages. - `--ddev-version-constraint`: Specify a `ddev_version_constraint` to validate `ddev` against. - `--default-container-timeout`: Default time in seconds that DDEV waits for all containers to become ready on start (see [default]()). - `--disable-settings-management`: Prevent DDEV from creating or updating CMS settings files. - `--disable-upload-dirs-warning`: Disable warnings about `upload-dirs` not being set when using `--performance-mode=mutagen`. - `--docker-buildx-version`: Control which `docker-buildx` plugin to use (see [default]()). - `--docroot`: Provide the relative docroot of the project, like `docroot` or `htdocs` or `web`, defaults to empty, the current directory. - `--fail-on-hook-fail`: Decide whether `ddev start` should be interrupted by a failing hook. - `--host-db-port`: The `db` container’s localhost-bound port. - `--host-https-port`: The `web` container’s localhost-bound HTTPS port. - `--host-webserver-port`: The `web` container’s localhost-bound HTTP port. - `--mailpit-http-port`: Router port to be used for Mailpit HTTP access (see [default]()). - `--mailpit-https-port`: Router port to be used for Mailpit HTTPS access (see [default]()). - `--ngrok-args`: Provide extra args to `ngrok` in `ddev share` (deprecated: use [`share_provider_args`]() in `.ddev/config.yaml`). - `--no-project-mount`: Whether to skip mounting project code into the `web` container. - `--nodejs-root`: The relative path, from the project root, to the directory containing the Node.js version file (see [`nodejs_root`]()). - `--nodejs-version`: Specify the Node.js version to use (see [default]()). - `--omit-containers`: Comma-delimited list of container types that should not be started when the project is started. - `--performance-mode`: Performance optimization mode, possible values are `global`, `none`, `mutagen`. - `--performance-mode-reset`: Reset performance mode to global configuration. - `--php-version`: PHP version that will be enabled in the `web` container (see [default]()). - `--project-name`: Provide the project name of project to configure (normally the same as the last part of directory name). - `--project-tld`: Set the top-level domain to be used for projects (see [default]()). - `--project-type`: Provide [the project type]() of project to configure. This is autodetected and this flag is necessary only to override the detection. - `--router-http-port`: The router HTTP port for this project (see [default]()). - `--router-https-port`: The router HTTPS port for this project (see [default]()). - `--share-default-provider`: Set the default share provider for the project (`ngrok`, `cloudflared`, or custom). Can be overridden globally with `ddev config global --share-default-provider=`. - `--share-provider-args`: Provide extra args to the share provider in `ddev share`. - `--show-config-location`: Output the location of the `.ddev/config.yaml` file if it exists, or error that it doesn’t exist. - `--timezone`: Specify timezone for containers and PHP, like `Europe/London` or `America/Denver` or `GMT` or `UTC`. If unset, DDEV will attempt to derive it from the host system timezone. - `--update`: Update project settings based on detection and `project-type` overrides (except for `generic` type). - `--upload-dirs`: Set the project’s upload directories, the destination directories of the `ddev import-files` command, or `--upload-dirs=""` to remove previously configured values. - `--use-dns-when-possible`: Use DNS for hostname resolution instead of `/etc/hosts` when possible (default `true`). - `--web-environment`: Set the environment variables in the `web` container: `--web-environment="TYPO3_CONTEXT=Development,SOMEENV=someval"` or `--web-environment=""` to remove previously configured values. - `--web-environment-add`: Append environment variables to the `web` container: `--web-environment-add="TYPO3_CONTEXT=Development,SOMEENV=someval"` - `--web-image`: Set the `web` container image ([for advanced use only]()). - `--web-image-default`: Set the default `web` container image, the same as `--web-image=""`. - `--web-working-dir`: Override the default working directory for the `web` service. - `--web-working-dir-default`: Unset a `web` service working directory override, the same as `--web-working-dir=""`. - `--webimage-extra-packages`: Comma-delimited list of Debian packages that should be added to `web` container when the project is started or `--webimage-extra-packages=""` to remove any previously configured packages. - `--webserver-type`: Set the project’s desired web server type: `nginx-fpm`, `apache-fpm`, `generic` (see [default]()). - `--working-dir-defaults`: Unset all service working directory overrides. - `--xdebug-enabled`: Whether Xdebug is enabled in the `web` container. - `--xhprof-mode`: XHProf mode, possible values are `global`, `prepend`, `xhgui` (see [default]()). - `--xhprof-mode-reset`: Reset XHProf mode to global configuration. ### `config global` Change global configuration. ``` # Opt out of sharing anonymized usage information ddev config global --instrumentation-opt-in=false # Skip the SSH agent for all projects ddev config global --omit-containers=ddev-ssh-agent ``` - `--fail-on-hook-fail`: If true, `ddev start` will fail when a hook fails. - `--instrumentation-opt-in`: Whether to allow [instrumentation reporting]() with `--instrumentation-opt-in=true` (see [default]()). - `--internet-detection-timeout-ms`: Increase timeout when checking internet timeout, in milliseconds (see [default]()). - `--letsencrypt-email`: Email associated with Let’s Encrypt, `ddev global --letsencrypt-email=me@example.com`. - `--mailpit-http-port`: The default Mailpit HTTP port for all projects, can be overridden by project configuration (see [default]()). - `--mailpit-https-port`: The default Mailpit HTTPS port for all projects, can be overridden by project configuration (see [default]()). - `--no-bind-mounts`: If `true`, don’t use bind-mounts. Useful for environments like remote Docker where bind-mounts are impossible. - `--no-tui`: If `true`, disable the interactive dashboard and show the classic help text instead (see [default]()). - `--omit-containers`: For example, `--omit-containers=ddev-ssh-agent` or `--omit-containers=""`. - `--omit-project-name-by-default`: If `true`, `ddev config` will not write the `name` field to `.ddev/config.yaml` unless explicitly set with `--project-name` (see [default]()). - `--omit-snapshot-on-delete`: If `true`, `ddev delete` will not take a snapshot before deleting a project (see [default]()). - `--performance-mode`: Performance optimization mode, possible values are `none`, `mutagen`. - `--performance-mode-reset`: Reset performance optimization mode to operating system default (`none` for Linux and WSL2, `mutagen` for macOS and traditional Windows). - `--project-tld`: Set the default top-level domain to be used for all projects, can be overridden by project configuration (see [default]()). - `--router-bind-all-interfaces`: Bind host router ports on all interfaces, not only on the localhost network interface. - `--router-http-port`: The default router HTTP port for all projects, can be overridden by project configuration (see [default]()). - `--router-https-port`: The default router HTTPS port for all projects, can be overridden by project configuration (see [default]()). - `--simple-formatting`: If `true`, use simple formatting for tables and implicitly set `NO_COLOR=1`. - `--ssh-agent-upstream`: Make `ddev-ssh-agent` relay to an existing SSH agent: `host` for the host’s agent, or the path to an agent socket; empty uses DDEV’s own agent (see [default]()). - `--table-style`: Table style for `ddev list` and `ddev describe`, possible values are `default`, `bold`, `bright` (see [default]()). - `--traefik-monitor-port`: Can be used to change the Traefik monitor port in case of port conflicts, for example `ddev config global --traefik-monitor-port=11999` (see [default]()). - `--use-hardened-images`: If `true`, use more secure ‘hardened’ images for an actual internet deployment. - `--use-letsencrypt`: Enables experimental Let’s Encrypt integration, `ddev config global --use-letsencrypt` or `ddev config global --use-letsencrypt=false`. - `--web-environment`: Set the environment variables in the `web` container: `--web-environment="TYPO3_CONTEXT=Development,SOMEENV=someval"` - `--web-environment-add`: Append environment variables to the `web` container: `--web-environment-add="TYPO3_CONTEXT=Development,SOMEENV=someval"` - `--wsl2-no-windows-hosts-mgt`: WSL2 only; make DDEV ignore Windows-side hosts file ([for advanced use only]()). - `--xdebug-ide-location`: For less usual IDE locations specify where the IDE is running for Xdebug to reach it ([for advanced use only]()). - `--xhprof-mode`: XHProf mode, possible values are `prepend`, `xhgui` (see [default]()). - `--xhprof-mode-reset`: Reset XHProf mode to default. ## `console` Run the `console` command; available only in projects of type `symfony` and `shopware6`, and only available if `bin/console` exists. ``` # Show all Symfony console subcommands ddev console list ``` ## `craft` Run a [Craft CMS command]() inside the web container (global shell web container command). Example: ``` # Run pending Craft migrations and apply pending project config changes ddev craft up ``` ## `dbeaver` Open [DBeaver]() with the current project’s database (global shell host container command). This command is only available if `DBeaver.app` is installed as `/Applications/DBeaver.app` for macOS, if `dbeaver.exe` is installed to all users as `C:/Program Files/dbeaver/dbeaver.exe` for WSL2 and Windows, and if `dbeaver` (or another binary like `dbeaver-ce`) available inside `/usr/bin` for Linux (Flatpak and snap support included). Example: ``` # Open the current project’s database in DBeaver ddev dbeaver ``` ## `delete` Remove all information, including the database, for an existing project. Flags: - `--all`, `-a`: Delete all projects. - `--clean-containers`: Clean up all DDEV Docker containers not required by this version of DDEV. (default `true`) - `--omit-snapshot`, `-O`: Omit/skip database snapshot. - `--yes`, `-y`: Skip confirmation prompt. Example: ``` # Delete my-project and my-other-project ddev delete my-project my-other-project # Delete the current project without taking a snapshot or confirming ddev delete --omit-snapshot --yes ``` ### `delete images` With `--all`, it deletes all `ddev/ddev-*` Docker images. Flags: - `--all`, `-a`: If set, deletes all Docker images created by DDEV. - `--yes`, `-y`: Skip confirmation prompt. Example: ``` # Delete images ddev delete images # Delete images and skip confirmation ddev delete images -y # Delete all DDEV-created images ddev delete images --all ``` ## `describe` *Aliases: `status`, `st`, `desc`.* Get a detailed description of a running DDEV project. Example: ``` # Display details for the current project ddev describe # Display details for my-project ddev describe my-project ``` ## `dotenv` Commands for managing the contents of `.env` files. See [Environment Variables]() for which filename reaches which service, the order the files override each other in, and where to keep a secret. ### `dotenv get` Get the value of an environment variable from a `.env` file. Provide the path relative to the project root when specifying the file. Example: ``` # Get APP_KEY from $DDEV_APPROOT/.env ddev dotenv get .env --app-key # Get ENV_KEY from $DDEV_APPROOT/.ddev/.env.web ddev dotenv get .ddev/.env.web --env-key # Get REDIS_TAG from $DDEV_APPROOT/.ddev/.env.redis ddev dotenv get .ddev/.env.redis --redis-tag # Get API_KEY from the gitignored $DDEV_APPROOT/.ddev/.env.web.local ddev dotenv get .ddev/.env.web.local --api-key ``` ### `dotenv global get` Get the value of an environment variable from a global `.env` file. Name the file as `.ddev/`, the same way as in a project; it is read from the [global DDEV directory](). Example: ``` # Get API_URL from the global .env.web ddev dotenv global get .ddev/.env.web --api-url # Get API_KEY from the gitignored global .env.web.local ddev dotenv global get .ddev/.env.web.local --api-key ``` ### `dotenv global set` *Alias: `dotenv global add`.* Create or update a global `.env` file, which applies to every project, with values specified via long flags from the command line. Flags in the format `--env-key=value` will be converted to environment variable names like `ENV_KEY="value"`. Name the file as `.ddev/`, the same way as in a project; it is written to the [global DDEV directory](). Example: ``` # Set API_URL for the web service of every project ddev dotenv global set .ddev/.env.web --api-url=https://example.com # Set two variables for the db service of every project ddev dotenv global set .ddev/.env.db --extra value --another-key "extra value" # Set API_KEY in a gitignored file, for the web service of every project ddev dotenv global set .ddev/.env.web.local --api-key=secret ``` ### `dotenv set` *Alias: `dotenv add`.* Create or update a `.env` file with values specified via long flags from the command line. Flags in the format `--env-key=value` will be converted to environment variable names like `ENV_KEY="value"`. Provide the path relative to the project root when specifying the file. Example: ``` # Set APP_KEY in the application's own $DDEV_APPROOT/.env ddev dotenv set .env --app-key=value # Set two variables for the web service ddev dotenv set .ddev/.env.web --extra value --another-key "extra value" # Set REDIS_TAG for the redis service ddev dotenv set .ddev/.env.redis --redis-tag 7-bookworm # Set API_URL for the web service, in a file labeled for one add-on ddev dotenv set .ddev/.env.web.myaddon --api-url=https://example.com # Set API_KEY in a gitignored file, for the web service ddev dotenv set .ddev/.env.web.local --api-key=secret ``` ## `dr` Run the Drupal `dr` CLI; available only in projects of type `drupal11` and `drupal12`, and only if `dr` is available in the project (Drupal 11.4+). ``` # Show dr status ddev dr system:status ``` ## `drush` Run the `drush` command; available only in projects of type `drupal*` and `backdrop`, and only available if `drush` is in the project. On projects of type `drupal`, `drush` should be installed in the project itself, (`ddev composer require drush/drush`). On projects of type `drupal7` `drush` 8 is provided by DDEV. ``` # Show drush status/configuration ddev drush st ``` ## `exec` *Alias: `.`.* [Execute a shell command in the container]() for a service. Uses the web service by default. To run your command in a different project, run `ddev exec --project `. To run your command in a different service container, run `ddev exec --service `. Use the `--raw` flag if you’d like to run a raw, uninterpreted command in a container. Flags: - `--dir`, `-d`: Define the execution directory within the container. - `--raw`: Use raw exec (do not interpret with Bash inside container). (default `true`) - `--project`, `-p`: Specify a project where to run the command. Defaults to the project in the current directory. - `--service`, `-s`: Define the service to connect to. (e.g. `web`, `db`) (default `"web"`) - `--quiet`, `-q`: Suppress detailed error message. - `--user`, `-u`: Defines the user to run shell as. Example: ``` # List the web container's docroot contents ddev exec ls /var/www/html # List the web container's docroot contents for a specific project ddev exec --project my-other-project ls /var/www/html # List the web container's vendor directory contents ddev exec --dir /var/www/html/vendor ls # Output a long, recursive list of the files in the web container ddev exec --raw -- ls -lR # Suppress detailed error message: # "Failed to execute command `exit 1`: exit status 1" ddev exec -q "exit 1" # List the db container's /root directory contents as root user ddev exec -s db -u root ls -la /root ``` ## `export-db` Dump a database to a file or to stdout. With `--file` and no `--compression`, the compression type comes from the file extension: `.gz`, `.zst`, `.xz`, `.bz2`, or `.sql`/`.mysql` for none. Any other extension, and output to stdout, uses gzip. Flags: - `--compression`: Compression type: `gzip`, `zstd`, `xz`, `bzip2`, or `none`. `zstd` is not available with MariaDB 5.5. - `--database`, `-d`: Target database to export from (default `"db"`) - `--file`, `-f`: Path to a SQL dump file to export to The older `--gzip`, `--gzip=false`, `--xz`, and `--bzip2` flags still work. Example: ``` # Dump and compress the current project’s database to `/tmp/db.sql.gz` ddev export-db --file=/tmp/db.sql.gz # Dump the current project’s database with zstd compression ddev export-db --file=/tmp/db.sql.zst # Dump the current project’s database, without compressing it, to `/tmp/db.sql` ddev export-db --file /tmp/db.sql # Dump and compress the current project’s `foo` database instead of `db` ddev export-db --database=foo --file=/tmp/db.sql.gz # Output the current project’s database and use `>` to write to `/tmp/db.sql.gz` ddev export-db > /tmp/db.sql.gz # Output the current project’s database with zstd compression ddev export-db --compression=zstd > /tmp/db.sql.zst # Dump my-project’s database, without compressing it, to `/tmp/my-project.sql` ddev export-db my-project --file=/tmp/my-project.sql ``` ## `heidisql` Open [HeidiSQL]() with the current project’s database (global shell host container command). This command is available on Windows, WSL2, and Linux. Requirements by platform: - **Windows**: HeidiSQL installed at `C:\Program Files\HeidiSQL\Heidisql.exe` - **WSL2**: HeidiSQL accessible via `/mnt/c/Program Files/HeidiSQL/heidisql.exe` - **Linux**: HeidiSQL available at `/usr/bin/heidisql` or at `/usr/local/bin/heidisql` Example: ``` # Open the current project's database in HeidiSQL ddev heidisql ``` ## `help` Help about any command. Example: ``` # Illuminate the virtues of the `describe` command ddev help describe ``` ## `hostname` Manage your hostfile entries. Flags: - `--remove`, `-r`: Remove the provided hostname - ip correlation. - `--remove-inactive`, `-R`: Remove hostnames of inactive projects. Example: ``` ddev hostname somesite.example.com 127.0.0.1 ``` `ddev hostname` runs a special `ddev-hostname` or `ddev-hostname.exe` executable to elevate privileges. The extra executable is installed/updated by DDEV’s normal installation process or by the Windows installation process. On WSL2, `ddev-hostname.exe` is provided by the `ddev-wsl2` package and by the Windows installer. Install the package with `sudo apt-get update && sudo apt-get install -y ddev-wsl2` or the equivalent for your Linux system. ## `import-db` [Import a SQL file]() into the project. Flags: - `--database`, `-d`: Target database to import into (default `"db"`) - `--extract-path`: Path to extract within the archive - `--file`, `-f`: Path to a SQL dump in `.sql`, `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`, `.tgz`, or `.zip` format - `--no-drop`: Do not drop the database before importing - `--no-progress`: Do not output progress Example: ``` # Start the interactive import utility ddev import-db # Import the `.tarballs/db.sql` dump to the project database ddev import-db --file=.tarballs/db.sql # Import the compressed `.tarballs/db.sql.gz` dump to the project database ddev import-db --file=.tarballs/db.sql.gz # Import the compressed `.tarballs/db.sql.gz` dump to a `other_db` database ddev import-db --database=additional_db --file=.tarballs/db.sql.gz # Import the `db.sql` dump to the project database ddev import-db < db.sql # Import the `db.sql` dump to the `my-project` default database ddev import-db my-project < db.sql # Uncompress `db.sql.gz` and pipe the result to the `import-db` command gzip -dc db.sql.gz | ddev import-db ``` ## `import-files` Pull the uploaded files directory of an existing project to the default public upload directory of your project. More usage information and a description of the Tar or ZIP archive is in the [usage section](). Flags: - `--extract-path`: Path to extract within the archive. - `--source`, `-s`: Path to the source directory or source archive in `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`, `.tgz`, or `.zip` format. - `--target`, `-t`: Target upload dir, defaults to the first upload dir. Example: ``` # Extract+import `/path/to/files.tar.gz` to the project’s first upload directory ddev import-files --source=/path/to/files.tar.gz # Import `/path/to/dir` contents to the project’s first upload directory ddev import-files --source=/path/to/dir # Import `.tarballs/files.tar.xz` contents to the project’s `../private` upload directory ddev import-files --source=.tarballs/files.tar.xz --target=../private # Import `/path/to/dir` contents to the project’s `sites/default/files` upload directory ddev import-files -s=.tarballs/files.tar.gz -t=sites/default/files ``` ## `launch` Launch a browser with the current site (global shell host container command). If the current project is not running, it will be started first. Flags: - `--mailpit`, `-m`: Open Mailpit. - `--print-url`: Print the URL instead of opening a browser. The output is the resolved URL itself, with no prefix, so it can be used directly in scripts. Useful where no browser is available (SSH sessions, containers, CI). - `--qr`: Print the URL and its QR code instead of opening a browser. Only useful for a URL a phone can reach, which `*.ddev.site` is not. The environment variable `DDEV_LAUNCH_PRINT_URL=true` behaves like the `--print-url` flag. Unlike the flag it is inherited by nested `ddev launch` invocations (for example from custom commands or add-ons that call `ddev launch` internally), so wrappers and external tools can capture the URL. Unlike `DDEV_DEBUG=true` or `DDEV_VERBOSE=true`, which print the URL with a `FULLURL` prefix and enable global debug logging, it prints only the URL. > [!TIP] > > **How to disable HTTP redirect to HTTPS?** > > Recommendations for: > > - [Google Chrome]() > - [Mozilla Firefox]() > - [Safari]() Example: ``` # Open your project’s base URL in the default browser ddev launch # Open Mailpit in the default browser ddev launch --mailpit # Print your project’s base URL instead of opening a browser ddev launch --print-url # Print a QR code for a URL, to scan with a phone ddev launch --qr https://your.example.com # Open your project’s base URL appended with `temp/phpinfo.php` ddev launch temp/phpinfo.php # Open the full URL (any website) in the default browser ddev launch https://your.ddev.site # Open your project’s base URL using a specific port ddev launch :3000 ``` ## `list` *Aliases: `l`, `ls`.* List projects. Flags: - `--active-only`, `-A`: If set, only currently active projects will be displayed. - `--continuous`: If set, project information will be emitted until the command is stopped. - `--continuous-sleep-interval`, `-I`: Time in seconds between `ddev list --continuous` output lists. (default `1`) - `--type`, `-t`: Show only projects of this type (e.g. `drupal`, `wordpress`, `php`). - `--wrap-table`, `-W`: Display table with wrapped text if required. Example: ``` # List all projects ddev list # List all running projects ddev list --active-only # List all WordPress projects ddev list --type wordpress ``` ## `logs` Get the logs from your running services. Flags: - `--follow`, `-f`: Follow the logs in real time. - `--service`, `-s`: Defines the service to retrieve logs from (e.g. `web`, `db`). (default `"web"`) - `--tail`: How many lines to show. - `--time`, `-t`: Add timestamps to logs. Example: ``` # Display recent logs from the current project’s web server ddev logs # Stream logs from the current project’s web server in real time ddev logs -f # Display recent logs from the current project’s database server ddev logs -s db # Display recent logs from my-project’s database server ddev logs -s db my-project ``` ## `magento` Run the `magento` command; available only in projects of type `magento2`, and only works if `bin/magento` is in the project. ``` # Show all magento subcommands ddev magento list ``` ## `maho` Run the `maho` command; available only in projects of type `maho`, and only works if the `maho` script is in the project root (it is copied there by Composer on install). ``` # Show all maho subcommands ddev maho list # Flush the cache ddev maho cache:flush ``` ## `mailpit` Launch a browser with mailpit for the current project (global shell host container command). Example: ``` # Open Mailpit in the default browser ddev mailpit ``` ## `mariadb` Run MariaDB client in the database container (global shell db container command). This is only available on projects that use the `mariadb` database type. (This is the same as the `mysql` command, but MariaDB is changing the name of their CLI client.) Example: ``` # Run the database container’s MariaDB client as root user ddev mariadb # Run the database container’s MariaDB client as db user ddev mariadb -udb -pdb # Pipe the `SHOW TABLES;` command to the MariaDB client to see a list of tables echo 'SHOW TABLES;' | ddev mariadb ``` ## `mutagen` Commands for [Mutagen]() status and sync, etc. ### `mutagen logs` Show Mutagen logs for debugging. Flags: - `--verbose`: Show full Mutagen logs. Example: ``` # Stream Mutagen’s logs in real time ddev mutagen logs # Stream Mutagen’s more detailed logs in real time ddev mutagen logs --verbose ``` ### `mutagen monitor` Monitor Mutagen status. Example: ``` # Start Mutagen’s sync process and monitor its status in real time ddev mutagen sync && ddev mutagen monitor ``` ### `mutagen reset` Stops a project and removes the Mutagen Docker volume. ``` # Reset Mutagen data for the current project ddev mutagen reset # Reset Mutagen data for my-project ddev mutagen reset my-project ``` ### `mutagen status` *Alias: `mutagen st`.* Shows Mutagen sync status. Flags: - `--verbose`, `-l`: Extended/verbose output for Mutagen status. Example: ``` # Display Mutagen sync status for the current project ddev mutagen status # Display Mutagen sync status for my-project ddev mutagen status my-project ``` ### `mutagen sync` Explicit sync for Mutagen. Flags: - `--verbose`: Extended/verbose output for Mutagen status. Example: ``` # Initiate Mutagen sync for the current project ddev mutagen sync # Initiate Mutagen sync for my-project ddev mutagen sync my-project ``` ### `mutagen version` Display the version of the Mutagen binary and the location of its components. Example: ``` # Print Mutagen details ddev mutagen version ``` ## `mysql` Run MySQL client in the database container (global shell db container command). This is only available on projects that use the `mysql` or `mariadb` database types. Example: ``` # Run the database container’s MySQL client as root user ddev mysql # Run the database container’s MySQL client as db user ddev mysql -udb -pdb # Pipe the `SHOW TABLES;` command to the MySQL client to see a list of tables echo 'SHOW TABLES;' | ddev mysql ``` ## `npm` Run [`npm`]() inside the web container (global shell web container command). Example: ``` # Install JavaScript packages using `npm` ddev npm install # Update JavaScript packages using `npm` ddev npm update ``` ## `npx` Run [`npx`]() inside the web container (global shell web container command). Example: ``` # Initialize Biome in the project ddev npx @biomejs/biome init # Create a new Next.js app ddev npx create-next-app@latest ``` ## `php` Run `php` inside the web container (global shell web container command). Example: ``` # Output the web container’s PHP version ddev php --version ``` ## `poweroff` *Alias: `powerdown`.* Completely stop all projects and containers. > [!TIP] > > This is the equivalent of running `ddev stop -a --stop-ssh-agent`. Example: ``` # Stop all projects and containers ddev poweroff ``` ## `psql` Run PostgreSQL client in the database container (global shell db container command). This is only available on projects that use the `postgres` database type. Example: ``` # List available databases ddev psql -l # List tables in the default 'db' database echo "\dt;" | ddev psql ``` ## `pull` Pull files and database using a configured [provider plugin](). Flags: - `--environment=ENV1=val1,ENV2=val2` - `--skip-confirmation`, `-y`: Skip confirmation step. - `--skip-db`: Skip pulling database archive. - `--skip-files`: Skip pulling file archive. - `--skip-import`: Download archive(s) without importing them. Example: ``` # Pull a backup from the configured Upsun project to use locally ddev pull upsun # Pull from Pantheon without confirming ddev pull pantheon -y # Pull the Upsun database only without confirming ddev pull upsun --skip-files -y # Pull the Acquia files only without confirming ddev pull acquia --skip-db -y # Download archives from Upsun without importing them ddev pull upsun --skip-import # Pull from Upsun overriding environment and token on the command line ddev pull upsun --environment="PLATFORM_ENVIRONMENT=main,UPSUN_CLI_TOKEN=abcdeyourtoken" # Pull from Pantheon overriding environment and token on the command line ddev pull pantheon --environment="DDEV_PANTHEON_ENVIRONMENT=dev,TERMINUS_MACHINE_TOKEN=abcdeyourtoken" # Pull from Lagoon overriding project and environment on the command line ddev pull lagoon --environment="LAGOON_PROJECT=your-project,LAGOON_ENVIRONMENT=main" ``` ## `push` Push files and database using a configured [provider plugin](). Flags: - `--environment=ENV1=val1,ENV2=val2` - `--skip-confirmation`, `-y`: Skip confirmation step. - `--skip-db`: Skip pushing database archive. - `--skip-files`: Skip pushing file archive. Example: ``` # Push local files and database to the configured Upsun project ddev push upsun # Push to Pantheon without confirming ddev push pantheon -y # Push database only to Upsun without confirming ddev push upsun --skip-files -y # Push files only to Acquia without confirming ddev push acquia --skip-db -y # Push to Upsun overriding environment and token on the command line ddev push upsun --environment="PLATFORM_ENVIRONMENT=main,UPSUN_CLI_TOKEN=abcdeyourtoken" # Push to Pantheon overriding environment and token on the command line ddev push pantheon --environment="DDEV_PANTHEON_ENVIRONMENT=dev,TERMINUS_MACHINE_TOKEN=abcdeyourtoken" # Push to Lagoon overriding project and environment on the command line ddev push lagoon --environment="LAGOON_PROJECT=your-project,LAGOON_ENVIRONMENT=main" ``` ## `querious` Open [Querious]() with the current project’s MariaDB or MySQL database (global shell host container command). This is only available if `Querious.app` is installed as `/Applications/Querious.app`, and only for projects with `mysql` or `mariadb` databases. Example: ``` # Open the current project’s database in Querious ddev querious ``` ## `restart` Restart one or several projects. With `--service`, only the named services get new containers, with their images built as `ddev start` builds them, and the rest of the project keeps running. This also brings back a service that is unhealthy or has crashed. A service in an [optional profile]() has to be started first, with `ddev start --profiles` or `ddev restart --profiles`. Restarting `web` restarts the whole project, with the optional services that were started. Flags: - `--all`, `-a`: Restart all projects. - `--no-cache`: Rebuild custom Docker image layers without cache. - `--omit-snapshot`, `-O`: With `--reset-database`, skip the snapshot of the database being removed. - `--profiles`: Start optional comma-separated Docker Compose profiles. - `--reset-database`: Remove the project’s existing database and start over with a new one. - `--seed-snapshot`: Seed a brand-new database volume from this snapshot name or file, instead of the stock starter database. - `--service`, `-s`: Restart only these comma-separated services. - `--skip-confirmation`, `-y`: Skip any confirmation steps. Example: ``` # Restart the current project ddev restart # Restart the current project without using Docker cache ddev restart --no-cache # Restart my-project and my-other-project ddev restart my-project my-other-project # Restart all projects ddev restart --all # Restart the current project with the busybox profile, without Docker cache ddev restart --profiles=busybox --no-cache # Restart only the db service ddev restart --service=db # Restart only the solr and redis services, without Docker cache ddev restart -s solr,redis --no-cache # Throw away the current database and restart with a new, empty one ddev restart --reset-database # Reset and initialize with external snapshot without confirmation ddev restart --reset-database --seed-snapshot=/tmp/newsnapshot-mariadb_11.8.zst -y ``` ## `sake` Run the `sake` command, only available for Silverstripe CMS projects and if the `sake` command is available in the `vendor/bin` folder. Common commands: - Build database: `ddev sake dev/build` (or `ddev sake db:build` from Silverstripe CMS 6 onwards) - List of available tasks: `ddev sake dev/tasks` (or `ddev sake tasks` from Silverstripe CMS 6 onwards) ## `self-upgrade` Output instructions for updating or upgrading DDEV. The command doesn’t perform the upgrade, but tries to provide instructions relevant to your installation. Example: ``` → ddev self-upgrade DDEV appears to have been installed with install_ddev.sh, you can run that script again to update. curl -fsSL https://ddev.com/install.sh | bash ``` ## `sequelace` Open [SequelAce]() with the current project’s database (global shell host container command). This command is only available if `Sequel Ace.app` is installed as `/Applications/Sequel Ace.app`, and only for projects with `mysql` or `mariadb` databases. Example: ``` # Open the current project’s database in SequelAce ddev sequelace ``` ## `share` [Share the current project]() on the internet via a tunnel provider like ngrok or cloudflared. The tunnel URL is also printed as a QR code, which you can scan to open it on a phone or tablet. DDEV supports multiple share providers: - **ngrok** (default) - Requires an [ngrok.com]() account - **cloudflared** - Free, no account required. Requires [cloudflared]() to be installed - **Custom providers** - Add your own providers in `.ddev/share-providers/` Flags: - `--provider`: Share provider to use (ngrok, cloudflared, or custom). - `--provider-args`: Arguments to pass to the share provider (overrides config file settings). - `--ngrok-args`: (Deprecated) Use `--provider-args` instead. The default provider can be configured globally with `ddev config global --share-default-provider=` or per-project with `ddev config --share-default-provider=`. See [`share_default_provider`]() for more details. Provider-specific arguments can be configured in `.ddev/config.yaml` with [`share_provider_args`](). Examples: ``` # Share the current project with the default provider (ngrok) ddev share # Share with cloudflared ddev share --provider=cloudflared # Share with cloudflared using a custom domain (named tunnel) ddev share --provider=cloudflared --provider-args="--tunnel my-tunnel --hostname mysite.example.com" # Share with ngrok, using domain `foo.ngrok-free.app` ddev share --provider-args="--domain foo.ngrok-free.app" # Share the current project using ngrok's basic-auth argument ddev share --provider-args="--basic-auth username:pass1234" # Share my-project with ngrok ddev share my-project ``` ## `snapshot` Create a database snapshot for one or more projects. This uses `xtrabackup` or `mariadb-backup` to create a database snapshot in the `.ddev/db_snapshots` directory. These are compatible with server backups using the same tools and can be restored with the [`snapshot restore`](<#snapshot-restore>) command. See [Snapshotting and Restoring a Database]() for more detail, or [Database Management]() for more on working with databases in general. Flags: - `--all`, `-a`: Snapshot all projects. (Will start stopped or paused projects.) - `--cleanup`, `-C`: Cleanup snapshots. - `--list`, `-l`: List snapshots. - `--name`, `-n`: Provide a name for the snapshot. - `--uncompressed`: Write the snapshot as an uncompressed mariadb-backup/xtrabackup stream instead of compressing it. This skips decompression on restore, but the file can be roughly as large as the database’s datadir, many times bigger than a compressed snapshot. Not available for PostgreSQL projects. See [Snapshots]() for when this unusual trade-off makes sense. - `--yes`, `-y`: Skip confirmation prompt. `ddev snapshot --list` also shows each snapshot’s compression: `zstd`, `gzip`, or `none` for an uncompressed snapshot. If the project is a Git worktree and a sibling worktree of the same project has snapshots of its own, those are listed too, with a `Worktree` column naming which one each came from. Example: ``` # Take a database snapshot for the current project ddev snapshot # Take a database snapshot for the current project, named `my_snapshot_name` ddev snapshot --name my_snapshot_name # Take a snapshot for the current project, cleaning up existing snapshots ddev snapshot --cleanup # Delete a single snapshot by name without deleting all snapshots ddev snapshot --cleanup --name my_snapshot_name # Take a snapshot for the current project, cleaning existing snapshots and skipping prompt ddev snapshot --cleanup -y # List the current project’s snapshots ddev snapshot --list # Take a snapshot for each project ddev snapshot --all # Take an uncompressed snapshot, trading disk space for a faster restore ddev snapshot --uncompressed ``` ### `snapshot restore` Restores a database snapshot, either by name from the `.ddev/db_snapshots` directory or by the path to a snapshot file elsewhere on disk. If the project is a Git worktree, snapshots from the same project checked out in other worktrees of the same repository are available too, whether picked interactively, restored by name, or via `--latest`. Flags: - `--force`, `-f`: Restore a snapshot made by a different version of the same database server, which may not succeed. - `--latest`: Use the latest snapshot. Example: ``` # Restore the most recent snapshot ddev snapshot restore --latest # Restore the previously-taken `my_snapshot_name` snapshot ddev snapshot restore my_snapshot_name # Restore a snapshot taken on an older version of the same database server ddev snapshot restore --force my_snapshot_name # Restore a snapshot file from outside the project ddev snapshot restore ~/tmp/mysnapshot-mariadb_11.8.zst ``` A snapshot normally has to match the project’s configured database type and version exactly. `--force` lifts that for a different version of the same server, which the underlying restore doesn’t itself check for; the database may fail to come up, in which case [`ddev start --reset-database`]() starts over. Restoring across database types (a MySQL snapshot into MariaDB, say) is still refused. ## `spark` Run the `spark` command; available only in projects of type `codeigniter`, and only available if `spark` is in the project root. ``` # Show all spark subcommands ddev spark list ``` ## `ssh` Starts a shell session in a service container. Uses the web service by default. Flags: - `--dir`, `-d`: Defines the destination directory within the container. - `--service`, `-s`: Defines the service to connect to. (default `"web"`) - `--user`, `-u`: Defines the user to run shell as. Example: ``` # SSH into the current project’s web container ddev ssh # SSH into the current project’s database container ddev ssh -s db # SSH into the current project’s database container as root user ddev ssh -s db -u root # SSH into the web container for my-project ddev ssh my-project # SSH into the docroot of the current project’s web container ddev ssh -d /var/www/html ``` ## `start` *Alias: `add`*. Start a DDEV project. If you run `ddev start` in a directory that has no DDEV project but looks like a web project, DDEV shows the configuration `ddev config --auto` would create (name, URL, project type, docroot, PHP version, database, and web server) and asks whether to use it, customize it with the `ddev config` questions, or cancel. DDEV recognizes a directory as a web project when it detects a supported project type, or finds a `composer.json`, a `package.json`, or an `index.php` or `index.html` at the root or in a common docroot such as `web` or `public`. Without a terminal to ask in, as in CI or a script, or with `--skip-confirmation` (`-y`), `ddev start` doesn’t configure anything; use `ddev config --auto && ddev start` there instead. Flags: - `--all`, `-a`: Start all projects. - `--no-cache`: Rebuild custom Docker image layers without cache. - `--omit-snapshot`, `-O`: With `--reset-database`, skip the snapshot of the database being removed. - `--profiles`: Start optional comma-separated Docker Compose profiles. - `--reset-database`: Remove the project’s existing database and start over with a new one. - `--seed-snapshot`: Seed a brand-new database volume from this snapshot name or file, instead of the stock starter database. - `--skip-confirmation`, `-y`: Skip any confirmation steps. Example: ``` # Start the current project ddev start # Start the current project without using Docker cache ddev start --no-cache # Start my-project and my-other-project ddev start my-project my-other-project # Start all projects ddev start --all # Throw away the current database and start over with a new, empty one ddev start --reset-database # Start over with a database seeded from a snapshot instead ddev start --reset-database --seed-snapshot=my_snapshot_name ``` See [Seeding a Fresh Database from a Snapshot]() and [Starting Over with a New Database](). ## `stop` *Aliases: `rm`, `remove`.* Stop and remove the containers of a project. Does not lose or harm anything unless you add `--remove-data`. Flags: - `--all`, `-a`: Stop and remove all running or container-stopped projects and remove from global projects list. - `--omit-snapshot`, `-O`: Omit/skip database snapshot. - `--remove-data`, `-R`: Remove stored project data (MySQL, logs, etc.). - `--snapshot`, `-S`: Create database snapshot. - `--stop-ssh-agent`: Stop the `ddev-ssh-agent` container. - `--unlist`, `-U`: Remove the project from global project list, so it won’t appear in [`ddev list`](<#list>) until started again. Example: ``` # Stop the current project ddev stop # Stop my-project, my-other-project, and my-third-project ddev stop my-project my-other-project my-third-project # Stop all projects ddev stop --all # Stop all projects and the `ddev-ssh-agent` container ddev stop --all --stop-ssh-agent # Stop all projects and remove their data ddev stop --remove-data ``` ## `tableplus` Open [TablePlus]() with the current project’s database (global shell host container command). This command is only available if `TablePlus.app` is installed as `/Applications/TablePlus.app`. Example: ``` # Open the current project’s database in TablePlus ddev tableplus ``` ## `tablepro` Open [TablePro]() with the current project’s database (global shell host container command). This command is only available if `TablePro.app` is installed as `/Applications/TablePro.app`. Example: ``` # Open the current project’s database in TablePro ddev tablepro ``` ## `tui` Launch the [interactive TUI dashboard](). Example: ``` # Launch DDEV TUI ddev tui ``` ## `typo3` Run the `typo3` command; available only in projects of type `typo3`, and only works if `typo3` is in the `$PATH` inside the container; normally it’s in `vendor/bin/typo3` so will be found. ``` # Show typo3 site configuration ddev typo3 site:show ``` ## `utility` *Aliases: `ut`, `debug`, `d`,`dbg`.* A collection of utility and debugging commands, often useful for [troubleshooting](). ### `utility addon-update-checker` Fetch and run the DDEV add-on update checker script from [https://ddev.com/s/addon-update-checker.sh](). This is a tool for add-on developers to verify their add-on’s scripts and tooling are up to date with the [`ddev-addon-template`](). If the target directory contains `install.yaml`, the checker runs there. Otherwise, it scans immediate subdirectories for `install.yaml` and runs the checker in each one, which is useful when working in a workspace with multiple add-ons checked out alongside each other. Flags: - `--dir`, `-d`: Directory of the add-on to check, or a workspace containing multiple add-on directories (defaults to current directory). Example: ``` # Run in the current add-on directory ddev utility addon-update-checker # Run in a specific add-on directory ddev utility addon-update-checker -d /path/to/my-addon # Run across all add-ons in a workspace ddev utility addon-update-checker -d /path/to/my-addons-workspace ``` ### `utility cd` Uses shell built-in `cd` to change to a project directory. For example, `ddevcd some-project` will change directories to the project root of the project named `some-project`. Note that this command can’t work until you make a small addition to your `.bashrc`, `.zshrc`, or `config.fish`. ``` # To see the explanation of what you need to do ddev utility cd # Where some-project is a project from the `ddev list` ddevcd some-project ``` ### `utility check-custom-config` Display custom configuration files in the current project’s `.ddev` directory. By default, shows only files that would warn on startup: user-created files and files with an unexpected `#ddev-generated` marker. Recognized add-on files and files with a `#ddev-silent-no-warn` marker are excluded. Flags: - `--all`: Show all custom configuration, annotating files with: - `(add-on )` for files installed by a named add-on - `(#ddev-generated)` for add-on files that also carry a `#ddev-generated` marker - `(unexpected #ddev-generated)` for files with a `#ddev-generated` marker not recognized as a DDEV or add-on file - `(#ddev-silent-no-warn)` for files silenced with a `#ddev-silent-no-warn` marker ``` # Show only files that would warn on startup ddev utility check-custom-config # Show all files including add-on, unexpected #ddev-generated, and silenced files ddev utility check-custom-config --all ``` ### `utility check-db-match` Verify that the database in the db server matches the configured [type and version](). Example: ``` # Check whether project’s running database matches configuration ddev utility check-db-match ``` ### `utility compose-config` Prints the current project’s docker-compose configuration. Example: ``` # Print docker-compose config for the current project ddev utility compose-config # Print docker-compose config for `my-project` ddev utility compose-config my-project ``` ### `utility configyaml` Prints the project [`config.*.yaml`]() usage. **Arguments:** `[project_name]` **Flags:** - `--full-yaml`: Output complete processed YAML configuration instead of individual fields - `--omit-keys=`: Comma-separated list of keys to omit from output (e.g., `web_environment`) **Examples:** ``` # Print config for the current project ddev utility configyaml # Print config specifically for `my-project` ddev utility configyaml my-project # Print complete YAML configuration ddev utility configyaml --full-yaml # Hide sensitive environment variables ddev utility configyaml --omit-keys=web_environment # Combine flags: full YAML output without sensitive keys ddev utility configyaml --full-yaml --omit-keys=web_environment ``` ### `utility delete-volume` Delete a Docker volume belonging to the current project, identified by either its short docker-compose name (e.g. `solr`) or its full Docker volume name (e.g. `ddev-myproject_solr`). If no name is given, pick one from an interactive list of the project’s volumes. If the project is running, you’ll be asked to stop it first, since a container-mounted volume can’t be removed. Shared volumes used by every project, like `ddev-global-cache`, can’t be deleted with this command. Flags: - `--yes`, `-y`: Skip confirmation prompts. Example: ``` # Choose a volume to delete from an interactive list ddev utility delete-volume # Delete the "solr" volume for the current project, prompting for confirmation ddev utility delete-volume solr # Delete by full Docker volume name, skipping confirmation ddev utility delete-volume ddev-myproject_solr --yes ``` ### `utility diagnose` Run quick diagnostics on your DDEV installation and current project. This command provides concise, actionable output for common troubleshooting scenarios. The command checks: - Docker environment and connectivity - Network configuration and DNS resolution - HTTPS/mkcert setup - Current project health (if in a project directory) For comprehensive output suitable for issue reports, use [`ddev utility test`](<#utility-test>) instead. **Environment variables:** - `DDEV_DIAGNOSE_FULL=true`: Include test project creation in diagnostics (slower but more thorough) **Examples:** ``` # Run diagnostics in a project directory ddev utility diagnose # Run with full diagnostics including test project creation DDEV_DIAGNOSE_FULL=true ddev utility diagnose # Run from anywhere (checks Docker and environment only) ddev utility diagnose ``` ### `utility dockercheck` Diagnose DDEV Docker provider setup. Example: ``` # Output contextual details for the Docker provider ddev utility dockercheck ``` ### `utility download-ddev` Download the `ddev` and `ddev-hostname` binaries built by CI or a release, for testing a specific build without replacing your installed DDEV. It only downloads the binaries into a directory (`~/tmp/ddev-download-ddev/` by default, so a download can’t accidentally end up on `$PATH` or as a stray file in a Git checkout, and each build stays separate from the ones downloaded before it) and prints how to use them in the current shell; it does not modify your installed DDEV. Flags: - `--pr `: Download the build from a pull request number - `--branch `: Download the build from a branch name - `--commit `: Download the build from a commit SHA, full or abbreviated - `--tag `: Download a release tag, for example `v1.25.3` - `--stable`: Download the latest stable release (default `false`) - `--head`: Download the latest main build (default `false`) - `--output `, `-o `: Output directory, used as given (default: `~/tmp/ddev-download-ddev/`, where `` is the build, for example `pr-8611`, `v1.25.3`, or `main`) - `--os `: OS override: `macos`, `linux`, or `windows` (default: current OS) - `--arch `: Architecture override: `amd64` or `arm64` (default: current architecture) - `--owner `: GitHub owner/org (default `ddev`; for PR builds this is the base repository, not a fork) - `--repo `: GitHub repository (default `ddev`) Note: Exactly one source flag (`--pr`, `--branch`, `--commit`, `--tag`, `--stable`, or `--head`) is required, and they are mutually exclusive. Releases and `main` builds are signed; PR and other branch builds are not. No source needs a GitHub token, but a [GitHub token](<#add-on>) avoids the low anonymous rate limit and downloads CI builds from GitHub directly rather than through nightly.link. If the GitHub API lookup fails, `--pr` falls back to the build links posted on the pull request, and `--head` to nightly.link’s latest `main` build, which is sometimes out of date. Examples: ``` # Download this PR's build for your current OS and architecture into ~/tmp/ddev-download-ddev/pr-8611 ddev utility download-ddev --pr 8611 # Download the latest main build into ~/tmp/head ddev utility download-ddev --head --output ~/tmp/head # Download a specific released version ddev utility download-ddev --tag v1.25.3 # Download the latest stable release ddev utility download-ddev --stable # Cross-download a macOS arm64 build of a branch ddev utility download-ddev --branch 20250101_feature --os macos --arch arm64 --output ~/tmp/ddev-macos-arm64 ``` ### `utility download-images` Download the basic Docker images required by DDEV. This can be useful on a new machine to prevent `ddev start` or other commands having to download the various images. Example: ``` # Download DDEV’s basic Docker images ddev utility download-images # Download DDEV’s Docker images for `my-project` ddev utility download-images my-project # Download DDEV’s Docker images for all projects ddev utility download-images --all ``` ### `utility fix-commands` Refreshes [custom command]() definitions without running [`ddev start`](<#start>). Example: ``` # Refresh the current project’s custom commands ddev utility fix-commands ``` ### `utility get-volume-db-version` Get the database type and version found in the `ddev-dbserver` database volume, which may not be the same as the configured database [type and version](). Example: ``` # Print the database volume's engine and version ddev utility get-volume-db-version ``` ### `utility gob-decode` Decode and display the contents of Go gob-encoded binary files used by DDEV, such as `.remote-config` files (remote configuration cache), `.amplitude.cache` files (analytics event cache), `.sponsorship-data` files (contributor sponsorship information), and `.addon-data` files (add-on registry cache). The decoder automatically detects the file type and uses the appropriate structure. The output is displayed as formatted JSON for readability. *(Hidden - show hidden utility commands with `ddev utility --show-hidden`)* Example: ``` # Decode a remote config file ddev utility gob-decode $HOME/.ddev/.remote-config # Decode a sponsorship data file ddev utility gob-decode $HOME/.ddev/.sponsorship-data # Decode an add-on registry cache file ddev utility gob-decode $HOME/.ddev/.addon-data # Decode an amplitude cache file ddev utility gob-decode $HOME/.ddev/.amplitude.cache # Decode any gob file with path expansion ddev utility gob-decode ~/path/to/file.gob ``` ### `utility hyperlink` Print a URL, or the URLs in piped text, as terminal hyperlinks when supported. Useful in [custom host commands](). *(Hidden - show hidden utility commands with `ddev utility --show-hidden`)* Example: ``` # Print a URL as a link ddev utility hyperlink https://docs.ddev.com # Link the URLs in piped text echo "See https://docs.ddev.com" | ddev utility hyperlink ``` ### `utility match-constraint` Check if the currently installed ddev matches the specified [version constraint](). Example: ``` if ddev utility match-constraint "< 1.25" >/dev/null 2>&1; then # do something for ddev versions below 1.25 ... else # do something for ddev versions 1.25+ ... fi ``` > [!TIP] You can also configure a [ddev version constraint per project](). ### `utility message-conditions` Show message conditions of this version of DDEV. *(Hidden - show hidden utility commands with `ddev utility --show-hidden`)* Example: ``` # Show message conditions for the current DDEV version ddev utility message-conditions ``` ### `utility migrate-database` Migrate a MySQL or MariaDB database to a different `dbtype:dbversion`. Works only with MySQL and MariaDB, not with PostgreSQL. It will export your database, create a snapshot, destroy your current database, and import into the new database type. It only migrates the ‘db’ database. It will update the database version in your project’s `config.yaml` file. Example: ``` # Migrate the current project's database to MariaDB 10.7 ddev utility migrate-database mariadb:10.7 ``` ### `utility mutagen` Allows access to any [Mutagen command](). Example: ``` # Run Mutagen's `sync list` command ddev utility mutagen sync list ``` ### `utility mutagen-diagnose` Diagnose Mutagen sync configuration and performance issues. This command analyzes your Mutagen setup and provides actionable recommendations for improving sync performance. The command checks: - Volume sizes and disk usage (warns if \>5GB, critical if \>10GB) - Upload directories configuration - Sync session status and problems - Large files being synced that could impact performance (\>50MB) - Ignore pattern configuration **Flags:** - `--all`, `-a`: Show all Mutagen volumes system-wide instead of just the current project **Examples:** ``` # Diagnose the current project's Mutagen configuration ddev utility mutagen-diagnose # Show all Mutagen volumes across all projects ddev utility mutagen-diagnose --all ``` See the [Mutagen troubleshooting documentation]() for more details. ### `utility port-diagnose` Identify processes occupying ports needed by DDEV. When run inside a project directory, checks that project’s configured ports (HTTP, HTTPS, Mailpit, XHGui). When run outside a project, checks the default ports 80 and 443. On WSL2, both the Linux and Windows sides are checked. Some port conflicts are only visible with elevated privileges (e.g. `docker-proxy` under rootful Docker CE). The tool will ask for permission before running any `sudo` command, showing the exact command it intends to run. Use `--allow-sudo` to pre-approve this without an interactive prompt. Flags: - `--allow-sudo`: Permit `sudo` use for elevated port detection without an interactive prompt. Example: ``` # Check ports for the current project (or defaults 80/443 outside a project) ddev utility port-diagnose # Allow sudo for elevated detection without interactive prompt ddev utility port-diagnose --allow-sudo ``` See also: [Troubleshooting port conflicts](). ### `utility rebuild` *Alias: `utility refresh`.* Rebuilds the project’s Docker cache with verbose output and restarts the project or the specified services. Services that have a container get a new one with the rebuilt image. Rebuilding `web` restarts the whole project, with the optional services that were started. Flags: - `--all`, `-a`: Rebuild all services and restart the project. - `--cache`: Keep Docker cache. - `--service`, `-s`: Rebuild these comma-separated services and restart them. (default `web`) Example: ``` # Rebuild the current project's web service without cache ddev utility rebuild # Rebuild the current project's web service with cache ddev utility rebuild --cache # Rebuild the current project's db service without cache ddev utility rebuild --service db # Rebuild the current project's solr and redis services without cache ddev utility rebuild -s solr,redis # Rebuild the current project's all services without cache ddev utility rebuild --all ``` ### `utility remote-data` Download and display remote configuration and sponsorship data used by DDEV from GitHub repositories. The downloaded content is displayed as formatted JSON to stdout. Optionally updates the local cached storage file (enabled by default). *(Hidden - show hidden utility commands with `ddev utility --show-hidden`)* Flags: - `--type`, `-t`: Type of data to download: `remote-config` (default), `sponsorship-data`, or `addon-data`. - `--update-storage`: Update local cached storage file (default `true`). Examples: ``` # Download remote config (default type) ddev utility remote-data # Download sponsorship data without updating local storage ddev utility remote-data --type=sponsorship-data --update-storage=false # Download add-on registry data ddev utility remote-data --type=addon-data ``` ### `utility test` Run diagnostics using the embedded [test script](). Example: ``` # Run DDEV's diagnostic suite ddev utility test ``` ### `utility testcleanup` Removes all diagnostic projects created with `ddev utility test`. Example: ``` # Remove all DDEV's diagnostic projects ddev utility testcleanup ``` ### `utility tls-diagnose` Diagnose TLS/HTTPS certificate trust issues. Checks mkcert installation and `CAROOT` configuration, OS trust store installation, certificate file validity, and live HTTPS connectivity when a project is running. On WSL2, also checks WSL2-specific CA sharing requirements: whether `$CAROOT` points to the Windows filesystem, whether `CAROOT` is in `$WSLENV`, whether the Windows certificate store contains the mkcert CA, and whether Windows-side and WSL2-side CA fingerprints match. Example: ``` # Run from any directory for mkcert, trust store, and cert file checks ddev utility tls-diagnose # Run from a running project directory to also check live HTTPS connectivity cd my-project && ddev utility tls-diagnose ``` See also: [Browser Shows Certificate Error for DDEV Sites](). ### `utility xdebug-diagnose` Diagnose Xdebug configuration (experimental) Example: ``` # Run quick check ddev utility xdebug-diagnose # Run more complete interactive check ddev utility xdebug-diagnose --interactive ``` ## `version` Print DDEV and component versions. Example: ``` # Print DDEV and platform version details ddev version ``` > [!TIP] > > `ddev --version` is a more concise command that only outputs the DDEV version without component versions. ## `wp` Run the [WP-CLI `wp` command](); available only in projects of type `wordpress` and `wp-bedrock`. ``` # Install WordPress site using `wp core install` ddev wp core install --url='$DDEV_PRIMARY_URL' --title='New-WordPress' --admin_user=admin --admin_email=admin@example.com --prompt=admin_password ``` > [!TIP] > > See [WordPress Specifics]() for more information. ## `xdebug` Enable or disable [Xdebug]() (global shell web container command). - The `on` argument is equivalent to `enable` and `true`. - The `off` argument is equivalent to `disable` and `false`. ``` # Display whether Xdebug is running ddev xdebug status # Display detailed Xdebug diagnostic information ddev xdebug info # Turn Xdebug on ddev xdebug # Turn Xdebug on ddev xdebug on # Turn Xdebug off ddev xdebug off # Toggle Xdebug on and off ddev xdebug toggle ``` The `ddev xdebug info` command displays detailed diagnostic information from Xdebug’s `xdebug_info()` function, including enabled features, optional features, diagnostic log, step debugging status, and all Xdebug configuration directives. This may be useful for troubleshooting Xdebug configuration issues. `xdebug info` is only supported on Xdebug 3+. ## `xhgui` Enable or disable [XHGui]() `ddev xhgui` only is useful if [xhprof\_mode]() is set to `xhgui`. - The `on` argument is equivalent to `enable` and `true`. - The `off` argument is equivalent to `disable` and `false`. ``` # Display whether XHGui is enabled and running ddev xhgui status # Turn XHGui on ddev xhgui # Launch the XHGui UI ddev xhgui launch # Turn XHGui on ddev xhgui on # Turn XHGui off ddev xhgui off ``` ## `xhprof` Enable or disable [Xhprof]() (global shell web container command). - The `on` argument is equivalent to `enable` and `true`. - The `off` argument is equivalent to `disable` and `false`. ``` # Display whether Xhprof is running ddev xhprof status # Turn Xhprof on ddev xhprof # Turn Xhprof on ddev xhprof on # Turn Xhprof off ddev xhprof off ``` ## `yarn` Run [`yarn` commands]() inside the web container in the root of the project (global shell host container command). > [!TIP] > > Use `--cwd` for another directory, or you can change directories to the desired directory and `ddev yarn` will act on the same relative directory inside the container. > [!TIP] > > If you want to define your Yarn version on a per project basis, set `corepack_enable: true` in `.ddev/config.yaml` or `ddev config --corepack-enable` Example: ``` # Use Yarn to install JavaScript packages ddev yarn install # Use Yarn to add the Lerna package ddev yarn add lerna # Use yarn in a relative directory cd web/core && ddev yarn add lerna # Use Yarn to add the Lerna package from the `web/core` directory ddev yarn --cwd web/core add lerna # Use latest yarn or specified yarn ddev config --corepack-enable && ddev restart ddev yarn set version stable ddev yarn --version ```