mlx-examples — The Reference Library Worth Reading

The reference library worth reading

ml-explore/mlx-examples is the closest thing MLX has to a canonical reference codebase. The repo is a collection of reference implementations of common models and patterns — minimal, well-commented, and deliberately not packaged as Python libraries. You don't pip install mlx-examples; you read it.

For learning what idiomatic MLX code looks like, mlx-examples is the single best resource I'd point at. Every pattern in this quest's code blocks was sanity-checked against something in this repo.

The directories worth bookmarking

llms/ — the canonical patterns for transformer language models in MLX. If you're writing a new model class or wondering how a particular architecture should look, this is the first place to read.
lora/ — reference LoRA / QLoRA fine-tuning loops, including data loading patterns. Compare to your own training loop when something feels off.
stable_diffusion/ — reference image-generation pipeline. Older than the FLUX path but still useful for understanding the diffusion model loop.
whisper/ — reference STT implementation. The simplest end-to-end "audio in, text out" loop you'll find.
mnist/ — the absolute minimum end-to-end training loop. If you're confused about MLX's training shape, start here — it's 100 lines of clear code that teach the whole pattern.
cifar/ — image classification on CIFAR; a step up from MNIST in complexity, still small enough to read end-to-end in 30 minutes.
bert/ — encoder-only transformer reference. Useful if you ever need to work with BERT-class models in MLX.

How to read it productively

Don't read mlx-examples cover to cover. Open it when you have a specific question — "what's the canonical way to load a model with sharded safetensors?" or "how should I structure a training loop with checkpointing?" — and find the closest matching example. The code is small enough to skim in a few minutes per file, and the patterns are reusable across your own projects.

What's NOT in mlx-examples

Production patterns. Mlx-examples is reference quality, not production quality — you'll find clear, minimal examples without the error handling, logging, queueing, and operational concerns that real services need. For production patterns, look at how Ollama-on-MLX or LM Studio wraps mlx-lm. prod.lesson1 covers the FastAPI wrapping pattern.

Code

Clone mlx-examples for grep-able local reference·bash

# Optional but useful — clone for local browsing.
git clone https://github.com/ml-explore/mlx-examples.git ~/code/mlx-examples
cd ~/code/mlx-examples

# The directory structure (top level):
ls -d */
# bert/  cifar/  cvae/  llms/  lora/  mnist/  music/  stable_diffusion/  whisper/  ...

# When debugging your own MLX code, grep across the examples:
rg "mx.eval" llms/
rg "value_and_grad" lora/

Read the smallest end-to-end example first·bash

# MNIST is ~100 lines and shows the full training loop end-to-end.
# Read this one first if any of MLX's training shape feels unclear.
cat ~/code/mlx-examples/mnist/main.py | head -80

Exercise

Clone mlx-examples locally if you haven't. Read mnist/main.py end to end (it's ~100 lines). Then read one other directory's main.py that maps to something you're actually doing — lora/lora.py if fine-tuning, stable_diffusion/main.py if generating images, etc. Two sentences on which patterns you noticed yourself wanting to borrow for your own code.