Repository files navigation

Buildx is a Docker CLI plugin for extended build capabilities withBuildKit.

• 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

Using Buildx with Docker requires Docker engine 19.03 or newer.

Docker Buildx is included inDocker Desktopfor Windows and macOS.

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

You can also download the latest binary from theGitHub 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:\ProgramData\Docker\cli-plugins
• C:\Program Files\Docker\cli-plugins

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

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

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

#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

Buildx is a Docker CLI plugin that extends thedocker build command with thefull support of the features provided byMoby BuildKitbuilder toolkit. It provides the same user experience asdocker build withmany new features like creating scoped builder instances and building againstmultiple nodes concurrently.

After installation, Buildx can be accessed through thedocker buildx commandwith Docker 19.03.docker buildx build is the command for starting a newbuild. With Docker versions older than 19.03 Buildx binary can be calleddirectly to access thedocker buildx subcommands.

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

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

Thedocker buildx build command supports features available fordocker build,including features such as outputs configuration, inline build caching, andspecifying target platform. In addition, Buildx also supports new features thatare not yet available for regulardocker 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 exposedthrough variousdrivers.Each driver defines how and where a build should run, and have differentfeature sets.

We currently support the following drivers:

• Thedocker driver (manual)
• Thedocker-container driver (manual)
• Thekubernetes driver (manual)
• Theremote driver (manual)

For more information, see thebuildersanddrivers guide.

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

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

You can create new instances using thedocker buildx createcommand. This creates a new builder instance with a single node based on yourcurrent configuration.

To use a remote node you can specify theDOCKER_HOST or the remote context namewhile creating the new builder. After creating a new instance, you can manage itslifecycle using thedocker buildx inspect,docker buildx stop, anddocker buildx rm commands. To list allavailable builders, usedocker buildx ls. Aftercreating a new builder you can also append new nodes to it.

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

Docker also features adocker contextcommand that can be used for giving names for remote Docker API endpoints.Buildx integrates withdocker context so that all of your contextsautomatically get a default builder instance. While creating a new builderinstance or when adding a node to it, you can also set the context name as thetarget.

BuildKit is designed to work well for building for multiple platforms and notonly for the architecture and operating system that the user invoking the buildhappens to run.

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

When the current builder instance is backed by thedocker-container orkubernetes 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 indocker runordocker service,Docker picks the correct image based on the node's platform.

You can build multi-platform images using three different strategies that aresupported 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 (forexample. if you are using Docker Desktop). It requires no changes to yourDockerfile and BuildKit automatically detects the secondary architectures thatare available. When BuildKit needs to run a binary for a different architecture,it automatically loads it through a binary registered in thebinfmt_mischandler.

For QEMU binaries registered withbinfmt_misc on the host OS to worktransparently inside containers they must be registered with thefix_binaryflag. This requires a kernel >= 4.8 and binfmt-support >= 2.1.7. You can checkfor proper registration by checking ifF is among the flags in/proc/sys/fs/binfmt_misc/qemu-*. While Docker Desktop comes preconfiguredwithbinfmt_misc support for additional platforms, for other installationsit likely needs to be installed usingtonistiigi/binfmtimage.

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

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

Assuming contextsnode-amd64 andnode-arm64 exist indocker context ls;

$docker buildx create --use --name mybuild node-amd64mybuild$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 goodsupport for cross-compilation. In that case, multi-stage builds in Dockerfilescan be effectively used to build binaries for the platform specified with--platform using the native architecture of the build node. A list of buildarguments likeBUILDPLATFORM andTARGETPLATFORM is available automaticallyinside your Dockerfile and can be leveraged by the processes running as partof your build.

# syntax=docker/dockerfile:1FROM --platform=$BUILDPLATFORM golang:alpine AS buildARG TARGETPLATFORMARG BUILDPLATFORMRUN echo"I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /logFROM alpineCOPY --from=build /log /log

You can also usetonistiigi/xx Dockerfilecross-compilation helpers for more advanced use-cases.

Want to contribute to Buildx? Awesome! You can find information aboutcontributing to this project in theCONTRIBUTING.md