Mojo 1.0 Mac findet keine GPU? Metal Toolchain Fehlerbehebung 2026

Mojo läuft, aber die GPU-Erkennung endet mit einem Metal-Fehler oder MAX serve bricht beim Kompilieren ab.

Schnellste Lösung: Beurteilen Sie zuerst die Fehlerstufe. Prüfen Sie macOS, Apple Silicon, Xcode-Pfad und Metal Toolchain, bevor Sie Mojo neu installieren. Erkennt ein minimales GPU-Programm das Gerät, liegt der Fehler meist bei Modellarchitektur, Kernel-Abdeckung oder verfügbarem Arbeitsspeicher – nicht beim M1 oder M2.

Zuletzt aktualisiert am 21.08.2026; Angaben und Befehle wurden gegen die stabile Mojo-1.0-Dokumentation, die MAX-Paketdokumentation, den MAX-26.5-Release und die offiziellen Änderungsnotizen geprüft.

Dieser Beitrag richtet sich an Sie, wenn Sie den Befehl mojo bereits ausführen können, ein GPU-Beispiel aber kein Gerät findet oder einen Metal-Fehler meldet. Er ist außerdem für AI-Entwickler gedacht, die Apple Silicon M1/M2 für MAX serve bewerten, sowie für Plattformverantwortliche, die eine reproduzierbare Mac-Umgebung bereitstellen müssen.

Drei Symptome, drei unterschiedliche Fehlerklassen

Ein typischer Fall sieht zunächst nach einem einzigen Problem aus: Mojo startet, der CPU-Code läuft, aber der GPU-Test endet mit einer Meldung wie „Metal toolchain not found“. Danach wird häufig die gesamte Umgebung gelöscht. Das erschwert die Ursachenanalyse und beseitigt nicht zwingend die eigentliche Fehlkonfiguration.

Behalten Sie bei jedem Test mindestens diese Informationen:

• vollständige Terminalausgabe des Befehls;
• Ausgabe von mojo --version und der verwendeten MAX-Pakete;
• macOS-Version und Chipbezeichnung;
• aktueller Xcode- beziehungsweise Command-Line-Tools-Pfad;
• den ersten vollständigen Metal- oder Compiler-Fehler, nicht nur die letzte Zeile;
• den Namen des Modells und den genauen MAX serve-Befehl.

Ordnen Sie das Ergebnis zunächst so ein:

Fall A: mojo ist nicht verfügbar.
Dann liegt der Fehler in PATH, Umgebung oder Paketinstallation. Metal ist zu diesem Zeitpunkt noch nicht bewiesen oder widerlegt. Prüfen Sie zuerst, ob das Terminal tatsächlich die erwartete virtuelle Umgebung verwendet.

Fall B: Mojo-Programme laufen, aber die Apple GPU bleibt unsichtbar.
Hier sind Systemvoraussetzungen, Xcode-Auswahl, Command-Line-Tools und die zusätzliche Metal Toolchain die ersten Verdächtigen. Ein funktionierender CPU-Test sagt nicht, dass die GPU-Entwicklungswerkzeuge korrekt installiert sind.

Fall C: Der minimale GPU-Test erkennt das Gerät, aber MAX serve scheitert.
Dann ist die Metal-Schicht grundsätzlich erreichbar. Prüfen Sie nun das Modell, die unterstützten Rechenkerne und den verfügbaren Unified Memory. Ein solcher Fehler beweist nicht, dass Mojo auf Apple Silicon M1/M2 unbrauchbar ist.

Diese Trennung ist der wichtigste Entscheidungspunkt: „Mojo kann ausgeführt werden“, „Metal kann angesprochen werden“ und „dieses Modell kann mit MAX serviert werden“ sind drei eigenständige Aussagen.

Unterstützt Ihr M1 oder M2 die GPU-Programmierung überhaupt?

Ja. Die offiziellen Anforderungen für Mojo 1.0 nennen macOS 15 oder neuer, Apple Silicon von M1 bis M5 sowie Xcode oder die entsprechenden Command-Line-Tools ab Version 16. Diese Angaben finden Sie in den offiziellen Systemanforderungen von Mojo 1.0.

Prüfen Sie die reale Maschine statt einer alten Projekt-Dokumentation:

sw_vers
uname -m
system_profiler SPHardwareDataType
xcode-select -p
xcodebuild -version

Achten Sie auf vier Befunde:

1. sw_vers muss ein unterstütztes macOS anzeigen.
2. uname -m sollte auf Apple Silicon typischerweise arm64 liefern.
3. system_profiler muss den tatsächlichen Apple-Chip nennen.
4. xcode-select -p und xcodebuild -version müssen auf eine vorhandene, unterstützte Entwicklungsumgebung zeigen.

Wenn macOS oder Xcode die Mindestanforderung nicht erfüllt, stoppen Sie die Mojo-Fehlersuche. Aktualisieren Sie die Maschine, wählen Sie eine passende Entwicklungsumgebung oder verschieben Sie den Test auf einen kompatiblen Apple-Silicon-Mac. Installieren Sie nicht gleichzeitig mehrere Ersatzpakete, um eine nicht erfüllte Systemvoraussetzung zu umgehen.

Wichtig für die M1/M2-Entscheidung: MAX 26.5 hat die Apple-Silicon-GPU-Unterstützung wieder bis M1 erweitert. Das wurde in den offiziellen MAX-26.5-Änderungen und den Release-Informationen zu MAX 26.5 dokumentiert. „GPU nicht gefunden“ darf deshalb nicht automatisch als „alter Chip wird nicht mehr unterstützt“ interpretiert werden.

Metal Framework oder Metal Toolchain: Wo liegt der Unterschied?

macOS bringt das Metal Framework mit. Das reicht jedoch nicht in jedem Entwicklungsfall für die GPU-Kompilierung von Mojo. Die separat benötigte Metal Toolchain stellt zusätzliche Werkzeuge bereit. Ein vorhandenes Metal Framework und eine funktionierende Metal Toolchain sind daher kein identischer Befund.

Wenn der Fehler ausdrücklich ein fehlendes Metal-Werkzeug nennt oder die GPU-Kompilierung an dieser Stelle abbricht, führen Sie den offiziellen Download-Befehl aus:

xcodebuild -downloadComponent MetalToolchain

Der Befehl muss in einer Umgebung ausgeführt werden, in der xcodebuild auf eine gültige Xcode-Installation oder die von Apple vorgesehene Entwicklungsumgebung zeigt. Verlassen Sie sich nicht auf eine Meldung wie „Download abgeschlossen“. Prüfen Sie anschließend den Exit-Status:

echo $?

Ein Wert 0 zeigt nur, dass dieser konkrete Befehl erfolgreich beendet wurde. Er beweist noch nicht, dass Mojo die GPU verwenden kann. Führen Sie danach erneut das kleinste verfügbare Mojo-GPU-Beispiel aus. Die offizielle Mojo-GPU-Einführung ist dafür die maßgebliche Referenz.

Nach einer macOS- oder Xcode-Aktualisierung kann die Toolchain erneut relevant werden. Das bedeutet nicht zwangsläufig, dass jede Mojo-Komponente neu installiert werden muss. Entscheidend ist, ob der Metal-Test vor dem Update funktionierte, welcher Xcode-Pfad aktuell gewählt ist und ob der Download-Befehl ohne Fehler endet.

Hinweis: Eine erfolgreiche Toolchain-Installation ohne anschließenden GPU-Test ist nur ein Zwischenbefund. Erst die Kombination aus korrektem Exit-Status, reproduzierbarem Mojo-GPU-Beispiel und sichtbarem Apple-GPU-Gerät bestätigt die Reparatur.

Xcode-Pfad und Command-Line-Tools sauber abgleichen

