World map

 

BM

World D2: Recipes

amd64 or arm64? buildx

You will learn: why a pack can fail on another CPU, and how buildx bakes for two at once.

Checked with Docker Engine 29 on 31 Oct 2026

The problem

bash
docker run --rm --platform linux/arm64 hello:1.0
exec /bin/cat: exec format error

Aina baked the pack on her Mac with an Apple chip. The server has an Intel chip. It stops at once. Real error: exec format error. Plain words: cooked for another kind of CPU.

Try it

Every image is built for one platform: The OS and CPU type an image is built for, like linux/amd64 or linux/arm64.: an OS plus a CPU type. Which CPU does each machine have?

Drag a card into a box. Or tap the card, then tap the box.

      Watch

      bash
      docker buildx build --platform linux/amd64,linux/arm64 -t hello:1.0 .
      [+] Building 1.9s (10/10) FINISHED docker:default
      => [linux/amd64 1/2] FROM docker.io/library/alpine:3.22@sha256:2e0b81d60 0.3s
      => [linux/arm64 1/2] FROM docker.io/library/alpine:3.22@sha256:2e0b81d60 0.4s
      => [linux/amd64 2/2] COPY hello.txt /hello.txt 0.0s
      => [linux/arm64 2/2] COPY hello.txt /hello.txt 0.0s
      => exporting to image 0.2s

      buildx bakes for two platforms in one go. Each step runs twice, once per CPU. Both packs share one name.

      Try it

      Build the command that bakes hello:1.0 for both CPU families.

      Tap the pieces in the right order.

      …

      Predict

      hello:1.0 now has two packs inside. A Raspberry Pi pulls it. What does it get?

      Check

      bash
      docker images --tree hello
      IMAGE ID DISK USAGE CONTENT SIZE EXTRA
      hello:1.0 31ab2ae30f0b 16.9MB 7.93MB
      ├─ linux/amd64 7ce15f9d7cf4 12.8MB 3.8MB
      └─ linux/arm64 7c100815fc45 4.13MB 4.13MB

      docker images --tree shows one name with two packs inside. That list is called an image index.

      Try it

      Your practice laptop is amd64. Build for it on purpose as hello:amd64, then run it.

      Your laptop~/hello

      • No open hatches

      Lunchboxes (containers)

      • No containers yet

      Frozen packs (images)

      • alpine:3.221 layers · 12.9MB

      You did it!

      You can now build images for amd64 and arm64.

      Go deeper (optional)

      To run steps for another CPU, Docker can use an emulator called QEMU. It is slow, so big teams often build each platform on its own machine.

      Where the story breaks: a cook gets the same cake from the same recipe. A Dockerfile may not. RUN apk add curl can fetch a newer curl next month. Pin versions to keep the taste.

      Real mission

      1. docker version --format "{{.Server.Arch}}"
      2. docker buildx build --platform linux/amd64,linux/arm64 -t hello:1.0 .
      3. docker images --tree hello

      0 of 3 steps done · Your ticks are saved.