Raised: $9,456
79% of monthly goal Help us cross the finish line!
Goal: $12,000
Raised: $9,456 Goal: $12,000
79% of monthly goal Help us cross the finish line!
Sponsor DDEV

DDEV v1.25.1 Docker Buildx Requirement

Stas Zhuk avatar
Stas Zhuk

March 5, 2026 2 min read

Edit this page
Docker Buildx releases page logo generated by GitHub

DDEV v1.25.1 introduced validation that checks for Docker Buildx. DDEV v1.25.3 will switch to the Docker Compose SDK exclusively and add optional Buildx configuration via ddev config global --docker-buildx-version. Docker Desktop, OrbStack, and Rancher Desktop users are not affected—Docker Buildx is bundled in those environments.

Table of Contents

The Error

You’ll see one of these when running ddev start:

compose build requires buildx 0.17.0 or later: docker CLI plugin "buildx" not found

compose build requires buildx 0.17.0 or later. Installed docker buildx: 0.13.1 (plugin path: /usr/lib/docker/cli-plugins/docker-buildx)

💡 Tip

Solution

Install Docker Buildx using the platform instructions below. On DDEV v1.25.3 and later, also run:

ddev config global --docker-buildx-version=system

Use --docker-buildx-version=<version> (e.g. 0.33.0) only if you can’t install a system Buildx.

Solutions by Platform

macOS (Lima, Colima)

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"]
}

Run brew info docker-buildx to see 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. Switch to Docker from the official Docker repositories:

  1. Backup your DDEV projects with ddev snapshot -a (optional but recommended)
  2. Uninstall Docker packages from Debian repositories
  3. Follow the Docker installation instructions in our documentation

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"]
}

NixOS users: the ddev package has been patched upstream (issue #8183, NixOS patch).

Why This Requirement Exists

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

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

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.

Posted In