What is a multi-platform image and how does it work?

A multi-platform image is a tag that points to an image index (the OCI term; Docker's older format calls it a manifest list) instead of a single image manifest. The index lists one manifest per OS/architecture pair, and each entry is labelled with its platform, such as linux/amd64 or linux/arm64. Each manifest then references that variant's config and layers.

  • myapp:1.4 (tag)
    • image index
      • manifest linux/amd64 → config + layers
      • manifest linux/arm64 → config + layers

When a client pulls the tag, the registry returns the index. The client reads the platform entries, picks the one that matches the host, and fetches only that manifest and its layers. An arm64 host and an x86 host can pull the same tag and run different binaries.

A tag points to exactly one object, which is why pushing two single-arch builds under the same name does not produce a multi-platform image. If you push an amd64 build to myapp:1.4 and then push an arm64 build to the same tag, the second push repoints the tag. The amd64 image is no longer referenced by the tag. The index has to be created in one build or assembled explicitly afterwards.

Buildx is the CLI front end, and BuildKit is the engine that does the work. The classic builder cannot produce an index at all. The default docker driver writes into the local image store, and that store can only hold an index when it is backed by containerd. The portable option is a dedicated builder that uses the docker-container driver. You create it with docker buildx create and select it with docker buildx use. Run docker buildx ls to list your builders and the platforms each one can target.

# 1. Create a dedicated builder that runs BuildKit in a container.
#    The docker-container driver can export an image index without
#    depending on a containerd-backed local image store.
docker buildx create --name multiarch --driver docker-container
docker buildx use multiarch

# Start the builder so it reports what it can target.
docker buildx inspect --bootstrap

# 2. List builders. The PLATFORMS column shows the targets each one
#    supports. Non-native targets such as linux/arm64 on an x86 host
#    show up only when emulation or a native node is available.
docker buildx ls

# 3. Build both variants in one invocation. BuildKit pushes one
#    manifest per platform plus an index that lists them under one tag.
#    --push is used because the result goes straight to the registry.
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/team/myapp:1.4 \
  --push .

# 4. Inspect the tag. The output should show an index (manifest list)
#    with a separate entry for linux/amd64 and for linux/arm64.
docker buildx imagetools inspect registry.example.com/team/myapp:1.4

# Anti-pattern: pushing separate single-arch builds to the SAME tag.
# The second push repoints the tag, so only arm64 remains referenced.
#   docker buildx build --platform linux/amd64 -t registry.example.com/team/myapp:1.4 --push .
#   docker buildx build --platform linux/arm64 -t registry.example.com/team/myapp:1.4 --push .

# Correct alternative: push each variant to its own tag, then assemble
# an index that references both under the shared tag.
docker buildx imagetools create \
  -t registry.example.com/team/myapp:1.4 \
  registry.example.com/team/myapp:1.4-amd64 \
  registry.example.com/team/myapp:1.4-arm64

Creating a docker-container builder, checking its supported platforms, building and pushing a single image index for amd64 and arm64, and assembling an index from separately pushed single-arch tags instead of overwriting one tag.

How do you build arm64 images with QEMU emulation?

Emulation is the fastest way to a working pipeline because the Dockerfile does not change. The kernel runs arm64 binaries through QEMU, and Buildx needs only three steps.

1. Register binfmt_misc handlers

Run docker run --privileged --rm tonistiigi/binfmt --install arm64 on the build host. The container registers QEMU interpreters with the kernel's binfmt_misc facility, so the kernel hands any arm64 ELF binary to the emulator. It needs --privileged because it writes kernel configuration. The registration is host-wide and lasts until reboot, so ephemeral CI runners must repeat it on every job.

2. Create a docker-container builder

Run docker buildx create --name multiarch --driver docker-container --use. The default docker driver cannot build several platforms in one invocation. The container driver runs its own BuildKit instance, which can.

3. Build and push

Run docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/app:tag --push . BuildKit builds each platform separately, then publishes one manifest list (image index) that points to both images. Clients pull the variant that matches their architecture.

The result goes straight to a registry because the classic local image store can hold only one platform per tag. If the daemon uses the containerd image store, it can keep image indexes and --load may accept several platforms. You cannot rely on that being enabled everywhere. For local testing, build one platform with --platform linux/arm64 --load and run it.

A minimal CI job follows these steps in order: check out the code, log in to the registry, register binfmt, create the builder, then build and push both platforms.

#!/usr/bin/env bash
# Minimal CI job for a generic shell-based runner.
# Assumes the CI system has already checked out the repository into the working directory.
set -euo pipefail

IMAGE="registry.example.com/team/app"
TAG="${CI_COMMIT_SHA:-dev}"   # placeholder: use your CI's commit variable

# 1. Log in to the registry. The credentials come from CI secrets and are never hard-coded.
echo "$REGISTRY_PASSWORD" | docker login registry.example.com \
  -u "$REGISTRY_USER" --password-stdin

# 2. Register QEMU binfmt_misc handlers for arm64.
#    The registration is host-wide and lost on reboot, so ephemeral runners repeat it every job.
docker run --privileged --rm tonistiigi/binfmt --install arm64

# 3. Create a builder that runs its own BuildKit instance.
#    The default docker driver cannot build several platforms in one invocation.
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap   # start the builder and list the platforms it supports

# 4. Build both platforms and push a single manifest list (image index).
#    The image is pushed, not loaded, because the classic local image store
#    holds only one platform per tag.
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t "$IMAGE:$TAG" \
  --push .

# Local testing (not part of CI): build one platform, load it, and run it.
#   docker buildx build --platform linux/arm64 -t app:arm64-test --load .
#   docker run --rm app:arm64-test uname -m   # prints aarch64 when run under emulation

A minimal shell CI job that logs in to the registry, registers QEMU binfmt handlers, creates a docker-container builder, and pushes an amd64/arm64 image index, followed by a single-platform --load command for local testing.

When should you avoid QEMU emulation?

Emulation is cheap to set up, but the cost lands on every CPU-bound step. QEMU translates each arm64 instruction into host instructions at runtime, so anything that keeps the CPU busy for a long time gets much slower. That includes compiling C, C++ or Rust; installing npm or pip packages that build native extensions from source; and running JIT-heavy toolchains such as the JVM or Node.js, whose own code generation now also runs under translation. Steps that mostly wait on the network or copy files, such as pulling base images or COPY layers, are barely affected.

Illustrative estimate (not measured): assume a Rust service whose release build takes 4 minutes natively on an x86 CI runner, and assume emulation slows that compile by a factor of 5 to 10. The arm64 leg would then take 20 to 40 minutes. A multi-platform build finishes only when its slowest platform does, so the whole pipeline now waits on that emulated leg.

Correctness is a separate problem. QEMU user-mode emulation translates syscalls to the host kernel, and that translation is incomplete for some less common syscalls, ioctls and /proc contents. Threading and signal handling under translation have a history of edge-case bugs. The memory model is the subtler issue. x86 orders memory operations more strictly than arm64, so emulating arm64 on an x86 host can hide data races that would show up on real ARM hardware. As a result, a green emulated build tells you less than a native run does, and emulated test results are weaker still.

Neither problem argues against starting with QEMU. They argue for writing the Dockerfile so that dropping emulation later is a small change, not a rewrite.

How do you cross-compile in a Dockerfile with BUILDPLATFORM and TARGETARCH?

Cross-compilation is that change. The build stage runs on the builder's own architecture at native speed, the compiler emits binaries for the target, and only the final stage uses target-platform images.

The key line is FROM --platform=$BUILDPLATFORM golang on the build stage. BuildKit sets BUILDPLATFORM, TARGETPLATFORM, TARGETOS and TARGETARCH automatically for each platform in --platform. BUILDPLATFORM works in a FROM line as-is, but inside a stage you must declare an arg with ARG TARGETOS TARGETARCH before you use it. For Go, pass the args straight to the toolchain: CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build. Disabling CGO gives you a pure-Go binary with no host C toolchain involved. The runtime stage has no --platform override, so it resolves to the target, and COPY --from=build drops the binary in.

Use the same args in RUN steps that download tools. A hardcoded linux-amd64.tar.gz URL produces an arm64 image that holds an x86 binary and fails only at runtime. TARGETARCH uses Go-style names (amd64, arm64), so map them when a vendor publishes x86_64 or aarch64 artifacts. Also confirm that every base image in a FROM line publishes all your target platforms. If one doesn't, the build fails or pulls the wrong variant.

Cross-compilation gets painful once C enters the build. With CGO enabled, you need a cross C compiler and target-architecture copies of every linked system library. You also have to match the libc: a binary linked against glibc won't run on a musl-based image such as Alpine. When this cost gets high, native builders become the better option.

# syntax=docker/dockerfile:1

# Build stage runs on the builder's native arch; Go cross-compiles for the target.
FROM --platform=$BUILDPLATFORM golang:1.22 AS build
# Automatic args must be declared inside the stage before use.
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
# CGO off: pure-Go static binary, no cross C toolchain or target libc needed.
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
    go build -o /out/app ./cmd/app

# Fetch a vendor tool for the TARGET arch (download itself runs natively).
FROM --platform=$BUILDPLATFORM alpine:3.20 AS fetch
ARG TARGETARCH
# Supply at build time, e.g. --build-arg TOOL_BASE_URL=... (no hardcoded amd64 URL).
ARG TOOL_BASE_URL
ARG TOOL_VERSION=1.4.2
# Map Go-style arch names to the vendor's naming; fail loudly on anything else.
RUN case "$TARGETARCH" in \
      amd64) ARCH=x86_64 ;; \
      arm64) ARCH=aarch64 ;; \
      *) echo "unsupported arch: $TARGETARCH" >&2; exit 1 ;; \
    esac \
 && mkdir -p /out \
 && wget -qO- "${TOOL_BASE_URL}/tool-${TOOL_VERSION}-linux-${ARCH}.tar.gz" \
    | tar -xz -C /out

