Quand MLX plante, la dernière ligne de l’erreur désigne le plus souvent le coupable : un Python pas natif ou trop ancien, un moteur absent sous Windows ou Linux, un mlx-lm plus vieux que le modèle, un fichier qu’il ne sait pas lire, un refus de Hugging Face, le plafond de mémoire ou un port occupé. Voici les 7, avec le texte exact et la solution.
Voir MLX faire tourner un modèle sur son propre Mac, c’est un vrai plaisir ; lire ses traces Python, nettement moins, même si elles font plus peur que mal. Nous avons repris chaque message de ce guide le 13 octobre 2026 avec mlx-lm 0.32.0 et mlx 0.32.3, toujours les dernières versions sur PyPI ce jour-là : la plupart, nous les avons déclenchés nous-mêmes, et les autres viennent du code de MLX et de ses outils de suivi des bugs. L’installation, le premier modèle et le serveur sont dans notre guide d’installation de MLX ; cette page prend le relais là où il s’arrête.
MLX (mlx-lm)Fiche logiciel
« No matching distribution found for mlx », ou une vieille version sans prévenir
L’échec d’installation le plus courant ressemble à ceci :
ERROR: Could not find a version that satisfies the requirement mlx (from versions: none)
ERROR: No matching distribution found for mlxpip dit vrai : il n’existe pas de MLX pour l’ordinateur sur lequel il croit tourner. Tous les paquets macOS de mlx 0.32.3 visent Apple silicon (arm64), et c’est exactement ce message que pip nous a renvoyé quand nous lui avons demandé celle d’un Mac Intel. Sur un Mac Intel, il n’y a rien à réparer. Sur un Mac à puce M, cela veut dire que votre Python, ou carrément votre terminal, tourne sous Rosetta. Le guide d’installation de MLX donne les vérifications :
python -c "import platform; print(platform.processor())" # doit afficher arm
uname -p # doit afficher armSi la première affiche i386, ce Python n’est pas natif : installez-en un qui l’est. Si uname -p affiche x86, c’est l’application Terminal elle-même qui passe par Rosetta : retrouvez-la dans le Finder, ouvrez « Lire les informations », décochez « Ouvrir avec Rosetta » et relancez le terminal.
Le piège le plus sournois, c’est celui qui n’affiche aucune erreur. mlx-lm 0.32.0 exige Python 3.11 ou plus récent, et avec un Python plus ancien, pip choisit en silence la dernière version qui l’accepte encore. Nous avons posé la question à pip pour un Mac Apple silicon avec 3 Python différents : le 3.11 obtient mlx-lm 0.32.0, le 3.10 la 0.31.3 d’avril et le 3.9 la 0.29.1. Le 3.9 n’a rien d’hypothétique : un rapport dans le suivi des bugs de mlx-lm montre mlx_lm.chat lancé depuis le Python 3.9 fourni avec les Command Line Tools d’Apple.
MLX sous Windows ou Linux : « No module named ‘mlx’ »
Ici, pip installe sans broncher et c’est la première commande qui échoue. Nous avons installé mlx-lm 0.32.0 sur une machine Linux, lancé mlx_lm.generate, et voilà le résultat :
ModuleNotFoundError: No module named 'mlx'pip a apporté mlx-lm, transformers et huggingface_hub, mais pas le moteur. La raison tient en une ligne des métadonnées du paquet : mlx-lm ne réclame mlx>=0.32.2 que si le système est macOS (platform_system == "Darwin"). Windows tombe sous la même condition, donc il s’y passe la même chose.
Sous Linux, la porte de sortie est une option (« extra ») qui apporte la bonne version de mlx :
pip install "mlx-lm[cpu]" # processeur seul
pip install "mlx-lm[cuda12]" # NVIDIA, CUDA 12
pip install "mlx-lm[cuda13]" # NVIDIA, CUDA 13Avec [cpu], nous avons obtenu mlx 0.32.3 et son paquet pour processeur, et les commandes ont démarré. Pour CUDA, le guide de MLX demande une carte NVIDIA d’architecture SM 7.5 ou plus récente, un pilote 550.54.14 ou plus récent (580 ou plus récent pour CUDA 13) et un Linux avec glibc 2.35 ou plus récent. La vitesse d’un modèle là-dessus, nous ne l’avons pas encore mesurée, alors nous ne la devinerons pas. Windows, c’est une autre affaire : mlx 0.32.4 publie des versions pour Windows, mais la documentation d’aucun des 2 paquets ne mentionne Windows, et mlx-lm ne propose aucune option pour lui.
« Model type … not supported » : votre mlx-lm est plus vieux que le modèle
De tous les messages de cette page, c’est celui qui cumule le plus de rapports dans le suivi des bugs de mlx-lm :
ValueError: Model type gemma4_unified not supported.Le mot du milieu, c’est le model_type du config.json du modèle, et mlx-lm cherche parmi ses définitions de modèles un fichier qui porte ce nom. S’il ne le trouve pas, il s’arrête. L’exemple n’est pas pris au hasard : le Gemma 4 12B en 4 bits de mlx-community déclare gemma4_unified. Avec mlx-lm 0.31.3, il donne exactement cette erreur ; avec la 0.32.0, il est reconnu, parce que la 0.32.0 rattache gemma4_unified à son code Gemma 4. Nous avons testé les 2 versions côte à côte. Mettez cela bout à bout avec les sections précédentes et vous obtenez toute la chaîne : un Python 3.10, c’est mlx-lm 0.31.3, et donc pas de Gemma 4 12B.
La solution, sur un Python natif 3.11 ou plus récent :
pip install -U mlx-lm
mlx_lm --versionLe dossier des définitions de modèles de la 0.32.0 compte 135 fichiers, contre 119 dans la 0.31.3. Si le type de votre modèle ne figure dans aucune version, mettre à jour ne changera rien, et les mainteneurs le disent sans détour à propos des architectures anciennes : ce modèle est « pretty old and unsupported ». La voie à suivre est alors un modèle plus récent de la même famille.
Un fichier GGUF, des safetensors absents ou un modèle qui veut exécuter son propre code
mlx-lm charge un dossier contenant un config.json et des fichiers model*.safetensors, rien d’autre. Donnez-lui un dossier qui ne contient qu’un GGUF, et il répond :
FileNotFoundError: [Errno 2] No such file or directory: '…/config.json'Donnez-lui le fichier .gguf lui-même, et c’est NotADirectoryError: [Errno 20] Not a directory. Un dossier avec le config mais sans les poids affiche FileNotFoundError: No safetensors found in …. Les 2 premiers disent la même chose : mlx-lm ne fait pas tourner de GGUF. Le troisième apparaît dès que le dossier n’a pas de safetensors, téléchargement interrompu compris. Cherchez le modèle chez mlx-community, ou convertissez-le depuis les poids d’origine sur Hugging Face avec mlx_lm.convert, comme le montre le guide d’installation.
Le dernier message de cette famille n’est pas un bug mais une sécurité. Certains modèles embarquent leur propre fichier Python, et depuis la 0.32.0, mlx-lm refuse de l’exécuter sans votre accord :
ValueError: The model at … requires importing and running a custom module ('….py') to build its architecture. This is disabled by default. Pass trust_remote_code=True if you trust this model.Nous l’avons testé avec un modèle dont le fichier aurait laissé une marque sur le disque : aucune marque. En ligne de commande, l’interrupteur s’appelle --trust-remote-code, pour mlx_lm.generate, mlx_lm.chat et mlx_lm.server.
Hugging Face répond « Repository Not Found », ou que l’accès au modèle est restreint
mlx-lm télécharge via la bibliothèque de Hugging Face, ces erreurs viennent donc de là. Une seule faute de frappe dans le nom suffit à produire ceci, et oui, c’est une erreur 401 alors que la page n’existe pas :
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: …)
Repository Not Found for url: https://huggingface.co/api/models/mlx-community/Qwen3-8B-4bitt/revision/main.
Please make sure you specified the correct `repo_id` and `repo_type`.Avant toute chose, relisez le nom lettre par lettre. Si le nom est juste et que le modèle fait partie de ceux qui demandent d’accepter leurs conditions d’abord, le message change :
huggingface_hub.errors.GatedRepoError: 401 Client Error. (Request ID: …)
Cannot access gated repo for url https://huggingface.co/….
Access to model … is restricted. You must have access to it and be authenticated to access it. Please log in.Acceptez les conditions sur la page du modèle avec votre compte, puis connectez-vous depuis le terminal avec hf auth login ; cette commande arrive avec le huggingface_hub qu’installe mlx-lm. Et si vous avez réglé HF_HUB_OFFLINE=1, comme le conseille le guide d’installation une fois les modèles téléchargés, un modèle que vous n’avez pas encore récupéré échoue avec LocalEntryNotFoundError: Cannot find an appropriate cached snapshot folder… et l’indication de passer HF_HUB_OFFLINE=0. Téléchargez-le une fois sans la variable, puis remettez-la.
« [WARNING] … maximum recommended size » et « Insufficient Memory » sur un Mac de 16 Go
C’est celui qui fait mal. mlx-lm demande à macOS combien de mémoire il recommande pour le GPU et en rend résidente jusqu’à cette quantité pour que le modèle reste rapide ; au-delà, tout ralentit et l’exécution peut planter. Quand les poids du modèle dépassent 90 % de ce chiffre, il vous prévient avant le premier token. Voici un cas réel tiré du suivi des bugs de mlx-lm : gpt-oss-20b dans sa version MLX 8 bits (gpt-oss-20b-MXFP4-Q8) sur un Mac mini M4 de 16 Go :
[WARNING] Generating with a model that requires 11516 MB which is close to the maximum recommended size of 10922 MB. This can be slow. See the documentation for possible work-arounds: https://github.com/ml-explore/mlx-lm/tree/main#large-models
libc++abi: terminating due to uncaught exception of type std::runtime_error: [METAL] Command buffer execution failed: Insufficient Memory (00000008:kIOGPUCommandBufferCallbackErrorOutOfMemory)La première ligne est un avertissement ; la seconde, le plantage. Regardez le plafond : 10 922 Mo, exactement 2/3 des 16 Go de ce Mac. Nous avons donc fait nos propres calculs pour un Mac avec 16 Go de mémoire unifiée, avec la taille réelle de chaque fichier MLX 4 bits de mlx-community et le cache en pleine précision :
Mac avec M4 et 16 Go unifiésFiche matériel
| Modèle (fichier MLX 4 bits) | Fichier | Total à 8k | Contexte maximal sous le plafond par défaut (10,67 Gio) | Avec le plafond relevé à 13,0 Gio |
|---|---|---|---|---|
| Qwen3 4B 2507 | 2,11 Gio | 3,98 Gio | 50 176 tokens | 65 536 tokens |
| Qwen3 8B | 4,29 Gio | 6,17 Gio | 36 864 tokens | 40 960 tokens (le maximum du modèle lui-même) |
| Gemma 4 12B | 6,28 Gio | 7,47 Gio | 103 424 tokens | 173 056 tokens |
| gpt-oss-20b | 10,41 Gio | 11,35 Gio | ne tient pas | 48 128 tokens |
Mémoire nécessaire (fichier MLX + cache KV + surcoût du logiciel) et plus grand contexte qui reste sous chaque limite, cherché par pas de 1 024 tokens. Calculé par Local AI Scope le 13 octobre 2026 : tailles de fichier mesurées sur Hugging Face ce jour-là, cache KV calculé d’après l’architecture de chaque modèle (pour Gemma 4 12B, recalculé le 15 octobre 2026), surcoût estimé. 10,67 Gio correspond au plafond de 10 922 Mo du rapport ci-dessus ; 13,0 Gio laisse 3 Gio à macOS, comme le font nos fiches matériel.
La solution documentée demande macOS 15 ou plus récent : relever la limite avec sudo sysctl iogpu.wired_limit_mb=N, où N est plus grand que le modèle en mégaoctets et plus petit que la mémoire du Mac. Sur un Mac de 16 Go, 13312 laisse à macOS les mêmes 3 Gio que réservent nos fiches. Dans le rapport ci-dessus, un mainteneur de MLX a proposé 14000 et ajouté la partie honnête : le système a toujours besoin d’un peu de mémoire, et vous serez limité en contexte. Si relever la limite n’est pas possible, plafonnez le contexte avec --max-kv-size dans mlx_lm.generate ou mlx_lm.chat (le serveur ne l’a pas), ou choisissez un modèle plus petit. Un message plus rare, [metal::malloc] Attempting to allocate … bytes which is greater than the maximum allowed buffer size of … bytes., est de la même famille : MLX a demandé un seul bloc de mémoire plus grand que ce que le GPU accepte d’un tenant.
Encore un plantage qui ressemble à un problème de mémoire et n’en est pas un : [METAL] Command buffer execution failed: Caused GPU Timeout Error (00000002:kIOGPUCommandBufferCallbackErrorTimeout) pendant le chargement d’un très gros modèle (148 Go et plus dans le rapport) depuis un partage réseau ou un disque USB. Dans le rapport du suivi des bugs de MLX, les mêmes fichiers copiés sur le disque interne du Mac se chargeaient sans souci, et les mainteneurs n’ont pas de correctif tant que Metal ne leur permet pas de modifier ce délai. Si vous chargez des modèles de cette taille depuis un disque externe, vous tenez votre suspect : copiez-les sur le disque interne.
Pour comprendre l’idée derrière tout ça, l’introduction d’Apple à MLX en explique les bases, mémoire unifiée comprise ; les fonctions clés commencent à 4:21 :
S’ouvre sur YouTube (sans cookies) seulement si vous appuyez. Plus de vidéos sur sa fiche →
Le serveur : « Address already in use » et un /health qui répond « unavailable »
mlx_lm.server écoute sur 127.0.0.1:8080. Si un autre programme occupe déjà ce port, la trace se termine par :
OSError: [Errno 48] Address already in useC’est le numéro sur Mac (sous Linux, nous avons obtenu 98, avec le même texte). Lors d’un de nos essais, le serveur ne s’est pas fermé après cette ligne, et Ctrl+C ne l’a pas arrêté non plus : si cela vous arrive, fermez cette fenêtre du terminal. Ensuite, trouvez qui occupe le port, ou prenez-en un autre :
lsof -nP -iTCP:8080 -sTCP:LISTEN
mlx_lm.server --model mlx-community/Qwen3-8B-4bit --port 8081Si le serveur tourne mais ne répond plus, demandez-lui : curl http://127.0.0.1:8080/health. Depuis la 0.32.0, il répond {"status": "unavailable"} avec un code 503 quand le fil qui génère le texte est mort. Relancez-le et lisez le journal depuis le début : la raison y est écrite.
Et si vous aviez l’impression que la mémoire grimpait à chaque changement de modèle dans le serveur, vous ne rêviez pas : jusqu’à la 0.31.3, le serveur gardait dans le cache mémoire de MLX chaque modèle qu’il avait chargé, comme l’a montré un rapport dans le suivi des bugs de mlx-lm. La 0.32.0 vide ce cache avant de charger le modèle suivant. Une raison de plus de mettre à jour. Avant d’ouvrir le serveur à d’autres machines, lisez ce que ses réglages par défaut laissent ouvert dans notre guide d’installation de MLX : aucune clé, et un CORS ouvert à n’importe quelle page.
Messages et valeurs par défaut tirés du code de mlx-lm 0.32.0 et de mlx 0.32.3, du guide d’installation de MLX, de leurs outils de suivi des bugs et de nos propres exécutions de mlx-lm 0.32.0 et 0.31.3 sous Linux, le 13 octobre 2026.
Vous utilisez aussi Ollama ou LM Studio ? Leurs erreurs sont différentes, leurs solutions aussi : Ollama ne fonctionne pas ? 9 erreurs, le message exact et la solution et LM Studio ne fonctionne pas ? 7 erreurs, le message exact et la solution. Et pour savoir ce que MLX envoie pendant que tout cela fonctionne, voyez sa fiche : MLX (mlx-lm) : ce qu’il envoie et si vous pouvez l’auditer.