Mehrere Xcode-Versionen, ein gelöschtes altes Xcode-Verzeichnis oder ein System-Upgrade führen häufig dazu, dass das Terminal auf eine nicht mehr vorhandene Entwicklerumgebung zeigt. Mojo kann dabei weiterhin aus einer virtuellen Umgebung starten. Genau diese Mischung macht den Fehler schwer erkennbar.

Prüfen Sie zunächst:

xcode-select -p
xcodebuild -version
ls -ld "$(xcode-select -p)"

Wenn der angezeigte Pfad nicht existiert oder eine unerwartete Xcode-Version meldet, korrigieren Sie die Auswahl. Bei einer vollständigen Xcode-Installation kann der Pfad beispielsweise so gesetzt werden:

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

Verwenden Sie diesen Pfad nur, wenn die Installation dort tatsächlich vorhanden ist. Prüfen Sie danach erneut:

xcode-select -p
xcodebuild -version

Apple beschreibt die Auswahl und Konfiguration der Command-Line-Tools in der offiziellen Xcode-Dokumentation. Folgen Sie bei abweichenden Installationsorten den dort beschriebenen Einstellungen, statt Pfade aus einem anderen Projekt zu übernehmen.

Typische Anzeichen für einen Pfadfehler sind:

• xcodebuild meldet eine fehlende Lizenz oder eine nicht vorhandene Entwicklerinstallation;
• der Metal-Download wird gegen eine alte Xcode-Version ausgeführt;
• der GPU-Fehler erscheint direkt nach einem Xcode-Wechsel;
• GUI und Terminal verwenden unterschiedliche Entwicklerpfade.

Nach der Korrektur sollten Sie nicht sofort alle virtuellen Umgebungen neu bauen. Wiederholen Sie zuerst den Metal-Download, den minimalen GPU-Test und erst danach den MAX-Aufruf. So bleibt sichtbar, welche Schicht tatsächlich repariert wurde.

Stimmen uv, pixi, Mojo und MAX aus derselben Umgebung?

Ein weiterer Fehler entsteht, wenn das Terminal nicht das Paket verwendet, das Sie gerade aktualisiert haben. mojo, max, Python und die virtuelle Umgebung können aus verschiedenen Installationspfaden stammen. Das betrifft besonders Projekte, die zwischen uv, pixi, globalen Paketen und einer älteren Modular-Umgebung wechseln.

Ermitteln Sie die tatsächlichen Programme:

which mojo
which max
which python
python -c "import sys; print(sys.executable)"

Ergänzen Sie, falls verfügbar, die jeweiligen Versionsbefehle:

mojo --version
max --version
python --version

Vergleichen Sie diese Pfade mit der aktivierten Umgebung. Wenn mojo aus einem globalen Verzeichnis kommt, Python aber aus einem Projekt-Environment, ist ein Versionsmix wahrscheinlicher als ein Metal-Defekt.

MAX 26.5 verwendet eine aufgeteilte Paketstruktur. Prüfen Sie deshalb, welche Funktion Sie tatsächlich benötigen:

• max[serve] für den Serve-Dienst;
• max[benchmark] für Benchmark-Aufgaben;
• max[all], wenn mehrere MAX-Komponenten in derselben Umgebung gebraucht werden.

Die MAX-Paketübersicht beschreibt diese Aufteilung. Fehlt serve, kann der Start des Dienstes scheitern, obwohl die GPU korrekt erkannt wird. Dieser Fehler ist dann ein fehlendes Paket oder ein falscher Environment-Aufruf – keine Metal Toolchain.

Gehen Sie beim Bereinigen begrenzt vor:

1. Aktivieren Sie das betroffene Projekt-Environment.
2. Notieren Sie die aktuellen Pfade und Versionen.
3. Entfernen Sie nur die widersprüchliche Installation in diesem Environment.
4. Erstellen Sie die Umgebung mit einer eindeutig festgelegten Paketquelle neu.
5. Installieren Sie nur die benötigten MAX-Komponenten.
6. Wiederholen Sie zuerst den Mojo-GPU-Test.
7. Starten Sie erst danach MAX serve.

