こんにちは、フルスタックエンジニアのryuです。
今回の記事では、MacでDockerを使ったときに表示されるno matching manifest for linux/arm64/v8 in the manifest list entriesというエラーの原因と対処方法について解説します。
私もApple SiliconのMacでDocker Composeを実行した際、このエラーに遭遇しました。エラーメッセージが長いため難しそうに見えますが、原因が分かれば確認するポイントはそれほど多くありません。
このエラーは簡単にいうと、使用しようとしているDockerイメージが、自分の環境のCPUアーキテクチャに対応していないときに発生します。
現在はARM64へ対応しているDockerイメージも増えています。そのため、最初からplatformを固定せず、イメージの対応状況を確認してから対処するのがおすすめです。
no matching manifest for linux/arm64/v8エラーとは？¶
Docker Composeでコンテナを起動しようとした際、以下のエラーが表示されました。
no matching manifest for linux/arm64/v8 in the manifest list entries
初めて見ると、manifestとは何だろう？ linux/arm64/v8とは何だろう？と戸惑いますよね。
このエラーを理解するためには、まずDockerイメージとCPUアーキテクチャの関係を知っておくと分かりやすいです。
ARM64とAMD64の違い¶
Dockerイメージには、どのCPUアーキテクチャで動作するかという情報があります。
AppleのM1、M2、M3、M4などを搭載したMacはARM64系のCPUを使っています。一方、従来のIntel Macや多くのサーバーではAMD64と呼ばれるアーキテクチャが利用されています。
代表的な表記をまとめると、次のようになります。
| Dockerでの表記 | 主な環境 | 意味 |
|---|---|---|
linux/arm64 |
Apple Siliconなど | ARM64向けLinux |
linux/arm64/v8 |
Apple Siliconなど | ARMv8系の64bit ARM |
linux/amd64 |
Intel・AMD系PCやサーバー | x86_64向けLinux |
linux/386 |
古い32bit環境 | x86向けLinux |
たとえば、Mac側がlinux/arm64/v8のイメージを必要としているのに、Docker Hubにlinux/amd64向けのイメージしか存在しなければ、Dockerは対応するイメージを取得できません。
その結果、no matching manifestというエラーが発生します。
自分のMacのCPUを確認する¶
まず、自分が使っているMacのアーキテクチャを確認してみましょう。
ターミナルで次のコマンドを実行します。
uname -m
Apple SiliconのMacであれば、次のように表示されます。
arm64
Intel Macでは、次のように表示されることがあります。
x86_64
エラーが発生したら、いきなりDocker Composeの設定を書き換えるのではなく、自分の環境と利用するDockerイメージの組み合わせを確認するところから始めると原因を切り分けやすくなります。
【関連記事】Dockerそのものをこれから学習する方は、Dockerの始め方を初心者向けに解説も参考にしてください。
no matching manifestエラーの対処方法¶
では、実際にエラーを解決していきます。
大きく分けると、ARM64に対応したイメージへ変更する方法と、AMD64向けイメージをエミュレーションして動かす方法があります。
まずDockerイメージの対応アーキテクチャを確認する¶
最初に確認したいのが、使用しているDockerイメージがARM64に対応しているかどうかです。
Docker HubのTags画面を見ると、タグごとに対応するOSやアーキテクチャを確認できます。イメージによってはlinux/amd64だけではなく、linux/arm64/v8も用意されています。
コマンドから確認したい場合は、次のような方法もあります。
docker buildx imagetools inspect mysql:8.0
出力の中にlinux/arm64やlinux/arm64/v8が含まれていれば、そのタグはARM64向けイメージを持っています。
現在のMySQL公式DockerイメージにはARM64へ対応しているタグもあります。そのため、古い記事でよく見かけるMac M1ではMySQLが動かないという理解ではなく、使用しているイメージとタグがARM64に対応しているかを見ることが重要です。
たとえば古いMySQLのタグや、特定のサードパーティ製イメージではARM64版が存在しない場合があります。その場合に、次のplatform指定を検討します。
docker-compose.ymlにplatformを指定する¶
ARM64へ対応していないAMD64向けイメージをApple SiliconのMacで動かしたい場合は、Composeファイルにplatformを指定できます。
たとえば、次のように設定します。
services:
db:
image: example/mysql-image:latest
platform: linux/amd64
Docker Composeのplatformは、そのサービスをどのプラットフォーム向けとして実行するかを指定する設定です。Docker公式のCompose仕様でもos[/arch[/variant]]の形式で指定できます。
設定後は、次のようにコンテナを起動します。
docker compose up -d
環境によって古いdocker-composeコマンドを使っている場合もありますが、現在のDocker Composeではdocker composeという形式が基本です。
【関連記事】LinuxへDocker Composeを導入する手順を知りたい方は、docker-composeをLinuxにインストールする方法も参考にしてください。
platformを指定したのに直らない場合¶
platform: linux/amd64を追加してもエラーが解消しない場合は、いくつか確認してみましょう。
まず、Composeファイルの記述が正しく読み込まれているかを確認します。
docker compose config
このコマンドを実行すると、Docker Composeが最終的にどのような設定として解釈しているのか確認できます。
次に、一度イメージを取得し直してみます。
docker compose pull
docker compose up -d
latestを使っていると、時間が経ったあとに内容が変わる可能性があります。開発環境を安定させたい場合は、利用するバージョンを明示する方法もあります。
services:
db:
image: mysql:8.0
エラーの原因を確認せず、何でもlinux/amd64に固定してしまうのはおすすめしません。
platform: linux/amd64を指定するときの注意点¶
platform: linux/amd64は便利ですが、Apple Silicon上でAMD64向けのコンテナを動かす場合は、CPUアーキテクチャを変換するためのエミュレーションが必要になります。
そのため、ARM64向けのネイティブイメージをそのまま実行する場合と比べて、動作が遅くなったり、メモリ使用量が増えたりする場合があります。
ARM64対応イメージがあるならそちらを使う¶
Docker公式ドキュメントでも、Apple Silicon上でARM64非対応のイメージをlinux/amd64として動かす方法が案内されています。
ただし、エミュレーションには制約もあるため、ARM64版が用意されているのであれば、できるだけARM64対応イメージを利用する方が自然です。
対処方法を整理すると、次のようになります。
| 状況 | おすすめの対処 |
|---|---|
| ARM64対応タグがある | ARM64対応イメージをそのまま使う |
| ARM64対応タグがない | platform: linux/amd64を検討する |
| 古いイメージを使っている | 新しいタグに変更できないか確認する |
| 自作イメージ | ARM64を含むマルチプラットフォームビルドを検討する |
なぜplatformが必要なのか理解しておくと、別のDockerイメージで同じエラーが出たときにも対応できます。
Dockerfileを自分で作っている場合¶
Docker Hubから取得したイメージではなく、自分でDockerfileを作っている場合は、ビルドするプラットフォームも確認してみましょう。
Dockerでは、複数のCPUアーキテクチャに対応するマルチプラットフォームイメージを作成できます。
たとえば、Buildxでは次のように対象を指定できます。
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t example/app:latest .
チーム内にIntel MacとApple Silicon Macが混在していたり、開発環境と本番サーバーでCPUアーキテクチャが異なったりする場合に役立ちます。
DockerをLinux環境へ導入するところから確認したい方は、【関連記事】LinuxにDockerをインストールする方法もご覧ください。
DockerのエラーはLinuxの知識があると理解しやすい¶
Dockerを使っていると、コンテナだけを勉強すればよいように感じるかもしれません。
しかし、実際にはLinux、CPU、ネットワーク、ファイルシステム、ポートなど、インフラの基礎知識がさまざまな場所で登場します。
今回のlinux/arm64/v8という表記も、LinuxとCPUアーキテクチャの組み合わせを表しています。仕組みが分かると、長いエラーメッセージを見ても何を確認すればよいのか判断しやすくなります。
InfraAcademyでは、Linuxやネットワーク、AWSなど、インフラエンジニアに必要な知識をブラウザ上で実際に操作しながら学習できます。
まずLinuxの基本操作から学びたい方は、Linux入門講座をご覧ください。
Dockerコンテナ同士の通信やポートの仕組みを理解したい場合は、ネットワーク講座でIPアドレスやルーティングなどを学んでおくと理解しやすくなります。
さらに、Dockerイメージをクラウド上で動かすところまで学習したい方は、AWS講座もおすすめです。
no matching manifest for linux/arm64/v8エラーまとめ¶
今回の記事では、no matching manifest for linux/arm64/v8 in the manifest list entriesというエラーの原因と対処方法について解説しました。
このエラーは、Dockerが現在の環境に合うイメージをmanifestの中から見つけられなかった場合に発生します。
Apple SiliconのMacで発生した場合は、まず使用しているDockerイメージのタグがARM64に対応しているか確認してみてください。
ARM64対応イメージがない場合は、Composeファイルに次のように設定することでAMD64向けイメージを利用できる場合があります。
services:
db:
image: example/image:latest
platform: linux/amd64
ただし、platform: linux/amd64は何でも解決できる設定ではありません。ARM64対応イメージがある場合は、そちらを使う方が基本的にはおすすめです。
エラーメッセージを見ると難しく感じますが、まず自分のCPUアーキテクチャとDockerイメージの対応状況を確認する。この順番で切り分ければ、原因を見つけやすくなります。
