Skip to content
BSWEN
Blog

How to Build and Run Multi-Platform Container Images on Apple Silicon with Rosetta

Cowrie
Cowrie
Dev @ Bswen

Problem

My MacBook Pro runs on Apple Silicon (arm64). But the production servers where I deploy containers are x86_64 (amd64). Building on my Mac and finding out only at deployment that an image has architecture-specific bugs wastes time.

I needed a way to build multi-platform images locally and test both architectures before pushing.

How Apple container Handles Multi-Arch

Apple container’s builder VM has Rosetta 2 support enabled by default. This means the build process can translate x86_64 instructions on the fly, so I can build amd64 images on my arm64 Mac without a separate emulation setup.

Diagram showing Apple Silicon arm64 host running x86_64 binaries through Rosetta 2 translation layer inside the container builder VM

Building a Multi-Platform Image

Build an image for both architectures in one command:

Build a multi-arch image
container build \
  --arch arm64 --arch amd64 \
  --tag my-image:latest \
  --file Dockerfile .

This produces an OCI image manifest that lists both architectures. Push it to any standard registry:

Push the multi-arch image
container image push registry.example.com/my-image:latest

Testing Both Architectures

I can test the arm64 variant natively:

Run arm64 variant
container run --arch arm64 --rm my-image uname -a

Output:

arm64 output
Linux 6.1.0 #1 SMP Fri Jun 12 09:50:20 CST 2026 aarch64 Linux

And the amd64 variant under Rosetta:

Run amd64 variant under Rosetta
container run --arch amd64 --rm my-image uname -a

Output:

amd64 (Rosetta) output
Linux 6.1.0 #1 SMP Fri Jun 12 09:50:20 CST 2026 x86_64 GNU/Linux

Both variants come from the same image. This makes it easy to catch architecture-specific issues during local development.

Disabling Rosetta

If I want to force native-only builds and disable x86_64 emulation entirely:

~/.config/container/config.toml
[build]
rosetta = false

By default it is true, which is what most developers want.

Real Workflow

Full multi-platform workflow
# 1. Build for both architectures
container build --arch arm64 --arch amd64 -t web-app:v1 .


# 2. Test arm64
container run --arch arm64 --rm web-app:v1 python -c "import platform; print(platform.machine())"


# 3. Test amd64
container run --arch amd64 --rm web-app:v1 python -c "import platform; print(platform.machine())"


# 4. Push the multi-arch manifest
container image push registry.example.com/web-app:v1


# 5. Deploy on production x86 servers — it works

Pipeline diagram showing five steps: build multi-arch image, test arm64 variant, test amd64 variant under Rosetta, push multi-arch manifest to registry, deploy on production x86 servers

Summary

In this post, I showed how to build multi-platform container images on Apple Silicon using Apple container’s built-in Rosetta support. The key point is that a single container build --arch arm64 --arch amd64 creates an OCI image that runs natively on arm64 and under Rosetta on amd64 — no separate emulation VMs needed.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: