DockerfileのplatformでLinux/amd64を指定する方法|マルチアーキテクチャ対応の基本

運営:リナックスマスター.JP(代表 宮崎智広)
HOME > Linux技術 リナックスマスター.JP(Linuxマスター.JP) > Docker > DockerfileのplatformでLinux/amd64を指定する方法|マルチアーキテクチャ対応の基本
「MacでビルドしたDockerイメージをLinuxサーバーに持っていったら起動しない。」
こういった経験はありませんか。

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を固定できる


「このままじゃマズい」と感じていませんか?
参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら

なぜ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

この指定をすると、ビルドするホストがlinux/arm64(AppleシリコンのMac)であっても、linux/amd64のubuntu:24.04レイヤーを取得してビルドします。

「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

これらの引数はFROM命令の前で宣言するか、FROM命令の後でステージごとに宣言します。
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

この警告は「ホスト(ARM Mac)のアーキテクチャと取得したイメージのアーキテクチャが違う」という意味です。
警告が出ても動く場合は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}}' イメージ名
DockerfileのplatformはFROM命令のオプションとして書くか、Docker ComposeのplatformキーとしてComposeファイルに書くかの2通りの方法で指定できます。

ARMアーキテクチャのMacで開発していて本番がlinux/amd64のLinuxサーバーという環境では、Dockerfileにplatformを明記しておくと、チームメンバーがアーキテクチャの違いを意識せずに本番と同じアーキテクチャのイメージをビルドできます。

【注意】FROM --platform=linux/amd64 をARMのMac上でビルドする場合、QEMUエミュレーションを使って実行するため、ネイティブビルドより時間がかかります。
CIパイプラインでビルドする場合は、linux/amd64のランナーを使うか、docker buildxのクロスコンパイル(--platform linux/amd64)を組み合わせるとビルド時間を短縮できます。
現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、
Dockerコンテナの設計から本番運用まで実際に手を動かして学べる講座を用意しています。
>>Docker実践講座の詳細はこちら

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。

姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら

Linux無料マニュアル(図解60P) 名前とメールで30秒登録

運営

リナックスマスター.JP(代表 宮崎智広)

株式会社イーネットマーキュリーが運営するLinux教育サイトです。代表の宮崎智広は現役のLinuxサーバー管理者として20年以上の実務経験を持ち、累計3,100名以上のエンジニアを指導してきました。実践型のLinuxセミナーや無料マニュアルの配布を通じてLinux人材の育成に取り組んでいます。