Wenn MLX streikt, nennt die letzte Zeile der Fehlermeldung meist den Schuldigen: ein Python, das nicht nativ oder zu alt ist, eine fehlende Engine unter Windows oder Linux, ein mlx-lm, das älter ist als das Modell, eine Datei, die es nicht lesen kann, ein Nein von Hugging Face, die Speichergrenze oder ein belegter Port. Hier sind alle 7, mit genauem Wortlaut und Lösung.
MLX auf dem eigenen Mac ein Modell rechnen zu sehen, macht richtig Spaß; seine Python-Tracebacks zu lesen, eher weniger, auch wenn sie schlimmer aussehen, als sie sind. Wir haben jede Meldung dieser Anleitung am 13. Oktober 2026 mit mlx-lm 0.32.0 und mlx 0.32.3 geprüft, an diesem Tag weiterhin die neuesten Versionen auf PyPI: Die meisten haben wir selbst ausgelöst, der Rest stammt aus dem Code von MLX und aus seinen Bugtrackern. Installation, erstes Modell und Server stehen in unserer Anleitung zur Einrichtung von MLX; diese Seite macht dort weiter, wo jene aufhört.
MLX (mlx-lm)Programm-Datenblatt
„No matching distribution found for mlx“ oder eine alte Version ohne Warnung
Der häufigste Installationsfehler sieht so aus:
ERROR: Could not find a version that satisfies the requirement mlx (from versions: none)
ERROR: No matching distribution found for mlxpip sagt die Wahrheit: Für den Rechner, auf dem es zu laufen glaubt, gibt es kein MLX. Alle macOS-Pakete von mlx 0.32.3 sind für Apple Silicon (arm64) gebaut, und genau diese Meldung hat uns pip geliefert, als wir es nach dem Paket für einen Intel-Mac gefragt haben. Auf einem Intel-Mac gibt es nichts zu reparieren. Auf einem Mac mit M-Chip heißt es, dass Ihr Python, oder gleich das ganze Terminal, unter Rosetta läuft. Die Installationsanleitung von MLX nennt die beiden Prüfungen:
python -c "import platform; print(platform.processor())" # muss arm ausgeben
uname -p # muss arm ausgebenGibt die erste i386 aus, ist dieses Python nicht nativ: Installieren Sie ein natives. Gibt uname -p x86 aus, läuft die Terminal-App selbst unter Rosetta: Suchen Sie sie im Finder, öffnen Sie „Informationen“, entfernen Sie das Häkchen bei „Mit Rosetta öffnen“ und starten Sie das Terminal neu.
Tückischer ist das Problem, das gar keinen Fehler ausgibt. mlx-lm 0.32.0 verlangt Python 3.11 oder neuer, und mit einem älteren Python wählt pip stillschweigend die letzte Version, die es noch akzeptiert. Wir haben pip für einen Mac mit Apple Silicon mit 3 verschiedenen Python-Versionen gefragt: 3.11 bekommt mlx-lm 0.32.0, 3.10 die 0.31.3 vom April und 3.9 die 0.29.1. Ein 3.9 ist auch keine Theorie: Ein Bericht im Bugtracker von mlx-lm zeigt mlx_lm.chat, gestartet aus dem Python 3.9 der Command Line Tools von Apple.
MLX unter Windows oder Linux: „No module named ‘mlx’“
Hier installiert pip ohne Murren, und erst der erste Befehl scheitert. Wir haben mlx-lm 0.32.0 auf einem Linux-Rechner installiert, mlx_lm.generate gestartet und Folgendes bekommen:
ModuleNotFoundError: No module named 'mlx'pip hat mlx-lm, transformers und huggingface_hub mitgebracht, aber nicht die Engine. Der Grund steht in einer Zeile der Paket-Metadaten: mlx-lm verlangt mlx>=0.32.2 nur, wenn das System macOS ist (platform_system == "Darwin"). Windows fällt unter dieselbe Bedingung, also passiert dort dasselbe.
Unter Linux führt ein Extra zum Ziel, das die passende mlx-Variante mitbringt:
pip install "mlx-lm[cpu]" # nur Prozessor
pip install "mlx-lm[cuda12]" # NVIDIA, CUDA 12
pip install "mlx-lm[cuda13]" # NVIDIA, CUDA 13Mit [cpu] bekamen wir mlx 0.32.3 und sein CPU-Paket, und die Befehle starteten. Für CUDA verlangt die Anleitung von MLX eine NVIDIA-Karte mit Architektur SM 7.5 oder neuer, einen Treiber ab 550.54.14 (ab 580 für CUDA 13) und ein Linux mit glibc 2.35 oder neuer. Wie schnell ein Modell dort läuft, haben wir noch nicht gemessen, also raten wir auch nicht. Windows ist eine andere Geschichte: mlx 0.32.4 veröffentlicht Pakete für Windows, aber die Dokumentation keines der 2 Pakete erwähnt Windows, und mlx-lm bietet dafür kein Extra an.
„Model type … not supported“: Ihr mlx-lm ist älter als das Modell
Von allen Meldungen auf dieser Seite hat diese die meisten Berichte im Bugtracker von mlx-lm:
ValueError: Model type gemma4_unified not supported.Das Wort in der Mitte ist der model_type aus der config.json des Modells, und mlx-lm sucht unter seinen Modelldefinitionen nach einer Datei mit diesem Namen. Findet es keine, hört es auf. Das Beispiel ist nicht zufällig gewählt: Das Gemma 4 12B in 4 Bit von mlx-community gibt gemma4_unified an. Mit mlx-lm 0.31.3 kommt genau dieser Fehler; mit der 0.32.0 wird es erkannt, weil die 0.32.0 gemma4_unified ihrem Gemma-4-Code zuordnet. Wir haben beide Versionen nebeneinander ausprobiert. Zusammen mit den vorigen Abschnitten ergibt sich die ganze Kette: Python 3.10 heißt mlx-lm 0.31.3, und das heißt kein Gemma 4 12B.
Die Lösung, auf einem nativen Python 3.11 oder neuer:
pip install -U mlx-lm
mlx_lm --versionDer Ordner mit den Modelldefinitionen der 0.32.0 enthält 135 Dateien, gegenüber 119 in der 0.31.3. Steht der Typ Ihres Modells in keiner Version, hilft auch kein Update, und die Maintainer sagen das bei alten Architekturen ganz offen: Dieses Modell sei „pretty old and unsupported“. Dann führt der Weg über ein neueres Modell derselben Familie.
Eine GGUF-Datei, fehlende Safetensors oder ein Modell, das eigenen Code ausführen will
mlx-lm lädt einen Ordner mit einer config.json und Dateien namens model*.safetensors, sonst nichts. Zeigen Sie auf einen Ordner, in dem nur eine GGUF liegt, antwortet es:
FileNotFoundError: [Errno 2] No such file or directory: '…/config.json'Zeigen Sie auf die .gguf-Datei selbst, heißt es NotADirectoryError: [Errno 20] Not a directory. Ein Ordner mit Config, aber ohne Gewichte meldet FileNotFoundError: No safetensors found in …. Die ersten beiden bedeuten dasselbe: mlx-lm führt kein GGUF aus. Die dritte taucht auf, sobald im Ordner keine Safetensors liegen, auch nach einem abgebrochenen Download. Suchen Sie das Modell bei mlx-community, oder wandeln Sie es mit mlx_lm.convert aus den Originalgewichten auf Hugging Face um, wie die Einrichtungsanleitung zeigt.
Die letzte Meldung dieser Familie ist kein Fehler, sondern eine Schutzsperre. Manche Modelle bringen eine eigene Python-Datei mit, und seit der 0.32.0 weigert sich mlx-lm, sie ohne Ihre Zustimmung auszuführen:
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.Wir haben das mit einem Modell getestet, dessen Datei eine Markierung auf der Platte hinterlassen hätte: keine Markierung. Auf der Kommandozeile heißt der Schalter --trust-remote-code, für mlx_lm.generate, mlx_lm.chat und mlx_lm.server.
Hugging Face meldet „Repository Not Found“ oder dass der Zugang zum Modell beschränkt ist
mlx-lm lädt über die Bibliothek von Hugging Face herunter, also kommen diese Fehler von dort. Ein einziger Tippfehler im Namen ergibt das hier, und ja, es ist ein 401, obwohl die Seite gar nicht existiert:
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`.Prüfen Sie vor allem anderen den Namen Buchstabe für Buchstabe. Stimmt der Name und gehört das Modell zu denen, bei denen man erst die Bedingungen akzeptieren muss, lautet die Meldung anders:
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.Akzeptieren Sie die Bedingungen auf der Seite des Modells mit Ihrem Konto und melden Sie sich dann im Terminal mit hf auth login an; dieser Befehl kommt mit dem huggingface_hub, den mlx-lm installiert. Und wenn Sie HF_HUB_OFFLINE=1 gesetzt haben, wie es die Einrichtungsanleitung empfiehlt, sobald Ihre Modelle heruntergeladen sind, scheitert ein noch nicht heruntergeladenes Modell mit LocalEntryNotFoundError: Cannot find an appropriate cached snapshot folder… und dem Hinweis, HF_HUB_OFFLINE=0 zu setzen. Laden Sie es einmal ohne die Variable herunter und setzen Sie sie danach wieder.
„[WARNING] … maximum recommended size“ und „Insufficient Memory“ auf einem Mac mit 16 GB
Das ist der Fehler, der wehtut. mlx-lm fragt macOS, wie viel Speicher es für die GPU empfiehlt, und verdrahtet bis zu dieser Menge fest, damit das Modell schnell bleibt; darüber hinaus wird alles langsam, und der Lauf kann abstürzen. Überschreiten die Gewichte des Modells 90 % dieses Werts, warnt es Sie noch vor dem ersten Token. Hier ein echter Fall aus dem Bugtracker von mlx-lm: gpt-oss-20b in seiner 8-Bit-MLX-Fassung (gpt-oss-20b-MXFP4-Q8) auf einem Mac mini M4 mit 16 GB:
[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)Die erste Zeile ist eine Warnung, die zweite der Absturz. Achten Sie auf die Grenze: 10.922 MB, genau 2/3 der 16 GB dieses Macs. Also haben wir selbst gerechnet, für einen Mac mit 16 GB Unified Memory, mit der echten Größe jeder 4-Bit-MLX-Datei von mlx-community und dem Cache in voller Genauigkeit:
Mac mit M4 und 16 GB Unified MemoryHardware-Datenblatt
| Modell (4-Bit-MLX-Datei) | Datei | Gesamt bei 8k | Größter Kontext unter der Standardgrenze (10,67 GiB) | Mit auf 13,0 GiB angehobener Grenze |
|---|---|---|---|---|
| Qwen3 4B 2507 | 2,11 GiB | 3,98 GiB | 50.176 Tokens | 65.536 Tokens |
| Qwen3 8B | 4,29 GiB | 6,17 GiB | 36.864 Tokens | 40.960 Tokens (das Maximum des Modells selbst) |
| Gemma 4 12B | 6,28 GiB | 7,47 GiB | 103.424 Tokens | 173.056 Tokens |
| gpt-oss-20b | 10,41 GiB | 11,35 GiB | passt nicht | 48.128 Tokens |
Benötigter Speicher (MLX-Datei + KV-Cache + Laufzeit-Overhead) und der größte Kontext, der unter der jeweiligen Grenze bleibt, gesucht in Schritten von 1.024 Tokens. Berechnet von Local AI Scope am 13. Oktober 2026: Dateigrößen an diesem Tag auf Hugging Face gemessen, KV-Cache aus der Architektur jedes Modells berechnet (bei Gemma 4 12B am 15. Oktober 2026 neu berechnet), Overhead geschätzt. 10,67 GiB entsprechen der Grenze von 10.922 MB aus dem Bericht oben; 13,0 GiB lassen macOS 3 GiB, wie es unsere Hardware-Steckbriefe tun.
Der dokumentierte Ausweg braucht macOS 15 oder neuer: die Grenze mit sudo sysctl iogpu.wired_limit_mb=N anheben, wobei N größer als das Modell in Megabyte und kleiner als der Speicher des Macs sein muss. Auf einem Mac mit 16 GB lässt 13312 macOS dieselben 3 GiB, die unsere Steckbriefe reservieren. Im Bericht oben schlug ein MLX-Maintainer 14000 vor und ergänzte den ehrlichen Teil: Das System braucht weiterhin etwas Speicher, und beim Kontext wird es eng. Kommt das Anheben nicht in Frage, begrenzen Sie den Kontext mit --max-kv-size in mlx_lm.generate oder mlx_lm.chat (der Server kennt die Option nicht), oder nehmen Sie ein kleineres Modell. Eine seltenere Meldung, [metal::malloc] Attempting to allocate … bytes which is greater than the maximum allowed buffer size of … bytes., gehört zur selben Familie: MLX wollte einen einzelnen Speicherblock, der größer ist, als die GPU am Stück annimmt.
Noch ein Absturz, der nach Speicher aussieht und keiner ist: [METAL] Command buffer execution failed: Caused GPU Timeout Error (00000002:kIOGPUCommandBufferCallbackErrorTimeout), während ein sehr großes Modell (148 GB und mehr im Bericht) von einer Netzwerkfreigabe oder einem USB-Laufwerk lädt. Im Bericht im Bugtracker von MLX ließen sich dieselben Dateien, auf die interne SSD des Macs kopiert, problemlos laden, und die Maintainer haben keine Lösung, solange Metal sie dieses Zeitlimit nicht ändern lässt. Laden Sie Modelle dieser Größe von einem externen Laufwerk, haben Sie Ihren Verdächtigen: Kopieren Sie sie auf die interne SSD.
Wer die Idee hinter alldem sehen will: Apples eigene Einführung in MLX erklärt die Grundlagen, Unified Memory inklusive; die wichtigsten Funktionen beginnen bei 4:21:
Öffnet YouTube (ohne Cookies) erst, wenn Sie auf Play drücken. Mehr Videos im Datenblatt →
Der Server: „Address already in use“ und ein /health, das „unavailable“ meldet
mlx_lm.server lauscht auf 127.0.0.1:8080. Belegt schon ein anderes Programm diesen Port, endet der Traceback mit:
OSError: [Errno 48] Address already in useDas ist die Nummer auf dem Mac (unter Linux bekamen wir 98, mit demselben Text). In einem unserer Durchläufe beendete sich der Server nach dieser Zeile nicht, und auch Ctrl+C hielt ihn nicht an: Falls Ihnen das passiert, schließen Sie dieses Terminalfenster. Finden Sie dann heraus, wer den Port belegt, oder nehmen Sie einen anderen:
lsof -nP -iTCP:8080 -sTCP:LISTEN
mlx_lm.server --model mlx-community/Qwen3-8B-4bit --port 8081Läuft der Server, antwortet aber nicht mehr, fragen Sie ihn: curl http://127.0.0.1:8080/health. Seit der 0.32.0 antwortet er mit {"status": "unavailable"} und einem 503, wenn der Thread, der den Text erzeugt, abgestürzt ist. Starten Sie ihn neu und lesen Sie das Log von oben: Dort steht der Grund.
Und falls Ihnen aufgefallen ist, dass der Speicher beim Wechsel zwischen Modellen im Server immer weiter wuchs: Das war keine Einbildung. Bis zur 0.31.3 behielt der Server jedes geladene Modell im Speicher-Cache von MLX, wie ein Bericht im Bugtracker von mlx-lm gezeigt hat. Die 0.32.0 leert diesen Cache, bevor sie das nächste Modell lädt. Ein Grund mehr fürs Update. Bevor Sie den Server für andere Rechner öffnen, lesen Sie in unserer Anleitung zur Einrichtung von MLX, was seine Voreinstellungen offen lassen: kein Schlüssel und CORS offen für jede Seite.
Meldungen und Voreinstellungen aus dem Code von mlx-lm 0.32.0 und mlx 0.32.3, der Installationsanleitung von MLX, ihren Bugtrackern und unseren eigenen Läufen von mlx-lm 0.32.0 und 0.31.3 unter Linux, am 13. Oktober 2026.
Nutzen Sie auch Ollama oder LM Studio? Deren Fehler sind andere, die Lösungen auch: Ollama funktioniert nicht? 9 Fehler, die genaue Meldung und die Lösung und LM Studio funktioniert nicht? 7 Fehler, die genaue Meldung und die Lösung. Und was MLX sendet, während all das läuft, steht in seinem Steckbrief: MLX (mlx-lm): was es nach Hause sendet und ob prüfbar.