こういった経験はありませんか。
M1/M2/M3チップのMacはデフォルトでlinux/arm64のイメージをビルドします。
一方、一般的な本番サーバーはlinux/amd64(x86_64、Intel/AMD系CPU)で動いています。
アーキテクチャが一致しないと、コンテナ起動時に「exec format error」が発生してプロセスを実行できません。
この記事では、DockerfileのFROM命令に
--platform=linux/amd64 を指定してアーキテクチャを固定する方法、ビルド時に自動設定される ARG BUILDPLATFORM/TARGETPLATFORM との組み合わせ設計、Docker ComposeのplatformキーでLinux/amd64を固定する手順を解説します。想定環境はDocker 24以降(RHEL 9系/Ubuntu 24.04 LTS)です。
この記事のポイント
・DockerfileのFROMに --platform=linux/amd64 を書くとビルド・実行のアーキテクチャをx86_64に固定できる
・「exec format error」はアーキテクチャの不一致が原因で、platformを指定すると解消できる
・ARG BUILDPLATFORM と ARG TARGETPLATFORM を使うとCI/CDでプラットフォームを動的に切り替えられる
・Docker ComposeのplatformキーでもサービスごとにLinux/amd64を固定できる
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
なぜDockerfileにplatformを指定するのか
Dockerイメージはアーキテクチャごとに別のバイナリで構成されています。linux/amd64向けにビルドされたイメージはlinux/arm64(ARMv8)環境では動きません。
ARMアーキテクチャのMacでビルドしたイメージをそのままx86_64のLinuxサーバーに持っていくと、シェルやアプリケーションのバイナリが実行できず「exec format error」が出ます。
この不一致を解消する方法のひとつが、DockerfileのFROM命令にplatformを指定することです。
FROM --platform=linux/amd64 と書くと、ビルドするホストのアーキテクチャに関係なく、linux/amd64のベースイメージを取得してビルドできます。Dockerコンテナを本番のLinuxサーバーで安定して動かす設計を体系的に学ぶなら、Docker実践講座もあわせて確認してみてください。
FROM --platform=linux/amd64 の書き方
1. FROMにplatformを直書きする
最もシンプルな指定方法は、FROM命令に--platform オプションをそのまま書くことです。
# ベースイメージのアーキテクチャをlinux/amd64に固定する FROM --platform=linux/amd64 ubuntu:24.04 RUN apt-get update && apt-get install -y curl
「Dockerfileに書く」と「
docker build --platform linux/amd64 とコマンドに書く」は、どちらも同じ効果が得られます。Dockerfileに書いておくと、コマンドを実行するメンバーがアーキテクチャを意識しなくても統一されるので、チーム開発ではDockerfile側に書くほうが管理しやすい設計です。
2. マルチステージビルドでplatformを使う場合
マルチステージビルドを使う場合は、ビルドステージとランタイムステージそれぞれにplatformを指定できます。「ビルドステージはホストのアーキテクチャで高速にコンパイルし、ランタイムステージだけlinux/amd64に固定する」という設計がよく使われます。
# ビルドステージ:ホストのアーキテクチャでコンパイルする($BUILDPLATFORMはDockerが自動設定する) FROM --platform=$BUILDPLATFORM golang:1.22 AS builder WORKDIR /app COPY . . # クロスコンパイルでlinux/amd64向けバイナリを生成する RUN GOARCH=amd64 GOOS=linux go build -o myapp . # ランタイムステージ:実行環境のアーキテクチャをlinux/amd64に固定する FROM --platform=linux/amd64 gcr.io/distroless/static-debian12 COPY --from=builder /app/myapp /myapp CMD ["/myapp"]
$BUILDPLATFORM はDockerが自動で提供するビルド引数で、ビルドを実行しているホストのプラットフォーム(例: linux/arm64)が入ります。ビルドステージをホストのアーキテクチャで動かし、ランタイムステージだけlinux/amd64に固定する設計にすると、ビルド速度を落とさずに実行環境のアーキテクチャを統一できます。
ARG BUILDPLATFORM と TARGETPLATFORM で動的に制御する
1. ARGの基本構文
Dockerには、ビルド時に自動で渡されるプラットフォーム引数が用意されています。ARG で宣言するだけでDockerが値を設定するので、--build-arg で渡す必要はありません。
# Dockerが自動で提供するビルド引数(ARGで宣言して有効化する) # BUILDPLATFORM : ビルドホストのプラットフォーム(例: linux/arm64) # BUILDARCH : ビルドホストのアーキテクチャ(例: arm64) # TARGETPLATFORM : ビルド対象のプラットフォーム(例: linux/amd64) # TARGETARCH : ビルド対象のアーキテクチャ(例: amd64) FROM ubuntu:24.04 ARG TARGETPLATFORM ARG TARGETARCH # 出力例(環境により異なります) RUN echo "ビルド対象: ${TARGETPLATFORM}, アーキテクチャ: ${TARGETARCH}" # ビルド対象: linux/amd64, アーキテクチャ: amd64
ARGはステージをまたがないので、マルチステージビルドでは各FROMの後に改めて宣言する必要があります。
2. CI/CDでplatformを動的に切り替える設計
GitHub Actionsなどのパイプラインでマルチアーキテクチャイメージをビルドする場合は、docker buildx と組み合わせる構成が実用的です。
# Docker BuildxでLinux/amd64のイメージをビルドする docker buildx build \ --platform linux/amd64 \ --tag myapp:latest \ --push \ . # linux/amd64とlinux/arm64の両方をビルドしてプッシュする場合 docker buildx build \ --platform linux/amd64,linux/arm64 \ --tag myapp:latest \ --push \ .
--platform linux/amd64,linux/arm64 とカンマ区切りで指定すると、両アーキテクチャのマニフェストリストを一度にビルドしてレジストリにプッシュできます。Dockerfileの
--platform オプションはベースイメージのアーキテクチャを固定する指定です。docker buildx --platform はビルドする対象アーキテクチャを指定するオプションです。両方を組み合わせて使うと、ビルドの意図をより明確にできます。
Docker ComposeのplatformキーでLinux/amd64を固定する
Composeファイルでも、サービスごとにplatformを指定できます。ARMのMacで開発環境を動かすとき、特定のサービスがlinux/amd64にしか対応していないケースがあります。
そのサービスだけplatformを指定しておくと、DockerがQEMUエミュレーションで動かしてくれます。
services: web: image: myapp:latest platform: linux/amd64 ports: - "8080:8080" db: image: postgres:16 platform: linux/amd64 volumes: - db_data:/var/lib/postgresql/data volumes: db_data:
platform: linux/amd64 を書くと、docker compose up 時にそのサービスがlinux/amd64のイメージを取得して起動します。エミュレーションはネイティブより遅くなりますが、動作確認には十分です。
本番向けイメージはアーキテクチャを統一する設計にしてください。
よくあるエラーと対処
1. exec format error が出た時の確認手順
コンテナ起動時に「exec format error」が出た場合、まずイメージのアーキテクチャを確認します。# イメージのアーキテクチャを確認する docker inspect --format '{{.Architecture}}' イメージ名:タグ # 出力例(環境により異なります) arm64
arm64 と表示されていれば、linux/amd64のサーバーでは動きません。Dockerfileに
FROM --platform=linux/amd64 を追加して再ビルドするか、Docker Hubのマルチアーキテクチャイメージを docker pull --platform linux/amd64 で取得し直してください。2. プラットフォーム不一致の警告が出た時
以下のような警告が出ることがあります。# 出力例(環境により異なります) WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
警告が出ても動く場合はQEMUエミュレーションで実行しています。
Dockerfileに
FROM --platform=linux/amd64 を書いてある場合、このホストアーキテクチャに関する警告は出なくなります。本記事のまとめ
| やりたいこと | 書き方 |
|---|---|
| Dockerfileでlinux/amd64に固定する | FROM --platform=linux/amd64 ubuntu:24.04 |
| ビルドホストのプラットフォームを取得する | ARG BUILDPLATFORM(自動設定される) |
| ビルド対象のプラットフォームを取得する | ARG TARGETPLATFORM(自動設定される) |
| docker buildxで指定アーキテクチャをビルドする | docker buildx build --platform linux/amd64 . |
| Docker Composeでサービスのplatformを固定する | platform: linux/amd64(composeファイルのserviceキー配下) |
| イメージのアーキテクチャを確認する | docker inspect --format '{{.Architecture}}' イメージ名 |
ARMアーキテクチャのMacで開発していて本番がlinux/amd64のLinuxサーバーという環境では、Dockerfileにplatformを明記しておくと、チームメンバーがアーキテクチャの違いを意識せずに本番と同じアーキテクチャのイメージをビルドできます。
【注意】
FROM --platform=linux/amd64 をARMのMac上でビルドする場合、QEMUエミュレーションを使って実行するため、ネイティブビルドより時間がかかります。CIパイプラインでビルドする場合は、linux/amd64のランナーを使うか、docker buildxのクロスコンパイル(
--platform linux/amd64)を組み合わせるとビルド時間を短縮できます。
Dockerコンテナの設計から本番運用まで実際に手を動かして学べる講座を用意しています。
>>Docker実践講座の詳細はこちら
3,100名以上が実践した「型」を無料で公開中
プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら
- 前のページへ:Elasticsearch用Dockerfileの設計と起動設定|メモリ制限とJVM設定の調整手順
- この記事の属するカテゴリ:Dockerへ戻る

無料メルマガで学習を続ける
Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。
登録無料・いつでも解除できます