How to Build Multi Architecture Docker Images (ARM, x86, etc.)

I had a use case to create a Docker image that supports multiple architectures. In this blog I have added steps to build the image for multiple architectures (amd64 , arm etc) using simple buildx method.

Issue

If you try to pull the Docker image that doesn't support all architectures, you will get the following error.

➜ docker pull techiescamp/hey:latest

latest: Pulling from techiescamp/hey
no matching manifest for linux/arm64/v8 in the manifest list entries

This happens because the image is built for only one architecture, which is the architecture of the machine that builds the image.

To solve this issue we can build a Docker image that can supports multiple architecture.

Building Multi-Architecture Docker Image Using buildx

To build a multi-architecture image, you need to use a Docker tool called buildx.

You don't have to install Buildx separately, it comes with the latest version of Docker Engine on MAC and Windows, and in Linux it comes with the latest Docker CLI version.

Create a Dockerfile and run the following command to build and push the multi-architecture support image.

docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v8 \
  -t techiescamp/hey:latest \
  --push .

Command Explanation:

• The platform flag, specify the architecture you want to build the image.
• In the above command I have given three architectures:
  • Linux/amd64 -> 64-bit Intel/AMD (x86_64)
  • Linux/arm64 -> 64-bit ARM (Apple M1/M2, AWS Graviton)
  • Linux/arm/v7 -> 32-bit ARM (older Raspberry Pi devices)
• Then on the -t flag you have to specify the image name and tag.
• The push flag pushes the image after building it.

I have built and pushed my image to Docker Hub.

It shows all the supported OS/architectures as shown below.