【UE5】Macで「missing Metal Toolchain」エラーの解決方法

はじめに

Macで久しぶりにUnreal Engine 5（UE5）を起動したところ、次のようなXcode Metalコンパイラのエラーが発生しました。

Xcode Metal コンパイラのエラー： error: cannot execute tool ‘metal’ due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain

このエラーは、UE5がシェーダーのコンパイルに使用する「Metal Toolchain」を見つけられない場合に発生します。

今回は、MacにMetal Toolchainをインストールし、UE5を正常に起動できるようにした手順を紹介します。

UE5でMetal Toolchainエラーが発生した原因

Metalは、Apple製デバイスでグラフィックス処理を行うためのAPIです。UE5をMacで動作させる際にも、Metalと関連する開発ツールが使用されます。

今回の環境では、Xcodeをインストールまたは更新した後、Metal Toolchainが正しくインストールされていなかったことがエラーの原因と考えられます。

また、Xcodeが複数インストールされている場合や、Command Line Toolsが参照先として選択されている場合にも、UE5からXcodeの開発ツールを見つけられないことがあります。

Metal Toolchainをインストールする

最初に「ターミナル」を開き、次のコマンドを実行します。

sudo xcodebuild -downloadComponent MetalToolchain

パスワードを求められた場合は、Macへログインするときに使用しているパスワードを入力します。

なお、パスワードを入力してもターミナル上には文字や記号が表示されませんが、そのまま入力してEnterキーを押せば問題ありません。

実行すると、次のようにMetal Toolchainのダウンロードが開始されます。

Password: Beginning asset download... Downloaded asset to: /System/Library/AssetsV2/com_apple_MobileAsset_MetalToolchain/... Done downloading: Metal Toolchain 17F109.

次のように「Done downloading」と表示されれば、Metal Toolchainのダウンロードは完了です。

バージョン番号や保存先のパスは、XcodeやmacOSのバージョンによって異なります。

Metalコンパイラがインストールされたか確認する

Metal Toolchainのインストール後、次のコマンドを実行します。

xcrun -find metal

私の環境では、次のような結果が表示されました。

/var/run/com.apple.security.cryptexd/mnt/com.apple.MobileAsset.MetalToolchain-v17.6.109.0.9RnGWi/Metal.xctoolchain/usr/bin/metal

このようにMetalコンパイラのパスが表示されれば、Metal Toolchainを認識できています。

何も表示されない場合やエラーになる場合は、次のXcode設定も確認します。

使用するXcodeを指定する

Macに複数のXcodeやCommand Line Toolsが入っている場合は、UE5が参照するXcodeを明示的に指定します。

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

現在選択されているXcodeのパスは、次のコマンドで確認できます。

xcode-select --print-path

次のように表示されれば、通常版のXcodeが選択されています。

/Applications/Xcode.app/Contents/Developer

Xcodeを別のフォルダや別名でインストールしている場合は、実際のXcodeの場所に合わせてパスを変更してください。

Xcodeのライセンスに同意する

Xcodeの更新後は、ライセンスへの同意が完了していないことがあります。

次のコマンドを実行します。

sudo xcodebuild -license accept

エラーが表示されなければ、ライセンスへの同意は完了です。

Xcodeの初期設定を実行する

続いて、Xcodeに必要な追加コンポーネントの初期設定を実行します。

sudo xcodebuild -runFirstLaunch

Appleの公式ドキュメントでも、Xcodeに必要なシステムコンポーネントをインストールする方法として xcodebuild -runFirstLaunch が案内されています。

コマンドの実行が完了したら、一度ターミナルを閉じます。

UE5を再起動する

ここまでの設定が完了したら、UE5を完全に終了してから、もう一度起動します。

今回の環境では、次の手順でMetal Toolchainを正常に認識できるようになりました。

  1. Metal Toolchainをインストールする
  2. Metalコンパイラのパスを確認する
  3. 使用するXcodeを指定する
  4. Xcodeのライセンスに同意する
  5. Xcodeの初期設定を実行する
  6. UE5を再起動する

UE5が起動している状態で設定を変更した場合は、必ずUE5を再起動してください。

それでもエラーが解消しない場合

上記の手順を実行してもエラーが続く場合は、次の点を確認します。

Xcodeが起動できるか確認する

Finderの「アプリケーション」からXcodeを起動します。

追加コンポーネントのインストールやライセンスへの同意を求められた場合は、画面の案内に従って完了させます。

Xcodeのバージョンを確認する

次のコマンドでXcodeのバージョンを確認できます。

xcodebuild -version

UE5のバージョンによって、対応しているmacOSやXcodeのバージョンが異なります。問題が解決しない場合は、Epic Gamesの公式ドキュメントで、使用しているUE5とXcodeの対応状況を確認してください。

Macを再起動する

Metal ToolchainをインストールしてもUE5が認識しない場合は、Macを再起動してから、もう一度UE5を立ち上げます。

まとめ

MacでUE5を起動した際に、次のエラーが表示されることがあります。

cannot execute tool 'metal' due to missing Metal Toolchain

この場合は、まず次のコマンドでMetal Toolchainをインストールします。

sudo xcodebuild -downloadComponent MetalToolchain

その後、Metalコンパイラが認識されているか確認します。

xcrun -find metal

必要に応じて、Xcodeの参照先設定、ライセンスへの同意、初期設定も実行します。

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch

今回の環境では、以上の設定を行うことでUE5のMetal Toolchainエラーを解消できました。

参考資料