Docker Buildx: what the CLI plugin adds to docker build, and how to install it

The gap Buildx fills in docker build

Plain docker build is tied to the daemon's builder. Buildx replaces that with a plugin that always builds through BuildKit, and it does so without requiring DOCKER_BUILDKIT=1, according to the README. The README lists what that buys you: multiple builder instances, multi-node builds for cross-platform images, Compose build support, high-level builds through Bake, and in-container drivers for both Docker and Kubernetes.

The audience is narrower than the feature list suggests. If you build one image for one architecture on one machine, the docker driver already covers you and Buildx adds a layer of indirection. The project pays off when a build has to produce a manifest list, when several machines share build work, or when the build definition has outgrown a single docker build invocation. The README frames the command as keeping the familiar UI from docker build while exposing BuildKit features that regular docker build does not have, including manifest lists, distributed caching and exporting results to OCI image tarballs.

Drivers, builder instances and where a build actually runs

The mechanism is a driver abstraction. Every builder instance points at a driver, and the driver decides how and where the build runs and which features are available. The README names five: docker, cloud, docker-container, kubernetes and remote. That is the single most important design decision in the project, because the driver, not Buildx itself, determines whether multi-platform output or cache export is even possible.

The docker driver runs builds inside the daemon you already have, which keeps things simple but inherits the daemon's constraints. The docker-container driver starts a dedicated BuildKit container, which is what most multi-platform workflows end up using. The kubernetes driver pushes the same idea into a cluster. Choosing wrong shows up as a feature that silently is not available rather than a clear error, so the driver is the first thing to check when a flag appears to do nothing.

The repository layout reflects this split: driver/, builder/, store/, commands/ and bake/ are separate top-level directories, with bake/ handling the HCL build definitions and monitor/ and policy/ sitting alongside them. Buildx is written in Go and vendors its dependencies, so the build path is self-contained.

Installing docker buildx on Linux, macOS and Windows

On Windows and macOS the README states Buildx ships with Docker Desktop, so there is nothing separate to install. On Linux, the Docker Engine package repositories include Buildx packages when the engine was installed following the official install documentation; the package to install is docker-buildx-plugin. That is the recommended route, and the README explicitly recommends against manual binary downloads for production because they will not be updated automatically with security updates.

To confirm the plugin is wired up, ask Docker for its version. A working install prints the plugin version and the git commit it was built from.

docker buildx version

Manual installation is documented for unattended or test setups. Download the binary from the releases page, rename it, and copy it to the CLI plugins directory for your OS. On Linux and macOS that is $HOME/.docker/cli-plugins, and on Windows it is %USERPROFILE%\.docker\cli-plugins. Unix installs may also need the executable bit set.

chmod +x ~/.docker/cli-plugins/docker-buildx

For a system-wide install on Unix, the README lists /usr/local/lib/docker/cli-plugins, /usr/local/libexec/docker/cli-plugins, /usr/lib/docker/cli-plugins and /usr/libexec/docker/cli-plugins. On Windows the options are C:\Program Files\Docker\cli-plugins and, for Docker 28.x and earlier only, C:\ProgramData\Docker\cli-plugins. Note that the ProgramData path is version-scoped, which matters if you script the install across a fleet.

Buildx can also be installed inside a Dockerfile using the docker/buildx-bin image. The README gives this example, which copies the binary into the plugin directory and then verifies it.

# syntax=docker/dockerfile:1
FROM docker
COPY --from=docker/buildx-bin /buildx /usr/libexec/docker/cli-plugins/docker-buildx
RUN docker buildx version

Once installed, the first real build is the same shape as docker build. The README shows the command and the progress output it produces.

docker buildx build .

A first multi-platform build and the engine version constraint

The README's warning is the practical starting point: Buildx requires Docker engine 19.03 or newer, and using an incompatible engine "may result in unexpected behavior" and will likely cause issues, especially with builders running more recent BuildKit versions. That is not a theoretical caveat. The plugin and the BuildKit it talks to are versioned separately, and the repository's own Dockerfile pins BuildKit at v0.33.0 and tests against Docker 29.8 plus alternate engines at 28.5 and 27.5.1. If your host runs an engine older than the plugin expects, the failure tends to surface at build time rather than install time.