# Runtime stage: no --platform override, so it resolves to the target platform.
# Check that this base image publishes every platform you pass to --platform.
FROM alpine:3.20
COPY --from=build /out/app /usr/local/bin/app
COPY --from=fetch /out/tool /usr/local/bin/tool
ENTRYPOINT ["/usr/local/bin/app"]

# Build both architectures:
#   docker buildx build --platform linux/amd64,linux/arm64 \
#     --build-arg TOOL_BASE_URL=<vendor-download-base> -t myorg/app:dev .

A multi-stage Dockerfile that runs the Go build on the native builder platform with CGO disabled, uses TARGETARCH to select the correct vendor tarball (mapped to x86_64/aarch64), and copies both binaries into a runtime stage that resolves to the target platform.

How do you use native arm64 builders in CI?

Native builders avoid both problems. Each architecture compiles on its own hardware, so the Dockerfile stays simple and builds run at full speed. There are two common ways to set this up.

One builder, two nodes

Create a builder that points at an amd64 machine, then add an arm64 machine to it with docker buildx create --append, declaring each node's platform with --platform. When you run a build with --platform linux/amd64,linux/arm64, buildx sends each platform to the node that declared it and assembles a single manifest list from the results. From the build command's point of view, nothing else changes.

Remote BuildKit endpoints run whatever instructions a Dockerfile contains, including RUN steps that can read secrets or reach your internal network. Never expose a plain TCP daemon. Use mutual TLS, or connect over SSH, and restrict which CI identities can reach the endpoint.

