DDEV Release v1.25.0 with Debian Trixie, XHGui, and Enhanced Windows Support

We’re excited to announce DDEV v1.25.0, featuring Debian Trixie as the base image, XHGui as the default profiler, and a completely revised Windows installer.

This release represents contributions from the entire DDEV community, with your suggestions, bug reports, code contributions, and financial support making it possible.

What’s Changed in This Major Release

Default versions updated:

Debian Trixie replaces Debian Bookworm as the base image for ddev-webserver and ddev-ssh-agent
XHGui is now the default profiler (replacing prepend mode). See XHGui Feature blog post
PHP 8.4 becomes the default for new projects, and PHP 8.5.2 is now available with full extension support including Xdebug
Node.js 24 becomes the default for projects that don’t specify another version
MariaDB 11.8 becomes the default for new projects

Major new features:

Revised Windows installer now uses per-user installation for WSL2 or traditional Windows (no admin account required). Download from ddev.com/download
Reworked ddev share command with a new cloudflared share provider for free sharing options. See (draft) New ddev share Provider System
New diagnostic commands:
- ddev utility xdebug-diagnose helps troubleshoot Xdebug issues. See (draft) Xdebug Understanding and Troubleshooting
- ddev utility mutagen-diagnose helps debug Mutagen issues. See (draft) Mutagen Functionality and Debugging
Faster snapshots: ddev snapshot now uses zstd instead of gzip for significantly faster exports and restores, thanks @deviantintegral
Experimental Podman and Docker Rootless support: See (draft) Podman and Docker Rootless in DDEV
FrankenPHP as an official add-on: ddev-frankenphp with many improvements. See updated (draft) Using FrankenPHP with DDEV
Traefik configuration standardization: Project configuration now uses a single file: .ddev/traefik/config/<projectname>.yaml (all other files are ignored)

What You Need to Do After Upgrading

After upgrading to v1.25.0, follow these steps:

Run ddev poweroff (DDEV will prompt you for this)
Update your projects: Run ddev config --auto on each project to update to current configuration
Update installed add-ons: Run ddev add-on list --installed to see your add-ons, then update them as needed
Free up disk space: Run ddev delete images to remove old Docker image versions
Check for breaking changes below if you use any removed features

Breaking Changes: What to Check

1. Debian Trixie base image

If your project has custom Dockerfiles or uses webimage_extra_packages, check they’re compatible with Debian Trixie.

What to do: Test your project after upgrading. See Debian Trixie release notes for known issues.

Note: DDEV already includes the tzdata-legacy package to handle removed timezones in Debian Trixie, so no action is needed for timezone-related changes.

2. Profiler changed to XHGui

If you use XHProf profiling, it now defaults to XHGui mode instead of prepend mode.

What to do: If you prefer the previous prepend mode, run:

ddev config global --xhprof-mode=prepend

3. Nginx modules now come from Debian repository

If you use custom nginx modules, the package names and module loading have changed. DDEV now uses nginx bundled with Debian Trixie instead of maintaining an extra dependency on the nginx.org repository.

What to do: Update your nginx module configuration.

Example: Adding NJS (JavaScript) support to nginx

For DDEV v1.24.10 and earlier:

ddev config --webimage-extra-packages="nginx-module-njs"

cat <<'EOF' > .ddev/web-build/Dockerfile.nginx
RUN sed -i '1i load_module modules/ngx_http_js_module.so;\nload_module modules/ngx_stream_js_module.so;\n' /etc/nginx/nginx.conf
EOF

For DDEV v1.25.0+:

ddev config --webimage-extra-packages="libnginx-mod-http-js,libnginx-mod-stream,libnginx-mod-stream-js" --ddev-version-constraint='>=v1.25.0'

cat <<'EOF' > .ddev/web-build/Dockerfile.nginx
RUN sed -i '1i load_module modules/ngx_stream_module.so;\nload_module modules/ngx_http_js_module.so;\nload_module modules/ngx_stream_js_module.so;\n' /etc/nginx/nginx.conf
EOF

4. Removed commands and features

If you use these commands, you’ll need to switch:

ddev nvm: Switch to nodejs_version or install the ddev-nvm add-on
ddev service: Use ddev add-on to install/remove services
NFS performance mode: Switch to Mutagen instead

5. Updated `ddev config` flags

If you use these flags in scripts, update them:

--mutagen-enabled → --performance-mode=mutagen
--upload-dir → --upload-dirs
--http-port → --router-http-port
--https-port → --router-https-port
--mailhog-port → --mailpit-http-port
--mailhog-https-port → --mailpit-https-port
--projectname → --project-name
--projecttype, --apptype → --project-type
--sitename → --project-name
--image-defaults → --web-image-default

6. Traefik configuration

If you have custom Traefik configuration, note that:

Only .ddev/traefik/config/<projectname>.yaml is used (other files are ignored)
Put global Traefik configuration in $HOME/.ddev/traefik/custom-global-config/
Traefik v3 syntax is now required

What to do if you have extra Traefik files:

Merge all your custom configuration into .ddev/traefik/config/<projectname>.yaml and remove the #ddev-generated comment from it
Track issue #8047 for potential future improvements to this workflow

Note: ddev-router no longer stops automatically when the last project stops. Use ddev poweroff to stop it manually.

7. Windows installation

If you’re on traditional Windows (not WSL2): The installer may prompt you to uninstall the previous system-wide installation before installing the new per-user version.

Other Improvements

This release includes many other improvements:

New Wagtail, CodeIgniter, and Drupal 12 project types
Improved Pantheon integration with new environment variables and option to pull from existing backups or fresh database dumps
Much faster ddev add-on list and ddev add-on search
Shell autocompletion for ddev add-on get <TAB>
SELinux environment detection with automatic bind mount labels
More portable database collations for MySQL/MariaDB exports
SSH config support in $HOME/.ddev/homeadditions/.ssh/config.d
DBeaver support for traditional Windows

See the full release notes for complete details.

From the entire team, thanks for using, promoting, contributing, and supporting DDEV!

If you have questions, reach out in any of the support channels.

Follow our blog, Bluesky, LinkedIn, Mastodon, and join us on Discord. Sign up for the monthly newsletter.

This article was edited and refined with assistance from Claude Code.