buildx

Docker CLI plugin for extended build capabilities with BuildKit

3,521

473

3,521

395

View on GitHub

Top Related Projects

buildkit

8,126

concurrent, cache-efficient, and Dockerfile-agnostic builder toolkit

kaniko

14,738

Build Container Images In Kubernetes

img

3,898

Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder.

buildah

7,358

A tool that facilitates building OCI images.

herokuish

1,450

Utility for emulating Heroku build and runtime tasks in containers

runc

11,985

CLI tool for spawning and running containers according to the OCI specification

Quick Overview

Docker Buildx is an official Docker CLI plugin that extends the Docker build capabilities. It provides support for new features like multi-platform builds, enhanced build cache, and advanced output options. Buildx is designed to improve the Docker build experience and offer more flexibility for developers.

Pros

Multi-platform build support, allowing creation of images for different architectures and operating systems
Enhanced caching mechanisms for faster and more efficient builds
Integration with Docker CLI, providing a seamless experience for existing Docker users
Support for advanced features like BuildKit and Dockerfile syntax enhancements

Cons

May require additional setup and configuration compared to standard Docker builds
Some advanced features might have a learning curve for new users
Potential compatibility issues with older Docker versions or certain build environments
Limited documentation for some of the more advanced features

Getting Started

To get started with Docker Buildx:

Ensure you have Docker installed (version 19.03 or later)
Install Buildx:
```
docker buildx create --use
```

Build a multi-platform image:

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t username/demo:latest .

Push the image to a registry:

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t username/demo:latest . --push

These commands create a Buildx builder instance, build a multi-platform image, and push it to a registry. Adjust the platforms and image name as needed for your project.

Competitor Comparisons

buildkit

8,126

concurrent, cache-efficient, and Dockerfile-agnostic builder toolkit

Pros of Buildkit

More flexible and extensible architecture
Better support for advanced caching strategies
Can be used independently of Docker

Cons of Buildkit

Steeper learning curve for beginners
Less integrated with Docker CLI out-of-the-box
Requires additional setup for some features

Code Comparison

Buildkit (using buildctl):

buildctl build \
    --frontend=dockerfile.v0 \
    --local context=. \
    --local dockerfile=. \
    --output type=image,name=myimage:latest,push=true

Buildx:

docker buildx build \
    --platform linux/amd64,linux/arm64 \
    -t myimage:latest \
    --push .

Buildkit provides a lower-level interface, offering more control but requiring more verbose commands. Buildx, built on top of Buildkit, provides a more user-friendly interface integrated with the Docker CLI, simplifying multi-platform builds and push operations.

Both projects aim to improve the container build process, with Buildkit focusing on flexibility and performance, while Buildx emphasizes ease of use and integration with existing Docker workflows. The choice between them depends on specific use cases and user preferences.

kaniko

14,738

Build Container Images In Kubernetes

Pros of kaniko

Runs without Docker daemon, making it suitable for containerized environments
Built-in support for caching layers in remote registries
Designed for security, running as non-root by default

Cons of kaniko

Slower build times compared to Buildx
Limited support for advanced Dockerfile features
Requires more setup and configuration for local development

Code Comparison

kaniko:

steps:
- name: 'gcr.io/kaniko-project/executor:latest'
  args:
  - --dockerfile=Dockerfile
  - --destination=gcr.io/project/image

Buildx:

- name: Build and push
  uses: docker/build-push-action@v2
  with:
    context: .
    file: ./Dockerfile
    push: true
    tags: user/app:latest

Both kaniko and Buildx are tools for building Docker images, but they serve different use cases. kaniko excels in containerized environments and offers enhanced security features, while Buildx provides faster builds and better integration with the Docker ecosystem. The choice between them depends on specific project requirements, build environment, and security considerations.

img

3,898

Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder.

Pros of img

Standalone tool, doesn't require Docker daemon
Supports unprivileged builds without root access
Faster builds due to efficient caching and parallelization

Cons of img

Less integrated with Docker ecosystem
May lack some advanced features of Buildx
Smaller community and fewer updates

Code Comparison

img:

img build -t myimage:latest .
img push myimage:latest

Buildx:

docker buildx build --platform linux/amd64,linux/arm64 -t myimage:latest .
docker buildx push myimage:latest

Summary

img is a lightweight, standalone tool for building Docker images without requiring the Docker daemon. It offers unprivileged builds and potentially faster performance. However, it may lack some advanced features and ecosystem integration compared to Buildx.

Buildx is more tightly integrated with the Docker ecosystem and offers advanced features like multi-platform builds. It has a larger community and more frequent updates but requires the Docker daemon to run.

Both tools aim to improve the Docker image building process, with img focusing on simplicity and independence, while Buildx emphasizes advanced features and ecosystem integration.

buildah

7,358

A tool that facilitates building OCI images.

Pros of Buildah

Rootless container builds without requiring a daemon
More flexible and granular control over image creation process
Can create images without a Dockerfile, allowing for more customization

Cons of Buildah

Steeper learning curve compared to Buildx
Less integrated with Docker ecosystem
May require additional tools for full container management

