Skip to content

Instantly share code, notes, and snippets.

@FalconIA

FalconIA/docker-multi-arch-images.md

Last active July 9, 2025 06:16
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save FalconIA/8b723676f881bbc976101ab09c7816f6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save FalconIA/8b723676f881bbc976101ab09c7816f6 to your computer and use it in GitHub Desktop.
Download ZIP
Docker: Building Multi-Arch Images for x86 and Arm
Raw
docker-multi-arch-images.md

Docker: Building Multi-Arch Images for x86 and Arm

Referer

Install other Arch emulators

  1. List current supported Arch

    » sudo docker buildx inspect --bootstrap
Name:   default
Driver: docker

Nodes:
Name:             default
Endpoint:         default
Status:           running
BuildKit version: v0.14.1
Platforms:        linux/amd64, linux/amd64/v2, linux/386
Labels:
 org.mobyproject.buildkit.worker.moby.host-gateway-ip: 172.17.0.1

  2. Install qemu-user emulators

    » sudo docker run --privileged --rm tonistiigi/binfmt --install arm64,arm
installing: arm64 OK
installing: arm OK
{
  "supported": [
    "linux/amd64",
    "linux/arm64",
    "linux/386",
    "linux/arm/v7",
    "linux/arm/v6"
  ],
  "emulators": [
    "python3.12",
    "qemu-aarch64",
    "qemu-arm"
  ]
}

  3. Verify

    » sudo docker buildx ls
NAME/NODE     DRIVER/ENDPOINT   STATUS    BUILDKIT   PLATFORMS
default*      docker
 \_ default    \_ default       running   v0.14.1    linux/amd64, linux/amd64/v2, linux/386, linux/arm64, linux/arm/v7, linux/arm/v6

~ » sudo docker buildx inspect --bootstrap
Name:   default
Driver: docker

Nodes:
Name:             default
Endpoint:         default
Status:           running
BuildKit version: v0.14.1
Platforms:        linux/amd64, linux/amd64/v2, linux/386, linux/arm64, linux/arm/v7, linux/arm/v6
Labels:
 org.mobyproject.buildkit.worker.moby.host-gateway-ip: 172.17.0.1

  4. Test

    » sudo docker run --rm arm64v8/alpine uname -a
WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64/v2) and no specific platform was requested
Linux d8763bae9de0 6.8.0-38-generic #38-Ubuntu SMP PREEMPT_DYNAMIC Fri Jun  7 15:25:01 UTC 2024 aarch64 Linux

» sudo docker run --rm arm32v7/alpine uname -a
WARNING: The requested image's platform (linux/arm/v7) does not match the detected host platform (linux/amd64/v2) and no specific platform was requested
Linux d5252941ace4 6.8.0-38-generic #38-Ubuntu SMP PREEMPT_DYNAMIC Fri Jun  7 15:25:01 UTC 2024 armv7l Linux

Build

Prepare Builder

List the existing builders:

» sudo docker buildx ls
NAME/NODE     DRIVER/ENDPOINT   STATUS    BUILDKIT   PLATFORMS
default*      docker
 \_ default    \_ default       running   v0.14.1    linux/amd64, linux/amd64/v2, linux/386, linux/arm64, linux/arm/v7, linux/arm/v6

Create a new builder using the docker-container driver which gives you access to more complex features like multi-platform builds and the more advanced cache exporters.

» sudo docker buildx create --name mybuilder --platform linux/amd64,linux/arm64 --bootstrap --use
[+] Building 12.8s (1/1) FINISHED
 => [internal] booting buildkit                                                                                   12.8s
 => => pulling image moby/buildkit:buildx-stable-1                                                                10.0s
 => => creating container buildx_buildkit_amd64_arm640                                                             2.7s
amd64_arm64

» sudo docker buildx ls                                                                               falconia@ubuntu
NAME/NODE          DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
mybuilder*         docker-container
 \_ mybuilder0      \_ unix:///var/run/docker.sock   running   v0.14.1    linux/amd64*, linux/arm64*, linux/amd64/v2, linux/386, linux/arm/v7, linux/arm/v6
default            docker
 \_ default         \_ default                       running   v0.14.1    linux/amd64, linux/amd64/v2, linux/386, linux/arm64, linux/arm/v7, linux/arm/v6

Example

Build a couple of image variants, and push them to Docker Hub.

Create a simple example Dockerfile:

# syntax=docker/dockerfile:1
FROM alpine:3.20
RUN apk add curl

Build the Dockerfile with buildx, passing the list of architectures to build for:

