v1.25.3

Installation

See the installation instructions for details, but it's easy:

• macOS: brew install ddev/ddev/ddev or just brew upgrade ddev.


• Linux: Use sudo apt-get update && sudo apt-get install ddev, see apt/yum installation


• Windows and WSL2: Download the Windows Installer; you can run it for install or upgrade.
  
  ⚠️ Traditional Windows users (not WSL2): If needed, the installer will prompt you to uninstall the previous system-wide installation to avoid conflicts with the new per-user installation.


• Consider ddev delete images or ddev delete images --all after upgrading to free up disk space used by previous Docker image versions. This does no harm.


• Consider ddev config --auto to update your projects to current configuration.

Highlights

Blog announcement: https://ddev.com/blog/release-v1-25-3/

• New Docker Compose library: Improved UX during ddev start and ddev stop; the separate ~/.ddev/bin/docker-compose binary is no longer needed and can be removed


• Faster ddev start: Reduced startup time by running post-healthcheck tasks concurrently, thanks to @jonesrussell


• Faster ddev stop: Fixed a bug in the webserver startup script that added an unnecessary ~10-second delay


• MariaDB 12.3 LTS support


• Podman and Docker rootless are no longer experimental: Both are now stable and ready for general use:
  
  
  
  • macOS (Podman rootless)
  
  
  • Linux/WSL2 (Docker rootless)
  
  
  • Linux/WSL2 (Podman rootless)
  
  
  
  

Breaking Changes

• Remove support for XDG_CONFIG_HOME, replaced by DDEV_XDG_CONFIG_HOME. Support for ~/.config/ddev on Linux is unchanged. This change was needed because some IDEs, such as PhpStorm, don't always see XDG_CONFIG_HOME set in the terminal (see this issue), which caused the IDE to recreate the ~/.ddev directory repeatedly


• Use stricter permissions for world-writable directories inside ddev-webserver. If you had post-start hooks that wrote to /usr/local/bin, update them to use ~/.local/bin instead, thanks to @AkibaAT


• Move N_PREFIX from /usr/local to /usr/local/n. This shouldn't affect most people, unless you referenced a full path such as /usr/local/bin/npm - the new location is /usr/local/n/bin/npm, or simply use npm without a full path


• Remove the ddev dr alias for ddev drush, since dr is now a built-in command for Drupal 11.4+

Features

• Node.js improvements: preserve nodejs_version in .ddev/config.yaml, and install several Node.js versions with n install <version> inside the web container


• Docker rootless on Linux no longer requires no-bind-mounts; disable it with ddev config global --no-bind-mounts=false


• Support the gvisor-tap-vsock network driver in Docker rootless


• Add new ddev dr command for Drupal 11.4+


• Allow using Mutagen together with ddev config global --use-hardened-images=true


• ddev version and ddev config now work even when Docker isn't running or is broken, and ddev poweroff shows progress output instead of appearing to hang


• Improve ddev list and ddev describe layout on narrow terminals


• Add OSC 8 terminal hyperlink support to ddev list, ddev describe, ddev add-on list, and ddev add-on search


• Show human-readable output when checking available disk space, thanks to @wolcen


• Always pull images when using ddev start --no-cache


• Respect the COMPOSER_NO_BLOCKING environment variable from the host in ddev composer


• Add ddev config global --docker-buildx-version to specify which Docker Buildx version to use (advanced use only)


• Respect docker-buildx installed via snap on Linux


• Support Debian, Kali, and eLxr WSL2 distros in the Windows installer, and avoid installing docker-ce over an existing Docker Desktop docker binary


• Add ddev utility addon-update-checker command for add-on maintainers


• Add #ddev-interactive option for add-on actions, thanks to @AkibaAT


• Add x-ddev.omit-ddev-labels extension to skip com.ddev.* label injection for specific services


• Support the Flatpak user binary for DBeaver on Linux, thanks to @nickchomey


• Add a quickstart for Drupal 12 (HEAD), thanks to @rpkoller


• Add troubleshooting for Let's Encrypt certificate failures, thanks to @jonpugh

Bug Fixes

