リンクをコピーしました

結論: Xcode → Settings → Components から Metal Toolchain をダウンロードして、Xcodeを閉じてからUEを起動し直せば直ります。
ターミナルなら xcodebuild -downloadComponent MetalToolchain でも入ります。Xcodeを上げたあとに再発したときも、対処は同じです。

はじめに

久しぶりに 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 のスレッドです。同じ症状で困っている方は参考にしてみてください。

追記(2026-09-27): Xcode 27 × UE 5.8 でも再発した

Xcode 27 に更新して、また UE 5.8 を立ち上げようとしたら、同じエラーが出ました。

「またこれかよ」と思った方、多いんじゃないでしょうか。僕だけだろうか。

と思いながら、この記事の手順どおりにやったら直りました。
起動スプラッシュに乗ったエラーはこんな感じです。

Unreal Editor 5.8.3 起動時の Xcode Metal Compiler error

Xcode を上げたあとも、下の手順で Metal Toolchain を入れ直せば同じ対処で通ります。

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

Xcode 16以降、Appleは Xcode.app 本体のサイズを抑えるために、Metal Toolchain(.metal シェーダーをコンパイルするためのツール群)をXcode本体から切り離し、必要になったタイミングで別途ダウンロードする方式に変えています。
そのため、以前のXcodeなら最初から使えていたMetalコンパイラが、新しいXcodeでは「初回だけ追加ダウンロードが必要」になった、というのがこのエラーの正体です。
Xcodeを上げたあとに、また同じ画面が出ることもあるので、そのたびにToolchainを入れ直す必要があります。
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(表示されているバージョン番号)をクリックしてダウンロードを開始します
Xcode Settings - Components で Metal Toolchain をダウンロード

ポイント: Metal Toolchain のバージョン番号(26.X.X や 27.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を閉じてかUE5のエディターの起動ボタンから起動するだけで解消しました。

それでも直らないとき

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

UE5とXcodeを両方入れると、Macのストレージはかなり圧迫されます。空きが厳しいなら、プロジェクトやキャッシュ用に外付けSSDを足す手もあります。
AI需要で値動きの大きいキオクシアのSSDも選択肢になります。買う前に価格と容量は見比べてください。

関連リンク