Docker Buildx

Docker hub

A Docker CLI plugin that extends docker build with BuildKit features including multi-platform image building, advanced cache management, and parallel builds. Buildx enables building images for linux/amd64, linux/arm64, and other architectures from a single machine.

Docker Buildx — Advanced Building With Multi-Platform Support

What Is Docker Buildx in Simple Terms?

Buildx is the advanced Docker build tool that exposes all BuildKit features through the CLI. The most useful feature is multi-platform building — you can build an image for both x86 (Intel/AMD) and ARM64 (Apple M1/M2, AWS Graviton) from a single command on a single machine, and Docker publishes a manifest that automatically serves the right architecture to each platform.

Bash

# Regular docker build — one platform
docker build -t payment-api:v3.1.0 .
# Builds for your current machine's architecture only
 
# Docker buildx — multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.razorpay.in/payment-api:v3.1.0 \
  --push .
# Builds for both architectures
# Pushes a manifest list that serves the right image per platform
# AWS Graviton instances automatically get the arm64 image
# Standard x86 servers automatically get the amd64 image

Setting Up Buildx

Bash

# buildx is included with Docker Desktop and Docker Engine 20.10+
docker buildx version
# github.com/docker/buildx v0.12.0
 
# Create a new builder (for multi-platform support)
docker buildx create \
  --name multiarch-builder \
  --driver docker-container \
  --use
 
# Inspect the builder
docker buildx inspect --bootstrap
# Shows: supported platforms: linux/amd64, linux/arm64, linux/arm/v7...
 
# List all builders
docker buildx ls
 
# Use a specific builder
docker buildx use multiarch-builder

Multi-Platform Build in GitHub Actions

YAML

- name: Set up QEMU (for cross-platform emulation)
  uses: docker/setup-qemu-action@v3
 
- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
 
- name: Build and push multi-platform
  uses: docker/build-push-action@v5
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: registry.razorpay.in/payment-api:v3.1.0
    cache-from: type=gha
    cache-to: type=gha,mode=max

BuildKit Features Through Buildx

Bash

# Secret mounts
docker buildx build \
  --secret id=github_token,src=$HOME/.secrets/github-token \
  -t myapp:latest .
 
# SSH mounts for private repos
docker buildx build \
  --ssh default=$SSH_AUTH_SOCK \
  -t myapp:latest .
 
# Registry cache export
docker buildx build \
  --cache-from type=registry,ref=registry.razorpay.in/payment-api:cache \
  --cache-to type=registry,ref=registry.razorpay.in/payment-api:cache,mode=max \
  -t registry.razorpay.in/payment-api:v3.1.0 \
  --push .
 
# Bake — build multiple images in parallel from a config file
docker buildx bake
# Uses docker-bake.hcl or docker-compose.yml to define build targets

Tip
Always use docker buildx build in CI/CD pipelines instead of docker build. Buildx gives you better cache support (cache-from/cache-to with registry), multi-platform capability when needed, and all BuildKit features like secret mounts. The commands are nearly identical — just add buildx after docker.

Frequently Asked Questions

Why do you need Buildx specifically for multi-architecture images?

A single `docker build` produces an image for the architecture of the machine running it — an M-series Mac produces arm64, a typical CI runner produces amd64. Buildx uses BuildKit's support for QEMU emulation and remote builder nodes to compile the same Dockerfile for multiple platforms in one command and push them under a single manifest list, so `docker pull myimage` automatically resolves to the right architecture for whoever's pulling it.

What's the practical downside of cross-platform Buildx builds via QEMU emulation?

Emulated builds (e.g. building arm64 on an amd64 CI runner) are significantly slower than native builds — often 5-10x — because every instruction is translated in software rather than run on real hardware. For CI pipelines building for multiple architectures regularly, using native runners per architecture (or a remote builder farm) instead of emulation is usually worth the added complexity once build times start hurting deploy velocity.