DevOps / CI/CD

DockerイメージがApple Siliconで動かない:2026年の修正

DockerイメージがApple Siliconで動かない:2026年の修正

Docker公式ドキュメントは、マルチプラットフォームの対象として linux/arm64 と linux/amd64 を扱っています。公式のマルチプラットフォーム説明でも確認できるこの2系統を最初に照合するのが入口です。勝者は原生arm64またはマルチプラットフォーム版です。amd64シミュレーションは、一時的な故障切り分けにだけ使うのが安全です。

この判断が必要な読者

Apple Silicon上でDockerの科研プロジェクトを再現したい研究生、amd64/arm64の両方を保守する開発者が対象です。Macのない研究室で、容器化した解析環境を納品・検収する課題責任者にも適しています。

起動したかどうかだけで合格にすると、論文再現や共同研究の引き継ぎで問題が残ります。確認すべき対象は、ホスト、DockerのLinux仮想環境、イメージ、コンテナ内バイナリの4層です。

DockerイメージがApple Siliconで動かないとき、最初に分ける故障

「イメージを取得できた」ことは、実行互換性の証明ではありません。Apple Siliconのホスト上でDockerを使う場合、次の3つを混同しないことが重要です。

  • イメージのプラットフォーム:manifestにlinux/arm64があるか。
  • コンテナ内の実行ファイル:ELFバイナリやネイティブ拡張がarm64か。
  • ビルド時の依存関係:Python、R、システムパッケージ、外部ツールが対象CPU向けに解決されているか。

まず、対象イメージの一覧を確認します。

docker manifest inspect IMAGE:TAG
docker buildx imagetools inspect IMAGE:TAG

manifestの確認方法はDocker manifest inspectの公式リファレンスに、イメージ詳細の表示方法はDocker imagetools inspectの公式リファレンスに整理されています。

判定は次のように分けます。

  • linux/arm64のみ:Apple Siliconでの原生実行を優先します。
  • linux/arm64とlinux/amd64の両方:自動選択を利用しつつ、各成果物を別々に検収します。
  • linux/amd64のみ:シミュレーションで短期診断はできますが、長期の科研基準環境にはしません。
  • manifestは対応しているが起動しない:内部バイナリ、動的ライブラリ、起動スクリプトへ調査を移します。

原生実行とamd64シミュレーションの違い

--platform linux/amd64を指定して起動すると、Dockerがamd64向けの経路を選べる場合があります。しかし、これはApple Silicon上でamd64のプログラムを原生実行していることを意味しません。AppleはLinux仮想マシン内でIntelバイナリを変換する仕組みについて、互換性と制約を説明しています。AppleのIntel Linuxバイナリに関する資料も確認が必要です。

症状ごとの優先順位は次のとおりです。

  • 起動直後に終了する:完全な標準出力と標準エラーを保存し、entrypoint、環境変数、対象CPUを確認します。
  • Illegal instructionが出る:コンテナ内バイナリやネイティブ拡張の命令セットを疑います。再起動を繰り返しても修復にはなりません。
  • ファイル監視が反応しない:Linux VM、共有ディレクトリ、監視方式の組み合わせを分離して再現します。
  • 解析だけ異常に重い:シミュレーション経路を疑います。ただし、速度差を数値で断定するにはプロジェクトの測定記録が必要です。

シミュレーションは「同じエラーが出るか」を調べる道具です。科研結果の基準環境や常用のCI実行環境として採用する前に、原生arm64または実機のamd64環境と比較してください。

依存パッケージの失敗は、イメージの問題とは限らない

コンテナが起動しても、依存関係の導入で止まることがあります。ここではエラーの種類を混ぜずに記録します。

  • パッケージマネージャーが候補を見つけられない。
  • ソースコードのコンパイルで失敗する。
  • 共有ライブラリのロード時に失敗する。
  • 取得した事前コンパイル済みファイルのCPUが合わない。

修復は、次の順番が安全です。

  1. arm64を明示的に含むベースイメージへ変更します。
  2. PythonやRの依存ファイルを固定し、解決されたパッケージの対象CPUを記録します。
  3. arm64向けの配布物がない依存だけを、ソースビルドまたは代替パッケージへ切り替えます。
  4. 共有ライブラリの検索パスとロード結果をログへ残します。
  5. クリーンなビルドで、キャッシュ由来の成功を排除します。

「インストールできた」という結果だけでは不十分です。研究用の外部ツールが実際に呼び出され、入力から期待する出力まで処理できるかを確認します。

Docker Buildxで直す場合と、直らない場合

Docker Buildxは、arm64とamd64のイメージをまとめて構築するための有力な選択肢です。ただし、対象プラットフォームを指定するだけでDockerfile内部の問題まで解決するわけではありません。Buildxのマルチプラットフォーム構築手順とbuildx buildの公式仕様を基準にします。

docker buildx build \
  --platform linux/arm64,linux/amd64 \
  -t registry.example/project:tag \
  --push .

