How to build docker image for ARM64 CPU architecture

By default (using the default docker builder), you can only build images for a single platform at a time and for the docker host architecture only:

ERROR: Multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")

But Docker also allows you to build the images for the:

target architecture other than the architecture of the machine where the build runs (i.e. docker host), e.g. to build the image for ARM64 on the machine with AMD64 architecture,
multiple platforms, which means that a single image may contain variants for different architectures, e.g. ARM64 and AMD64 (X86_64).

Single-platform image

1. Install GEMU emulator (to enable an execution of different multi-architecture containers):

sudo apt-get install -y qemu qemu-user-static

2. Verify that arm architecture was properly added:

docker buildx ls

3. Build an image for the target architecture by specifying the –platform flag:

docker build --platform linux/amd64 -t <IMAGE-URI> -f Dockerfile .

You can also use the buildx plugin:

docker buildx build --platform linux/amd64 -t <IMAGE-URI> -f Dockerfile .

Multi-platform image

1. To build for multiple platforms at once, create a new builder that uses the docker-container driver. When using docker-container driver with buildx, –-platform flag can accept multiple values as an input separated by a comma. With multiple values the result will be built for all of the specified platforms and joined together into a single manifest list.

2. Assuming you have installed and added support for the target architecture (e.g. ARM64), you can now initiate builder, as you cannot use docker driver directly to build for multiple platforms simultaneously. Create a new builder using the docker-container driver which gives you access to more complex features like multi-platform builds:

docker buildx create --name <BUILDER-NAME> --bootstrap --use

Build the image with buildx, passing the list of architectures (linux/amd64 and linux/arm64) to build for:

docker buildx build --platform linux/amd64,linux/arm64 --push -t <IMAGE-URI> -f Dockerfile .

ATTENTION! You have to explicitly specify the the output (–load for local or –push for remote, respectively) for the docker build, otherwise the following error is raised:

WARNING: No output specified with docker-container driver. Build result will only remain in the build cache. To push result image into registry use --push or to load image into docker use --load

ATTENTION! It is not possible to push a multi-platform image to a docker engine, otherwise the following error is raised:

ERROR: docker exporter does not currently support exporting manifest lists

Instead all images in the engine are single platform, and you push the multi-platform image directly to the selected registry.
So finally, the multi-platform image cannot be pushed to a docker engine (–load does not work) but directly to the selected registry so that –push must be specified explicitly.

3. inspect the image to verify all is done properly:

docker buildx imagetools inspect <IMAGE-URI>

That’s all, thank you for your attention.