» sudo docker buildx build --platform linux/amd64,linux/arm64 -t falconia/buildx-example:latest --push .
[+] Building 21.3s (12/12) FINISHED                                                        docker-container:amd64_arm64
 => [internal] load build definition from Dockerfile                                                               0.1s
 => => transferring dockerfile: 100B                                                                               0.0s
 => resolve image config for docker-image://docker.io/docker/dockerfile:1                                          0.4s
 => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:e87caa74dcb7d46cd820352bfea12591f3dba3ddc4285e19c7  0.2s
 => => resolve docker.io/docker/dockerfile:1@sha256:e87caa74dcb7d46cd820352bfea12591f3dba3ddc4285e19c7dcd13359f7c  0.1s
 => [linux/arm64 internal] load metadata for docker.io/library/alpine:3.20                                         0.3s
 => [linux/amd64 internal] load metadata for docker.io/library/alpine:3.20                                         0.5s
 => [internal] load .dockerignore                                                                                  0.2s
 => => transferring context: 2B                                                                                    0.0s
 => CACHED [linux/amd64 1/2] FROM docker.io/library/alpine:3.20@sha256:b89d9c93e9ed3597455c90a0b88a8bbb5cb7188438  0.5s
 => => resolve docker.io/library/alpine:3.20@sha256:b89d9c93e9ed3597455c90a0b88a8bbb5cb7188438f70953fede212a0c439  0.4s
 => CACHED [linux/arm64 1/2] FROM docker.io/library/alpine:3.20@sha256:b89d9c93e9ed3597455c90a0b88a8bbb5cb7188438  0.5s
 => => resolve docker.io/library/alpine:3.20@sha256:b89d9c93e9ed3597455c90a0b88a8bbb5cb7188438f70953fede212a0c439  0.4s
 => [linux/amd64 2/2] RUN apk add curl                                                                             2.8s
 => [linux/arm64 2/2] RUN apk add curl                                                                             8.5s
 => exporting to image                                                                                             8.6s
 => => exporting layers                                                                                            3.3s
 => => exporting manifest sha256:e94a1838bd916fef3594d390c5b456b925f11391e9771761fd52c4ec29dd9a97                  0.2s
 => => exporting config sha256:d9f710c2c5dbf529bec381b1324ab6507e92151075fd3cc1a31b86c5b577bd68                    0.1s
 => => exporting attestation manifest sha256:a2572826089c9bc5401d6e850ffe89adb48388ed399a5b30ad94645e04630dfc      0.2s
 => => exporting manifest sha256:69c0ca95c2b75e1aa95989930cc39be17ca4c6f8b0374f378a9fe76261e2bcb8                  0.1s
 => => exporting config sha256:3396c163935de77ad164cd4e77baccd1813078bdad5d3fe7cf66ffcfbf12eaf7                    0.1s
 => => exporting attestation manifest sha256:43b7a5cc4999e22448b75e5d53761e12d215d9839efec6f27e31b4c39711a71a      0.3s
 => => exporting manifest list sha256:ef01e1e39550c3de8b4134786d3b14e743f8bfcce9de96dd4a5e8ba626343579             0.2s
 => => pushing layers                                                                                              2.4s
 => => pushing manifest for docker.io/falconia/buildx-example:latest@sha256:ef01e1e39550c3de8b4134786d3b14e743f8b  1.4s
 => [auth] falconia/buildx-example:pull,push token for registry-1.docker.io                                        0.0s

Inspect the image using docker buildx imagetools command:

» docker buildx imagetools inspect falconia/buildx-example:latest
Name:      docker.io/falconia/buildx-example:latest
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:ef01e1e39550c3de8b4134786d3b14e743f8bfcce9de96dd4a5e8ba626343579

Manifests:
  Name:        docker.io/falconia/buildx-example:latest@sha256:e94a1838bd916fef3594d390c5b456b925f11391e9771761fd52c4ec29dd9a97
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64

  Name:        docker.io/falconia/buildx-example:latest@sha256:69c0ca95c2b75e1aa95989930cc39be17ca4c6f8b0374f378a9fe76261e2bcb8
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/arm64

  Name:        docker.io/falconia/buildx-example:latest@sha256:a2572826089c9bc5401d6e850ffe89adb48388ed399a5b30ad94645e04630dfc
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    unknown/unknown
  Annotations:
    vnd.docker.reference.digest: sha256:e94a1838bd916fef3594d390c5b456b925f11391e9771761fd52c4ec29dd9a97
    vnd.docker.reference.type:   attestation-manifest

  Name:        docker.io/falconia/buildx-example:latest@sha256:43b7a5cc4999e22448b75e5d53761e12d215d9839efec6f27e31b4c39711a71a
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    unknown/unknown
  Annotations:
    vnd.docker.reference.digest: sha256:69c0ca95c2b75e1aa95989930cc39be17ca4c6f8b0374f378a9fe76261e2bcb8
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment