How to Build Multi-Platform Image in Docker Easily

Use docker buildx build --platform to create multi-platform Docker images. This command lets you specify target platforms like linux/amd64 and linux/arm64 and build images that run on different hardware architectures.

Syntax

The basic syntax to build a multi-platform image is:

• docker buildx build: Uses the Buildx builder for advanced builds.
• --platform: Specifies one or more target platforms separated by commas.
• -t: Tags the image with a name.
• --push: Pushes the built image directly to a registry (optional but recommended for multi-platform images).
• .: The build context, usually the current directory.

bash

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

Example

This example builds and pushes a multi-platform image for linux/amd64 and linux/arm64 platforms using a simple Dockerfile.

bash

docker buildx create --use
cat <<EOF > Dockerfile
FROM alpine
CMD ["echo", "Hello from multi-platform image"]
EOF
docker buildx build --platform linux/amd64,linux/arm64 -t yourdockerhubusername/multiarch-example:latest --push .

Output

=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 94B
=> [internal] load .dockerignore
=> => transferring context: 2B
=> [internal] load metadata for docker.io/library/alpine:latest
=> [1/1] FROM docker.io/library/alpine:latest
=> exporting to image
=> => exporting layers
=> => writing image sha256:...
=> => naming to docker.io/yourdockerhubusername/multiarch-example:latest
Pushed yourdockerhubusername/multiarch-example:latest to registry

Common Pitfalls

• Not enabling Buildx: You must create and use a Buildx builder with docker buildx create --use before building multi-platform images.
• Forgetting to push: Multi-platform images require pushing to a registry to store all platform variants; local builds alone won't create a usable multi-platform image.
• Unsupported platforms: Make sure your Dockerfile and base images support the target platforms.
• Old Docker versions: Multi-platform builds require Docker 19.03 or newer with Buildx enabled.

bash

docker build -t myimage:latest .
# Wrong: This builds only for the current platform

docker buildx build --platform linux/amd64,linux/arm64 -t myimage:latest --push .
# Right: Builds and pushes multi-platform image

Quick Reference

Option	Description
docker buildx create --use	Create and switch to a Buildx builder for multi-platform builds
--platform	Specify target platforms like linux/amd64, linux/arm64
-t	Tag the image with a name
--push	Push the built image to a registry
.	Build context, usually current directory

Key Takeaways

Use Docker Buildx with --platform to build images for multiple architectures.

Always push multi-platform images to a registry to store all variants.

Create and use a Buildx builder before building multi-platform images.

Ensure your base images support the target platforms.

Docker version 19.03 or newer is required for multi-platform builds.