Per-architecture jobs, merged by digest

The alternative is to run one job per architecture on native CI runners. Each job builds a single platform and pushes it by digest, with no tag. Each job then publishes its digest as a job output or artifact. A final job depends on all the build jobs and runs docker buildx imagetools create -t repo:tag repo@sha256:… repo@sha256:… to write the multi-platform manifest.

This structure also handles partial failures. If the arm64 job fails, the merge job never runs, so the existing tag keeps pointing at the last complete multi-platform image. The amd64 digest that did get pushed is left untagged, and your registry's cleanup policy can remove it later. The tag only moves once every platform has succeeded.

# --- Approach 1: one builder, two native nodes (reached over SSH, not plain TCP) ---
docker buildx create --name native --node amd64-node \
  --platform linux/amd64 ssh://ci@amd64-builder.internal
docker buildx create --name native --append --node arm64-node \
  --platform linux/arm64 ssh://ci@arm64-builder.internal

# buildx routes linux/amd64 to amd64-node and linux/arm64 to arm64-node,
# then pushes one manifest list under the tag.
docker buildx build --builder native \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/app:1.4.0 --push .

# --- Approach 2: per-arch jobs push by digest, final job merges ---
# Runs once per native runner, with ARCH=amd64 or ARCH=arm64.
build_one() {
  docker buildx build --platform "linux/${ARCH}" \
    --output type=image,name=registry.example.com/app,push-by-digest=true,name-canonical=true,push=true \
    --metadata-file meta.json .
  # Hand the digest to the merge job, for example as a job output or artifact.
  jq -r '."containerimage.digest"' meta.json > "digest-${ARCH}.txt"
}