• Windows installer: fix installation on WSL2 Ubuntu 26.04, which previously failed due to the deprecated wslu package


• Suppress 404 logs for favicon.ico and robots.txt; in some cases these caused Nginx to run a PHP script twice


• Prevent recursion in global web command wrappers


• Use the correct settings.ddev.php for each Drupal version


• Fix a bug where .ddev/apache/apache-site.conf went missing when using a custom Nginx config


• Detect a missing docker CLI, which is required when using Mutagen


• Limit the ENV HOME="" workaround for MySQL 8.x to the database context only


• Podman and macOS: restrict the keep-id userns setting to Linux only


• Use the nodejs_version set during the ddev-webserver image build; if you installed global npm packages in post-start hooks, move them to extra Dockerfiles instead


• Use wrapper scripts in ddev-dbserver to avoid mysql deprecation warnings with MariaDB 11.x+


• Warn when the CAROOT environment variable is set but the mkcert CA files (needed for HTTPS in your browser) are inaccessible


• Normalize OSTYPE detection on Linux, thanks to @Mikee-3000


• Avoid double-sourcing bashrc configuration in ddev ssh


• Skip OS-generated metadata files (.DS_Store, Thumbs.db, desktop.ini) during custom-config detection and in .ddev/.gitignore


• Restore path autocompletion for ddev add-on get


• Don't prompt to run ddev poweroff after updating ddev-ssh-agent


• Fix a case typo in ddev sequelace so Sequel Ace is detected on case-sensitive macOS filesystems, thanks to @mficzel

Internal Changes

• Migrate DDEV documentation from Material for MkDocs to Zensical


• Upgrade Bubble Tea (ddev tui) to v2


• Add light/dark/system preference variants for the brand logo


• Remove automated testing on macOS Intel; macOS amd64 binaries are still built and distributed, only CI testing on Intel hardware is removed


• Add automated testing for macOS Podman rootless


• Improve the test embargo system for Go, Bats, and CI workflows; tests can now be skipped when needed


• Add custom GitHub workflows to run tests on branches without opening a PR


• Rework local HTTP test helpers for clearer failure output


• Remove the build step for the Docker image used in ddev auth ssh


• Bump all Go dependencies

Minor Updates

• PHP 8.4.22 and 8.5.7

What's Changed

