docker buildxでamd64/arm64両対応のコンテナイメージを作成する

Dockerコンテナイメージをamd64とarm64の両プラットフォーム向けにマルチプラットフォームビルドする方法は公式サイトのMulti-platform buildsに記載されています。同ページのStrategiesセクションにはマルチプラットフォームビルドに関して以下、3種類の方法が記載されています。

Using emulation, via QEMU

Use a builder with multiple native nodes

Use cross-compilation with multi-stage builds

1番の方法は最も簡単ですが、パフォーマンスが出ないそうです。とは言え、私の場合はそこまで頻繁にイメージ作成するわけではありませんので、最も手軽な1番を実施する方法をメモしておきます。

検証環境¶

対象	バージョン
Ubuntu	24.04.3 LTS

今回はamd64(x86_64)環境を利用しています。

# uname -a
Linux localhost 6.8.0-71-generic #71-Ubuntu SMP PREEMPT_DYNAMIC Tue Jul 22 16:52:38 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

docker buildxのインストール¶

マルチプラットフォームビルドするにはDocker Buildxを利用します。以前にUbuntu へ docker をインストールするワンライナーというメモを書きましたが、以下のワンライナーでUbuntuへDockerやbuildxをインストールできます。

curl -fsSL https://get.docker.com | sh

QEMUのインストール¶

QEMUを利用する為、Binfmtをインストールします。Binfmtは「Cross-platform emulator collection distributed with Docker images.」と説明されています。

docker run --privileged --rm tonistiigi/binfmt --install all

ビルダーインスタンスの作成¶

マルチプラットフォームビルド用のビルダーインスタンスを作成します。

docker buildx create \
  --name mybuild \
  --driver docker-container \
  --bootstrap --use

Dockerfileを用意する¶

ビルド用のDockerfileを用意します。

Dockerhubへログインする¶

後述しますが、buildxでビルドしたコンテナイメージをそのままリポジトリへアップロードするには事前にイメージリポジトリへログインしている必要があります。DockerHubへログインする手順はDockerHub へイメージを登録するに記載しましたが、以下を実行します。

docker login

ビルドする¶

buildxでビルドします。但し、デフォルトではビルドが成功してもキャッシュするのみであり、イメージは登録されないようです。

docker buildx build --platform linux/amd64,linux/arm64 --tag sample:latest .

ビルドが成功した際、イメージをリポジトリへ登録するには--output=type=registryオプションを指定します。前述した通り、このオプションを指定する際は事前にDockerhubなどのリポジトリへログインしている必要があります。

docker buildx build --platform linux/amd64,linux/arm64 --tag sample:latest --output=type=registry .

参考¶

# docker buildx build --help
Usage:  docker buildx build [OPTIONS] PATH | URL | -

Start a build

Aliases:
  docker build, docker builder build, docker image build, docker buildx b

Options:
      --add-host strings              Add a custom host-to-IP mapping (format: "host:ip")
      --allow stringArray             Allow extra privileged entitlement (e.g., "network.host", "security.insecure")
      --annotation stringArray        Add annotation to the image
      --attest stringArray            Attestation parameters (format: "type=sbom,generator=image")
      --build-arg stringArray         Set build-time variables
      --build-context stringArray     Additional build contexts (e.g., name=path)
      --builder string                Override the configured builder instance
      --cache-from stringArray        External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")
      --cache-to stringArray          Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")
      --call string                   Set method for evaluating build ("check", "outline", "targets") (default "build")
      --cgroup-parent string          Set the parent cgroup for the "RUN" instructions during build
      --check                         Shorthand for "--call=check" (default )
  -D, --debug                         Enable debug logging
  -f, --file string                   Name of the Dockerfile (default: "PATH/Dockerfile")
      --iidfile string                Write the image ID to a file
      --label stringArray             Set metadata for an image
      --load                          Shorthand for "--output=type=docker"
      --metadata-file string          Write build result metadata to a file
      --network string                Set the networking mode for the "RUN" instructions during build (default "default")
      --no-cache                      Do not use cache when building the image
      --no-cache-filter stringArray   Do not cache specified stages
  -o, --output stringArray            Output destination (format: "type=local,dest=path")
      --platform stringArray          Set target platform for build
      --progress string               Set type of progress output ("auto", "quiet", "plain", "tty", "rawjson"). Use plain to show container output (default "auto")
      --provenance string             Shorthand for "--attest=type=provenance"
      --pull                          Always attempt to pull all referenced images
      --push                          Shorthand for "--output=type=registry"
  -q, --quiet                         Suppress the build output and print image ID on success
      --sbom string                   Shorthand for "--attest=type=sbom"
      --secret stringArray            Secret to expose to the build (format: "id=mysecret[,src=/local/secret]")
      --shm-size bytes                Shared memory size for build containers
      --ssh stringArray               SSH agent socket or keys to expose to the build (format: "default|<id>[=<socket>|<key>[,<key>]]")
  -t, --tag stringArray               Name and optionally a tag (format: "name:tag")
      --target string                 Set the target build stage to build
      --ulimit ulimit                 Ulimit options (default [])