# Runs only after every build job has succeeded (declare them as dependencies).
merge() {
  set -euo pipefail
  amd64=$(cat digest-amd64.txt)
  arm64=$(cat digest-arm64.txt)
  # Fail before tagging if any digest is missing, so the tag never points at a partial image.
  [[ -n "$amd64" && -n "$arm64" ]] || { echo "missing digest" >&2; exit 1; }
  # Write the multi-platform manifest and move the tag in one step.
  docker buildx imagetools create -t registry.example.com/app:1.4.0 \
    "registry.example.com/app@${amd64}" \
    "registry.example.com/app@${arm64}"
  docker buildx imagetools inspect registry.example.com/app:1.4.0
}

Two native approaches: one builder with an amd64 and an arm64 node joined with --append, and per-architecture jobs that push untagged images by digest, after which a final merge job tags the multi-platform manifest only when every platform has succeeded.

How do you cache and verify multi-platform builds in CI?

Cache

CI runners are usually ephemeral, so every job starts with an empty BuildKit cache. A single-platform build that misses cache is only slow. A multi-platform build that misses cache rebuilds every layer once per architecture, and the arm64 layers take longest if they run under emulation. Each platform produces its own layers, and those layers cannot be shared across architectures, so the cache has to persist outside the runner.

Use --cache-to and --cache-from with type=registry, which stores cache as a separate image reference such as myapp:buildcache. Another option is your CI provider's cache backend if BuildKit supports it. Add mode=max to also export layers from intermediate stages. Without it, only the final stage's layers are exported, and that is a poor fit for multi-stage cross-compiling Dockerfiles.

Expect the cache to grow by roughly the size of one platform's layers for each platform you add. Invalidation also affects every platform: changing the base image or a line early in the Dockerfile forces a rebuild for every architecture.

Verification

A green build only proves the image was assembled. It does not prove the arm64 binary runs.

  1. Inspect the index. Run docker buildx imagetools inspect on the pushed reference.
  2. Check the platform entries. Confirm there is one entry each for linux/amd64 and linux/arm64. If your build attaches attestation manifests, they can appear as extra entries marked unknown/unknown. That is expected.
  3. Smoke test arm64. Run the arm64 image on a native arm64 runner or under QEMU with --platform linux/arm64. Use a command that exercises the binary, such as a version flag or a health check.

This catches problems like a binary built for the wrong architecture or a missing dynamic library. Promote the tag only after the smoke test passes.

Which approach should you choose: emulation, native builders or cross-compilation?

There is no single best approach. Compare them on the costs that actually affect your pipeline:

Criterion QEMU emulation Native arm64 builders Cross-compilation
Build speed Slow for compile-heavy steps Fast Fast, runs on the build host
Fidelity High, but emulator bugs can surface Highest, tests run on target Binary untested until run on target
Dockerfile complexity None None Moderate (BUILDPLATFORM, TARGETARCH)
Pipeline complexity Low High (runners, merging manifests) Low
Operational cost Build minutes Runner provisioning and maintenance Lowest
Best fit Interpreted languages, small images, infrequent builds Heavy native compilation, frequent builds, on-target test suites Go and other clean toolchains

Every option carries a cost that grows with the number of platforms. Build minutes, cache size and registry storage all scale roughly with platform count, so two architectures cost about twice as much to build, cache and store. Native builders also add work that has nothing to do with your code: patching runner images, keeping capacity available and debugging jobs that fail on only one architecture. Whichever path you take, check that every base image and system package you depend on publishes arm64 builds. A missing arm64 variant can block the whole build until you find a replacement.

A practical default is to start with emulation and write the Dockerfile so that switching away from it is cheap. Use multi-stage builds and pin the compile stage to BUILDPLATFORM. Then, when emulated builds get too slow, moving to cross-compilation or native runners only changes the pipeline configuration. You avoid rewriting the Dockerfile in the middle of a delivery deadline.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to docker buildx multi-platform, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.