• test: Reenable Drupal 12 bats test (#8346) [skip ci] by @rpkoller in #8346


• chore(claude): fix PreToolUse hook matcher for git commit static analysis (#8345) [skip ci] by @stasadev in #8345


• docs(add-ons): Minor updates to creating-add-ons.md by @rfay in #8347


• perf: combined startup time optimizations, for #8096 by @jonesrussell in #8145


• fix(windows): remove wslu from installer, fixes #8326 by @stasadev in #8351


• fix(webserver): replace phar.io/filippo.io links with GitHub releases, improve Dockerfile, for #8012 by @stasadev in #8352


• docs(quickstart): add a quickstart for Drupal 12 (#8357) [skip ci] by @rpkoller in #8357


• feat(docker): always pull images with --no-cache by @stasadev in #8363


• fix(download-images): pull webserver image, for #8304 by @stasadev in #8358


• fix(start): use image digest for rebuild detection, fix rand and ssh-agent data races, for #8145 by @stasadev in #8359


• fix(test): skip TestCheckLiveConnectivityWithProject on Rancher/Colima/Lima, fix misleading WSL2 labels by @rfay in #8365


• docs(windows): add WSL2 installation step to Docker docs by @stasadev in #8355


• chore: fix claude hooks and update agent docs [skip ci] by @rfay in #8370


• chore: remove macOS amd64 CI testing (#8372) [skip ci] by @rfay in #8372


• fix(drupal): use configured project type for settings.php version selection by @rfay in #8366


• ci: run golangci-lint by @stasadev in #8375


• docs(mutagen): explain how to reset to the default mode, fixes #8367 by @silverham in #8368


• docs(configuration): Add ddev config --database=<database type>:<version> example command (#8387) [skip ci] by @silverham in #8387


• build: bump fuxingloh/multi-labeler from 4 to 5 (#8385) [skip ci] by @dependabot[bot] in #8385


• docs: clarify --cleanup --name for single snapshot deletion (#8384) [skip ci] by @CallMeLeon167 in #8384


• docs(add-ons): add real example for bats testing (#8377) [skip ci] by @stasadev in #8377


• fix(commands): normalize $OSTYPE detection for linux, fixes #8382 by @Mikee-3000 in #8383


• docs: Add Xcode iOS simulator info (#8371) [skip ci] by @jamesmacwhite in #8371


• feat(utility): add ddev utility addon-update-checker command by @stasadev in #8373


• fix(add-ons): autocomplete for path by @stasadev in #8376


• test(wsl2): fix TestHostDBPort by @stasadev in #8391


• test(windows): fix TestUtilityAddonUpdateCheckerCmd, for #8373 by @stasadev in #8394


• docs(quickstart): Add description to Drupal Git clone example by @gitressa in #8395


• fix(ddev-webserver): ddev stop takes 10s due to bash deferring SIGTERM during foreground cat, fixes #8295 by @rfay in #8396


• docs: unify homeadditions path resolution and Composer auth.json handling by @eiriksm in #8400


• docs(providers): align --environment examples and flags, fixes #8402 by @stasadev in #8403


• test(share): improve cloudflared debug output on unmarshal errors by @rfay in #8398


• ci(github): reorganize test jobs, add custom workflow_dispatch, remove unused workflows by @stasadev in #8401


• feat(add-on): add #ddev-interactive option for actions, fixes #8155 by @AkibaAT in #8381


• refactor(tui): upgrade bubbletea/bubbles/lipgloss to v2 by @stasadev in #8404


• ci: add DDEV_EMBARGO_PHP_VERSIONS to skip specific PHP versions in TestPHPConfig [skip ci] by @rfay in #8407


• feat: use docker-compose library, optionally download docker-buildx, fixes #7915, for #8295 by @stasadev in #8234


• ci(docs): add stable docs branch workflow, fixes #7862 by @stasadev in #8408


• ci(forks): fetch variables from public-variables branch by @stasadev in #8410


• ci(wsl2): read public-variables in pwsh, for #8410 by @stasadev in #8411


• ci: improve test embargo system for Go, bats, and CI workflows by @stasadev in #8413


• docs(config): improve wording for database and docker_buildx_version, for #8387 by @stasadev in #8409


• refactor: improve CheckAvailableSpace reliability and output, fixes #8388 by @wolcen in #8412


• ci(buildkite): fix MSYS path conversion breaking public-variables fetch on Windows, for #8410 by @stasadev in #8416


• docs(brand-guide): add light, dark, and auto logo variants to logos table, fixes #8417 by @stasadev in #8419


• feat(docs): migrate from mkdocs-material to zensical, fixes #7840, fixes #8216 by @stasadev in #8421


• docs(add-ons): mention #ddev-generated in quickstart by @chx in #8420


• ci(docs): enable zensical strict mode, use dynamic Pages base URL, for #8421 by @stasadev in #8423


• fix(ddev-dbserver): unlink stale socket before mysqld init by @stasadev in #8424


• test: add details to TestCmdAddonPHP by @stasadev in #8425


• chore(sponsors): update percentage and api link [skip ci] by @stasadev in #8427


• ci(pr): migrate to ddev/commit-message-checker@v3 by @stasadev in #8428


• test(lima): fix broken cleanup in TestCmdAddonPHP, for #8425 by @stasadev in #8430


• fix: replace remaining world writeable directories, fixes #8251 by @AkibaAT in #8379


• chore(composer): add COMPOSER_NO_BLOCKING by @stasadev in #8432


• fix(exec): allocate TTY only when stdout is also a terminal, for #8234 by @stasadev in #8431


• feat(docker-rootless): remove no-bind-mounts requirement, test gvisor-tap-vsock by @stasadev in #8426


• build: pin Node.js to 24.15.0, fixes #8436 by @stasadev in #8438


• test(linux): wait for nc to bind before asserting in port-diagnose tests by @stasadev in #8446


• test: rework local HTTP test helpers with clearer failure output by @stasadev in #8447


• fix(nodejs): move install to Dockerfile, add ~/n/bin to PATH, fixes #8414, fixes #8415 by @stasadev in #8443


• fix(zensical): retry strict build on false-positive "page does not exist" warnings by @stasadev in #8451


• ci(linux): use full homebrew formulae name, fixes #8450 by @stasadev in #8455


• test(quickstart): update asterios page check by @stasadev in #8454


• feat: add MariaDB 12.3 LTS support, fixes #8452 by @rfay in #8453


• fix(dbserver): use wrapper scripts for MariaDB 11.x+ MySQL compat, fixes #6861 by @stasadev in #8456


• test(buildkite): Fix brew upgrade to use -y for new 6.0.0 release, fix setup-homebrew by @rfay in #8469


• build(gnupg): Remove references to obsolete gnupg2 by @rfay in #8475


• fix: recreate service on ddev utility rebuild -s, support profile services by @stasadev in #8463


• fix(nodejs): preserve nodejs_version in config.yaml, fixes #8186 by @stasadev in #8462


• fix(nodejs): move N_PREFIX to /usr/local/n and make it writable, fixes #8465 by @stasadev in #8467


• fix(nginx): suppress favicon.ico and robots.txt 404 logs, fixes #7010 by @stasadev in #8461


• fix(ssh): use RawCmd to avoid double-sourcing bashrc, fixes #5232 by @stasadev in #8460


• docs: install util-linux-extra in Docker setup, fixes #8350 (#8480) [skip ci] by @rfay in #8480


• feat: improve ddev list/describe table layout, add OSC 8 terminal hyperlinks, fixes #5535, fixes #6113 (#8474) [skip ci] by @rfay in #8474


• fix: skip OS-generated metadata files in custom-config detection and .ddev/.gitignore, fixes #8418 (#8478) [skip ci] by @rfay in #8478


• fix(mutagen): detect missing docker CLI early, fixes #8457 by @rfay in #8479


• docs(docker): add troubleshooting for permission denied, for #8471 (#8483) [skip ci] by @stasadev in #8483


• test(quickstart): update shopware6 by @stasadev in #8482


• fix: warn when CAROOT is set but CA files are inaccessible, fixes #8485 (#8486) [skip ci] by @rfay in #8486


• fix(tui): prevent docker/cli stdin from consuming TUI shortcuts, fixes #8440 by @stasadev in #8489


• fix: add /usr/local/n/bin to sudo secure_path, fixes #8488 by @stasadev in #8490


• fix(start): show warnings from log-stderr.sh on start, fixes #8441 by @stasadev in #8481


• build(deps): bump go dependencies, migrate to go-github v88 by @stasadev in #8492


• test(quickstart): pin @sveltejs/[email protected] by @stasadev in #8497


• test(docs): Ignore link check URLs [skip ci] by @rfay in #8499


• build: bump actions/checkout from 6 to 7 (#8504) [skip ci] by @dependabot[bot] in #8504


• fix: restrict XDG_CONFIG_HOME to Linux, add DDEV_XDG_CONFIG_HOME for cross-platform overrides, fixes #8493 by @rfay in #8494


• fix(webserver): prevent recursion in global web command wrappers, for #6902 by @stasadev in #8495


• fix(nodejs): always install gulp-cli and yarn, fixes #8496 (#8498) [skip ci] by @stasadev in #8498


• feat(windows): support Debian and Kali WSL2 distros in GUI installer, fixes #8439, fixes #8468 by @rfay in #8464


• build: Fix gomt error that crept in [skip ci] by @rfay in #8509


• test: Add script to compare start time performance [skip ci] by @rfay in #8510


• test(quickstart): remove pin for @sveltejs/adapter-node, for #8497 by @stasadev in #8511


• ci(github): add brew sandbox setup, remove obsolete env, for #8469 by @stasadev in #8512


• fix(mysql): guard ENV HOME injection to db context only, fixes #8508 by @stasadev in #8513


• fix(docker): do not cache build on start, fixes #8433 by @stasadev in #8506


• feat(drupal): Support new dr command built into drupal11.4+, fixes #8500 by @rfay in #8507


• fix(dbeaver): Add flatpak user binary path to search list, fixes #8517 by @nickchomey in #8518


• refactor(auth-ssh): remove build step, fixes #8501 by @stasadev in #8503


• feat: allow mutagen with use-hardened-images, for #3680 by @stasadev in #8491


• feat(docker): respect docker-buildx from snap on linux, fixes #8515 by @stasadev in #8519


• docs: replace newgrp with sg for docker group activation, fixes #8350 by @rfay in #8524


• fix(commands): correct case typo in ddev sequelace, fixes #8521 (#8522) [skip ci] by @mficzel in #8522


• build(deps): bump moby and docker-compose by @stasadev in #8523


• docs: skip codeberg, use stable link for docs in github workflows (#8528) [skip ci] by @stasadev in #8528


• build: remove pin for Node.js, for #8438 by @stasadev in #8527


• fix(start): do not ask for poweroff with new ddev-ssh-agent, fixes #8520 by @stasadev in #8525


• ci(podman): update workflow for Podman 6 by @stasadev in #8526


• fix(podman): restrict keep-id userns to Linux only, fixes #8223, fixes #8529 by @stasadev in #8516


• docs: Remove link to very old processwire thread (#8533) [skip ci] by @rfay in #8533


• fix: continue when #ddev-generated is missing in generate config functions, for #2305 by @stasadev in #8532


• docs: Ignore winaero.com, cert expired [skip buildkite] (#8537) [skip ci] by @rfay in #8537


• ci: add macOS Podman rootless Buildkite pipeline, for #8223 (#8530) [skip ci] by @rfay in #8530


• test(auth-ssh): harden ddevauthssh.expect against passphrase prompt race by @stasadev in #8536


• build: bump actions/cache from 5 to 6 (#8538) [skip ci] by @dependabot[bot] in #8538


• fix: stop honoring XDG_CONFIG_HOME on Linux too, use DDEV_XDG_CONFIG_HOME, fixes #8493 by @stasadev in #8531


• fix: correct typos in global and project config comment docs (#8541) [skip ci] by @stasadev in #8541


• test: fix TestCheckForMultipleGlobalDdevDirs on Windows, for #8531 (#8542) [skip ci] by @rfay in #8542


• feat: add x-ddev.omit-ddev-labels to skip com.ddev.* label injection, fixes #8389 by @stasadev in #8540


• build(docker): bump images to v1.25.3 for release, fixes #8544 by @stasadev in #8547


• ci(buildkite): trim podman machine and run maintenance post-test (#8551) [skip ci] by @stasadev in #8551


• docs(typo3): require Camino theme, drop empty distribution prompt (#8548) [skip ci] by @rfay in #8548


• docs(hosting): add guidance for Let's Encrypt failures by @jonpugh in #8543


• docs(docker): add Podman and Docker rootless setup, fixes #8434 by @stasadev in #8552


• ci(macos): untap pre-installed aws/tap before brew install by @rfay in #8559


• docs(wsl2): use Ubuntu-26.04 instead of Ubuntu-24.04, for #8326, for #8408 by @stasadev in #8553


• fix(webserver): restore nonstandard router port in HTTP_HOST for nginx-fpm, fixes #8554 by @rfay in #8555


• fix(router): temp pin for traefik:3.6.13, for #8562 by @stasadev in #8564


• fix(shopware): pin Twig <3.28 to work around admin HTTP 500 by @rfay in #8557


• docs: add TYPO3 special handling for ddev share, fixes #7799 by @rfay in #8556

New Contributors

• @silverham made their first contribution in #8368


• @CallMeLeon167 made their first contribution in #8384


• @Mikee-3000 made their first contribution in #8383


• @wolcen made their first contribution in #8412


• @chx made their first contribution in #8420


• @mficzel made their first contribution in #8522


• @jonpugh made their first contribution in #8543

Full Changelog: v1.25.2...v1.25.3