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
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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