Mojo 1.0 Mac : GPU introuvable ? 2026 Metal Toolchain dépannage

Le programme Mojo s’exécute, mais le GPU Apple reste invisible ou renvoie une erreur Metal Toolchain.

Solution la plus rapide : ne condamnez pas votre M1 ou votre M2. Vérifiez d’abord macOS, le chemin Xcode et le composant Metal Toolchain ; si le test GPU minimal passe, cessez de réinstaller Mojo et examinez plutôt MAX, le modèle et la mémoire disponible.

Dernière mise à jour : 21 août 2026. Les exigences et la matrice Apple Silicon ont été vérifiées dans la documentation officielle des prérequis Mojo, les notes de version de MAX 26.5 et la documentation des modèles MAX.

Cette page s’adresse aux développeurs Mac qui peuvent déjà lancer mojo, mais obtiennent une erreur de périphérique ou de compilation Metal. Elle vise aussi les ingénieurs qui évaluent MAX serve sur Apple Silicon M1/M2, ainsi que les responsables de plateforme qui doivent fournir un environnement reproductible à une petite équipe.

Trois couches à ne pas confondre

Un diagnostic Mojo 1.0 sur Mac devient beaucoup plus simple lorsque vous séparez trois conclusions :

• Mojo fonctionne : la commande est installée, le gestionnaire de paquets trouve le bon environnement et un programme de base s’exécute.
• Metal est accessible : le compilateur peut utiliser le composant Metal Toolchain et un exemple GPU minimal peut identifier le périphérique Apple.
• Le modèle peut être servi : MAX serve reconnaît l’architecture du modèle, compile son graphe et dispose des noyaux ainsi que de la mémoire nécessaires.

Ces résultats sont indépendants. Un succès au premier niveau ne prouve pas les deux autres. À l’inverse, un échec de MAX serve ne démontre pas que le GPU est absent.

Conservez avant toute modification :

• la sortie de mojo --version ;
• la sortie de xcode-select --print-path ;
• la version macOS et le modèle exact du Mac ;
• la commande MAX complète ;
• les lignes d’erreur depuis le premier avertissement jusqu’à l’arrêt du processus.

Ne copiez pas uniquement la dernière ligne. Une erreur « outil introuvable » appelle une vérification du chemin. Une erreur de compilation de graphe appelle une analyse du modèle. Ces deux cas peuvent se terminer par un message similaire, mais ne se corrigent pas de la même manière.

Le programme GPU de référence doit rester votre point de comparaison. La documentation Mojo consacrée au premier programme GPU permet de vérifier l’appel au GPU sans ajouter immédiatement la complexité d’un serveur d’inférence.

Prérequis système et puce Apple Silicon

La première règle est stricte : si le système ou la puce ne satisfait pas les prérequis officiels, arrêtez le dépannage logiciel. Mojo 1.0 prend en charge macOS 15 ou une version ultérieure, les puces Apple Silicon M1 à M5, ainsi que Xcode ou les outils en ligne de commande en version 16 ou ultérieure, selon la page officielle des exigences Mojo.

Cela signifie qu’un Mac Apple Silicon M1/M2 appartient à la plage officiellement compatible. Un message indiquant que le GPU n’est pas détecté ne doit donc pas être traduit automatiquement par « ancien matériel abandonné ». Il faut distinguer :

• un système macOS trop ancien ;
• un Xcode installé, mais non sélectionné ;
• les outils en ligne de commande absents ou dirigés vers une ancienne installation ;
• un composant Metal Toolchain manquant ;
• un modèle MAX non couvert sur Apple Silicon.

Dans « Informations système », relevez le nom du processeur et la version de macOS. Dans le terminal, contrôlez ensuite l’outil développeur actif :

sw_vers
uname -m
xcode-select --print-path
xcodebuild -version

La commande uname -m aide à confirmer que le terminal utilise bien l’architecture attendue. Le chemin renvoyé par xcode-select doit pointer vers une installation Xcode valide ou vers le répertoire des outils en ligne de commande. Pour les règles de sélection des outils, reportez-vous à la documentation Apple sur la configuration des outils en ligne de commande.

Si macOS ou Xcode est trop ancien, trois choix sont raisonnables :

