Building Multi-Platform Images with Docker Buildx

By default, x86_64 platforms can only build x86_64 images. If you need to build multi-platform images (such as ARM64) on an x86_64 platform, you can use the Docker official Buildx tool to complete multi-platform image building.

Install Docker Buildx

The latest version of the Docker client already includes the Buildx plugin by default, so separate installation is usually not required. You can run the command docker buildx version to check the plugin version. If it returns correctly, the Buildx plugin is built-in.

Initialization

To enable this feature, perform the following initialization:

# Create a new Buildx builder instance
docker buildx create --name multiarch --driver docker-container --bootstrap
# Switch to the specified Buildx builder instance
docker buildx use multiarch
# Display detailed information about the Buildx builder
docker buildx inspect --bootstrap

Build Multi-Platform Images

After installation and enabling, you can use Docker Buildx to build multi-platform images. For example, the original build command is:

build -t ${IMAGE_NAME}:${VERSION} .

The Docker Buildx build command is:

docker buildx build --platform linux/amd64,linux/arm64 -t ${IMAGE_NAME}:${VERSION} . --push

• --platform: Specifies the target platforms, such as linux/amd64, linux/arm64, or darwin/amd64.
• --push: Automatically pushes the image to the Docker Hub repository after building.

After building, you can check the image tag to see that it supports multiple platforms.

If your image supports multiple platforms, pulling the image will automatically download the image corresponding to your platform.

Summary

• The latest version of Docker includes the Buildx plugin by default, so no separate installation is needed.
• Docker Buildx needs to be initialized before use.
• When building images with Docker Buildx, it is recommended to add the --push parameter; otherwise, the image will not appear in docker images. The specific reason is unclear.

This article references the following content:

• Docker Buildx