Löschen Sie nicht vorsorglich alle Projekte auf dem Mac. Eine funktionierende Umgebung ist zugleich ein Vergleichspunkt und kann zeigen, ob der Fehler projektbezogen ist.

Die passende Reparatur nach Fehlerklasse

Nutzen Sie diese Prüfliste, bevor Sie Pakete entfernen:

• [ ] mojo --version funktioniert in der erwarteten virtuellen Umgebung.
• [ ] which mojo, which max und which python zeigen auf zusammengehörige Projektpfade.
• [ ] sw_vers bestätigt macOS 15 oder neuer.
• [ ] system_profiler SPHardwareDataType bestätigt Apple Silicon.
• [ ] xcode-select -p zeigt auf eine vorhandene Entwicklerinstallation.
• [ ] xcodebuild -version bestätigt Xcode oder Command-Line-Tools ab Version 16.
• [ ] xcodebuild -downloadComponent MetalToolchain endet mit Exit-Status 0.
• [ ] Das minimale Mojo-GPU-Beispiel erkennt das Apple-GPU-Gerät.
• [ ] Für den Serve-Test ist max[serve] in derselben Umgebung installiert.
• [ ] Das Zielmodell ist in der offiziellen MAX-Modellübersicht für die verwendete Umgebung berücksichtigt.
• [ ] Der vollständige Modell-Compile-Fehler ist zusammen mit Versionen und Pfaden gesichert.

Die Auswertung ist eindeutig:

• Ein Punkt bis einschließlich Toolchain fehlt: Reparieren Sie die lokale Entwicklungsumgebung und wiederholen Sie den minimalen GPU-Test.
• Alle Basispunkte sind erfüllt, aber das GPU-Beispiel scheitert: Prüfen Sie erneut Xcode-Pfad, Metal-Fehler und Systemgrenzen; installieren Sie nicht sofort MAX neu.
• Der GPU-Test funktioniert, aber MAX serve scheitert: Prüfen Sie max[serve], Modellarchitektur, Kernel-Abdeckung und Unified Memory.
• Nur ein Modell scheitert: Testen Sie eine unterstützte Modellvariante oder wechseln Sie das Modell.
• Mehrere Teammitglieder benötigen dieselbe Umgebung: Reproduzieren Sie den Test auf einem separaten Apple-Silicon-Mac mit identischem Log-Schema.

Damit lautet die operative Entscheidung: Umgebung reparieren, wenn die Basistests scheitern; Modell oder MAX-Komponente ändern, wenn nur der Serve-Schritt scheitert; auf eine andere Apple-Silicon-Umgebung wechseln, wenn Speicher, Auslastung oder Reproduzierbarkeit die lokale Maschine begrenzen.

Der minimale GPU-Test entscheidet zwischen Umgebung und Modell

Führen Sie die Tests in dieser Reihenfolge aus:

1. System erfassen: sw_vers, uname -m und system_profiler SPHardwareDataType ausführen.
2. Entwicklerpfad prüfen: xcode-select -p und xcodebuild -version ausführen.
3. Metal Toolchain nach Bedarf installieren: xcodebuild -downloadComponent MetalToolchain.
4. Exit-Status prüfen: direkt danach echo $? ausführen und die Ausgabe sichern.
5. Mojo-GPU-Beispiel starten: den offiziellen Einführungs-Code ohne eigene Modelländerungen ausführen.
6. Ergebnis klassifizieren: Gerät sichtbar oder nicht sichtbar.
7. MAX isoliert testen: erst jetzt max[serve] und das Zielmodell prüfen.
8. Logs bündeln: Versionen, Pfade, Modellname und vollständigen Fehler gemeinsam dokumentieren.

Wenn Schritt 5 erfolgreich ist, sollten Sie nicht wieder zu Schritt 3 springen, nur weil MAX serve einen Compilerfehler meldet. Prüfen Sie stattdessen die Modellkompatibilität, die Paketaufteilung von MAX 26.5 und den verfügbaren Arbeitsspeicher.

