Build Multi-Architecture Extensions for Docker Desktop

--- title: Build multi-arch extensions description: Step three in creating an extension. keywords: Docker, Extensions, sdk, build, multi-arch aliases: - /desktop/extensions-sdk/extensions/multi-arch/ --- It is highly recommended that, at a minimum, your extension is supported for the following architectures: - `linux/amd64` - `linux/arm64` Docker Desktop retrieves the extension image according to the user’s system architecture. If the extension does not provide an image that matches the user’s system architecture, Docker Desktop is not able to install the extension. As a result, users can’t run the extension in Docker Desktop. ## Build and push for multiple architectures If you created an extension from the `docker extension init` command, the `Makefile` at the root of the directory includes a target with name `push-extension`. You can run `make push-extension` to build your extension against both `linux/amd64` and `linux/arm64` platforms, and push them to Docker Hub. For example: ```console $ make push-extension ``` Alternatively, if you started from an empty directory, use the command below to build your extension for multiple architectures: ```console $ docker buildx build --push --platform=linux/amd64,linux/arm64 --tag=username/my-extension:0.0.1 . ``` You can then check the image manifest to see if the image is available for both architectures using the [`docker buildx imagetools` command](/reference/cli/docker/buildx/imagetools/_index.md): ```console $ docker buildx imagetools inspect username/my-extension:0.0.1 Name: docker.io/username/my-extension:0.0.1 MediaType: application/vnd.docker.distribution.manifest.list.v2+json Digest: sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 Manifests: Name: docker.io/username/my-extension:0.0.1@sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/amd64 Name: docker.io/username/my-extension:0.0.1@sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/arm64 ``` > [!TIP] > > If you're having trouble pushing the image, make sure you're signed in to Docker Hub. Otherwise, run `docker login` to authenticate. For more information, see [Multi-platform images](/manuals/build/building/multi-platform.md) page. ## Adding multi-arch binaries If your extension includes some binaries that deploy to the host, it’s important that they also have the right architecture when building the extension against multiple architectures. Currently, Docker does not provide a way to explicitly specify multiple binaries for every architecture in the `metadata.json` file. However, you can add architecture-specific binaries depending on the `TARGETARCH` in the extension’s `Dockerfile`.

To ensure Docker Desktop users on different architectures can install and run your extension, it's recommended to support at least `linux/amd64` and `linux/arm64`. The `make push-extension` command (if available from `docker extension init`) or `docker buildx build` can be used to build and push multi-architecture images. You can verify the image manifest using `docker buildx imagetools inspect`. For extensions with host binaries, use the `TARGETARCH` variable in the Dockerfile to include architecture-specific binaries.