Support building MLX-Swift on Linux through SwiftPM (CPU only) by Joannis · Pull Request #304 · ml-explore/mlx-swift

Joannis · 2025-12-01T15:37:56Z

Based on #293

Proposed changes

Linux compilation works.
Doesn't support cross-compilation yet

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)

incertum · 2025-12-01T17:32:17Z

Amazing @Joannis! Let me check in with @davidkoski and ask when we might be ready to bump mlx-c in order to unblock current PRs.

incertum · 2025-12-02T18:31:14Z

@Joannis you may rebase this PR now since the other PR got merged yesterday. Happy to help with the review once it's rebased.

Joannis · 2025-12-18T20:39:24Z

Rebased @incertum

incertum · 2025-12-18T23:06:11Z

Rebased @incertum

wohoo, could you run pre-commit run --all and re-push?

This commit should not exist f85906c after a clean rebase (since you worked on top of the previous PR). You could cherry delete it and or perhaps retry the rebase? Thanks a bunch!

incertum · 2025-12-18T23:07:57Z

Source/MLXNN/Normalization.swift

    }

    open func callAsFunction(_ x: MLXArray) -> MLXArray {
+        #if canImport(MLXFast)


@davidkoski do you have more context around MLXFast issues? Intuitively it sounds like something you would like to have. It seems to just compile fine over CMake on Linux.

I am not sure what this is for. MLXFast used to be a separate package, but was folded into MLX, see Sources/MLX/MLXFast.swift.

MLXFast remains as a stub to avoid breaking things and this function is:

@available(*, deprecated, message: "layerNorm is now available in the main MLX module") @_disfavoredOverload public func layerNorm( _ x: MLXArray, weight: MLXArray? = nil, bias: MLXArray? = nil, eps: Float, stream: StreamOrDevice = .default ) -> MLXArray { return MLXFast.layerNorm(x, weight: weight, bias: bias, eps: eps, stream: stream) }

What issue is this working around?

In this case MLXFast is an enum to give a namespace to look like the old module MLXFast. So we have:

MLXFast.layerNorm (the module MLXFast if you were to import that)

MLX.MLXFast.layerNorm aka MLXFast.layerNorm (the new home, you should not import MLXFast and it is not here)

MLX.layerNorm (just forwards to MLX.MLXFast.layerNorm for convenience)

OK, so the code here is referencing the second one as there is no import of MLXFast, thus we are getting the MLXFast scoped to the MLX module.

incertum · 2025-12-18T23:12:49Z

Dockerfile

@@ -0,0 +1,24 @@
+FROM swift:6.2.1-jammy AS base


Could we move the Dockerfile somewhere under .github for CI use or for documentation purposes?

How much work would it be to add the swift build to https://github.com/ml-explore/mlx-swift/blob/main/.github/scripts/setup%2Bbuild-linux-container-cmake.sh

or better yet a new script / CI job (my preference)?

davidkoski · 2025-12-19T00:36:40Z

Package.swift

+            dependencies: [
+                "MLX",
+                "MLXRandom", 
+                .target(name: "MLXFast", condition: .when(platforms: [.macOS, .iOS, .tvOS, .visionOS, .watchOS]))


I think these references to MLXFast are:

stale

maybe causing the problems in Normalization.swift. I propose the following:

diff --git a/Package.swift b/Package.swift index d88d9e4..0d1ed11 100644 --- a/Package.swift +++ b/Package.swift @@ -188,7 +188,7 @@ let package = Package( ), .target( name: "MLXNN", - dependencies: ["MLX", "MLXRandom", "MLXFast"], + dependencies: ["MLX"], swiftSettings: [ .enableExperimentalFeature("StrictConcurrency") ] @@ -218,7 +218,7 @@ let package = Package( .testTarget( name: "MLXTests", dependencies: [ - "MLX", "MLXRandom", "MLXNN", "MLXOptimizers", "MLXFFT", "MLXLinalg", "MLXFast", + "MLX", "MLXNN", "MLXOptimizers", ] ),

davidkoski · 2025-12-19T17:07:59Z

FYI #319 will have more Package.swift changes -- if we can get this merged first you won't have to figure out how to merge those in.

Outstanding issues. These have to be fixed before the merge:

swift-format
figure out this MLXFast issue
move Dockerfile under .github

Ideally this would be fixed but we can do a followup PR:

integrate swift build into GitHub actions

Joannis · 2025-12-23T13:30:03Z

@davidkoski shall I use that as a base branch then?

davidkoski · 2025-12-23T16:43:10Z

@davidkoski shall I use that as a base branch then?

I think it is fine to get this prepared on its own. The mlx-c part isn't tagged yet, so it isn't ready to merge.

If we can get this merged then I will adopt it in that branch -- I think that will be easier.

davidkoski · 2026-01-14T18:12:41Z

@Joannis mlx/mlx-c have both been updated. Do you want to rebase and we can get this merged? I will maintain the Package.swift with these changes going forward.

Joannis · 2026-01-28T11:03:40Z

Hey @davidkoski , I missed your message. Will update it next week, as I'm currently prepping for FOSDEM

davidkoski · 2026-01-28T16:53:11Z

Hey @davidkoski , I missed your message. Will update it next week, as I'm currently prepping for FOSDEM

Awesome, no rush, take your time -- when we get this integrated I can cut a new release.

Joannis · 2026-01-28T18:13:00Z

@davidkoski I don't know what your policy is regarding this, but it would be good to have SwiftPM on Linux in CI

Joannis · 2026-01-28T18:31:36Z

My Dockerfile to test:

FROM swift:6.2.1-jammy AS base

RUN apt-get update && apt-get install -y \
    libblas-dev \
    liblapack-dev \
    liblapacke-dev \
    libopenblas-dev \
    gfortran \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

FROM base AS builder

COPY . .
RUN swift build -c release --product Example1 --static-swift-stdlib -Xlinker -s -v

# Final image
FROM base

# Copy executable from SwiftPM build directory
COPY --from=builder /app/.build/*/release/Example1 /app/Example1

CMD ["./Example1"]

Joannis · 2026-01-28T18:34:09Z

By the way, on the topic of:

I have run pre-commit run --all-files to format my code / installed pre-commit prior to committing changes

Should that be swift format -ri .?

Joannis · 2026-01-28T18:49:44Z

I was indeed able to remove the MLXFast change now. I can make a follow-up PR for the CI side of things. If you want to use a specific workflow let me know.

Joannis · 2026-01-28T18:52:11Z

This screenshot is the dockerfile running on my WendyOS Linux device:

davidkoski · 2026-01-28T22:53:26Z

@davidkoski I don't know what your policy is regarding this, but it would be good to have SwiftPM on Linux in CI

Yes, we can add it in this PR or a followup, but for sure we would want it.

davidkoski · 2026-01-28T22:55:00Z

By the way, on the topic of:

I have run pre-commit run --all-files to format my code / installed pre-commit prior to committing changes

Should that be swift format -ri .?

pre-commit is a command that consumes the .pre-commit-config.yaml -- the swift format piece is probably the one that 99.9% of the people care about so this might be a good change in wording.

davidkoski · 2026-01-28T22:56:25Z

I was indeed able to remove the MLXFast change now. I can make a follow-up PR for the CI side of things. If you want to use a specific workflow let me know.

Either way is fine -- since adding this doesn't break anything existing (e.g. there is no linux swiftpm build right now) we are safe to merge without CI in place.

Since I think this is complete perhaps we should merge this and have another PR for CI? That keeps us moving forward and keeps this away from merge conflicts.

davidkoski · 2026-01-28T22:57:20Z

Package.swift

+        "framework",
+        "include-framework",
+        "metal-cpp",
+        // Exclude Metal backend files on Linux, but keep no_metal.cpp for stubs


It is too bad swiftpm doesn't have an easier way to do this!

It's a bigger problem than it seems too, as #if os(macOS) evaluates to true when cross-compiling from macOS -> Linux

Oh right! I ran into that problem elsewhere -- this is not about the target but where it is running.

davidkoski · 2026-01-28T22:58:26Z

Package.swift

+        "mlx/tests",
+
+        // special handling for cuda -- we need to keep one file:
+        // mlx/mlx/backend/cuda/no_cuda.cpp


I guess this will be refactored in a similar way once we have swiftpm + cuda (assuming it is possible)

Correct, it looks it to become possible. We (at the Build & Packaging Workgroup) have discussed this requirement many times over at length. For now, we'll just have to let the swift evolution process go on and happen.

davidkoski · 2026-01-28T22:59:56Z

Package.swift

+    let mlxSwiftExcludes: [String] = [
+        "GPU+Metal.swift",
+        "MLXArray+Metal.swift",
+        "MLXFast.swift",


This one is unfortunate -- did it not build? Or does it just not have CPU implementations?

It doesn't have a CPU implementation, at least as far as I can tell..

davidkoski

Looks great, thank you!

davidkoski · 2026-01-28T23:47:03Z

CI runs and I reviewed and it looks good -- what do you think about merging now and we can get the CI running later?

Joannis · 2026-01-29T00:23:08Z

Yeah let's merge it now! Happy to have CI in a follow-up

heckj · 2026-01-30T00:28:04Z

I got all exited about this PR merging and went and cobbled up a little container that loaded the deps and then tried to use the MLX-swift package as a dependency, and I'm afraid the lack of MLXFast blew it up in my face.

I was just reaching for

import MLX
import MLXNN
import MLXOptimizers

print("Hello Swift")

but it looks like trying to reach for MLXNN as a module isn't happy:

89.59 /app/.build/checkouts/mlx-swift/Source/MLXNN/Normalization.swift:107:9: error: cannot find 'MLXFast' in scope
89.59 105 |
89.59 106 |     open func callAsFunction(_ x: MLXArray) -> MLXArray {
89.59 107 |         MLXFast.layerNorm(x, weight: weight, bias: bias, eps: eps)
89.59     |         `- error: cannot find 'MLXFast' in scope
89.59 108 |     }
89.59 109 | }
89.59

davidkoski · 2026-01-30T04:04:09Z

Yeah, we may need a compatibility layer -- this is all over in MLXNN as well.

Joannis marked this pull request as ready for review December 1, 2025 15:39

Joannis force-pushed the update/support-linux-native-build-cmake-cpu-backend branch 2 times, most recently from 878fc10 to e8dd62b Compare December 1, 2025 18:20

incertum mentioned this pull request Dec 2, 2025

new[CI]: add linux container cmake swift builds #307

Merged

4 tasks

Joannis force-pushed the update/support-linux-native-build-cmake-cpu-backend branch from e8dd62b to 76494af Compare December 18, 2025 20:38

incertum reviewed Dec 18, 2025

View reviewed changes

davidkoski reviewed Dec 19, 2025

View reviewed changes

Joannis requested a review from incertum January 28, 2026 18:27

Joannis force-pushed the update/support-linux-native-build-cmake-cpu-backend branch from 7590346 to 94a0d2a Compare January 28, 2026 18:30

Joannis requested a review from davidkoski January 28, 2026 18:30

Joannis force-pushed the update/support-linux-native-build-cmake-cpu-backend branch from 94a0d2a to bd63fca Compare January 28, 2026 18:33

Support for building through SwiftPM on Linux (CPU only)

a932421

Joannis force-pushed the update/support-linux-native-build-cmake-cpu-backend branch from bd63fca to a932421 Compare January 28, 2026 18:48

davidkoski reviewed Jan 28, 2026

View reviewed changes

davidkoski approved these changes Jan 28, 2026

View reviewed changes

davidkoski merged commit f688d89 into ml-explore:main Jan 29, 2026
7 checks passed

Joannis deleted the update/support-linux-native-build-cmake-cpu-backend branch January 29, 2026 10:04

Conversation

Joannis commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Uh oh!

incertum commented Dec 1, 2025

Uh oh!

incertum commented Dec 2, 2025

Uh oh!

Joannis commented Dec 18, 2025

Uh oh!

incertum commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

davidkoski commented Dec 19, 2025

Uh oh!

Joannis commented Dec 23, 2025

Uh oh!

davidkoski commented Dec 23, 2025

Uh oh!

davidkoski commented Jan 14, 2026

Uh oh!

Joannis commented Jan 28, 2026

Uh oh!

davidkoski commented Jan 28, 2026

Uh oh!

Joannis commented Jan 28, 2026

Uh oh!

Joannis commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Joannis commented Jan 28, 2026

Uh oh!

Joannis commented Jan 28, 2026

Uh oh!

Joannis commented Jan 28, 2026

Uh oh!

davidkoski commented Jan 28, 2026

Uh oh!

davidkoski commented Jan 28, 2026

Uh oh!

davidkoski commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

davidkoski left a comment

Choose a reason for hiding this comment

Uh oh!

davidkoski commented Jan 28, 2026

Uh oh!

Joannis commented Jan 29, 2026

Uh oh!

Uh oh!

heckj commented Jan 30, 2026

Uh oh!

davidkoski commented Jan 30, 2026

Joannis commented Dec 1, 2025 •

edited

Loading

incertum commented Dec 18, 2025 •

edited

Loading

Joannis commented Jan 28, 2026 •

edited

Loading

davidkoski commented Jan 28, 2026 •

edited

Loading