buildx Documentation

1. Project Overview & Quickstart (docker/buildx) Copy Chapter

Buildx

Buildx is a Docker CLI plugin for extended build capabilities with
BuildKit.

[!TIP]
Key features

• Familiar UI from docker build
• Full BuildKit capabilities with container driver
• Multiple builder instance support
• Multi-node builds for cross-platform images
• Compose build support
• High-level builds with Bake
• In-container driver support (both Docker and Kubernetes)

• Installing
  • Windows and macOS
  • Linux packages
  • Manual download
  • Dockerfile
• Building
• Getting started
  • Building with Buildx
  • Working with builder instances
  • Building multi-platform images
• Reference
• Contributing

Installing Copy Chapter

Using Buildx with Docker requires Docker engine 19.03 or newer.

[!WARNING]
Using an incompatible version of Docker may result in unexpected behavior,
and will likely cause issues, especially when using Buildx builders with more
recent versions of BuildKit.

Windows and macOS Copy Section

Docker Buildx is included in Docker Desktop
for Windows and macOS.

Linux packages Copy Section

Docker Engine package repositories contain Docker Buildx packages when installed according to the
Docker Engine install documentation. Install the
docker-buildx-plugin package to install the Buildx plugin.

Manual download Copy Section

[!IMPORTANT]
This section is for unattended installation of the Buildx component. These
instructions are mostly suitable for testing purposes. We do not recommend
installing Buildx using manual download in production environments as they
will not be updated automatically with security updates.

On Windows and macOS, we recommend that you install Docker Desktop
instead. For Linux, we recommend that you follow the instructions specific for your distribution.

You can also download the latest binary from the GitHub releases page.

Rename the relevant binary and copy it to the destination matching your OS:

Or copy it into one of these folders for installing it system-wide.

On Unix environments:

• /usr/local/lib/docker/cli-plugins OR /usr/local/libexec/docker/cli-plugins
• /usr/lib/docker/cli-plugins OR /usr/libexec/docker/cli-plugins

On Windows:

• C:\Program Files\Docker\cli-plugins
• C:\ProgramData\Docker\cli-plugins (for docker 28.x and earlier only)

[!NOTE]
On Unix environments, it may also be necessary to make it executable with chmod +x:

shell Copy

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

Dockerfile Copy Section

Here is how to install and use Buildx inside a Dockerfile through the
docker/buildx-bin image:

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

Building Copy Chapter

# Buildx 0.6+
$ docker buildx bake "https://github.com/docker/buildx.git"
$ mkdir -p ~/.docker/cli-plugins
$ mv ./bin/build/buildx ~/.docker/cli-plugins/docker-buildx

# Docker 19.03+
$ DOCKER_BUILDKIT=1 docker build --platform=local -o . "https://github.com/docker/buildx.git"
$ mkdir -p ~/.docker/cli-plugins
$ mv buildx ~/.docker/cli-plugins/docker-buildx

# Local
$ git clone https://github.com/docker/buildx.git && cd buildx
$ make install

Getting started Copy Chapter

Building with Buildx Copy Section

Buildx is a Docker CLI plugin that extends the docker build command with the
full support of the features provided by Moby BuildKit
builder toolkit. It provides the same user experience as docker build with
many new features like creating scoped builder instances and building against
multiple nodes concurrently.

After installation, Buildx can be accessed through the docker buildx command
with Docker 19.03. docker buildx build is the command for starting a new
build. With Docker versions older than 19.03 Buildx binary can be called
directly to access the docker buildx subcommands.

$ docker buildx build .
[+] Building 8.4s (23/32)
 => ...

Buildx will always build using the BuildKit engine and does not require
DOCKER_BUILDKIT=1 environment variable for starting builds.

The docker buildx build command supports features available for docker build,
including features such as outputs configuration, inline build caching, and
specifying target platform. In addition, Buildx also supports new features that
are not yet available for regular docker build like building manifest lists,
distributed caching, and exporting build results to OCI image tarballs.

Buildx is flexible and can be run in different configurations that are exposed
through various drivers.
Each driver defines how and where a build should run, and have different
feature sets.

We currently support the following drivers:

• The docker driver (manual)
• The docker-container driver (manual)
• The kubernetes driver (manual)
• The remote driver (manual)

For more information, see the builders
and drivers guide.

[!NOTE]
For more information, see Docker Build docs.

Working with builder instances Copy Section

By default, Buildx will initially use the docker driver if it is supported,
providing a very similar user experience to the native docker build. Note that
you must use a local shared daemon to build your applications.

Buildx allows you to create new instances of isolated builders. This can be
used for getting a scoped environment for your CI builds that does not change
the state of the shared daemon or for isolating the builds for different
projects. You can create a new instance for a set of remote nodes, forming a
build farm, and quickly switch between them.

