mlx-swift-examples: Apple silicon machine learning demos you can actually read

What mlx-swift-examples is for, and who should open it

The repository is a set of example programs built on MLX Swift, the array framework for Apple silicon. The README describes it as "Example MLX Swift programs", and the language model examples use implementations that now live in MLX Swift LM. That framing matters: this is a place to read working code, not a package to depend on.

The intended reader is a Swift developer who wants to run a model locally on an iPhone, an iPad or a Mac and needs to see how the pieces fit together. The applications directory covers a chat app with LLM and VLM support, a minimal chat example, an evaluation example that pulls a model and tokenizer from Hugging Face, a LoRA fine-tuning app for macOS, a stable diffusion image generator, and an MNIST trainer. The tools directory offers the same capabilities as command line programs. A third group, under Numerical, drops models entirely and shows MLX array idioms on classic problems: gradient descent fitting a quadratic, a 2D heat diffusion simulation, and a Mandelbrot renderer.

That third group is the most underrated part. If you already know Swift but not MLX, a Mandelbrot renderer that compares plain MLX against compiled MLX and a custom Metal kernel teaches more about the framework's performance model than a chat demo does. Chat demos mostly teach you about tokenizers and model loading.

How the examples are organized, and where the libraries actually live

The top level splits into Applications, Tools, Numerical and Libraries, alongside a Package.swift, an Xcode project, a Configuration directory, Data, and a shell script named mlx-run. Applications and Tools hold runnable targets. Numerical holds the model-free demos. Libraries holds the reusable pieces this repository still ships: StableDiffusion, for SDXL Turbo and Stable Diffusion, and MLXMNIST.

There is a boundary you need to understand before you start. The README states plainly that MLXLMCommon, MLXLLM, MLXVLM and MLXEmbedders have moved to a separate repository, mlx-swift-lm, which contains only reusable libraries. Previous URLs and tags continue to work, and previous tags are supported in the new repository. But going forward, all updates to those libraries happen elsewhere. So the LLM and VLM code you read here is example code that consumes libraries maintained in another place. If you copy an LLM pattern out of this repository, you are copying a consumer, and the API it consumes may move without this repository changing.

The README also notes a workflow tip for contributors who want to edit both repositories at once, pointing to Apple's documentation on editing a package dependency as a local package in Xcode. That is a contributor convenience, not a runtime requirement.

Installing mlx-swift-examples and running llm-tool

There is no install step in the usual sense. The README does not document a Homebrew formula, a package manager install, or a prebuilt binary download. You get the code by cloning the repository or opening the Xcode project, and you run the examples from Xcode or from the command line. The README's Running section gives one example invocation:

./mlx-run llm-tool --prompt "swift programming language"

The README explains that mlx-run is a shell script that uses the Xcode command line tools to locate the built binaries, and that it is equivalent to running from Xcode itself. So the script does not build anything for you; it finds what Xcode already produced. If the binary is missing, the script has nothing to locate, and you should build the target in Xcode first.

If you want to use the reusable libraries in your own package rather than run an example, the README gives this package declaration:

.package(url: "https://github.com/ml-explore/mlx-swift-examples/", branch: "main"),

and then a product dependency in a target:

.target(
    name: "YourTargetName",
    dependencies: [
        .product(name: "StableDiffusion", package: "mlx-libraries")
    ]),

Note the mismatch worth checking in your own manifest: the package URL is mlx-swift-examples, while the product's package name in the README snippet is mlx-libraries. Copy the snippet as given and confirm it resolves against the branch you actually depend on. Depending on branch: "main" also means you track whatever lands next, which is the opposite of what you want for a shipped app.

The examples are demos, and the README says so

The clearest limitation is written into the README itself. LLMBasic is described as a minimal LLM chat example application with "only two features: load the model and evaluate a prompt." That is honest labeling, and it tells you what the other applications are too: demonstrations of a capability, not products. If you need conversation history, streaming cancellation, retries or state persistence, you will be writing it.

The second limitation is the repository split. Anyone who wants the current, maintained implementation of LLM and VLM support should be reading mlx-swift-lm, not this repository. The README is explicit that all updates to those libraries now happen in the other repository. Treating mlx-swift-examples as the canonical source for MLX Swift language model code means reading a snapshot that the maintainers have said will not receive those library updates.

The third is platform. The README describes MNISTTrainer, LLMEval, MLXChatExample and StableDiffusionExample as running on both iOS and macOS, and LoRATrainingExample as macOS only. If your target is something else, the examples do not cover it. And the README points to a separate MLX troubleshooting page rather than documenting build problems here, so when a build fails you are reading two documents, not one.

Compared with mlx-swift-lm and with writing your own MLX Swift target

The obvious alternative is mlx-swift-lm, and the difference is one of role rather than features. mlx-swift-lm contains only reusable libraries: MLXLLMCommon for the shared LLM and VLM API, MLXLLM for language model implementations, MLXVLM for vision language models, and MLXEmbedders for encoders and embedding models. mlx-swift-examples contains runnable programs that use those libraries, plus libraries that stayed behind, StableDiffusion and MLXMNIST.

That split gives you a clean decision rule. If you need an API to build against, the libraries repository is the one whose contents are maintained for that purpose. If you need to see a complete program, including the parts nobody writes documentation for, this repository is the one with the runnable targets. The second alternative is starting from an empty Swift package and adding mlx-swift yourself. That gives you full control and no example baggage, but you lose the reference implementations, and the Numerical demos in particular are hard to reconstruct from an API listing alone because the interesting content is the comparison between plain MLX, compiled MLX and a custom Metal kernel.

Licence, releases and the cost of tracking main

The repository is MIT licensed, which is permissive and places few conditions on reuse beyond preserving the notice. That applies to the code in this repository. It does not automatically cover the model weights the examples download from Hugging Face, and the README does not discuss model licensing at all. If you plan to ship anything built on a downloaded model, check that model's own terms separately. Nothing here is legal advice.

On releases, the listed tags are 2.25.8, 2.25.9 and 2.29.1, dated between 2025-09-29 and 2025-10-16. The last push to the repository was on 2026-07-20, and the repository is not archived. The upgrade cost that matters is not version drift in this repository; it is the split. The README says previous tags are supported in mlx-swift-lm, so a tag you pin here has a counterpart there, but library updates land in the other repository. Pinning a tag protects you from churn in the examples while the libraries underneath keep moving.

Editorial conclusion

Adopt it if you are learning MLX Swift on Apple hardware, or if you need a working reference for a specific pattern such as LoRA fine-tuning or a custom Metal kernel, and you are willing to read the application source rather than an API reference. Do not adopt it as a dependency for production LLM or VLM work: the README states that MLXLMCommon, MLXLLM, MLXVLM and MLXEmbedders have moved to mlx-swift-lm, and that all future updates to those libraries happen there. Verify the Swift and Xcode version your machine has against the package manifest before you clone, since the repository publishes no setup guide of its own. If you only want a chat app, start with LLMBasic and read its README before the code.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ml-explore/mlx-swift-examples on GitHub
4. README
5. Releases