mlx 0.2.0

Dart bindings for Apple's MLX array framework on Apple Silicon: tensors, neural-network layers, FFT, quantization, and safetensors — via FFI to mlx-c.

mlx

Dart bindings for Apple's MLX array framework on Apple Silicon, via FFI to mlx-c.

Provides the MlxArray tensor type with a DType system and lazy eval; the ops surface (elementwise math, matmul, reductions, FFT, channels-last convolutions, group-wise quantization); keyed random sampling; safetensors loading; and an MLXNN-style neural-network layer (Module, linear / conv / embedding / norm / RNN layers, KV-cache) whose parameter names match MLX-converted checkpoints 1:1.

Platform: macOS on Apple Silicon only.

Install

dart pub add mlx
dart run mlx:setup

dart run mlx:setup builds the native mlx-c libraries once and installs them into a user-level cache (~/Library/Caches/mlx-dart/<tag>/, override the base with MLX_DART_CACHE); the loader finds them automatically afterwards — no environment variables required. It is idempotent (re-running is a no-op until the pinned mlx-c tag changes; --force rebuilds). The build clones and compiles MLX + mlx-c, so it needs git, cmake, and the Xcode command line tools, and takes a couple of minutes the first time.

Bundling native artifacts in an application

A packaged macOS application can take explicit authority over the native runtime before using any MLX API:

import 'dart:io';

import 'package:mlx/mlx.dart';

void configureNativeMlx(
  Directory bundleDirectory, {
  required bool signedRelease,
}) {
  configureMlxNativeArtifacts(
    signedRelease
        // A packaged release must never fall through to machine-local code.
        ? MlxNativeArtifactAuthority.bundleExclusive(bundleDirectory)
        // Development keeps the setup-cache and repository fallbacks.
        : MlxNativeArtifactAuthority.bundleFirst(bundleDirectory),
  );
}

The directory must directly contain libmlxc.dylib, libmlxc_dart_shim.dylib, libmlx.dylib, mlx.metallib, and a .mlx_c_version manifest for the package's pinned mlx-c tag. The manifest must contain verified SHA-256 entries for all four runtime files. Files may not resolve outside that directory. Use bundleExclusive for a release build so a missing or incomplete bundle fails closed; bundleFirst is convenient in development because it falls back as one unit to the existing MLX_C_LIB → setup cache → repository → Homebrew search order. With no configuration, loader behavior keeps that developer search order.

Configuration is isolate-local, single-assignment, and must happen before resolveMlxNativeArtifacts or any native-backed operation. Call it separately with the same authority inside every Dart isolate that uses MLX. A host can run inspectMlxNativeArtifactDirectory first to surface readiness diagnostics without opening executable code.

For signed application bundles, sign the nested dylibs first, then generate the four manifest hashes, and sign the outer application last. Signing a Mach-O file after hashing it invalidates its manifest entry.

Usage

import 'package:mlx/mlx.dart';

void main() {
  final a = MlxArray.fromList(<double>[1, 2, 3, 4], <int>[2, 2]);
  final b = ones(<int>[2, 2]);
  final c = matmul(a, b);
  eval(<MlxArray>[c]); // MLX is lazy — force evaluation before reading.
  print(c);
}

See example/example.dart for a runnable version.