MLX not working? 7 errors, the exact message and the fix

When MLX fails, the last line of the error usually names the culprit: a Python that is not native or too old, no engine on Windows or Linux, an mlx-lm older than the model, a file it cannot read, Hugging Face saying no, the memory ceiling or a busy port. Here are the 7, with the exact text and the fix.

Watching MLX run a model on your own Mac is a joy; reading its Python tracebacks, less so, although they look scarier than they are. Every message below was checked on 13 October 2026 against mlx-lm 0.32.0 and mlx 0.32.3, still the latest versions on PyPI that day: most of them we triggered ourselves, and the rest come from the MLX code and its issue trackers. Installing it, the first model and the server are covered in our MLX setup guide; this page picks up where that one ends.

MLX (mlx-lm)Runtime sheet→

“No matching distribution found for mlx”, or an old version without a warning

The most common installation failure looks like this:

ERROR: Could not find a version that satisfies the requirement mlx (from versions: none)
ERROR: No matching distribution found for mlx

pip is telling the truth: there is no MLX for the computer it thinks it is on. Every macOS build of mlx 0.32.3 is for Apple silicon (arm64), and we got this exact message by asking pip for an Intel Mac build. On an Intel Mac there is nothing to fix. On an M-series Mac it means your Python, or your whole terminal, is running under Rosetta. MLX’s own installation guide gives the checks:

python -c "import platform; print(platform.processor())"   # must print arm
uname -p                                                    # must print arm

If the first says i386, that Python is not native: install a native one. If uname -p says x86, the terminal app itself is under Rosetta: find it in Finder, open Get Info, untick “Open using Rosetta” and restart the terminal.

The sneakier problem is the one that prints no error at all. mlx-lm 0.32.0 needs Python 3.11 or newer, and on an older Python pip quietly picks the last version that still accepts it. We asked pip for an Apple silicon Mac with 3 different Pythons: 3.11 gets mlx-lm 0.32.0, 3.10 gets 0.31.3 from April, and 3.9 gets 0.29.1. A 3.9 is not hypothetical either: one report in mlx-lm’s tracker shows mlx_lm.chat running from the Python 3.9 inside Apple’s Command Line Tools.

MLX on Windows or Linux: “No module named ‘mlx'”

Here pip installs without complaint and the first command fails. We installed mlx-lm 0.32.0 on a Linux machine, ran mlx_lm.generate, and got:

ModuleNotFoundError: No module named 'mlx'

pip brought mlx-lm, transformers and huggingface_hub, but not the engine. The reason is one line in mlx-lm’s package metadata: it asks for mlx>=0.32.2 only when the system is macOS (platform_system == "Darwin"). Windows hits the same marker, so the same thing happens there.

On Linux the way out is an extra that brings the right build of mlx:

pip install "mlx-lm[cpu]"      # processor only
pip install "mlx-lm[cuda12]"   # NVIDIA, CUDA 12
pip install "mlx-lm[cuda13]"   # NVIDIA, CUDA 13

With [cpu] we got mlx 0.32.3 and its CPU package, and the commands started. For CUDA, MLX’s guide asks for an NVIDIA card of architecture SM 7.5 or newer, a driver 550.54.14 or newer (580 or newer for CUDA 13) and a Linux with glibc 2.35 or newer. How fast a model runs there we have not measured yet, so we will not guess. Windows is a different story: mlx 0.32.4 publishes Windows builds, but neither package’s documentation mentions Windows, and mlx-lm offers no Windows extra.

“Model type … not supported”: your mlx-lm is older than the model

Of all the messages on this page, this is the one with the most reports in mlx-lm’s tracker:

ValueError: Model type gemma4_unified not supported.

The word in the middle is the model_type from the model’s config.json, and mlx-lm looks for a file with that name among its model definitions. If it is not there, it stops. We did not pick that example at random: the Gemma 4 12B 4-bit model in mlx-community declares gemma4_unified. On mlx-lm 0.31.3 it gives exactly that error; on 0.32.0 it is recognised, because 0.32.0 maps gemma4_unified onto its Gemma 4 code. We ran both versions side by side. Put that next to the previous sections and you get the full chain: a Python 3.10 means mlx-lm 0.31.3, and that means no Gemma 4 12B.

The fix, on a native Python 3.11 or newer:

pip install -U mlx-lm
mlx_lm --version

0.32.0’s folder of model definitions has 135 files, up from 119 in 0.31.3. If your model’s type is not in any version, updating will not help, and the maintainers have said so plainly about old architectures: that model is “pretty old and unsupported”. Then the way forward is a newer model from the same family.

A GGUF file, a missing safetensors, or a model that wants to run its own code

mlx-lm loads a folder with a config.json and model*.safetensors files, nothing else. Point it at a folder that only holds a GGUF and you get:

FileNotFoundError: [Errno 2] No such file or directory: '…/config.json'

Point it at the .gguf file itself, and it is NotADirectoryError: [Errno 20] Not a directory. A folder with the config but without weights says FileNotFoundError: No safetensors found in …. The first 2 mean the same thing: mlx-lm does not run GGUF. The third shows up whenever the folder has no safetensors, a half-finished download included. Look for the model in mlx-community, or convert it from the original Hugging Face weights with mlx_lm.convert, as the setup guide shows.

The last message in this family is a safety catch, not a bug. Some models ship a Python file of their own, and since 0.32.0 mlx-lm refuses to run it unless you say so:

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.

We tested it with a model whose file would have left a marker on disk: no marker. On the command line the switch is --trust-remote-code, for mlx_lm.generate, mlx_lm.chat and mlx_lm.server.