1. mettre à niveau le système et les outils, après avoir vérifié les contraintes de vos autres projets ;
2. isoler Mojo dans un autre environnement Apple Silicon compatible ;
3. utiliser temporairement un Mac Apple Silicon distant pour reproduire le problème.

Réinstaller Mojo avant de régler une version système insuffisante ne change rien. Vous risquez seulement de remplacer un message explicite par une chaîne d’erreurs plus difficile à lire.

Metal Framework et Metal Toolchain

macOS fournit déjà les interfaces Metal nécessaires aux applications. Le Metal Toolchain est un composant de développement supplémentaire, utilisé lors de certaines étapes de compilation. Ces deux éléments ne sont donc pas interchangeables : voir Metal dans le système ne prouve pas que le composant requis par Mojo est installé.

La commande officielle à essayer lorsque Mojo signale un outil Metal absent est :

xcodebuild -downloadComponent MetalToolchain

Lancez-la avec le même contexte utilisateur que celui qui exécute Mojo. Notez le code de sortie, les avertissements et le chemin de l’installation Xcode. Un téléchargement terminé visuellement n’est pas une preuve de fonctionnement : l’étape décisive consiste à relancer l’exemple GPU minimal.

La séquence de contrôle est la suivante :

1. exécutez xcode-select --print-path ;
2. confirmez que le chemin existe et correspond à Xcode ou aux outils actifs ;
3. lancez xcodebuild -version ;
4. téléchargez le composant avec la commande officielle ;
5. conservez la sortie et le code de retour ;
6. fermez puis rouvrez le terminal afin d’éviter un ancien contexte de variables ;
7. relancez le programme GPU minimal ;
8. comparez le résultat avec le journal sauvegardé avant la modification.

Après une mise à niveau de macOS ou de Xcode, le composant peut devenir indisponible pour le nouveau chemin actif. Cela ne signifie pas qu’il faut toujours le réinstaller. Commencez par corriger la sélection du développeur. Relancez le téléchargement seulement si le composant manque réellement ou si le test GPU échoue encore au stade de la compilation Metal.

Point de contrôle : si le téléchargement réussit, mais que le même exemple GPU échoue avec le même message, arrêtez les téléchargements répétitifs. Le chemin Xcode, les autorisations, la version sélectionnée ou le journal complet sont désormais plus importants que la présence apparente du fichier.

Chemin Xcode et outils en ligne de commande

Les installations multiples sont une cause fréquente de divergence. Vous pouvez avoir une version récente de Xcode dans le dossier Applications, tandis que xcode-select pointe encore vers une version supprimée ou vers les seuls outils en ligne de commande. Mojo utilise alors un environnement différent de celui que vous inspectez graphiquement.

Commencez par comparer les chemins :

which mojo
which max
which python
xcode-select --print-path

Puis vérifiez que chaque fichier existe réellement :

test -e "$(xcode-select --print-path)" && echo "chemin présent"

Si le chemin est obsolète, sélectionnez l’installation valide avec xcode-select. La forme générale est la suivante :

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

Adaptez le chemin à votre installation réelle. Ne saisissez pas cette commande avec un emplacement supposé. Une équipe qui conserve plusieurs versions de Xcode doit documenter le chemin choisi dans le script d’initialisation du projet, puis l’afficher dans les journaux de diagnostic.

Contrôlez aussi l’acceptation des composants Xcode si le système le demande. Après une mise à jour, un premier lancement de Xcode peut être nécessaire pour finaliser l’installation. Tant que xcodebuild -version renvoie une version inattendue ou une erreur, il est prématuré d’accuser Mojo.

Dans votre rapport d’incident, ajoutez le chemin du développeur actif. Deux collègues équipés d’un Mac Apple Silicon identique peuvent obtenir des résultats opposés si l’un appelle une ancienne installation Xcode et l’autre la nouvelle. C’est particulièrement important pour les projets audio, vidéo et design : les extensions, les compilateurs natifs et les scripts de rendu peuvent dépendre du même environnement de développement.

Environnements uv, pixi et paquets MAX

Le deuxième type de faux diagnostic vient d’un décalage entre le paquet installé et le programme réellement appelé. Un terminal peut lancer un mojo global, alors que votre projet utilise un environnement pixi ou uv. De même, max et Python peuvent provenir de chemins différents.

Inspectez les exécutables avant de supprimer quoi que ce soit :

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

Comparez ces résultats avec l’environnement activé. Recherchez notamment :

