An image that runs on an Intel Linux machine may fail on an Arm Mac or a Windows machine. A multiarch container image solves this by publishing platform-specific variants under one image name and tag. When you run it, Docker selects the variant matching the machine’s operating system and CPU. The app can behave the same even though the image pulled is different. section 12.0
The publisher does the extra work: build each variant, push the variants to a registry, then push a manifest list that links them to one tag. Building several separately tagged images is not enough to make that shared tag multi-platform. If no variant matches a machine, Docker cannot pull a suitable image. section 12.3 section 12.1
Build and check two Linux variants
With a multi-platform base image and suitable build tools in your Dockerfile, build for Arm with `docker build --platform linux/arm64 -t hello:arm64 ./hello` and for Intel with `docker build --platform linux/amd64 -t hello:amd64 ./hello`. Check the engine with `docker info -f '{{.OSType}}/{{.Architecture}}'` and an image with `docker image inspect hello:arm64 -f '{{.Os}}/{{.Architecture}}'`. Docker Desktop can use QEMU emulation when the target CPU differs from your own; a Linux Docker Engine needs QEMU installed separately. section 12.1
Choose how to produce and publish the shared tag:
- For manual control, tag and push each platform-specific image first. Use `docker manifest create` with the shared tag and all variant tags, then `docker manifest push`. `docker manifest inspect` lets you check a published image’s supported platforms without pulling it. section 12.3
- For a repeatable build, configure Buildx nodes for the target platforms and run `docker buildx build` with `--platform`, a shared tag, and `--push`. Buildx builds the variants and pushes their manifest list; its nodes can use emulation or separate native machines. section 12.4
# build and push the hello app for all the builder's platforms: docker buildx build --builder ch12-builder ` --platform linux/arm64,linux/amd64 ` -t "$dockerId/ch12-hello-x:2e" ` --push ./hello
The Buildx command builds Linux Arm64 and Intel variants and publishes them under one Docker Hub tag. It assumes the named builder and Docker ID variable have already been set up; the shown line continuations use PowerShell syntax. section 12.4
Check that every variant actually runs. A multi-platform base image does not make an OS-specific `RUN` or `CMD` command portable: a build may succeed but its container may fail. A single Dockerfile is simpler when its commands work on every target; otherwise, use platform-specific Dockerfiles. To keep future options open, choose multi-platform base images and avoid OS-specific commands where possible. section 12.2 section 12.5
