リンクをコピーしました

【UE5 Mac】Xcode Metal Compiler error の解決方法｜Metal Toolchain のダウンロード手順

はじめに

久しぶりに Unreal Engine 5.6.1 を起動しようとしたところ、**Xcode から「Xcode Metal Compiler error」**が表示されて「？」ってなりました。

Xcode Metal Compiler error: error: error: cannot execute tool 'metal due to
missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain

本記事では、このエラーの解決した方法を解説します。
Mac で Unreal Engine を開発している方を対象としています。

Xcode Metal Compiler errorのエラー画面（Xcode）

ヒントになったのは、Stack Overflow のスレッドです。同じ症状で困っている方は参考にしてみてください。

なぜこのエラーが出るのか

Xcode 16以降、Appleは Xcode.app 本体のサイズを抑えるために、Metal Toolchain（.metal シェーダーをコンパイルするためのツール群）をXcode本体から切り離し、必要になったタイミングで別途ダウンロードする方式に変えています。
そのため、以前のXcodeなら最初から使えていたMetalコンパイラが、新しいXcodeでは「初回だけ追加ダウンロードが必要」になった、というのがこのエラーの正体です。
UE5はビルド時に内部でMetalシェーダーのコンパイルを行うため、Toolchain未ダウンロードの状態だとこのエラーで止まります。
つまりUE5固有のバグというより、Xcode側の配布方式変更にUE5のビルドプロセスが引っかかった形です。

Xcode Metal Compiler error の解決手順

Step 1: Xcode を開き Metal Toolchain をダウンロードする

  1. Xcode を起動します
  2. メニューから Xcode → Settings → Components を開きます
  3. Download Metal Toolchain 26.X.X をクリックしてダウンロードを開始します
Xcode Settings - Components で Metal Toolchain をダウンロード

ポイント: Metal Toolchain のバージョン番号（26.X.X）は、お使いの Xcode のバージョンにより異なります。

Step 2: ダウンロード完了を確認する

ダウンロードが完了すると、Metal Toolchain の横にチェックマークなどが出るはずです。

Metal Toolchain ダウンロード完了の確認画面

Step 3: UE5 エディタを起動して確認する

  1. Xcode をいったん終了します
  2. Unreal Engine 5 のエディタを起動します
  3. Metal Compiler error が表示されず、正常に起動すると思います

筆者の環境では、macやUE5の再起動は不要でした。
Xcodeを閉じてかUE５のエディターの起動ボタンから起動するだけで解消しました。

それでも直らないとき

  • xcodebuild -downloadComponent MetalToolchain をターミナルから直接実行し、コマンドライン側でダウンロードを試す
  • Xcodeのバージョンとコマンドラインツール（xcode-select -p で確認）が食い違っていないか確認する
  • 会社・大学のネットワークなど、Appleの配布サーバーへのアクセスが制限されている環境では、ダウンロード自体が止まることがあるので回線を変えて試す

関連リンク