Wenn Schritt 5 fehlschlägt, verwenden Sie den Fehlertext als Beleg. „GPU nicht gefunden“ kann auf einen falschen Entwicklerpfad, eine fehlende Metal Toolchain oder eine nicht erfüllte Systemvoraussetzung zurückgehen. Der Chipname allein liefert diese Erklärung nicht.

Wann sollten Sie reparieren, das Modell wechseln oder den Mac wechseln?

Nach dem Test gibt es drei belastbare Wege.

Lokale Umgebung reparieren
Wählen Sie diesen Weg, wenn macOS, Chip und Xcode kompatibel sind, aber Pfad, Toolchain oder virtuelle Umgebung inkonsistent sind. Für wiederholbare Abläufe dokumentieren Sie die Befehle und die vollständigen Versionen. Eine kurze interne Anleitung kann anschließend in der MacHTML-Hilfe für Entwicklungsumgebungen mit Ihren Teamkonventionen abgeglichen werden.

Modell oder MAX-Aufruf ändern
Wählen Sie diese Option, wenn der minimale GPU-Test erfolgreich ist und nur das Zielmodell beim Graph-Compile scheitert. Prüfen Sie zuerst die offizielle Modellübersicht. Ein Modellwechsel ist oft sinnvoller als wiederholtes Neuinstallieren von Mojo, wenn die benötigte Architektur auf Apple Silicon nicht abgedeckt ist.

Apple-Silicon-Umgebung mit mehr Reserven verwenden
Das ist angemessen, wenn Unified Memory, parallele Teamtests, Gerätekonkurrenz oder reproduzierbare Remote-Ausführung die lokale Maschine begrenzen. Halten Sie beim Wechsel dieselben Logs und denselben minimalen GPU-Test bereit. So vergleichen Sie nicht nur „läuft“ gegen „läuft nicht“, sondern sehen, ob der Fehler mit der Umgebung oder mit dem Modell wandert.

Die frühere Annahme, der Mojo-Compiler und die Toolchain würden erst später vollständig geöffnet, ist für den Stand nach ModCon 2026 nicht mehr maßgeblich: Die vollständige Öffnung wurde am 18.08.2026 offiziell angekündigt. Das ändert jedoch nichts daran, dass Modellabdeckung und Apple-Silicon-Unterstützung in MAX getrennt bewertet werden müssen. Eine Konferenzankündigung ist kein Beleg dafür, dass jedes genannte Projekt bereits als Mac-Funktion allgemein verfügbar ist.

Wenn Sie Ihre Diagnose anschließend in einer kontrollierten Umgebung wiederholen möchten, können Sie über die MacHTML-Konsole für entfernte Mac-Umgebungen dieselben Prüfungen mit identischem Log-Schema durchführen. Achten Sie bei Teamzugriffen auf getrennte Konten, minimale Rechte und eine DSGVO-konforme Protokollierung sensibler Modell- oder Zugangsdaten.

Für einen einmaligen Test ist eine gemietete Apple-Silicon-Umgebung oft praktischer als ein sofortiger Hardwarekauf: Sie vermeiden die Vorlaufzeit für ein zusätzliches Gerät, können eine Umgebung mit mehr Arbeitsspeicher gezielt für die Reproduktion anfordern und müssen die Maschine nicht dauerhaft administrieren. Die Nachteile Ihrer bisherigen lokalen Lösung bleiben aber real: begrenzter Unified Memory, belegte GPU durch andere Prozesse und schwer reproduzierbare Teamzustände. Wenn genau diese drei Punkte Ihren MAX-Test blockieren, ist MacHTML als zeitlich begrenzte Testumgebung die sachlichere Option. Für dauerhaft hohe Last, lokale Peripherie oder zwingenden physischen Gerätezugriff bleibt ein eigener Mac die bessere Wahl.