--- title: Multi-platform images description: Introduction to multi-platform images and how to build them keywords: build, buildx, buildkit, multi-platform images redirect_from: - /build/buildx/multiplatform-images/ - /desktop/multi-arch/ - /docker-for-mac/multi-arch/ - /mackit/multi-arch/ --- Docker images can support multiple platforms, which means that a single image may contain variants for different architectures, and sometimes for different operating systems, such as Windows. When you run an image with multi-platform support, Docker automatically selects the image that matches your OS and architecture. Most of the Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64){:target="blank" rel="noopener" class=""}. For example, the `busybox` image supports `amd64`, `arm32v5`, `arm32v6`, `arm32v7`, `arm64v8`, `i386`, `ppc64le`, and `s390x`. When running this image on an `x86_64` / `amd64` machine, the `amd64` variant is pulled and run. ## Building multi-platform images When you invoke a build, you can set the `--platform` flag to specify the target platform for the build output. For example, `linux/amd64`, `linux/arm64`, or `darwin/amd64`. By default, you can only build for a single platform at a time. If you want to build for multiple platforms at once, you can: - Create a new builder that uses the [`docker-container` driver](../drivers/docker-container.md) - Turn on the [containerd snapshotter storage](../../desktop/containerd/index.md) ## Strategies You can build multi-platform images using three different strategies, depending on your use case: 1. Using the [QEMU emulation](#qemu) support in the kernel 2. Building on [multiple native nodes](#multiple-native-nodes) using the same builder instance 3. Using a stage in your Dockerfile to [cross-compile](#cross-compilation) to different architectures ### QEMU Building multi-platform images under emulation with QEMU is the easiest way to get started if your builder already supports it. Docker Desktop supports it out of the box. It requires no changes to your Dockerfile, and BuildKit automatically detects the secondary architectures that are available. When BuildKit needs to run a binary for a different architecture, it automatically loads it through a binary registered in the `binfmt_misc` handler. > **Note** > > QEMU performs full-system emulation of non-native platforms, which is much > slower than native builds. Compute-heavy tasks like compilation and > compression or decompression likely results in a large performance hit. > > Use [cross-compilation](#cross-compilation) instead, if possible. For QEMU binaries registered with `binfmt_misc` on the host OS to work transparently inside containers, they must be statically compiled and registered with the `fix_binary` flag. This requires a kernel version 4.8 or later, and `binfmt-support` version 2.1.7 or later. You can verify your registration by checking if `F` is among the flags in `/proc/sys/fs/binfmt_misc/qemu-*`. While Docker Desktop comes preconfigured with `binfmt_misc` support for additional platforms, for other installations it likely needs to be installed using [`tonistiigi/binfmt`](https://github.com/tonistiigi/binfmt) image: ```console $ docker run --privileged --rm tonistiigi/binfmt --install all ``` ### Multiple native nodes Using multiple native nodes provide better support for more complicated cases that are not handled by QEMU and generally have better performance. You can add additional nodes to the builder instance using the `--append` flag. Assuming contexts `node-amd64` and `node-arm64` exist in `docker context ls`; ```console $ docker buildx create --use --name mybuild node-amd64 mybuild $ docker buildx create --append --name mybuild node-arm64 $ docker buildx build --platform linux/amd64,linux/arm64 . ``` For information on using multiple native nodes in CI, with GitHub Actions, refer to [Configure your GitHub Actions builder](../ci/github-actions/configure-builder.md#append-additional-nodes-to-the-builder). ### Cross-compilation Depending on your project, if the programming language you use has good support for cross-compilation, multi-stage builds in Dockerfiles can be effectively used to build binaries for target platforms using the native architecture of the build node. Build arguments such as `BUILDPLATFORM` and `TARGETPLATFORM` are automatically available for use in your Dockerfile, and can be leveraged by the processes running as part of your build. ```dockerfile # syntax=docker/dockerfile:1 FROM --platform=$BUILDPLATFORM golang:alpine AS build ARG TARGETPLATFORM ARG BUILDPLATFORM RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log FROM alpine COPY --from=build /log /log ``` ## Getting started Run the [`docker buildx ls` command](../../engine/reference/commandline/buildx_ls.md) to list the existing builders: ```console $ docker buildx ls NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS default * docker default default running v0.11.6 linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 ``` This displays the default builtin driver, that uses the BuildKit server components built directly into the docker engine, also known as the [`docker` driver](../drivers/docker.md). Create a new builder using the [`docker-container` driver](../drivers/docker-container.md) which gives you access to more complex features like multi-platform builds and the more advanced cache exporters, which are currently unsupported in the default `docker` driver: ```console $ docker buildx create --name mybuilder --bootstrap --use ``` Now listing the existing builders again, we can see our new builder is registered: ```console $ docker buildx ls NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS mybuilder * docker-container mybuilder0 unix:///var/run/docker.sock running v0.12.1 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6 default docker default default running v{{ site.buildkit_version }} linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 ``` ## Example Test the workflow to ensure you can build, push, and run multi-platform images. Create a simple example Dockerfile, build a couple of image variants, and push them to Docker Hub. The following example uses a single `Dockerfile` to build an Alpine image with cURL installed for multiple architectures: ```dockerfile # syntax=docker/dockerfile:1 FROM alpine:3.16 RUN apk add curl ``` Build the Dockerfile with buildx, passing the list of architectures to build for: ```console $ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t /:latest --push . ... #16 exporting to image #16 exporting layers #16 exporting layers 0.5s done #16 exporting manifest sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c 0.0s done #16 exporting config sha256:a26f329a501da9e07dd9cffd9623e49229c3bb67939775f936a0eb3059a3d045 0.0s done #16 exporting manifest sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf 0.0s done #16 exporting config sha256:9fcc6de03066ac1482b830d5dd7395da781bb69fe8f9873e7f9b456d29a9517c 0.0s done #16 exporting manifest sha256:29666fb23261b1f77ca284b69f9212d69fe5b517392dbdd4870391b7defcc116 0.0s done #16 exporting config sha256:92cbd688027227473d76e705c32f2abc18569c5cfabd00addd2071e91473b2e4 0.0s done #16 exporting manifest list sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 0.0s done #16 ... #17 [auth] /:pull,push token for registry-1.docker.io #17 DONE 0.0s #16 exporting to image #16 pushing layers #16 pushing layers 3.6s done #16 pushing manifest for docker.io//:latest@sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 #16 pushing manifest for docker.io//:latest@sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 1.4s done #16 DONE 5.6s ``` > **Note** > > * `` must be a valid Docker ID and `` and valid repository on > Docker Hub. > * The `--platform` flag informs buildx to create Linux images for AMD 64-bit, > Arm 64-bit, and Armv7 architectures. > * The `--push` flag generates a multi-arch manifest and pushes all the images > to Docker Hub. Inspect the image using [`docker buildx imagetools` command](../../engine/reference/commandline/buildx_imagetools.md): ```console $ docker buildx imagetools inspect /:latest Name: docker.io//:latest MediaType: application/vnd.docker.distribution.manifest.list.v2+json Digest: sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 Manifests: Name: docker.io//:latest@sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/amd64 Name: docker.io//:latest@sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/arm64 Name: docker.io//:latest@sha256:29666fb23261b1f77ca284b69f9212d69fe5b517392dbdd4870391b7defcc116 MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/arm/v7 ``` The image is now available on Docker Hub with the tag `/:latest`. You can use this image to run a container on Intel laptops, Amazon EC2 Graviton instances, Raspberry Pis, and on other architectures. Docker pulls the correct image for the current architecture, so Raspberry PIs run the 32-bit Arm version and EC2 Graviton instances run 64-bit Arm. The digest identifies a fully qualified image variant. You can also run images targeted for a different architecture on Docker Desktop. For example, when you run the following on a macOS: ```console $ docker run --rm docker.io//:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 uname -m aarch64 ``` ```console $ docker run --rm docker.io//:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 uname -m armv7l ``` In the above example, `uname -m` returns `aarch64` and `armv7l` as expected, even when running the commands on a native macOS or Windows developer machine. ## Support on Docker Desktop [Docker Desktop](../../desktop/index.md) provides `binfmt_misc` multi-architecture support, which means you can run containers for different Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`. This does not require any special configuration in the container itself as it uses [qemu-static](https://wiki.qemu.org/Main_Page){:target="blank" rel="noopener" class=""} from the Docker Desktop VM. Because of this, you can run an ARM container, like the `arm32v7` or `ppc64le` variants of the busybox image.