Install & Compatibility
Where this runs
tested against v0.6.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.960 runs
build_error
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 37.5s · import 0.000s · 885MB
921MB installed
● package 921MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VLMModel
✓ from mlx_vlm import VLMModel
✗ from mlx_vlm import VLMModel
This quickstart demonstrates how to load a pre-trained Vision Language Model (VLM) from Hugging Face using `mlx-vlm` and perform an image-to-text inference. It creates a dummy image, processes a text prompt and the image, and generates a descriptive response.
import os
from mlx_vlm import VLMModel, VLMProcessor
from PIL import Image
from pathlib import Path
# Create a dummy image for the quickstart to be runnable
dummy_image_path = Path("example_image.png")
if not dummy_image_path.exists():
Image.new('RGB', (100, 50), color = 'blue').save(dummy_image_path)
# Use an environment variable for model path or default to a common VLM
model_id = os.environ.get("MLX_VLM_MODEL", "mlx-community/Qwen-VL-Chat-mlx")
try:
print(f"Loading model: {model_id}...")
# Make sure to install with 'mlx-vlm[vision]' if using a vision model
model, processor = VLMModel.from_pretrained(model_id)
print("Model loaded.")
# Load the dummy image
image = Image.open(dummy_image_path)
# Prepare inputs
text_prompt = "Describe this image in detail."
inputs = processor(text=text_prompt, images=[image])
print(f"Prompt: {text_prompt}")
# Generate response
output_tokens = model.generate(inputs, max_new_tokens=50)
response = processor.decode(output_tokens)
print("Generated response:")
print(response)
except Exception as e:
print(f"An error occurred: {e}")
print("\nTroubleshooting Tips:")
print(" 1. Ensure you are on an Apple Silicon Mac.")
print(" 2. Install with appropriate extras: `pip install 'mlx-vlm[vision]'` or `pip install 'mlx-vlm[omni]'`.")
print(" 3. Check that the model_id is correct and supported by mlx-vlm.")
finally:
# Clean up the dummy image
if dummy_image_path.exists():
dummy_image_path.unlink()
Debug
Known issues
gotchaMLX-VLM is exclusively designed for Apple Silicon (macOS) and leverages the MLX framework. It will not function on other platforms such as Linux, Windows, or with NVIDIA/AMD GPUs.fixEnsure you are running your code on an Apple Silicon Mac.
affects: All
gotchaMany VLM models require additional installation extras (e.g., `pip install 'mlx-vlm[vision]'` or `'mlx-vlm[omni]'`). These extras bring in dependencies like `torch` and `torchvision`. Failing to install the correct extras can lead to `ModuleNotFoundError` or other runtime errors during model loading or processing.fixIdentify the specific model's requirements and install `mlx-vlm` with the appropriate extras, e.g., `pip install 'mlx-vlm[vision]'`.
affects: All
gotchaThe `mlx-vlm` library is under very active and rapid development. APIs, particularly for model loading, processing, and inference parameters, can change quickly between minor versions. This may necessitate code adjustments when upgrading.fixRegularly consult the official GitHub repository for release notes and changes. For production environments, pin your `mlx-vlm` version to a specific minor release to ensure stability, e.g., `mlx-vlm==0.4.*`.
affects: All 0.x.x versions
Upgrade
Version history
0.6.3latest on PyPI · released Jun 10, 2026
Audit
Dependencies
mlxrequiredCore deep learning framework for Apple Silicon.
torchoptionalRequired for [vision] and [omni] extras, used by certain model processors (e.g., torchvision).
torchvisionoptionalRequired for [vision] and [omni] extras, used by certain model processors.
ffmpegoptionalRequired system-wide for [omni] extra support for audio/video processing.