できない.dev

Docker で「platform (linux/amd64) does not match」警告が出てイメージを使えない

platform (linux/amd64) does not match は、--platform の明示かマルチアーキビルドで消える。
arm64 の Mac で amd64 専用イメージを動かすと出る警告で、Rosetta はエミュレーションを速くするだけで platform を変えない。

公開: 更新:

要約

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested は、Apple Silicon ホストで amd64 のみのイメージを --platform なしで実行したときに出る警告である。
エミュレーションで動作はするが極端に遅く、native 実行できないバイナリで落ちることもある。
警告は --platform の明示か buildx マルチアーキで消える。
Rosetta はエミュレーションを速くする設定で、イメージの platform は変わらない。

解決策

1. プラットフォームを明示

docker run --platform=linux/arm64 myimage:tag
docker pull --platform=linux/amd64 myimage:tag

公開側で arm64 タグが用意されていれば、明示するだけで native 実行に切り替わる。
amd64 のみのイメージなら --platform=linux/amd64 を明示する。
動きはエミュレーションのままで、警告だけが出なくなる。

2. buildx でマルチアーキビルド

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/me/app:latest --push .

公式の Multi-platform images ドキュメント(新しいタブで開く) のとおり、buildx で一度のコマンドで複数アーキの manifest list が作れる。
配布側で揃えれば利用側で警告は出なくなる。

3. Rosetta を有効化

Docker Desktop の Settings → General → Use Rosetta for x86_64/amd64 emulation on Apple Silicon を有効にする(Docker Desktop の Mac 設定ドキュメント(新しいタブで開く))。
QEMU より高速で、amd64 only のイメージしか使えない場面で体感差が大きい。

4. Dockerfile を両対応にする

FROM --platform=$BUILDPLATFORM node:20 AS build
ARG TARGETPLATFORM
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"

$BUILDPLATFORM と $TARGETPLATFORM を使い分けると、ビルド側でクロスコンパイルしつつ、実行イメージは target に揃えられる。

よくある原因

  1. amd64 only のイメージを使っている。
    公式以外のイメージは arm64 タグを公開していないものがある。
  2. FROM 行のイメージに arm64 が無い。
    docker buildx imagetools inspect <イメージ> の Platform: の行で確かめる(node:20-bullseye には linux/arm64/v8 がある)。
  3. Rosetta が無効になっている。
    Docker Desktop 4.16 以降で利用できる x86_64 emulator が無効のままで、QEMU 経由の遅いエミュレーションになっている。
  4. CI とホストでアーキテクチャが違う。
    GitHub Actions の ubuntu-latest は amd64、ローカル Mac は arm64 で、build 物のキャッシュが食い違う。