Building Docker Images for Multiple Architectures

Aug 26, 2025

4min read

Building Docker Images for Multiple Architectures

Applications can run on different types of processors, Intel/AMD servers (x86_64), ARM devices (Raspberry Pi, ARM servers), and Apple Silicon chips (M1/M2/M3). Building Docker images that work on all these architectures will allow you to deploy your application on any infrastructure without compatibility issues.

Most Common Architectures:

linux/amd64 (x86_64): Traditional servers, VPS, most cloud infrastructure.
linux/arm64 (aarch64): ARM servers, Raspberry Pi 4+.

1. Prepare Your Environment

1.1 Verify Docker Buildx

Docker Buildx is a tool that extends Docker build capabilities, it's already included in Docker Desktop and Docker Engine in the latest versions:

docker buildx version

After executing this command, you should see the buildx version.

screenshot of executing the docker buildx version command

Execution of the "docker buildx version" command

1.2 Create a Multi-Architecture Builder

# Create and use a new builder
sudo docker buildx create --name multiarch-builder --use --bootstrap

# Verify capabilities
sudo docker buildx inspect multiarch-builder

In multiarch-builder you can put any name you want.

screenshot of executing the sudo docker buildx create --name multiarch-builder --use --bootstrap command

Execution of the "sudo docker buildx create --name multiarch-builder --use --bootstrap" command

2. Build a Multi-Architecture Image

2.1 Base Dockerfile

This is an example of any Dockerfile.

FROM alpine:latest
RUN apk add --no-cache curl
COPY app.sh /app.sh
RUN chmod +x /app.sh
CMD ["/app.sh"]

2.2 Image Construction

With the following Docker command you can create an image that works on different CPU architectures, in this case for amd64 and arm64.

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t your-user/my-app:latest \
  . \
  --push

Command breakdown:

--platform: Comma-separated list of architectures.
-t: Image tag.
--push: Automatically uploads to registry (mandatory for multi-arch).

Graphic explaining how multi-arch image works with Docker buildx

Illustration showing in general how buildx works

3. Test on Different Architectures

This is a very useful command you should know to select which architecture to run the image with.

# Force specific architecture
docker run --platform linux/arm64 your-user/my-app:latest

You can also decide this in docker-compose with the platform:

services:
  app:
    image: your-user/my-app:latest
    platform: linux/arm64

Conclusion

Building multi-architecture Docker images is essential in today's ecosystem, where your applications can run on very diverse infrastructures. With Docker Buildx and the techniques shown in this tutorial, you can deploy on any architecture without modifying code and take advantage of more economical ARM servers.

byandrev