You can create new instances using the docker buildx create
command. This creates a new builder instance with a single node based on your
current configuration.

To use a remote node you can specify the DOCKER_HOST or the remote context name
while creating the new builder. After creating a new instance, you can manage its
lifecycle using the docker buildx inspect,
docker buildx stop, and
docker buildx rm commands. To list all
available builders, use docker buildx ls. After
creating a new builder you can also append new nodes to it.

To switch between different builders, use docker buildx use <name>.
After running this command, the build commands will automatically use this
builder.

Docker also features a docker context
command that can be used for giving names for remote Docker API endpoints.
Buildx integrates with docker context so that all of your contexts
automatically get a default builder instance. While creating a new builder
instance or when adding a node to it, you can also set the context name as the
target.

[!NOTE]
For more information, see Builders docs.

Building multi-platform images Copy Section

BuildKit is designed to work well for building for multiple platforms and not
only for the architecture and operating system that the user invoking the build
happens to run.

When you invoke a build, you can set the --platform flag to specify the target
platform for the build output, (for example, linux/amd64, linux/arm64, or
darwin/amd64).

When the current builder instance is backed by the docker-container or
kubernetes driver, you can specify multiple platforms together. In this case,
it builds a manifest list which contains images for all specified architectures.
When you use this image in docker run
or docker service,
Docker picks the correct image based on the node's platform.

You can build multi-platform images using three different strategies that are
supported by Buildx and Dockerfiles:

1. Using the QEMU emulation support in the kernel
2. Building on multiple native nodes using the same builder instance
3. Using a stage in Dockerfile to cross-compile to different architectures

QEMU is the easiest way to get started if your node already supports it (for
example. if you are using Docker Desktop). It requires no changes to your
Dockerfile and BuildKit automatically detects the secondary architectures that
are available. When BuildKit needs to run a binary for a different architecture,
it automatically loads it through a binary registered in the binfmt_misc
handler.

For QEMU binaries registered with binfmt_misc on the host OS to work
transparently inside containers they must be registered with the fix_binary
flag. This requires a kernel >= 4.8 and binfmt-support >= 2.1.7. You can check
for proper registration by checking if F is among the flags in
/proc/sys/fs/binfmt_misc/qemu-*. While Docker Desktop comes preconfigured
with binfmt_misc support for additional platforms, for other installations
it likely needs to be installed using tonistiigi/binfmt
image.

$ docker run --privileged --rm tonistiigi/binfmt --install all

Using multiple native nodes provide better support for more complicated cases
that are not handled by QEMU and generally have better performance. You can
add additional nodes to the builder instance using the --append flag.

Assuming contexts node-amd64 and node-arm64 exist in docker context ls;

$ docker buildx create --use --name mybuild node-amd64
mybuild
$ docker buildx create --append --name mybuild node-arm64
$ docker buildx build --platform linux/amd64,linux/arm64 .

Finally, depending on your project, the language that you use may have good
support for cross-compilation. In that case, multi-stage builds in Dockerfiles
can be effectively used to build binaries for the platform specified with
--platform using the native architecture of the build node. A list of build
arguments like BUILDPLATFORM and TARGETPLATFORM is available automatically
inside your Dockerfile and can be leveraged by the processes running as part
of your build.

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log
FROM alpine
COPY --from=build /log /log

You can also use tonistiigi/xx Dockerfile
cross-compilation helpers for more advanced use-cases.

[!NOTE]
For more information, see Multi-platform builds docs.

Contributing Copy Chapter

Want to contribute to Buildx? Awesome! You can find information about
contributing to this project in the CONTRIBUTING.md

2. Official Technical Reference & Guides (docker/docs) Copy Chapter

Docs @ Docker

Welcome to the Docker Documentation repository. This is the source for the Docker Docs Website.

Feel free to open pull requests or issues. Our docs are completely open source, and we deeply appreciate contributions from the Docker community!

Provide feedback Copy Chapter

We’d love to hear your feedback! To submit feedback:

• Click New issue on the docs repository, or
• Click Request changes in the right column of every page on
  docs.docker.com, or
• Click Give feedback on every page in the docs.

To get community support, use the Docker Community Slack. Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See Docker
Pricing for details.

If you have an idea for a new feature or behavior change in a specific aspect of
Docker or have found a product bug, file an issue in the project's
repository.

Contribute to Docker docs Copy Chapter

We welcome contributions! To get started:

• CONTRIBUTING.md - Contribution workflow and setup
• STYLE.md - Writing style and content guidelines
• COMPONENTS.md - Component and shortcode usage

Copyright and license Copy Chapter

Copyright 2013-2026 Docker, Inc., released under the Apache 2.0 license.