Repository files navigation

MLXSharp is the first .NET wrapper aroundApple MLX that plugs straight intoMicrosoft.Extensions.AI. It is designed and tested on macOS (Apple silicon) but ships prebuilt native binaries for both macOS and Linux so that NuGet consumers can run out-of-the-box.

• .NET 9 / C# 13 preview friendly APIs that implementIChatClient,IEmbeddingGenerator<string, Embedding<float>>, and image helpers.
• Dependency Injection extensions (AddMlx) and Semantic Kernel integration (AddMlxChatCompletion).
• Native runtime loader that understandsMLXSHARP_LIBRARY, custom paths, and packaged runtimes.
• CI pipeline that builds the managed code once, produces macOS and Linux native libraries in parallel, and packs everything into distributable NuGet packages.

Add the package and wire it into the service collection:

dotnet add package ManagedCode.MLXSharp

usingMicrosoft.Extensions.DependencyInjection;usingMLXSharp;varservices=newServiceCollection();services.AddMlx(builder=>{builder.Configure(options=>{options.ChatModelId="mlx-chat";options.EmbeddingModelId="mlx-embedding";});builder.UseManagedBackend(newMlxManagedBackend());// Switch to the native backend when libmlxsharp.{dylib|so} is available.// builder.UseNativeBackend();});varprovider=services.BuildServiceProvider();varchat=provider.GetRequiredService<IChatClient>();varreply=awaitchat.GetResponseAsync("hello MLX",CancellationToken.None);

dotnet add package ManagedCode.MLXSharp.SemanticKernel

usingMicrosoft.SemanticKernel;usingMLXSharp.SemanticKernel;varkernelBuilder=Kernel.CreateBuilder();kernelBuilder.AddMlxChatCompletion(b=>b.UseManagedBackend(newMlxManagedBackend()));varkernel=kernelBuilder.Build();varhistory=newChatHistory();history.AddUserMessage("Summarise MLX in one sentence");varresponse=awaitkernel.GetRequiredService<IChatCompletionService>().GetChatMessageContentsAsync(history,newPromptExecutionSettings(),kernel,CancellationToken.None);

extern/mlx/                  # MLX sources (git submodule)native/                      # CMake project that builds libmlxsharpsrc/MLXSharp/                # Managed MLXSharp library + runtime assetssrc/MLXSharp.SemanticKernel/ # Semantic Kernel integrationsrc/MLXSharp.Tests/          # Integration tests

1. Install .NET 9, CMake, and ensure Xcode command-line tools (macOS) or build-essential + OpenBLAS/LAPACK headers (Linux) are available.
2. Sync submodules:

   git submodule update --init --recursive

3. Build for your platform:

   # macOS (Apple silicon)cmake -S native -B native/build/macos -DCMAKE_BUILD_TYPE=Releasecmake --build native/build/macosexport MLXSHARP_LIBRARY=$(pwd)/native/build/macos/libmlxsharp.dylib# Linuxcmake -S native -B native/build/linux -DCMAKE_BUILD_TYPE=Releasecmake --build native/build/linuxexport MLXSHARP_LIBRARY=$(pwd)/native/build/linux/libmlxsharp.so

4. Run your application ordotnet pack with explicit paths:

   dotnet pack src/MLXSharp/MLXSharp.csproj \    -p:MLXSharpMacNativeBinary=$PWD/native/build/macos/libmlxsharp.dylib \    -p:MLXSharpMacMetallibBinary=$PWD/native/build/macos/extern/mlx/mlx/backend/metal/kernels/mlx.metallib \    -p:MLXSharpLinuxNativeBinary=$PWD/native/build/linux/libmlxsharp.so

The CMake project vendored from MLX builds MLX and the shim in one go. macOS builds enable Metal automatically; disable or tweak MLX options by passing flags such as-DMLX_BUILD_METAL=OFF or-DMLX_BUILD_BLAS_FROM_SOURCE=ON.

1. dotnet-build (Ubuntu): restores the solution and compiles managed projects.
2. native-assets (Ubuntu): downloads the signed native binaries published with the latest MLXSharp release and uploads them as workflow artifacts.
3. package-test (macOS): pulls down the staged native artifacts, copies them intosrc/MLXSharp/runtimes/{rid}/native, rebuilds, runs the integration tests, and produces NuGet packages.

The managed integration tests still piggy-back onmlx_lm until the native runner is feature-complete. Bring your own HuggingFace bundle (any MLX-compatible repo) and pointMLXSHARP_MODEL_PATH to it before running:

export MLXSHARP_HF_MODEL_ID=<your-mlx-model>export MLXSHARP_MODEL_PATH=$PWD/models/<your-mlx-model>huggingface-cli download"$MLXSHARP_HF_MODEL_ID" --local-dir"$MLXSHARP_MODEL_PATH"python -m pip install mlx-lmdotnettest

MLXSHARP_HF_MODEL_ID is picked up by the Python smoke test; omit it to fall back tomlx-community/Qwen1.5-0.5B-Chat-4bit.

When running locally you can place prebuilt binaries underlibs/native-osx-arm64 (and/orlibs/native-libs) and a corresponding model bundle undermodel/. The test harness auto-discovers these folders and configuresMLXSHARP_LIBRARY,MLXSHARP_MODEL_PATH, andMLXSHARP_TOKENIZER_PATH so you can iterate completely offline.

The integration suite invokespython -m mlx_lm.generate with deterministic settings (temperature0, seed42) and asserts that the generated response for prompts like “Скільки буде 2+2?” contains the correct answer. Test output includes the raw generation transcript so you can verify the model behaviour directly from the CI logs.

Work is in progress to move inference fully into the native MLX backend. The current build exposes new configuration knobs viaMlxClientOptions:

When the C++ implementation catches up you’ll be able to set the environment variables below and exercise the path end-to-end:

export MLXSHARP_TOKENIZER_PATH=$PWD/models/<model-name>/tokenizer.jsonexport MLXSHARP_MODEL_PATH=$PWD/models/<model-name>

Until then,EnableNativeModelRunner should stayfalse to avoid runtime errors from the stub implementation.

This initial release is focused on macOS developers who want MLX inside .NET applications. Linux binaries are produced to keep NuGet packages complete, and Windows support is not yet available.