DockerHow-ToBeginner · 3 min read

How to Use Docker Buildx for Multi-Platform Builds

Use docker buildx to build Docker images with extended features like multi-platform support by running docker buildx build. First, create and use a builder instance with docker buildx create --use, then build images with docker buildx build --platform to specify target platforms.

📐

Syntax

The basic syntax for using docker buildx is:

docker buildx create [OPTIONS]: Create a new builder instance.
docker buildx use [NAME]: Switch to a specific builder instance.
docker buildx build [OPTIONS] PATH: Build an image using Buildx with options like --platform to specify target platforms.

This lets you build images for different CPU architectures and push them to registries.

bash

docker buildx create --name mybuilder --use
docker buildx build --platform linux/amd64,linux/arm64 -t username/myimage:tag .

💻

Example

This example shows how to create a builder, build a multi-platform image for amd64 and arm64, and push it to Docker Hub.

bash

docker buildx create --name mybuilder --use
# Build and push multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 -t username/myimage:latest --push .

Output

Creating builder instance 'mybuilder'... Building [linux/amd64, linux/arm64]... [+] Building 10.0s (10/10) FINISHED => exporting to image => pushing layers => pushing manifest for username/myimage:latest Successfully pushed username/myimage:latest

⚠️

Common Pitfalls

Common mistakes when using docker buildx include:

Not creating or switching to a builder instance before building, causing errors.
Forgetting to use --push to upload multi-platform images to a registry.
Not specifying --platform, which builds only for the current platform.
Using docker build instead of docker buildx build for multi-platform builds.

Always ensure your Docker version supports Buildx (Docker 19.03+).

bash

docker buildx build -t username/myimage:latest .
# This builds only for the current platform and does not push.

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

📊

Quick Reference

Command	Description
docker buildx create --name NAME --use	Create and switch to a new builder instance
docker buildx ls	List all builder instances
docker buildx build --platform PLATFORMS -t IMAGE --push PATH	Build multi-platform image and push to registry
docker buildx inspect	Show builder info and capabilities
docker buildx rm NAME	Remove a builder instance

✅

Key Takeaways

Create and use a builder instance before building with Buildx.

Use --platform to specify target architectures for multi-platform images.

Add --push to upload images to a registry after building.

Docker Buildx requires Docker 19.03 or newer.

Use docker buildx build instead of docker build for advanced builds.