Docker M1 Macで「The requested image's platform (linux/amd64) does not match the detected host platform」エラーの解決方法

問題の説明

Apple Silicon（M1/M2）搭載のMacでDockerコンテナーを実行しようとすると、以下のエラーが発生することがあります：

The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

このエラーは、AMD64（x86_64）アーキテクチャ用にビルドされたDockerイメージを、ARM64アーキテクチャのM1/M2 Macで実行しようとした際に発生します。エラー発生後はプロセスが停止し、qemu-system-aarch64が100% CPU使用率で動作し続けることがあります。

解決方法

方法1: ビルド時にプラットフォームを指定する

Dockerイメージをビルドする際に、明示的にプラットフォームを指定します：

docker build --platform linux/arm64 .

Docker Composeを使用する場合：

docker-compose build --build-arg PLATFORM=linux/arm64

方法2: Docker Composeファイルでプラットフォームを指定する

docker-compose.ymlファイル内でサービスのプラットフォームを明示的に指定します：

version: '3.8'
services:
  ganache:
    platform: linux/arm64
    build:
      context: ./development
      dockerfile: ganache.dockerfile
    ports:
      - 8545:8545

方法3: 実行時にプラットフォームを指定する

既存のイメージを実行する場合、--platformフラグを使用します：

docker run --platform linux/amd64 your-image-name

TIP

この方法はエミュレーションを使用するため、パフォーマンスが低下する可能性があります。

方法4: 環境変数でデフォルトプラットフォームを設定する

ターミナルで環境変数を設定して、すべてのDocker操作のデフォルトプラットフォームを指定できます：

export DOCKER_DEFAULT_PLATFORM=linux/amd64

方法5: アーキテクチャ固有のイメージタグを使用する

多くのDockerイメージは、特定のアーキテクチャ用のタグを提供しています：

services:
  localstack:
    image: localstack/localstack:1.2.0-amd64  # AMD64用
    # image: localstack/localstack:1.2.0-arm64  # ARM64用

方法6: Colimaを使用する（x86_64エミュレーション）

Colimaをインストールしてx86_64アーキテクチャでDockerを実行します：

# Colimaのインストール
brew install colima

# x86_64アーキテクチャでColimaを起動
colima start --memory 4 --arch x86_64

# 通常通りDockerコマンドを使用
docker run [image-name]

推奨される解決策

状況に応じて最適な解決方法を選択してください：

1. 新しいプロジェクトの場合: Dockerfileとdocker-compose.ymlで明示的にマルチプラットフォーム対応を行う
2. 既存のAMD64イメージを使用する必要がある場合: --platform linux/amd64フラグを使用
3. 開発環境: Colimaを使用してx86_64環境をエミュレート
4. 本番環境を想定する場合: ネイティブARM64イメージの使用を推奨

注意事項

エミュレーションを使用する方法（特にColimaや--platform linux/amd64）は、パフォーマンスオーバーヘッドが発生する可能性があります。可能な限りネイティブARM64イメージを使用することが推奨されます。

マルチプラットフォームイメージのビルド

Docker Buildxを使用して、複数のアーキテクチャに対応したイメージを作成できます：

# Buildxのセットアップ
docker buildx create --name multiarch-builder --use
docker buildx inspect --bootstrap

# マルチプラットフォームイメージのビルドとプッシュ
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t username/image-name:latest \
  --push .

まとめ

Apple Silicon MacでのDocker使用においてプラットフォーム不一致エラーは常见の問題ですが、上記の解決方法を用いることで簡単に対処できます。状況に応じて適切な方法を選択し、シームレスな開発体験を実現してください。