After installation, docker buildx is reachable as a subcommand with Docker 19.03 and later. On older engines the README notes the Buildx binary can be called directly to reach the docker buildx subcommands, which is a fallback rather than a supported configuration.

Creating a scoped builder instance and pointing it at a driver is the step that separates a single-machine build from a multi-platform one. The README does not spell out the create command in the text shown here, so the reference documentation under docs/reference/buildx.md is where the exact flags live. What the README does commit to is the capability: multi-node builds for cross-platform images, and exporting results to OCI image tarballs, neither of which regular docker build offers.

Where Buildx is the wrong tool

The clearest limitation is the one the README states about installation: manual binary installs are documented as suitable mostly for testing, and the project does not recommend them for production because they are not updated automatically with security updates. If your environment cannot use Docker Desktop or the distribution packages, you are taking on the update path yourself, and that is a real operational cost, not a footnote.

The second limitation is the driver matrix. Feature availability depends on the driver, and the README describes drivers as having different feature sets without enumerating which flag needs which driver. That means a build that works on one machine can fail on another with the same Buildx version, because the builder instance points somewhere else. Debugging that requires knowing the driver, not just the command.

The third is version coupling. Buildx is a plugin talking to BuildKit through a Docker engine, and the README's warning about incompatible versions is the project telling you that the three move together. If you pin one and float the others, you own the consequences. Teams that build single-platform images on a managed CI runner get none of the multi-platform benefit and inherit all of this coupling.

Buildx against plain docker build, and against Bake

The honest comparison is Buildx versus docker build, because Buildx is that command extended rather than a separate tool. The README says docker buildx build supports what docker build supports, including outputs configuration, inline build caching and target platform selection, and adds manifest lists, distributed caching and OCI tarball export. So the difference is not a different mental model; it is a superset with a driver layer underneath.

Bake is the more interesting internal alternative. It is listed as a key feature and lives in its own bake/ directory with a docker-bake.hcl at the repository root. Where docker buildx build takes flags on the command line, Bake reads an HCL file describing targets, which is closer to how a repository with several images wants to describe its builds. The trade-off is that a Bake file is another artifact to keep in sync with your Dockerfiles, and for a single image it is more configuration than the build needs.

The Makefile in the repository shows the project using its own tool for its own release work: the BAKE_TARGETS list runs binaries, lint, validate-vendor, validate-docs and validate-authors through $(BUILDX_CMD) bake, and BUILDX_CMD resolves to docker buildx when the plugin is available. That is a fair signal that Bake is aimed at repositories with several build outputs rather than one.

Licence, maintenance and the upgrade path

Buildx is Apache-2.0. That permits commercial and private use with the usual obligations around notices and the licence text, but this is a description of the identifier, not legal advice; check the LICENSE file in the repository for the actual terms before relying on it.

The repository is not archived, and the last push was on 2026-09-21. Recent releases include v0.37.1 on 2026-09-11 and v0.37.0 on 2026-09-02, with a release candidate v0.37.0-rc2 on 2026-09-01. The release cadence means upgrade cost is mostly a question of which Docker engine and BuildKit versions you pair with the plugin, since those are pinned in the project's own Dockerfile rather than left floating.

Upgrading through the Docker Engine package repositories is the path the README recommends, and it is the one that keeps security updates flowing. If you installed manually, the README is explicit that you will not get those updates automatically, so the upgrade cost there is whatever process you build around the releases page. The README does not document a rollback procedure for a plugin upgrade, so plan for that before you need it.

Editorial conclusion

Adopt Buildx if you need multi-platform images, named builder instances or Bake files, and you control the Docker engine version on your build hosts. Skip it if your builds are single-platform and your CI already pins a working docker build path, because you would be adding a driver lifecycle to manage for no output change. Before rolling it out, run docker buildx version on each build host to confirm the plugin is present and check the engine version against the 19.03 minimum the README states, then run one image through docker buildx build and compare the result with your existing pipeline output.

Frequently asked questions

Official sources

1. docker/buildx on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases