2026年8月21日時点で、Mojo 1.0の公式対応範囲はmacOS 15以降、Apple Silicon M1〜M5、XcodeまたはCommand Line Tools 16以降です。公式のシステム要件を満たしているなら、M1やM2を最初から非対応と判定しないでください。Mojo 1.0 Metal Toolchainエラーは、まずmacOS、Xcodeの参照先、Metal Toolchainの順に切り分けます。最小GPUプログラムが動いた後にMAX serveだけ失敗するなら、再インストールではなくモデルとメモリを調べます。
このページは、すでにmojoコマンドを実行できるのに、Apple GPUやMetalで止まるMac開発者向けです。M1/M2でMAX serveを評価するAIエンジニア、チーム用の再現環境を用意するプラットフォーム担当者にも適しています。
まず「動く」を3つの結論に分けます
典型的には、次のような状態です。
mojoで簡単なコードは実行できます。しかしGPUサンプルでは、Metalデバイスが見つからない、Toolchainがない、またはGPUコンパイルに失敗します。
この場合、結論を一つにまとめてはいけません。
- Mojo言語が動く：ランタイムとパッケージの呼び出しは成立しています。
- Metalを呼び出せる：Apple GPUを使う開発ツールチェーンと最小GPUコードが成立しています。
- 目的のモデルをMAX serveできる：MAXのモデル対応、カーネル、メモリ条件まで満たしています。
最初に保存するのは、mojo --versionの出力、which mojo、which max、xcode-select -p、GPUサンプルの標準出力と標準エラーです。エラーの最後の数行だけでなく、モデル名、コンパイル対象、選択された環境も残してください。これがないまま全環境を削除すると、原因と変更点を同時に失います。
症状から修復先を決める判断リスト
次のチェック項目を上から順に確認してください。チェックが付いた行が、次に実行する作業を決めます。
- [ ]
mojo --versionまたは単純なMojoコードが失敗する
→ Mojo、uv、pixi、Pythonの実体パスを確認します。Metalの調査は後です。 - [ ] Mojoコードは動くが、最小GPUプログラムでデバイスやToolchainが見つからない
→ macOS、XcodeまたはCommand Line Tools、xcode-selectの参照先、Metal Toolchainを確認します。 - [ ] 最小GPUプログラムはApple GPUを認識するが、
MAX serveだけがモデルコンパイルで失敗する
→ MAX 26.5のモデル対応、Apple Silicon向けカーネル、ユニファイドメモリを確認します。 - [ ] M1/M2で、macOS 15以降とXcodeまたはCommand Line Tools 16以降を満たしていない
→ 先にOSまたは開発ツールを更新します。パッケージを削除しても解決しません。 - [ ] ローカルでは再現できるが、チームのMacごとに結果が変わる
→ バージョンとログを固定し、同じ手順を別のApple Silicon環境で再実行します。
決定条件は明確です。 最小GPUプログラムが未成功なら環境修復、最小GPUプログラムが成功してMAX serveだけ失敗するならモデルまたはメモリの調査、両方が成功してチーム内だけ再現しないなら実行環境の統一を選びます。
この判断で重要なのは、GPU検出の失敗とモデル対応の失敗を同じ問題として扱わないことです。
M1/M2の対応確認と環境の境界を先に確定します
Appleのシステム情報、またはターミナルのsystem_profiler SPHardwareDataTypeで、実際のチップとmacOSを確認します。公式要件はmacOS 15以降、Apple Silicon M1〜M5、XcodeまたはCommand Line Tools 16以降です。Mojo 1.0の要件と照合してください。
判断は次の通りです。
- チップがApple Siliconで、macOSとXcodeの要件を満たしている
→ ソフトウェア層の調査へ進みます。 - M1またはM2である
→ それだけを理由にGPU非対応とはしません。MAX 26.5ではApple Silicon GPUの対応がM1まで拡張されています。26.5のリリース説明を確認します。 - macOSまたはXcodeが要件未満である
→ MojoやMAXを入れ直す前に、OS更新、Xcode更新、または別のApple Silicon環境への切り替えを検討します。 - Intel Macである
→ 今回のApple Silicon GPU検証の前提から外れます。Mac上のMojo GPU実行環境として扱わず、別環境を選びます。
ここで止めるべきケースを見逃すと、uvやpixiの環境を何度作り直しても結果は変わりません。
Metal FrameworkとMetal Toolchainを別々に確認します
macOSにMetal Frameworkが存在することと、GPUコードの開発に必要なMetal Toolchainが利用できることは同じではありません。GPUコンパイル段階でToolchainが見つからない場合は、公式手順に従って次のコマンドを実行します。
xcodebuild -downloadComponent MetalToolchain
このコマンドを実行したら、表示だけで成功と判断しません。終了コードを確認し、同じターミナルで最小GPUサンプルを再実行します。MojoのGPU入門にある基本例と同じ層で検証するのが安全です。
切り分けは以下の通りです。
- ダウンロードコマンド自体が失敗する
→ Xcodeの導入状態、権限、接続状態、選択中の開発者ディレクトリを確認します。 - ダウンロードは成功したが、最小GPU例が失敗する
→ Toolchainの参照先かXcode選択が不整合です。 - 最小GPU例が成功する
→ Metal環境は少なくとも基本実行可能です。MAX serveの失敗をMetal故障として扱わないでください。
macOS更新後に突然失敗した場合も同じです。Toolchainを再取得する価値はありますが、再取得後の最小GPU実行が修復の証拠になります。
Xcodeの参照先とCLI Toolsの不整合を直します
Xcodeを複数入れている場合、端末が参照している開発者ディレクトリと、実際に使いたいXcodeが異なることがあります。削除済みの旧Xcodeを指しているケースもあります。
まず状態を記録します。
xcode-select -p
xcodebuild -version
xcrun --find metal
xcode-select -pのパスが存在するか、xcodebuild -versionが意図したXcodeを示すかを確認します。AppleのCommand Line Tools設定手順に沿って、Xcodeの設定とCLI Toolsの選択をそろえてください。
必要なら、使用するXcodeを明示的に選びます。
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
実際のインストール場所が異なる場合は、そのパスに置き換えます。切り替え後にxcodebuild -versionとxcrun --find metalを再確認し、最小GPU例を実行します。ここで直れば、Mojoの再インストールは不要です。
uv、pixi、旧modular環境の混在を分離します
GPUが見えないと思っていても、実際には異なる仮想環境から古いmojoやmaxを呼び出していることがあります。次の出力を一組で保存します。
which mojo
which max
python -c "import sys; print(sys.executable)"
python -m pip list
uvとpixiを同じプロジェクトで使うこと自体が直ちに問題なのではありません。問題は、シェルのPATHが想定外の実行ファイルを先に拾うこと、安定版と開発版を混ぜること、プロジェクトのPythonとMAXの実行環境が分離していることです。
MAX 26.5ではパッケージ構成が分かれています。サービス起動が目的ならmax[serve]、ベンチマークが目的ならmax[benchmark]、用途をまとめるならmax[all]が候補です。MAX Packagesの説明で現在の指定を確認してください。サービス用コンポーネントが入っていない状態を、Metalの故障と誤認しないことが重要です。
環境を作り直す場合も、該当プロジェクトだけを対象にします。ほかのプロジェクトで動いている環境まで削除する必要はありません。
最小GPU成功後はMAX serveの問題として調べます
最小GPUプログラムがApple GPUを認識したら、次はモデル側です。MAXはApple Silicon上ですべてのモデルを同じように扱うわけではなく、対応モデルは限定されています。公式のモデル対応一覧で、対象モデルのアーキテクチャとサポート状況を確認します。
確認する順番は次の通りです。
- 使用モデル名とバージョンをログから確定します。
- モデル一覧に同じアーキテクチャがあるか確認します。
- MAX 26.5でApple Silicon向けの対応変更があるか、変更履歴を確認します。
- エラーがMetal初期化、カーネル選択、モデルグラフ変換のどこで出たかを分けます。
- スワップ発生、ほかのプロセスによるメモリ占有、同時実行数を確認します。
M1/M2でGPUが使えることと、特定モデルをMAX serveできることは別です。モデルグラフのコンパイル失敗は、チップそのものがMojo非対応という意味ではありません。
対処は三つに分かれます。
- 対応モデルで再現できるなら、本機の環境を修復します。
- Metalは正常で対象モデルだけ失敗するなら、Macで対応しやすいモデルへ変更します。
- メモリ不足、端末占有、チーム内再現性が問題なら、より余裕のあるApple Silicon環境へ移します。
修復、モデル変更、環境移行の選択基準
本機の修復を選ぶ条件
- 最小GPUプログラムが失敗している。
- XcodeまたはCLI Toolsの参照先を修正していない。
xcode-select -pと実際に使うXcodeが一致していない。mojoとmaxが想定した仮想環境から呼び出されていない。
この場合は、環境情報を保存してから、Xcodeの参照先、Metal Toolchain、対象プロジェクトの依存関係を順に直します。
モデル変更を選ぶ条件
- 最小GPUプログラムは成功している。
- MAX serveだけがモデルグラフやカーネル選択で失敗している。
- 対象モデルが公式のApple Silicon対応範囲に明記されていない。
- 同じ環境で対応モデルは起動できる。
この場合、Mojoの再インストールを繰り返すより、対応モデル一覧を基準にモデルを選び直す方が合理的です。
Apple Silicon環境の移行を選ぶ条件
- モデル対応は確認できるが、利用可能なユニファイドメモリが不足している。
- ほかのプロセスや開発者による端末占有で再現性がない。
- チーム全員が同じmacOS、Xcode、パッケージ状態を維持できない。
- 短期間の検証や、複数環境での再現確認が目的である。
移行先でも、同じmojo --version、xcode-select -p、Metal Toolchainの終了状態、最小GPUログ、MAX serveログを採取してください。ログの形式をそろえないと、環境を変えても比較できません。
よくある切り分け
M1とM2を非対応と決めつけてよいですか？
いいえ。公式要件はApple Silicon M1〜M5を含みます。M1/M2で最小GPU例が失敗する場合は、まずmacOS、Xcode、Metal Toolchainを確認します。ただし、MAXで利用できるモデル範囲やメモリ条件は別に判定する必要があります。
Metal Toolchainを入れたのにエラーが残る場合は？
取得コマンドの終了状態、xcode-select -p、xcodebuild -versionを確認してください。別のXcodeを参照している、またはCLI Toolsだけが古い状態では、ダウンロード済みでもMojoから正しく見えない場合があります。
macOSやXcodeの更新後に再取得するべきですか？
更新後にGPUコンパイルが失敗した場合は、Metal Toolchainの存在確認と再取得を行う候補になります。ただし、再取得だけで終わらせず、最小GPUプログラムが成功するかで判定します。Frameworkと開発用Toolchainを混同しないでください。
最小GPUプログラムが正常なのにMAX serveが失敗する理由は？
MAXのモデル対応、Apple Silicon向けカーネル、モデルグラフの変換、利用可能なユニファイドメモリを確認します。Metalが正常なら、Mojoのインストール障害として全体を作り直すより、対象モデルを変更する方が早い場合があります。
max[serve]がないことはGPU故障ですか？
必ずしもそうではありません。MAX 26.5では用途別のパッケージ構成になっているため、サービス起動に必要な依存関係が現在の環境にない可能性があります。max[serve]、max[benchmark]、max[all]のどれが必要かを公式パッケージ説明で確認してください。
本機修復とMacHTMLのリモート環境を分けて考えます
最小GPU例まで失敗しているなら、現在のMacのXcodeまたはMetal環境を直すのが先です。一方、Metalは認識するのにMAX serveがモデル、メモリ、端末占有で止まるなら、同じログを使える別のApple Silicon環境へ移した方が調査を続けやすいことがあります。
自前のMacは物理インターフェースや長期の固定負荷に向きますが、OS更新でToolchainの再確認が必要になり、チーム全員のXcodeやパッケージをそろえる負担も残ります。MacHTMLのMacレンタルなら、必要な期間だけ検証環境を用意し、最小GPUログとMAX serveログを比較しながら移行できます。
利用条件を確認したい場合は、MacHTMLのコンソールまたはMacHTMLの料金案内から、用途、必要なチップ世代、メモリ要件、利用期間を照会してください。環境を借りる場合も、最初に取得したログ一式を基準にして、Metal検出とモデル起動を別々に検証するのが安全です。
最終更新：2026年8月21日。Mojo 1.0のシステム要件、MAX Packages、MAX 26.5のリリース情報と変更履歴を確認しています。
Mojo 1.0とGPU環境の検証にMacHTMLをご活用ください
MacHTMLなら、実機に近い環境でGPUの検出や開発ツールの動作を確認できます。 手元の環境を変更せず、リモート接続でモデルのコンパイルや推論処理を検証できます。 必要なときにMacの計算資源を確保できるため、環境構築の手間を抑えて検証を始められます。 開発や検証の用途に合わせてMac環境を選び、安定した作業環境をご利用いただけます。