M1 / M2 Mac（Apple Silicon）環境で Docker イメージを docker pull した際、次のようなエラーに遭遇することがあります。
no matching manifest for linux/arm64/v8 in the manifest list entries
これは、対象の Docker イメージが arm64 アーキテクチャ（Apple Silicon）向けにビルドされていない ことを意味します。
この記事では、このエラーの仕組みと原因、そして --platform オプションやマルチアーキテクチャ対応による解決策を解説します。
エラーの原因
Docker Desktop for Mac（Apple Silicon 版）はデフォルトで arm64 (linux/arm64/v8) のプラットフォームとして動作します。
そのため、Docker Hub 上に「arm64 向けの manifest（マニフェスト情報）」が存在しないイメージを pull しようとすると、このエラーが出ます。
docker pull someimage:latest
# => no matching manifest for linux/arm64/v8
たとえば、古いバージョンの Node.js や MySQL、Elasticsearch などの公式イメージには、amd64 向けのみ存在するものがあります。
代表的な発生パターン
1. x86 専用のイメージを pull している
Docker Hub のイメージが linux/amd64 のみでビルドされている場合、Apple Silicon（arm64）では直接実行できません。
例：
docker pull some-legacy-image:1.0
2. buildx / manifest 設定がないカスタムイメージ
自作の Dockerfile でビルドした際、docker build のデフォルト設定が amd64 のみになっている場合があります。
この場合、M1/M2 Mac で pull すると同じく「no matching manifest」エラーが発生します。
対処法
対処法1: --platform オプションでアーキテクチャを指定する
手っ取り早い解決策は、--platform フラグで amd64 を明示的に指定してイメージを pull することです。
docker pull --platform linux/amd64 someimage:latest
この方法では、Rosetta 2 を利用して x86 イメージをエミュレーション実行します。
パフォーマンスは若干低下しますが、開発環境では多くの場合これで十分です。
また、docker run 時にも指定可能です。
docker run --platform linux/amd64 someimage
対処法2: Dockerfile からビルドする際に --platform を指定する
自分でビルドする場合も同様に、docker build にプラットフォームを指定できます。
docker buildx build --platform linux/arm64 -t myimage:latest .
これにより、arm64 向けのバイナリを生成できます。
複数プラットフォームを一度にビルドすることも可能です。
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myimage:multiarch \
--push .
このようにすると、Docker Hub などにマルチアーキテクチャのマニフェストが登録され、どの環境でも自動的に適切なイメージが取得されます。
対処法3: Docker Hub で対応アーキテクチャを確認する
Docker Hub の各イメージページでは、対応しているアーキテクチャが明記されています。
たとえば、Node.js の公式イメージでは以下のように記載されています。
OS/ARCH
linux/amd64
linux/arm64/v8
arm64 がない場合は、代替のタグを探すか、--platform linux/amd64 を付けるしかありません。
対処法4: docker-compose.yml に platform を記述する
Compose 環境でも、各サービスごとにプラットフォームを指定できます。
services:
app:
image: someimage:latest
platform: linux/amd64
これにより、Apple Silicon でも自動的にエミュレーションで実行されます。
対処法5: buildx を使ってマルチアーキテクチャ対応イメージを作る
本番環境で両方のアーキテクチャをサポートしたい場合は、docker buildx を使ってマルチアーキテクチャ対応のイメージをビルドします。
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t myorg/app:latest --push .
これにより、Docker Hub で自動的にプラットフォームを判別して適切なイメージが配信されるようになります。
まとめ
「no matching manifest for linux/arm64」エラーは、Docker イメージが M1/M2 Mac（arm64）に対応していないことが原因です。
主な解決策は以下の通りです。
- 一時対応：
--platform linux/amd64を付けて実行する - 永続対応：
docker buildxを使ってマルチアーキテクチャ対応にする - Docker Hub で対応アーキテクチャを確認してから利用する
開発段階ではエミュレーション実行で十分ですが、本番運用では buildx を用いたマルチプラットフォーム対応が推奨されます。
参考
- Docker Docs: Build multi-platform images
- Docker Hub: Understanding manifest lists
- Stack Overflow: no matching manifest for linux/arm64/v8 in the manifest list entries
- Apple Developer: About the Rosetta Translation Environment
