Docker & Kubernetes

Multi-Arch Docker Images (ARM + x86): Why and How

Home Blog Docker & Kubernetes

Docker & Kubernetes

"It works on my Mac but the server says exec format error." If you've seen that message, you've hit the multi-architecture problem. Here's why it happens and how to fix it for good.

Why architecture matters now

A container image contains compiled binaries for one CPU architecture. For years, almost everything was amd64 (x86-64), so nobody thought about it. That has changed:

  • Developer laptops on Apple Silicon are arm64.
  • ARM cloud servers (AWS Graviton, Azure Cobalt, Google Axion, Ampere-based instances) often cost noticeably less for the same performance.
  • Production servers in many data centres, including many on-premise and government environments, are still amd64.

An image built on a Mac won't run natively on an x86 server, and the other way round.

The solution: multi-arch manifests

A multi-arch image is really a manifest list: one tag (myapp:2.3.0) that points to several images, one per architecture. When a machine pulls the tag, it automatically receives the variant that matches its CPU.

Building with docker buildx

# one-time: create a builder that supports multiple platforms
docker buildx create --name multi --use

# build for both architectures and push in one step
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:2.3.0 \
  --push .

Multi-arch builds must be pushed to a registry (or exported), because your local Docker image store traditionally holds one architecture per tag.

Making builds fast

Building for a foreign architecture uses QEMU emulation, which can be slow, especially for Python packages that compile C extensions. Ways to speed it up:

  • Use slim official base images such as python:3.12-slim, which already publish both architectures.
  • Prefer pre-built wheels. Most popular Python packages now ship aarch64 wheels, so nothing needs compiling.
  • Use build caching (--cache-from/--cache-to) in CI.
  • Use native builders for each architecture (an ARM CI runner plus an x86 runner) for large projects. Buildx can combine them.

In CI/CD

GitHub Actions, GitLab CI and most other CI systems support buildx with QEMU out of the box. A typical pipeline:

  1. Set up QEMU and buildx.
  2. Log in to the registry (Docker Hub, Harbor, ECR, GCR and so on).
  3. Build for linux/amd64,linux/arm64 with a version tag, and optionally a moving tag such as stable.
  4. Push, then update your deployment manifests to the new version.

Pitfalls to watch for

  • Architecture-specific downloads in your Dockerfile, for example curl-ing an amd64 binary. Use the TARGETARCH build argument to pick the right one.
  • Old base images that only publish amd64.
  • Testing only one architecture. Run at least a smoke test on both.

Verify what you pushed

docker buildx imagetools inspect registry.example.com/myapp:2.3.0

This lists every platform the tag supports. Check it before you deploy.

We use multi-arch builds as standard on our client projects, including frontend and backend images for government platforms. Need a hand with your container pipeline? Get in touch.