add upgrade docs, how to use, how to develop. by davidkoski · Pull Request #206 · ml-explore/mlx-swift-lm

davidkoski · 2026-04-11T19:01:49Z

Proposed changes

Documentation on:

upgrading from 2.x
how to use mlx-swift-lm
how to develop mlx-swift-lm
integration packages and integration macros

Checklist

Put an x in the boxes that apply.

I have read the CONTRIBUTING document
I have run pre-commit run --all-files to format my code / installed pre-commit prior to committing changes
I have added tests that prove my fix is effective or that my feature works
I have updated the necessary documentation (if needed)

The top level README.md has information on upgrading, etc. -- this is a start at moving it into the documentation proper and documenting how to integrate (3 ways) with downloaders/tokenizers. Let me know what you think.

When we are ready to release 3.x I think the README can be cut down substantially and just point at the hosted docs.

davidkoski · 2026-04-11T19:02:54Z

@@ -0,0 +1,66 @@
+# Developing mlx-swift-lm
+
+Techniques for developing _in_ mlx-swift-lm.


This should help people who are developing new models or KVCache, etc -- it walks through the ways that you can develop and test.

davidkoski · 2026-04-11T19:03:34Z

@@ -0,0 +1,147 @@
+# Upgrade From 2.x Release
+
+Notes on upgrading from mlx-swift-lm 2.x releases.


Specifically on how to upgrade, based on notes from ml-explore/mlx-swift-examples#468

davidkoski · 2026-04-11T19:04:18Z

@@ -0,0 +1,237 @@
+# Using mlx-swift-lm
+
+How to use mlx-swift-lm in your own tools and applications


The current top level README with more explanation

davidkoski · 2026-04-11T19:05:40Z

+simplest way, but consider <doc:#Integration-Package> as there are alternate
+implementations that may provide features and capabilities that you want.
+
+### Implementing Protocols


Building the integration by hand.

davidkoski · 2026-04-11T19:06:38Z

+
+See <doc:#Xcode-projects> for information about how to hook it up.
+
+### MLXHuggingFace Macros


Parity with 2.x -- use the macros. If you are just trying to get things up and running on 3.x this is probably the easiest (in terms of dependency wrangling, especially before we cut the release).

davidkoski · 2026-04-11T19:07:07Z

 > to decouple from tokenizer and downloader packages some breaking
 > changes were introduced. See [Breaking Changes](#breaking-changes) for more information.
+>
+> Additionally [upgrading documentation](https://swiftpackageindex.com/ml-explore/mlx-swift-lm/main/documentation/mlxlmcommon/upgrade)) has detailed instructions on upgrading.


Once merged the docs will show up here -- the link doesn't exist yet.

davidkoski · 2026-04-11T19:07:26Z

+
+> [!NOTE]
+> https://github.com/ml-explore/mlx-swift-examples/pull/468 is a branch in mlx-swift-examples
+> that uses the new 3.x APIs.


Pointer for people who want to try the integration in mlx-swift-examples.

davidkoski · 2026-04-11T19:07:50Z


 For some example applications and tools that use MLX Swift LM, check out [MLX Swift Examples](https://github.com/ml-explore/mlx-swift-examples).

+## Documentation


Just moved this back up to the top

davidkoski · 2026-04-11T19:08:08Z

-| [huggingface/swift-huggingface](https://github.com/huggingface/swift-huggingface) | [DePasqualeOrg/swift-huggingface-mlx](https://github.com/DePasqualeOrg/swift-huggingface-mlx) |
 | [DePasqualeOrg/swift-hf-api](https://github.com/DePasqualeOrg/swift-hf-api) | [DePasqualeOrg/swift-hf-api-mlx](https://github.com/DePasqualeOrg/swift-hf-api-mlx) |
+| [huggingface/swift-huggingface](https://github.com/huggingface/swift-huggingface) | [DePasqualeOrg/swift-huggingface-mlx](https://github.com/DePasqualeOrg/swift-huggingface-mlx) |


Reordered so it is consistent with the other table.

angeloskath

Looks great!

…elease

DePasqualeOrg · 2026-04-16T17:04:42Z

The docs on SPI are not building for some reason, which means that the links to the doc articles are not working: https://swiftpackageindex.com/ml-explore/mlx-swift-lm/builds

davidkoski · 2026-04-16T17:21:52Z

The docs on SPI are not building for some reason, which means that the links to the doc articles are not working: https://swiftpackageindex.com/ml-explore/mlx-swift-lm/builds

Thanks for spotting that -- let me see if I can figure out what is going on there. Perhaps it is just lag in the doc builds. SPI does see the new tag.

davidkoski · 2026-04-16T17:24:08Z

Maybe it is just this:

We are currently processing a large build job backlog and it may take much longer than usual for compatibility information to appear

DePasqualeOrg · 2026-04-16T19:01:17Z

Edit: Comment moved to #216

davidkoski requested a review from angeloskath April 11, 2026 19:01

davidkoski commented Apr 11, 2026

View reviewed changes

Comment thread Libraries/MLXLMCommon/Documentation.docc/using.md Outdated

davidkoski commented Apr 11, 2026

View reviewed changes

angeloskath approved these changes Apr 13, 2026

View reviewed changes

davidkoski mentioned this pull request Apr 13, 2026

v3 api embedder fixes #202

Merged

4 tasks

davidkoski added 4 commits April 14, 2026 09:07

add upgrade docs, how to use, how to develop.

d59626b

fix link

29417f9

update blurb

82b8417

fix link

ec4538d

davidkoski force-pushed the upgrade-docs branch from e6bfb5c to ec4538d Compare April 14, 2026 16:07

davidkoski added 2 commits April 14, 2026 16:30

add macro docs, reference for shortcut

3972614

move some documentation from README to upgrade. Prep README for 3.x r…

f9798ec

…elease

This comment was marked as spam.

Sign in to view

davidkoski merged commit 1c05248 into main Apr 15, 2026
3 checks passed

davidkoski deleted the upgrade-docs branch April 15, 2026 14:29

ekryski mentioned this pull request May 5, 2026

Merge main into alpha (v3 API + Gemma 4 fixes) — pre-tag for v3.32.0-alpha ekryski/mlx-swift-lm#167

Merged

4 tasks

		@@ -0,0 +1,66 @@
		# Developing mlx-swift-lm

		Techniques for developing _in_ mlx-swift-lm.

		@@ -0,0 +1,147 @@
		# Upgrade From 2.x Release

		Notes on upgrading from mlx-swift-lm 2.x releases.

		@@ -0,0 +1,237 @@
		# Using mlx-swift-lm

		How to use mlx-swift-lm in your own tools and applications


		See <doc:#Xcode-projects> for information about how to hook it up.

		### MLXHuggingFace Macros


		For some example applications and tools that use MLX Swift LM, check out [MLX Swift Examples](https://github.com/ml-explore/mlx-swift-examples).

		## Documentation

Conversation

davidkoski commented Apr 11, 2026

Proposed changes

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

angeloskath left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as spam.

Uh oh!

Uh oh!

DePasqualeOrg commented Apr 16, 2026

Uh oh!

davidkoski commented Apr 16, 2026

Uh oh!

davidkoski commented Apr 16, 2026

Uh oh!

DePasqualeOrg commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

DePasqualeOrg commented Apr 16, 2026 •

edited

Loading