Skip to content

Fix metallib path for cargo install — use stable ~/.mlx/ directory - #328

Open
rgbkrk wants to merge 1 commit into
oxiglade:mainfrom
rgbkrk:fix/metallib-cargo-install-v0.25
Open

Fix metallib path for cargo install — use stable ~/.mlx/ directory#328
rgbkrk wants to merge 1 commit into
oxiglade:mainfrom
rgbkrk:fix/metallib-cargo-install-v0.25

Conversation

@rgbkrk

@rgbkrk rgbkrk commented Mar 19, 2026

Copy link
Copy Markdown

Problem

When a binary using mlx-rs is installed via cargo install, it fails at runtime:

MLX error: Failed to load the default metallib. library not found library not found library not found

cargo install builds in a temporary directory, then copies only the binary to ~/.cargo/bin/. The CMake build bakes METAL_PATH as an absolute path to the metallib inside this temp dir. After install, the temp dir is deleted and the metallib is unreachable.

Fix

Override MLX_METAL_PATH in the CMake config to point to a stable versioned directory: ~/.mlx/lib/v{mlx-sys-version}/. The directory is created before CMake runs so CMake outputs the compiled metallib there directly. The compiled-in METAL_PATH now survives temp dir cleanup.

MLX's runtime metallib search order:

  1. Co-located with binary → still works for local builds
  2. Bundle resources → still works
  3. SwiftPM bundle → still works
  4. METAL_PATH compiled-in fallback → now points to ~/.mlx/lib/v0.2.0/mlx.metallib

Testing

Tested with the voice TTS crate:

# Patched build — metallib goes to stable location
cargo build --release -p voice
strings target/release/voice | grep metallib
# Shows: /Users/.../.mlx/lib/v0.2.0/mlx.metallib

ls ~/.mlx/lib/v0.2.0/mlx.metallib
# -rw-r--r--  84M  mlx.metallib

# Install and run — works even though build dir is gone
cargo install --path crates/voice-cli --force
voice -o /tmp/test.wav "hello"  # Success!

Fixes #327

Note: this PR is based on the v0.25.3 tag. Happy to rebase onto main if preferred — the build.rs on main has additional changes (clang_rt workaround) but the fix is the same.

@minghuaw

Copy link
Copy Markdown
Collaborator

Would you please rebase onto the main branch? I'll try to take a look this weekend.

Copy mlx.metallib to a stable versioned directory (~/.mlx/lib/v{version}/)
during the CMake build by overriding MLX_METAL_PATH. The compiled-in
METAL_PATH fallback now survives cargo install temp dir cleanup.

Previously, METAL_PATH pointed to the CMake build directory inside
Cargo's temp workspace. When cargo install copies only the binary and
deletes the temp dir, the metallib becomes unreachable at runtime:

  MLX error: Failed to load the default metallib.

Fixes oxiglade#327
@rgbkrk
rgbkrk force-pushed the fix/metallib-cargo-install-v0.25 branch from cbf768f to 6ed5172 Compare March 20, 2026 06:51
@rgbkrk

rgbkrk commented Mar 20, 2026

Copy link
Copy Markdown
Author

done

rgbkrk added a commit to rgbkrk/mlx-rs that referenced this pull request Mar 22, 2026
Cherry-picked metallib cargo install fix from PR oxiglade#328.
Stable metallib path at ~/.mlx/lib/v{version}/ survives
cargo install temp dir cleanup.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cargo install breaks: metallib path baked in at compile time points to temp directory

2 participants