ml-explore / ml-explore/mlx

macOS 26 wheel is built for 26.2 but tagged macosx_26_0 — pip installs it on 26.0/26.1, where NAX is enabled on M5-class GPUs

Open
#4,525 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
28.5k
Forks
2.3k
Avg merge
3d 8h
Merged PRs (30d)
62

Description

Summary

The mlx-metal macOS 26 wheel is built with a 26.2 deployment target (.github/workflows/release.yml: macos-target: '26.2'), but it is tagged macosx_26_0_arm64, so pip installs it on macOS 26.0 and 26.1.

Observed

otool -l mlx/lib/libmlx.dylib | grep -A4 LC_BUILD_VERSION

mlx-metal 0.32.2 wheel minos
macosx_14_0_arm64 14.0
macosx_15_0_arm64 15.0
macosx_26_0_arm64 26.2

0.32.0's macOS 26 build is also 26.2; 0.31.2's is 26.0.

Why it matters

With a 26.2 target, the __builtin_available(macOS 26.2, ...) in is_nax_available() (mlx/backend/metal/device.cpp) is folded to true. On an M5-class GPU (get_architecture_gen() >= 17) running macOS 26.0 or 26.1, the NAX kernels are therefore selected on an OS that predates them. M1–M4 are unaffected by this check, because the generation test keeps NAX off.

We haven't run this on 26.0/26.1 hardware; judging by #3951, the binary would load and fail at runtime rather than at load.

The platform tag cannot express the requirement: for macOS 11+ pip only generates macosx_N_0 tags, so there is no macosx_26_2 tag to publish under.

Possible fixes
  • State in the install docs that the macOS 26 wheel needs macOS 26.2+ (they currently say macOS >= 14.0), with the workaround for 26.0/26.1: update macOS, or install an earlier mlx.
  • In the 26.2-target build, check the running OS version for real (not a folded __builtin_available) before enabling NAX, and fall back below 26.2.
Context

Found while lowering our package's floor to macOS 15; it links the libmlx.dylib from whichever mlx-metal build pip picks. Related: #3821 (why the 26 wheel targets 26.2) and #3951 (a newer-target binary on an older OS).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with .github/workflows/release.yml to trace the macOS 26.2 deployment target and with mlx/backend/metal/device.cpp at is_nax_available(). Review related issues #3821 and #3951, then determine whether the fix is documentation-only or needs runtime version handling; done means the wheel no longer enables NAX incorrectly on macOS 26.0/26.1.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, github-actions, macos
Domain
backend, build-system, operating-systems
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.