DDEV v1.25.1 Docker Buildx Requirement

DDEV v1.25.1 introduced validation that checks for Docker Buildx, and you may encounter an error when running ddev start if your system isn’t configured correctly. This post explains why this dependency exists, who’s affected, and how to resolve it. Note that DDEV v1.25.2 will bundle a private Docker Buildx to eliminate this configuration requirement.

Who’s Affected
The Error
Why This Requirement Exists
Solutions by Platform
What’s Next for DDEV
Need Help?

Who’s Affected

Most users won’t need to do anything. Docker Desktop, OrbStack, and Rancher Desktop bundle Docker Buildx automatically.

You may need to take action if you’re using:

macOS with Lima or Colima - requires manual installation via Homebrew
Ubuntu or Debian with Docker from Ubuntu/Debian repositories instead of Docker’s repositories - older versions don’t meet requirements
NixOS - requires package update

If you’re running Docker Desktop, OrbStack, or Rancher Desktop, you can skip this article.

The Error

When running ddev start on DDEV v1.25.1 without a compatible Buildx version, you’ll see:

$ ddev start
Docker buildx check failed: compose build requires buildx 0.17.0 or later: docker CLI plugin "buildx" not found.
Please install buildx: https://github.com/docker/buildx#installing

Or if Buildx is installed but doesn’t match the required version:

$ ddev start
Docker buildx check failed: compose build requires buildx 0.17.0 or later.
Installed docker buildx: 0.13.1 (plugin path: /usr/lib/docker/cli-plugins/docker-buildx)
Please update buildx: https://github.com/docker/buildx#installing

Why This Requirement Exists

This is an upstream dependency from Docker Compose, not a DDEV-specific choice.

Here’s how we got here:

Docker Compose v2.37.0 (released June 2025) made the bake builder the default build backend
Docker Compose v2.40.2 (released October 2025) introduced a minimum version requirement for Docker Buildx (≥0.17.0)
DDEV v1.24.8 (released September 2025) updated to Docker Compose v2.39.3, which uses the bake builder by default
DDEV v1.25.1 (released February 2026) added validation to catch this configuration issue early and provide clear guidance

The requirement comes from Docker Compose itself. DDEV now validates your system configuration to prevent confusing build failures.

Solutions by Platform

macOS with Lima or Colima (or if you have this problem for any reason)

Install Docker Buildx via Homebrew:

brew install docker-buildx

After installation, configure Docker to find the plugin. Add cliPluginsExtraDirs to $HOME/.docker/config.json:

{
  "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"]
}

You can see this information anytime with:

brew info docker-buildx

The post-install messages from Homebrew will show you the exact path for your system.

Debian

Debian 13 (Trixie) includes Docker Buildx v0.13.1 from the Debian repositories, which doesn’t meet the ≥0.17.0 requirement.

Solution: Switch to Docker from the official Docker repositories.

Backup your DDEV projects with ddev snapshot -a.
Uninstall Docker packages from Debian repositories
Follow the Docker installation instructions in our documentation

The official Docker repositories provide current versions of all Docker components including Docker Buildx ≥0.17.0.

NixOS

NixOS users should track DDEV issue #8183. A NixOS patch is available - once merged, you’ll get the fix through normal system updates without manual intervention.

Generic Solution

If the platform-specific solutions above don’t work, you can manually place the docker-buildx binary in one of Docker’s expected plugin directories:

Linux/macOS:

$HOME/.docker/cli-plugins/
/usr/local/lib/docker/cli-plugins/
/usr/local/libexec/docker/cli-plugins/
/usr/lib/docker/cli-plugins/
/usr/libexec/docker/cli-plugins/

Traditional Windows (not needed for WSL2):

%USERPROFILE%\.docker\cli-plugins\
%ProgramFiles%\Docker\cli-plugins\

See Docker’s plugin manager source for Linux/macOS and Windows for the complete list.

Alternatively, place the binary anywhere and configure Docker to find it by adding cliPluginsExtraDirs to $HOME/.docker/config.json (or %USERPROFILE%\.docker\config.json on Windows):

{
  "cliPluginsExtraDirs": ["/path/to/your/custom/plugin/directory"]
}

What’s Next for DDEV

We’re working to make this smoother in upcoming releases:

DDEV v1.25.2 (upcoming) will likely bundle a private Docker Buildx that DDEV uses exclusively. This eliminates the system configuration requirement for most users. I’m working on this in PR #8198.

Future releases will transition from our private Docker Compose binary to the Docker Compose SDK. This gives DDEV more control over upstream dependencies and reduces configuration complexity.

Need Help?

If you’re still seeing issues after following these steps, reach out in any of the support channels.

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