MLX Swift LM

MLX Swift LM is a Swift package to build tools and applications with large language models (LLMs) and vision language models (VLMs) in MLX Swift.

Important

The main branch is a new major version number: 3.x. In order to decouple from tokenizer and downloader packages some breaking changes were introduced. See upgrading documentation for detailed instructions on upgrading.

Important

We use swift-format to keep the code formatting consistent. CI has this pinned to 602.0.0 right now. 603 has a behavior change that is not controlled by configuration -- the plan is to pick up 604 when it is out and have configuration to keep the formatting consistent regardless of version. For now, please use 602. Thank you!

Some key features include:

• Model loading with integrations for a variety of tokenizer and model downloading packages.
• Low-rank (LoRA) and full model fine-tuning with support for quantized models.
• Many model architectures for both LLMs and VLMs.

For some example applications and tools that use MLX Swift LM, check out MLX Swift Examples.

Documentation

Developers can use these examples in their own programs -- just import the swift package!

• Porting and implementing models
• Techniques for developing in mlx-swift-lm
• MLXLLMCommon: Common API for LLM and VLM
• MLXLLM: Large language model example implementations
• MLXVLM: Vision language model example implementations
• MLXEmbedders: Popular encoders and embedding models example implementations

Usage

This package integrates with a variety of tokenizer and downloader packages through protocol conformance. Users can pick from three ways to integrate with these packages, which offer different tradeoffs between freedom and convenience.

See documentation on how to integrate mlx-swift-lm and downloaders/tokenizers.

Note

If the documentation link shows a 404, view the source.

Installation

Add the core package to your Package.swift:

.package(url: "https://github.com/ml-explore/mlx-swift-lm", .upToNextMajor(from: "3.31.3")),

Then chose an integration package for downloaders and tokenizers.

Note

If the documentation link shows a 404, view the source.

Quick Start

See also MLXLMCommon. The simplest way to get started is using the MLXHuggingFace macros, which provide a default Hugging Face downloader and tokenizer integration.

Package.swift

dependencies: [
    .package(url: "https://github.com/ml-explore/mlx-swift-lm", .upToNextMajor(from: "3.31.3")),
    .package(url: "https://github.com/huggingface/swift-huggingface", from: "0.9.0"),
    .package(url: "https://github.com/huggingface/swift-transformers", from: "1.3.0"),
],
targets: [
    .target(
        name: "YourTargetName",
        dependencies: [
            .product(name: "MLXLLM", package: "mlx-swift-lm"),
            .product(name: "MLXLMCommon", package: "mlx-swift-lm"),
            .product(name: "MLXHuggingFace", package: "mlx-swift-lm"),
            .product(name: "HuggingFace", package: "swift-huggingface"),
            .product(name: "Tokenizers", package: "swift-transformers"),
        ]),
]

Usage

import MLXLLM
import MLXLMCommon
import MLXHuggingFace
import HuggingFace
import Tokenizers

let model = try await #huggingFaceLoadModelContainer(
    configuration: LLMRegistry.gemma3_1B_qat_4bit
)

let session = ChatSession(model)
print(try await session.respond(to: "What are two things to see in San Francisco?"))
print(try await session.respond(to: "How about a great place to eat?"))

For alternative integration approaches (custom downloaders, alternative tokenizer packages, local-only weights), see the using documentation.