Cuando MLX falla, la última línea del error suele señalar al culpable: un Python que no es nativo o es demasiado viejo, que falte el motor en Windows o Linux, un mlx-lm más antiguo que el modelo, un fichero que no sabe leer, un «no» de Hugging Face, el techo de memoria o un puerto ocupado. Aquí van los 7, con el texto exacto y el arreglo.
Ver a MLX mover un modelo en tu propio Mac es una gozada; leer sus trazas de Python, bastante menos, aunque asustan más de lo que muerden. Hemos repasado cada mensaje de esta guía el 13 de octubre de 2026 contra mlx-lm 0.32.0 y mlx 0.32.3, que ese día seguían siendo las últimas versiones en PyPI: la mayoría los hemos provocado nosotros y el resto sale del código de MLX y de sus gestores de incidencias. La instalación, el primer modelo y el servidor están en nuestra guía para instalar MLX; esta página empieza donde acaba aquella.
MLX (mlx-lm)Ficha del programa
«No matching distribution found for mlx», o una versión vieja sin avisar
El fallo de instalación más habitual tiene esta pinta:
ERROR: Could not find a version that satisfies the requirement mlx (from versions: none)
ERROR: No matching distribution found for mlxpip no miente: para el ordenador en el que cree estar no hay MLX. Todo lo que mlx 0.32.3 publica para macOS es para Apple silicon (arm64), y este mismo mensaje es el que nos dio pip cuando le pedimos la de un Mac Intel. Si tu Mac es Intel, no hay nada que arreglar. Si es un Mac con chip M, significa que tu Python, o el terminal entero, se está ejecutando bajo Rosetta. La guía de instalación de MLX da las 2 comprobaciones:
python -c "import platform; print(platform.processor())" # tiene que salir arm
uname -p # tiene que salir armSi la primera dice i386, ese Python no es nativo: instala uno que lo sea. Si uname -p dice x86, la propia aplicación del terminal va con Rosetta: búscala en el Finder, abre «Obtener información», desmarca «Abrir con Rosetta» y vuelve a abrir el terminal.
Más traicionero es el problema que no imprime ningún error. mlx-lm 0.32.0 pide Python 3.11 o posterior, y con un Python más viejo pip elige en silencio la última versión que todavía lo acepta. Se lo preguntamos a pip para un Mac con Apple silicon con 3 Python distintos: con 3.11 instala mlx-lm 0.32.0, con 3.10 la 0.31.3 de abril y con 3.9 la 0.29.1. Lo del 3.9 no es teoría: en el gestor de incidencias de mlx-lm hay un informe con mlx_lm.chat funcionando desde el Python 3.9 que traen las Command Line Tools de Apple.
MLX en Windows o Linux: «No module named ‘mlx’»
Aquí pip instala sin rechistar y lo que falla es el primer comando. Instalamos mlx-lm 0.32.0 en un equipo con Linux, lanzamos mlx_lm.generate y esto fue lo que salió:
ModuleNotFoundError: No module named 'mlx'pip se trajo mlx-lm, transformers y huggingface_hub, pero no el motor. La razón está en una línea de los metadatos del paquete: mlx-lm solo pide mlx>=0.32.2 cuando el sistema es macOS (platform_system == "Darwin"). Windows cae en la misma condición, así que allí pasa lo mismo.
En Linux, la salida es un extra que se trae la versión de mlx que toca:
pip install "mlx-lm[cpu]" # solo procesador
pip install "mlx-lm[cuda12]" # NVIDIA, CUDA 12
pip install "mlx-lm[cuda13]" # NVIDIA, CUDA 13Con [cpu] nos llegaron mlx 0.32.3 y su paquete para CPU, y los comandos arrancaron. Para CUDA, la guía de MLX pide una tarjeta NVIDIA de arquitectura SM 7.5 o posterior, un controlador 550.54.14 o posterior (580 o posterior para CUDA 13) y un Linux con glibc 2.35 o posterior. A qué velocidad va un modelo ahí todavía no lo hemos medido, así que no vamos a adivinarlo. Windows es otra historia: mlx 0.32.4 publica versiones para Windows, pero la documentación de ninguno de los 2 paquetes menciona Windows, y mlx-lm no ofrece ningún extra para él.
«Model type … not supported»: tu mlx-lm es más viejo que el modelo
De todos los mensajes de esta página, es el que más informes acumula en el gestor de incidencias de mlx-lm:
ValueError: Model type gemma4_unified not supported.La palabra del medio es el model_type del config.json del modelo, y mlx-lm busca entre sus definiciones de modelos un fichero que se llame así. Si no lo encuentra, se para. El ejemplo no lo hemos elegido al azar: el Gemma 4 12B de 4 bits de mlx-community declara gemma4_unified. Con mlx-lm 0.31.3 da exactamente ese error; con la 0.32.0 lo reconoce, porque la 0.32.0 asigna gemma4_unified a su código de Gemma 4. Probamos las 2 versiones en paralelo. Júntalo con las secciones anteriores y tienes la cadena completa: un Python 3.10 significa mlx-lm 0.31.3, y eso significa quedarte sin Gemma 4 12B.
El arreglo, en un Python nativo 3.11 o posterior:
pip install -U mlx-lm
mlx_lm --versionLa carpeta de definiciones de modelos de la 0.32.0 tiene 135 ficheros, frente a 119 en la 0.31.3. Si el tipo de tu modelo no está en ninguna versión, actualizar no servirá, y los mantenedores lo dicen sin rodeos de las arquitecturas antiguas: ese modelo es «pretty old and unsupported». Entonces el camino es un modelo más reciente de la misma familia.
Un GGUF, unos safetensors que faltan o un modelo que quiere ejecutar su propio código
mlx-lm carga una carpeta con un config.json y ficheros model*.safetensors, y nada más. Si le das una carpeta que solo tiene un GGUF, responde:
FileNotFoundError: [Errno 2] No such file or directory: '…/config.json'Si le das el propio fichero .gguf, sale NotADirectoryError: [Errno 20] Not a directory. Y una carpeta con el config pero sin pesos dice FileNotFoundError: No safetensors found in …. Los 2 primeros quieren decir lo mismo: mlx-lm no ejecuta GGUF. El tercero aparece siempre que en la carpeta no haya safetensors, también con una descarga a medias. Busca el modelo en mlx-community o conviértelo desde los pesos originales de Hugging Face con mlx_lm.convert, como explica la guía de instalación.
El último mensaje de esta familia no es un fallo, es un seguro. Algunos modelos traen un fichero de Python propio, y desde la 0.32.0 mlx-lm se niega a ejecutarlo si no se lo pides:
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.Lo probamos con un modelo cuyo fichero habría dejado una marca en el disco: ni rastro de la marca. En la línea de comandos, el interruptor es --trust-remote-code, para mlx_lm.generate, mlx_lm.chat y mlx_lm.server.
Hugging Face dice «Repository Not Found», o que el modelo es de acceso restringido
mlx-lm descarga a través de la biblioteca de Hugging Face, así que estos errores vienen de ahí. Basta una errata en el nombre para ver esto, y sí, es un 401 aunque la página no exista:
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`.Antes que nada, repasa el nombre letra a letra. Si el nombre está bien y el modelo es de los que piden aceptar sus condiciones primero, el mensaje cambia:
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.Acepta las condiciones en la página del modelo con tu cuenta y luego inicia sesión desde el terminal con hf auth login; ese comando llega con el huggingface_hub que instala mlx-lm. Y si has puesto HF_HUB_OFFLINE=1, como sugiere la guía de instalación cuando ya tienes tus modelos, un modelo que todavía no has descargado falla con LocalEntryNotFoundError: Cannot find an appropriate cached snapshot folder… y la pista de poner HF_HUB_OFFLINE=0. Descárgalo una vez con la variable quitada y vuelve a ponerla.
«[WARNING] … maximum recommended size» e «Insufficient Memory» en un Mac de 16 GB
Este es el que duele. mlx-lm le pregunta a macOS cuánta memoria recomienda para la GPU y fija hasta esa cantidad para que el modelo vaya rápido; si te pasas, todo se vuelve lento y la ejecución puede caerse. Cuando los pesos del modelo superan el 90 % de esa cifra, te avisa antes del primer token. Aquí va un caso real del gestor de incidencias de mlx-lm: gpt-oss-20b en su versión MLX de 8 bits (gpt-oss-20b-MXFP4-Q8) en un Mac mini M4 con 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)La primera línea es un aviso; la segunda, la caída. Fíjate en el techo: 10.922 MB, exactamente 2/3 de los 16 GB de ese Mac. Así que hicimos nuestras propias cuentas para un Mac con 16 GB de memoria unificada, con el tamaño real de cada fichero MLX de 4 bits de mlx-community y la caché a precisión completa:
Mac con M4 y 16 GB unificadosFicha del equipo
| Modelo (fichero MLX de 4 bits) | Fichero | Total a 8k | Contexto máximo bajo el techo por defecto (10,67 GiB) | Con el techo subido a 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 (el máximo del propio modelo) |
| Gemma 4 12B | 6,28 GiB | 7,47 GiB | 103.424 tokens | 173.056 tokens |
| gpt-oss-20b | 10,41 GiB | 11,35 GiB | no cabe | 48.128 tokens |
Memoria necesaria (fichero MLX + caché KV + sobrecarga del programa) y el mayor contexto que queda por debajo de cada límite, buscado en pasos de 1.024 tokens. Calculado por Local AI Scope el 13 de octubre de 2026: tamaños de fichero medidos en Hugging Face ese día, caché KV calculada a partir de la arquitectura de cada modelo (en Gemma 4 12B, recalculada el 15 de octubre de 2026) y sobrecarga estimada. 10,67 GiB es el techo de 10.922 MB del informe de arriba; 13,0 GiB deja 3 GiB para macOS, como hacen nuestras fichas de hardware.
La salida documentada exige macOS 15 o posterior: subir el límite con sudo sysctl iogpu.wired_limit_mb=N, donde N es mayor que el modelo en megabytes y menor que la memoria del Mac. En un Mac de 16 GB, 13312 deja para macOS los mismos 3 GiB que reservan nuestras fichas. En el informe de arriba, un mantenedor de MLX propuso 14000 y añadió la parte honesta: el sistema sigue necesitando algo de memoria y vas a ir justo de contexto. Si subirlo no es opción, limita el contexto con --max-kv-size en mlx_lm.generate o mlx_lm.chat (el servidor no lo tiene), o elige un modelo más pequeño. Un mensaje más raro, [metal::malloc] Attempting to allocate … bytes which is greater than the maximum allowed buffer size of … bytes., es de la misma familia: MLX pidió un único bloque de memoria más grande de lo que la GPU acepta de una pieza.
Una caída más que parece de memoria y no lo es: [METAL] Command buffer execution failed: Caused GPU Timeout Error (00000002:kIOGPUCommandBufferCallbackErrorTimeout) mientras se carga un modelo muy grande (de 148 GB para arriba en el informe) desde una unidad de red o un disco USB. En el informe del gestor de incidencias de MLX, los mismos ficheros copiados al disco interno del Mac cargaron sin problema, y los mantenedores no tienen arreglo mientras Metal no les deje cambiar ese tiempo límite. Si cargas modelos de ese tamaño desde un disco externo, ya tienes sospechoso: cópialos al interno.
Si te apetece ver la idea que hay detrás de todo esto, la introducción de la propia Apple a MLX explica sus fundamentos, memoria unificada incluida; las funciones clave empiezan en el 4:21:
Se abre en YouTube (sin cookies) solo si pulsas. Más vídeos en su ficha →
El servidor: «Address already in use» y un /health que dice «unavailable»
mlx_lm.server escucha en 127.0.0.1:8080. Si otro programa ya tiene ese puerto, la traza acaba en:
OSError: [Errno 48] Address already in useEse es el número en un Mac (en Linux nos salió 98, con el mismo texto). En una de nuestras pruebas el servidor no se cerró tras esa línea, y Ctrl+C tampoco lo paró: si te pasa, cierra esa ventana del terminal. Después averigua quién tiene el puerto, o usa otro:
lsof -nP -iTCP:8080 -sTCP:LISTEN
mlx_lm.server --model mlx-community/Qwen3-8B-4bit --port 8081Si el servidor está en marcha pero deja de contestar, pregúntale: curl http://127.0.0.1:8080/health. Desde la 0.32.0 responde {"status": "unavailable"} con un 503 cuando el hilo que genera el texto ha muerto. Reinícialo y lee el registro desde arriba: el motivo está escrito ahí.
Y si notabas que la memoria crecía al ir cambiando de modelo en el servidor, no eran imaginaciones tuyas: hasta la 0.31.3, el servidor guardaba en la caché de memoria de MLX cada modelo que había cargado, como mostró un informe en el gestor de incidencias de mlx-lm. La 0.32.0 vacía esa caché antes de cargar el siguiente modelo. Un motivo más para actualizar. Antes de abrir el servidor a otros equipos, lee lo que deja abierto de serie en nuestra guía para instalar MLX: sin clave y con CORS abierto a cualquier página.
Mensajes y valores por defecto sacados del código de mlx-lm 0.32.0 y mlx 0.32.3, de la guía de instalación de MLX, de sus gestores de incidencias y de nuestras propias ejecuciones de mlx-lm 0.32.0 y 0.31.3 en Linux, el 13 de octubre de 2026.
¿También usas Ollama o LM Studio? Sus errores son otros, y sus arreglos también: ¿Ollama no funciona? 9 errores, su mensaje exacto y el arreglo y ¿LM Studio no funciona? 7 errores, su mensaje exacto y el arreglo. Y para saber qué manda MLX mientras todo esto funciona, mira su ficha: MLX (mlx-lm): qué manda a casa y si lo puedes auditar.