Code Comparison

Buildah:

buildah from fedora
buildah run fedora-working-container dnf install -y httpd
buildah commit fedora-working-container fedora-httpd
buildah push fedora-httpd docker://myregistry.example.com/fedora-httpd:latest

Buildx:

FROM fedora
RUN dnf install -y httpd

docker buildx build -t myregistry.example.com/fedora-httpd:latest .
docker push myregistry.example.com/fedora-httpd:latest

Buildah offers a more script-like approach to image creation, allowing for greater flexibility and control over the build process. Buildx, on the other hand, relies on Dockerfiles and provides a more streamlined, integrated experience within the Docker ecosystem. While Buildah excels in customization and rootless builds, Buildx offers easier adoption for those already familiar with Docker.

herokuish

1,450

Utility for emulating Heroku build and runtime tasks in containers

Pros of Herokuish

Simulates Heroku build environment, making it easier to test and debug Heroku-style applications locally
Supports multiple buildpacks out of the box, allowing for greater flexibility in application deployment
Provides a consistent environment for running apps across different platforms

Cons of Herokuish

Limited to Heroku-style applications, less versatile for general-purpose Docker builds
May introduce overhead due to the Heroku-like layer, potentially impacting performance
Less actively maintained compared to Buildx, with fewer recent updates and contributions

Code Comparison

Herokuish example:

docker run --rm -v /path/to/app:/tmp/app gliderlabs/herokuish /bin/herokuish buildpack build

Buildx example:

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

Key Differences

Herokuish focuses on replicating the Heroku environment for local development and testing, while Buildx is a more general-purpose tool for building and managing Docker images across multiple platforms. Buildx offers advanced features like multi-platform builds and build caching, making it more suitable for complex Docker workflows. Herokuish, on the other hand, excels in providing a familiar environment for Heroku developers working locally or in CI/CD pipelines.

runc

11,985

CLI tool for spawning and running containers according to the OCI specification

Pros of runc

Industry-standard low-level container runtime
Lightweight and focused on container execution
Widely adopted and supported across container ecosystems

Cons of runc

Limited to container runtime functionality
Requires additional tools for image building and management
Less user-friendly for developers new to containerization

Code Comparison

runc:

spec, err := loadSpec(context.Background(), specConfig)
if err != nil {
    return err
}
status, err := startContainer(context.Background(), spec, opts)

buildx:

b, err := builder.New(dockerCli, options...)
if err != nil {
    return err
}
response, err := b.Build(ctx, targets, options...)

Key Differences

runc focuses on container runtime execution
buildx specializes in multi-platform image building
runc is lower-level, while buildx offers higher-level abstractions
buildx integrates closely with Docker, while runc is more independent

Use Cases

Use runc for low-level container management and execution
Choose buildx for advanced Docker image building, especially for multi-architecture support

Community and Ecosystem

runc: Part of the Open Container Initiative (OCI)
buildx: Tightly integrated with the Docker ecosystem

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

buildx

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

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 build constructs (bake)
In-container driver support (both Docker and Kubernetes)

For more information on how to use Buildx, see Docker Build docs.

Installing

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

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

Linux packages

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

[!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:

OS	Binary name	Destination folder
Linux	`docker-buildx`	`$HOME/.docker/cli-plugins`
macOS	`docker-buildx`	`$HOME/.docker/cli-plugins`
Windows	`docker-buildx.exe`	`%USERPROFILE%\.docker\cli-plugins`

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

[!NOTE] On Unix environments, it may also be necessary to make it executable with chmod +x:
$ chmod +x ~/.docker/cli-plugins/docker-buildx

Dockerfile

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

Set buildx as the default builder

Running the command docker buildx install sets up docker builder command as an alias to docker buildx build. This results in the ability to have docker build use the current buildx builder.

To remove this alias, run docker buildx uninstall.

Building

# 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

Building with buildx

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 (guide, reference)
The docker-container driver (guide, reference)
The kubernetes driver (guide, reference)
The remote driver (guide)

For more information on drivers, see the drivers guide.

Working with builder instances

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 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.

Building multi-platform images

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:

Using the QEMU emulation support in the kernel
Building on multiple native nodes using the same builder instance
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.

High-level build options

See High-level builds with Bake for more details.

Contributing

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

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of Buildkit

Cons of Buildkit

Code Comparison

Pros of kaniko

Cons of kaniko

Code Comparison

Pros of img

Cons of img

Code Comparison

Summary

Pros of Buildah

Cons of Buildah

Code Comparison

Pros of Herokuish

Cons of Herokuish

Code Comparison

Key Differences

Pros of runc

Cons of runc

Code Comparison

Key Differences

Use Cases

Community and Ecosystem

Convert designs to code with AI

README

buildx

Table of Contents

Installing

Windows and macOS

Linux packages

Manual download

Dockerfile

Set buildx as the default builder

Building

Getting started

Building with buildx

Working with builder instances

Building multi-platform images

High-level build options

Contributing

Top Related Projects

Convert designs to code with AI