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 603.0.0 right now.

View Current Release Planning and read about Contributing.

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
• MLXGuidedGeneration: Grammar-constrained generation (JSON Schema or EBNF) for any MLX model.
• MLXFoundationModels: Bridge MLX models into Apple's FoundationModels.LanguageModel for use with LanguageModelSession. (Requires the macOS/iOS/visionOS 27.0 SDK.)

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", .upToNextMinor(from: "3.32.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", .upToNextMinor(from: "3.32.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.

FoundationModels integration

MLXFoundationModels is a bridge between MLX models and Apple's FoundationModels framework: build an MLXLanguageModel, pass it to LanguageModelSession, and generate through the standard FoundationModels API. Requires the macOS/iOS/visionOS 27.0 SDK.

import Foundation
import FoundationModels
import HuggingFace
import MLXFoundationModels
import MLXHuggingFace
import MLXLLM
import MLXLMCommon
import Tokenizers

@available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
@Generable
struct Recommendation {
    let attraction: String
    let neighborhood: String
    let tip: String
}

if #available(iOS 27.0, macOS 27.0, visionOS 27.0, *) {
    let model = #huggingFaceLanguageModel(
        configuration: LLMRegistry.gemma3_1B_qat_4bit,
        capabilities: [.guidedGeneration])
    let session = LanguageModelSession(model: model)

    let recommendation = try await session.respond(
        to: "Recommend one thing to do in Chicago.",
        generating: Recommendation.self)
    print(recommendation.content)
    // Recommendation(
    //     attraction: "Art Institute of Chicago",
    //     neighborhood: "Loop",
    //     tip: "Admire Seurat's Sunday on La Grande Jatte up close.")
}

Here, we combine MLXFoundationModels with MLXGuidedGeneration by requesting a @Generable type: the response is grammar-constrained to that type's schema. MLXGuidedGeneration is a standalone primitive that constrains any MLX model's output to a schema.

Other capabilities include .vision, .toolCalling, and .reasoning. See Libraries/MLXFoundationModels for the full capability set, custom weights and loaders, and more information about using MLXFoundationModels.

Contributing

See CONTRIBUTING.md for how to build, test, and submit changes.

Smaller, focused PRs are easier and quicker to review. Sometimes larger PRs can't be helped. If you want to discuss, feel free to open an issue or ask questions in a PR. If responses are slow, feel free to @ davidkoski - there is a lot of activity and it probably just got past me. I will do my best to respond!