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

In this blog I have added steps to build a Docker image for multiple architectures (amd64 , arm etc) using simple buildx method.

Why Build Multi Arch Docker Images?

Multi-architecture Docker images let your containerized apps run on different CPU types like x86_64, ARM64, and ARM32 without needing separate builds or deployments.

This is required in most projects becuase, modern Kubernetes environments span multiple architectures.

A classic example is AWS’s Karpenter-based scaling solution. Karpenter might automatically provision a mix of nodes. Around 70% ARM-based Graviton instances, which are more cost-effective, and 30% x86 instances to support legacy workloads.

Also, you might develop on an Intel/AMD Mac or PC (x86_64), deploy to ARM-based cloud instances (like AWS Graviton), or run on edge devices with ARM processors. Now, if your Kubernetes cluster has ARM-based worker nodes and you try deploying a pod using an image built only for amd64, it will fail to run.

Multi-arch images solve this by ensuring your app runs smoothly across all platforms, no matter the underlying architecture.

Arch Issue Example

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/v8 -> 64-bit ARM
• 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.

Other Supported Architectures

There are also other architectures that Docker supports. Below are the list of other architectures you can build using build.

• Linux/arm/v7 -> 32-bit ARM (older Raspberry Pi devices)
• linux/ppc64le -> 64-bit PowerPC Little Endian used in some systems in IBM.
• linux/s390x -> IBM Z and LinuxONE systems.
• windows/amd64 -> For 64-bit Windows systems.
• linux/riscv64 -> RISC-V 64-bit.