Hugging Face says “Repository Not Found”, or that the model is gated

mlx-lm downloads through Hugging Face’s library, so these errors come from there. A single typo in the name gives this, and yes, it is a 401 even though the page does not exist:

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`.

Check the name letter by letter before anything else. If the name is right and the model is one of those that ask you to accept its conditions first, the message is different:

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.

Accept the conditions on the model’s page with your account, then log in from the terminal with hf auth login; that command comes with the huggingface_hub that mlx-lm installs. And if you set HF_HUB_OFFLINE=1, as the setup guide suggests once your models are downloaded, a model you have not downloaded yet fails with LocalEntryNotFoundError: Cannot find an appropriate cached snapshot folder… and the hint to set HF_HUB_OFFLINE=0. Download it once with the variable off, then switch it back on.

“[WARNING] … maximum recommended size” and “Insufficient Memory” on a 16 GB Mac

This is the one that hurts. mlx-lm asks macOS how much memory it recommends for the GPU and wires up to that amount to keep the model fast; past it, things get slow, and the run can crash. When the model’s weights pass 90% of it, it warns you before the first token. Here is a real case from mlx-lm’s tracker: gpt-oss-20b in its 8-bit MLX build (gpt-oss-20b-MXFP4-Q8) on a Mac mini M4 with 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)

The first line is a warning; the second one is the crash. Note the ceiling: 10,922 MB, exactly 2/3 of that Mac’s 16 GB. So we ran our own numbers for a Mac with 16 GB of unified memory, with the real size of each 4-bit MLX file in mlx-community and the cache at full precision:

Mac with M4 and 16 GB unified memoryHardware sheet→

Model (4-bit MLX file)	File	Total at 8k	Largest context under the default ceiling (10.67 GiB)	With the ceiling raised to 13.0 GiB
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 (the model’s own maximum)
Gemma 4 12B	6.28 GiB	7.47 GiB	103,424 tokens	173,056 tokens
gpt-oss-20b	10.41 GiB	11.35 GiB	does not fit	48,128 tokens

Memory needed (MLX file + KV cache + runtime overhead) and the largest context that stays under each limit, searched in steps of 1,024 tokens. Calculated by Local AI Scope on 13 October 2026: file sizes measured on Hugging Face that day, KV cache calculated from each model’s architecture (for Gemma 4 12B, recalculated on 15 October 2026), overhead estimated. 10.67 GiB is the 10,922 MB ceiling from the report above; 13.0 GiB leaves 3 GiB for macOS, as our hardware sheets do.

The documented way out needs macOS 15 or newer: raise the limit with sudo sysctl iogpu.wired_limit_mb=N, where N is larger than the model in megabytes and smaller than the Mac’s memory. On a 16 GB Mac, 13312 leaves the same 3 GiB for macOS that our sheets keep. In the report above, an MLX maintainer suggested 14000 and added the honest part: the system still needs some memory, and you will be limited in how much context you can use. If raising it is not an option, cap the context with --max-kv-size in mlx_lm.generate or mlx_lm.chat (the server does not have it), or pick a smaller model. A rarer message, [metal::malloc] Attempting to allocate … bytes which is greater than the maximum allowed buffer size of … bytes., comes from the same family: MLX asked for a single block of memory larger than the GPU accepts in one piece.

One more crash that looks like memory and is not: [METAL] Command buffer execution failed: Caused GPU Timeout Error (00000002:kIOGPUCommandBufferCallbackErrorTimeout) while a very large model (148 GB and up in the report) loads from a network share or a USB drive. In the report in MLX’s tracker, the same files copied to the Mac’s internal drive loaded fine, and the maintainers have no fix while Metal does not let them change the timeout. If you load models that size from an external drive, that is your suspect: copy them to the internal one.

If you want the idea behind all this, Apple’s own introduction to MLX explains its fundamentals, unified memory included; the key features start at 4:21:

The server: “Address already in use”, and /health says “unavailable”

mlx_lm.server listens on 127.0.0.1:8080. If something else already holds that port, the traceback ends with:

OSError: [Errno 48] Address already in use

That is the number on a Mac (we got 98 on Linux, same text). In one of our runs the server did not exit after that line, and Ctrl+C did not stop it either: if that happens, close that terminal window. Then find out who has the port, or use another:

lsof -nP -iTCP:8080 -sTCP:LISTEN
mlx_lm.server --model mlx-community/Qwen3-8B-4bit --port 8081

If the server is running but stops answering, ask it: curl http://127.0.0.1:8080/health. Since 0.32.0 it answers {"status": "unavailable"} with a 503 when the thread that generates text has died. Restart it and read the log from the top: the reason is written there.

And if memory kept growing as you switched models through the server, it was not your imagination: up to 0.31.3 the server kept each model it had loaded in MLX’s memory cache, as a report in mlx-lm’s tracker showed. 0.32.0 clears that cache before loading the next model. One more reason to update. Before you open the server to other machines, read what its defaults leave open in our MLX setup guide: no key, and CORS open to any page.

Messages and defaults from the code of mlx-lm 0.32.0 and mlx 0.32.3, MLX’s installation guide, their issue trackers and our own runs of mlx-lm 0.32.0 and 0.31.3 on Linux, on 13 October 2026.

Running Ollama or LM Studio as well? Their errors are different, and so are the fixes: Ollama not working? 9 errors, the exact message and the fix and LM Studio not working? 7 errors, the exact message and the fix. And for what MLX sends out while all this works, see its sheet: MLX (mlx-lm): what it sends home and whether you can audit it.