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.

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.

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 one of the methods below to select download and tokenizer implementations.

Method 1: Integration Packages

Then add your preferred tokenizer and downloader integrations, see how to integrate mlx-swift-lm and downloaders/tokenizers:

.package(url: "https://github.com/DePasqualeOrg/swift-tokenizers-mlx", from: "0.2.0", traits: ["Swift"]),
.package(url: "https://github.com/DePasqualeOrg/swift-hf-api-mlx", from: "0.2.0"),

And add the libraries to your target:

.target(
    name: "YourTargetName",
    dependencies: [
        .product(name: "MLXLLM", package: "mlx-swift-lm"),
        .product(name: "MLXLMTokenizers", package: "swift-tokenizers-mlx"),
        .product(name: "MLXLMHFAPI", package: "swift-hf-api-mlx"),
    ]),

Method 2: Macros

This preserves parity with mlx-swift-lm 2.x. Simply reference the huggingface packages and use the MLXHuggingFace macros to adapt the APIs. Read more here.

Add these to your dependencies:

.package(url: "https://github.com/huggingface/swift-huggingface", .upToNextMajor(from: "0.9.0")),
.package(url: "https://github.com/huggingface/swift-transformers", .upToNextMajor(from: "1.3.0")),

And add the libraries to your target:

.target(
    name: "YourTargetName",
    dependencies: [
        .product(name: "MLXLMCommon", package: "mlx-swift-lm"),
        .product(name: "MLXLLM", package: "mlx-swift-lm"),
        .product(name: "MLXHuggingFace", package: "mlx-swift-lm"),
        .product(name: "HuggingFace", package: "swift-huggingface"),
        .product(name: "Tokenizers", package: "swift-transformers"),
    ]),

Quick Start

You can get started with a wide variety of open-weights LLMs and VLMs using this simplified API (for more details, see MLXLMCommon):

If using the integration macros, you can get started with code like this:

import MLXLLM
import MLXLMCommon
import MLXHuggingFace

import HuggingFace
import Tokenizers

let modelConfiguration = LLMRegistry.gemma3_1B_qat_4bit

let model = try await #huggingFaceLoadModelContainer(
    configuration: modelConfiguration
)

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?"))

Using the adapter packages you would have similar code -- replace the imports and the load line.

For example, loading from a local directory using the DePasqualeOrg/swift-tokenizers-mlx:

import MLXLLM
import MLXLMTokenizers

let modelDirectory = URL(filePath: "/path/to/model")
let container = try await loadModelContainer(
    from: modelDirectory,
    using: TokenizersLoader()
)