このコマンドを使う前に、次を確認します。

  • FROMが単一CPU向けのベースイメージを固定していないか。
  • ダウンロードURLにamd64の文字列を直書きしていないか。
  • ビルド段階で実行するツールが、ビルド機ではなく対象CPU向けになっているか。
  • 最終段階へ、別プラットフォームの生成物をコピーしていないか。
  • arm64とamd64のログ、digest、実行ファイル情報を別々に保存しているか。

BUILDPLATFORMはビルドを実行する側、TARGETPLATFORMは成果物の対象側を表します。Dockerのビルド変数資料の役割を確認し、クロスコンパイルの設計に反映します。単純な変数追加では、依存パッケージやダウンロードスクリプトのCPU固定までは解除できません。

対照リスト:どの修正を選ぶか

  • arm64版が公式に提供されている
    原生arm64へ移行します。長期運用、CI、研究成果の提出に向きます。
  • 両方の版を公開できる
    Buildxでマルチプラットフォーム化し、manifestと各成果物を検収します。
  • amd64版しかなく、まず障害を再現したい
    シミュレーションを短期間使います。結果の再現性は別途判定します。
  • 依存ソフトがarm64に対応していない
    無理に移行せず、Linux基準環境を保持します。Apple Silicon側は補助検証に限定します。

5段階で行う科研用の合格判定

次のチェックリストは、起動確認で終わらせないための最小手順です。

  • [ ] イメージdigestを固定し、linux/arm64とlinux/amd64のmanifestを保存する。
  • [ ] 実行コマンド、環境変数、マウント先、入力データを記録する。
  • [ ] 起動ログ、依存導入ログ、終了コードをファイルへ書き出す。
  • [ ] コンテナ内の主要バイナリとネイティブ拡張の対象CPUを確認する。
  • [ ] 乱数seed、入力ファイル、外部ツールの版、数値ライブラリを固定する。
  • [ ] 原生arm64、amd64シミュレーション、研究室のLinux基準環境を同じ入力で比較する。
  • [ ] 出力ファイル、主要な中間値、エラー内容をプロジェクトの許容条件で判定する。
  • [ ] 検証後に一時データ、認証情報、キャッシュを削除する。

Docker Desktop自体の対応状況や既知の問題は、Docker DesktopのMac向けインストール要件と公式の既知の問題一覧で確認します。Docker側の更新後は、以前成功した結果をそのまま基準にせず、digestを固定した再検証が必要です。

FAQ:Apple Silicon向けDocker検証の分岐点

Apple Siliconでアーキテクチャ不一致になる理由

ホストのCPUとイメージの対象CPUが同じとは限りません。さらに、コンテナ内の実行ファイルやネイティブ拡張が別アーキテクチャのまま残ることもあります。取得成功ではなく、manifest、実行ファイル、依存ライブラリを順に確認します。

amd64専用の科研イメージを使う条件

短期の障害再現なら、amd64を指定したシミュレーションを候補にできます。ただし、ファイル監視、ネイティブ拡張、数値出力、外部ツールの挙動は別途確認します。研究成果の基準環境として固定する場合は、原生arm64版か実機のamd64環境を優先します。

Docker Buildxで2種類のイメージを作る方法

--platform linux/arm64,linux/amd64を指定し、Dockerfileのベースイメージ、ダウンロード処理、ビルド段階を点検します。Buildxの完了表示だけで合格にせず、manifestの対象、各イメージのdigest、コンテナ内バイナリの形式を分けて保存します。

Macがない研究室の検証方法

Apple Siliconの実機へ接続できる隔離環境を一時的に用意し、クリーンな状態から同じdigestを実行します。コマンド、入力、ログ、出力を研究室のLinux環境と比較すれば、Mac固有の障害を切り分けられます。長期契約や機器購入は、その検証結果を見て判断します。

シミュレーション成功と再現性の関係

シミュレーションで終了コードが正常でも、科研結果の一致は証明できません。seed、入力、数値ライブラリ、外部ツール、出力差分を確認し、プロジェクト固有の許容範囲で判定します。比較記録がない場合は「起動確認済み」と表現し、「再現済み」とは書きません。

最後に選ぶべき環境

現在のLinux基準環境は、Apple Silicon固有の起動不具合を直接再現できないことがあります。Windows環境は実験室の既存資産を活用しやすい一方、macOS上のDocker動作、Apple Siliconのarm64依存、Mac固有の共有処理を同じ条件で確認できません。amd64シミュレーションも、ネイティブ互換性や科研結果の一致を保証するものではありません。

そのため、故障がApple Silicon上でのみ発生すると確認できた段階では、まず実機のMacを使った隔離検証が合理的です。ProxyMacの日本語向け利用案内を確認し、必要な期間だけ遠隔のMac環境を確保して、イメージdigest、完全なログ、出力差分を保存します。検証後に継続利用が必要か、研究室での購入が妥当かを判断する順番なら、不要な設備投資を先に固定せずに済みます。料金条件を比較する場合は、日本向け料金案内で最新情報を確認してください。

Apple Silicon対応の検証環境を、必要なときに

ProxyMacなら、Macをリモートで利用し、arm64向けイメージの動作確認を実機環境で進められます。
手元に対応するMacがない場合でも、遠隔操作でビルドや実行結果を確認し、原因を切り分けられます。