"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
aarch64wheels, 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:
- Set up QEMU and buildx.
- Log in to the registry (Docker Hub, Harbor, ECR, GCR and so on).
- Build for
linux/amd64,linux/arm64with a version tag, and optionally a moving tag such asstable. - 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 theTARGETARCHbuild 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.