• un paquet stable dans un environnement et une version de développement dans un autre ;
• un mojo global prioritaire dans le PATH ;
• un Python appartenant à un projet différent ;
• un paquet max installé sans le module de service nécessaire ;
• un ancien environnement conservé après un changement de méthode d’installation.

MAX 26.5 a séparé plusieurs usages en paquets. Selon la tâche, vous pouvez avoir besoin de max[serve], de max[benchmark] ou de max[all]. La documentation officielle des paquets MAX décrit cette organisation. Une commande de service absente ou un module non installé n’est pas une erreur Metal.

La documentation du changement de paquets dans MAX 26.5 doit servir de référence lorsque vos commandes proviennent d’un ancien guide. Nettoyez uniquement l’environnement en cause. Ne supprimez pas tous les environnements de la machine si un autre projet fonctionne.

GPU visible, modèle refusé

Lorsque le programme GPU minimal passe, le diagnostic change complètement. Vous avez alors démontré que Mojo peut atteindre le GPU Apple et que la chaîne Metal n’est probablement pas le blocage principal. MAX serve ajoute trois contraintes :

• l’architecture du modèle doit être reconnue ;
• les noyaux nécessaires doivent exister pour Apple Silicon ;
• le graphe compilé doit tenir dans la mémoire unifiée disponible, avec macOS et les autres processus.

MAX ne prend pas en charge l’ensemble des modèles disponibles sur les plateformes NVIDIA ou AMD. La liste officielle des modèles MAX constitue la référence à consulter avant de modifier votre Mac. Elle mentionne notamment des familles comme Llama, Gemma, Nemotron et FLUX.2, mais la présence d’une famille ne garantit pas que toutes ses variantes, tous ses formats ou toutes ses opérations soient disponibles sur Apple Silicon.

Examinez le premier échec de compilation, pas seulement le message final. Les indices utiles sont :

• nom de l’opérateur non pris en charge ;
• architecture ou format de poids inattendu ;
• noyau Apple Silicon absent ;
• allocation mémoire refusée ;
• erreur apparue après le chargement des poids, et non au démarrage de Metal.

La matrice suivante évite de réinstaller au mauvais endroit :

Pour un flux de création audio ou vidéo, testez aussi les processus concurrents : aperçu vidéo, station audio numérique, navigateur avec plusieurs onglets et outils de génération peuvent consommer une partie de la mémoire unifiée. Ne transformez toutefois pas une supposition en mesure : sans journal ou observation reproductible, écrivez « mémoire insuffisante probable » et non une capacité chiffrée.

La version 26.5 est importante pour M1 et M2, car les notes de publication indiquent que la prise en charge du GPU Apple Silicon a été étendue de nouveau à M1. Cela confirme la compatibilité de la plateforme ; cela ne transforme pas chaque modèle MAX en modèle compatible. Utilisez les notes de publication MAX 26.5 pour distinguer une correction de matrice matérielle d’une prise en charge de modèle.

Trois décisions après le diagnostic

Une fois les journaux réunis, choisissez une seule branche :

Réparer la machine locale si mojo est cohérent, que le modèle figure dans la documentation MAX et que l’erreur se situe clairement dans le chemin Xcode ou le composant Metal. Cette option conserve vos caches et vos outils de création, mais exige de documenter précisément le développeur actif.

Changer de modèle ou de variante si le GPU minimal fonctionne et que MAX échoue sur une opération, un format ou une architecture non couverte. Cette voie est souvent plus rapide qu’une nouvelle installation complète. Elle convient aux prototypes d’inférence, aux essais de génération d’images et aux chaînes de traitement vidéo où une variante compatible répond au besoin.

Déplacer le test vers un Mac Apple Silicon distant si la mémoire unifiée, l’occupation de la machine ou la reproductibilité d’équipe limite le diagnostic. Dans ce cas, envoyez le même programme GPU minimal, la même sortie xcode-select et la même commande MAX. Un environnement distant n’est utile que si vous comparez des journaux équivalents ; changer simultanément de modèle, de paquet et de système ne produit aucune conclusion fiable.

Vous pouvez suivre l’état de l’environnement depuis la console MacHTML et consulter le centre d’aide MacHTML lorsque le test doit être reproduit par plusieurs personnes. Pour une équipe qui prépare un poste distant, définissez avant toute demande les critères d’acceptation : commande Mojo exécutable, chemin Xcode attendu, succès du test GPU minimal et comportement du modèle ciblé.

Le compilateur et l’outillage Mojo ont par ailleurs été annoncés comme entièrement ouverts lors de ModCon 2026. Ne reprenez donc pas les anciennes informations de prévision indiquant une ouverture future. Cette évolution ne modifie pas les prérequis macOS, Xcode, Metal ni la couverture de modèles de MAX ; elle change surtout la disponibilité du code et des outils pour l’inspection et la contribution.

Questions fréquentes

Pourquoi Mojo 1.0 ne détecte-t-il pas le GPU Apple sur mon Mac ?

Le problème vient généralement de la chaîne de développement, et non du processeur. Vérifiez d’abord macOS 15 ou une version ultérieure, un Mac Apple Silicon et Xcode ou les outils en ligne de commande en version 16 ou ultérieure. Contrôlez ensuite le chemin actif avec xcode-select, puis installez le Metal Toolchain demandé par Mojo.

Que faire si Mojo signale encore une erreur après le téléchargement du Metal Toolchain ?

Ne considérez pas le téléchargement comme une validation. Contrôlez le code de sortie de la commande, le développeur actif et la présence du composant dans Xcode. Relancez ensuite le programme GPU minimal fourni par la documentation Mojo. S’il échoue toujours, conservez sa sortie complète avant de reconstruire l’environnement ou de changer de version.

Les Mac Apple Silicon M1 et M2 prennent-ils en charge la programmation GPU avec Mojo ?

Oui. La matrice officielle de Mojo 1.0 couvre les puces Apple Silicon de M1 à M5. MAX 26.5 a en outre rétabli la prise en charge du GPU Apple Silicon sur M1. Cette compatibilité du matériel ne garantit toutefois pas qu’un modèle donné soit pris en charge par MAX ou qu’il tienne dans la mémoire unifiée disponible.

Pourquoi MAX serve échoue-t-il alors que le programme GPU minimal fonctionne ?

Les deux tests ne valident pas la même chose. Le programme minimal confirme l’accès à Metal et au GPU, tandis que MAX serve doit aussi compiler le graphe, trouver les noyaux adaptés à l’architecture du modèle et disposer d’assez de mémoire unifiée. Examinez donc le modèle, le paquet MAX installé et la mémoire avant de réinstaller Mojo.

Une mise à jour de macOS ou de Xcode impose-t-elle de réinstaller le Metal Toolchain ?

Pas systématiquement, mais une mise à jour peut rendre le composant indisponible pour le développeur actuellement sélectionné. Vérifiez d’abord le chemin Xcode et les outils en ligne de commande. Si le composant est absent ou si la compilation Metal échoue après cette vérification, relancez le téléchargement officiel, puis confirmez la réparation avec un test GPU minimal.

Choisir entre votre Mac actuel et un environnement MacHTML

Votre Mac actuel reste le meilleur choix si vous avez un projet stable, un accès physique aux périphériques audio ou vidéo et un modèle déjà validé. En revanche, il devient un mauvais poste de reproduction lorsque le système sert simultanément au montage, au design, au développement et à l’inférence. Les conflits de mémoire unifiée, les versions Xcode différentes et les environnements uv ou pixi mélangés rendent alors les journaux difficiles à comparer.

Un Mac local peut aussi être indisponible au moment où l’équipe doit tester une autre génération Apple Silicon. Acheter une nouvelle machine règle parfois la capacité, mais immobilise un budget et ne garantit pas que le modèle MAX sera mieux couvert. Louer un environnement MacHTML est plus pertinent pour un essai borné, une validation de migration ou une reproduction à distance : vous pouvez reprendre la même commande, comparer le même test GPU et décider ensuite si l’achat d’un Mac dédié est justifié.

Si votre journal montre simplement un chemin Xcode cassé, réparez d’abord l’environnement existant. Si le test minimal passe, mais que la machine manque de mémoire ou que plusieurs développeurs doivent reproduire le problème, transmettez ces journaux à MacHTML avec le modèle, la génération Apple Silicon, la version macOS, la version Xcode et la durée prévue du test. C’est cette preuve technique, plutôt qu’un message « GPU introuvable », qui permet de choisir un environnement distant adapté.