Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Move the Studio MLX pins to mlx 0.32.2 and mlx-vlm 0.7.1 (#11080)

Long Yixingfb4fc4f535c6
diff --git a/studio/backend/tests/test_mlx_inference_backend.py b/studio/backend/tests/test_mlx_inference_backend.py
index bf1340f51e6..2f433a114e5 100644
--- a/studio/backend/tests/test_mlx_inference_backend.py
+++ b/studio/backend/tests/test_mlx_inference_backend.py
@@ -6039,9 +6039,10 @@ def test_mlx_vlm_every_release_reads_one_models_rate_the_same_way(
):
"""A model's declared rate must not depend on which mlx-vlm is installed.
- Studio pins ``mlx-vlm>=0.4.4,<0.7.0``, so the release without a resolver is the one a real
- install runs; reading the rate only through the resolver left every shipped install sampling
- at the library default instead of the rate the checkpoint asked for.
+ Studio pins ``mlx-vlm>=0.4.4,<=0.7.1``, which spans both shapes: releases with no resolver
+ and, from 0.7.0, releases that have one. Reading the rate only through the resolver left
+ every install on the older shape sampling at the library default instead of the rate the
+ checkpoint asked for.
"""
from core.inference import mlx_inference
diff --git a/studio/backend/tests/test_mlx_repair.py b/studio/backend/tests/test_mlx_repair.py
index 8018d8f3fa5..e74baa1d7ea 100644
--- a/studio/backend/tests/test_mlx_repair.py
+++ b/studio/backend/tests/test_mlx_repair.py
@@ -61,9 +61,9 @@ def test_uv_cmd_targets_this_interpreter_with_mlx_packages(monkeypatch):
# mlx-vlm keeps a floor so the resolver cannot backtrack to an old one that
# imports but breaks VLM Train/Export, and a ceiling so this unattended
# install cannot cross a major line on its own.
- assert "mlx-vlm>=0.4.4,<0.7.0" in cmd
+ assert "mlx-vlm>=0.4.4,<=0.7.1" in cmd
# Pinned, not floored: see _MLX_INSTALL_SPECS.
- assert "mlx==0.32.1" in cmd
+ assert "mlx==0.32.2" in cmd
assert "mlx-lm==0.31.3" in cmd
# Look the requirement up by name rather than by prefix. Asserting on
# startswith("mlx==") could only ever be checked on a spec that already
@@ -74,6 +74,39 @@ def test_uv_cmd_targets_this_interpreter_with_mlx_packages(monkeypatch):
assert spec.startswith("=="), f"{name} must be pinned, not floored: got {spec}"
+def test_install_narrows_mlx_vlm_to_what_the_installed_zoo_declares(monkeypatch):
+ # An mlx-vlm the installed zoo excludes must not be installed unattended: 0.7.1 passes
+ # `cache` to gated_delta_update and an older zoo's patch does not take it, so training
+ # raises TypeError after mlx_stack_available() has already cleared the chat-only gate.
+ monkeypatch.setattr(
+ mr, "_zoo_declared_specifier", lambda name: "<0.7.0,>=0.4.4" if name == "mlx-vlm" else ""
+ )
+ packages = mr._install_packages()
+ vlm = next(p for p in packages if p.startswith("mlx-vlm"))
+ assert "<0.7.0" in vlm
+ # mlx and mlx-lm are pinned at both ends, so they are left alone: intersecting them with a
+ # zoo one patch release behind would empty the range and break every self-heal.
+ assert "mlx==0.32.2" in packages
+ assert "mlx-lm==0.31.3" in packages
+
+
+def test_install_keeps_the_full_range_when_the_zoo_declares_nothing(monkeypatch):
+ # No zoo installed, or unreadable metadata: there is no constraint to honour.
+ monkeypatch.setattr(mr, "_zoo_declared_specifier", lambda _name: "")
+ assert mr._install_packages() == mr.MLX_PACKAGES
+
+
+def test_zoo_declared_specifier_reads_the_real_requirement(monkeypatch):
+ monkeypatch.setattr(
+ mr,
+ "_zoo_declared_specifier",
+ mr._zoo_declared_specifier,
+ )
+ # Markers and ordering are the installed zoo's business; only the range comes back.
+ spec = mr._zoo_declared_specifier("mlx-vlm")
+ assert spec == "" or all(part[0] in "<>=!~" for part in spec.split(","))
+
+
def test_uv_executable_finds_installer_location_when_path_is_minimal(monkeypatch, tmp_path):
uv = tmp_path / ".local" / "bin" / "uv"
uv.parent.mkdir(parents = True)
@@ -142,8 +175,11 @@ def test_repair_install_pins_transformers_and_cleans_up(monkeypatch):
reinstall_pairs = set(zip(cmd, cmd[1:]))
for name in mr._MLX_PACKAGE_NAMES:
assert ("--reinstall-package", name) in reinstall_pairs
- for pkg in mr.MLX_PACKAGES:
+ # Not MLX_PACKAGES verbatim: mlx-vlm carries the installed zoo's range appended to ours.
+ for pkg in mr._install_packages():
assert pkg in cmd
+ for pkg in mr.MLX_PACKAGES:
+ assert any(sent.startswith(pkg) for sent in cmd), pkg
assert created_paths and not Path(created_paths[0]).exists()
# The install mirrors the main installer by relaxing the transformers pin via
# UV_OVERRIDE so a current mlx-vlm can coexist with the Unsloth Transformers pin.
@@ -221,7 +257,7 @@ def test_repair_rejects_inadequate_stack(monkeypatch):
def test_inadequate_stack_warning_names_the_floors_not_the_install_pins(monkeypatch):
# The gate this message reports on is mlx_stack_available(), which tests the
# floors. Quoting the install pins instead would tell an operator running a
- # perfectly usable mlx 0.33 that they need exactly 0.32.1.
+ # perfectly usable mlx 0.33 that they need exactly 0.32.2.
warnings = []
# Pin both, or this test measures the host. attempt_mlx_repair returns early
# when _uv_executable() finds nothing, long before the message under test, so
diff --git a/studio/backend/utils/mlx_repair.py b/studio/backend/utils/mlx_repair.py
index a524fe57ef4..e4ac59fd681 100644
--- a/studio/backend/utils/mlx_repair.py
+++ b/studio/backend/utils/mlx_repair.py
@@ -30,13 +30,64 @@ _UNRESOLVED_PYTHON_MARKER = "No virtual environment or system Python installatio
_MLX_MIN_VERSIONS = {"mlx": "0.22.0", "mlx-lm": "0.31.2", "mlx-vlm": "0.4.4"}
_MLX_PACKAGE_NAMES = tuple(_MLX_MIN_VERSIONS)
_MLX_RUNTIME_IMPORTS = ("mlx.core", "mlx_lm", "mlx_lm.sample_utils", "mlx_vlm")
-# What the self-heal INSTALLS, as opposed to the floors above, which judge a stack that is already there. Pinned rather than floored because this install is unattended and default-on and mlx ships breaking changes in patch releases: 0.32.1 broke model loading here (unslothai/unsloth#9466). Keep in sync with unsloth-zoo's pyproject darwin deps; mlx-vlm stays a range so the resolver can pick 0.6.15, where the installer overrides mlx-vlm's transformers requirement, and 0.6.4 under the plain cap. 0.32.1 is chosen with its known defect: it segfaults at interpreter finalization when a fused Metal custom kernel is the last work a process did, worked around in tests/_run_then_exit_hard.py, while staying on 0.32.0 would give back mlx#3833, where two fast.metal_kernel instances sharing a name but not a source run the first kernel's code for the second.
+# What the self-heal INSTALLS, as opposed to the floors above, which judge a stack that is already there. Pinned rather than floored because this install is unattended and default-on and mlx ships breaking changes in patch releases: 0.32.1 broke model loading here (unslothai/unsloth#9466). Keep in sync with unsloth-zoo's pyproject darwin deps; mlx-vlm stays a range so the resolver can pick 0.7.1, where the installer overrides mlx-vlm's transformers requirement, and 0.6.4 under the plain cap. mlx moves to 0.32.2 because mlx-vlm 0.7.x floors it there; that release also retires the interpreter-finalization segfault 0.32.1 hit when a fused Metal custom kernel was the last work a process did, and still carries the fix for mlx#3833, where two fast.metal_kernel instances sharing a name but not a source ran the first kernel's code for the second.
_MLX_INSTALL_SPECS = {
- "mlx": "==0.32.1",
+ "mlx": "==0.32.2",
"mlx-lm": "==0.31.3",
- "mlx-vlm": ">=0.4.4,<0.7.0",
+ "mlx-vlm": ">=0.4.4,<=0.7.1",
}
MLX_PACKAGES = tuple(f"{name}{spec}" for name, spec in _MLX_INSTALL_SPECS.items())
+
+
+def _zoo_declared_specifier(package: str) -> str:
+ """The version range the INSTALLED unsloth-zoo declares for `package`, or "".
+
+ The specs above track the zoo in the repository, but the self-heal runs against whatever zoo is on
+ the machine, and it never upgrades it. mlx-vlm 0.7.1 passes `cache` to `gated_delta_update`, which a
+ zoo predating that keyword does not accept, so admitting 0.7.1 next to an older zoo raises TypeError
+ at the first Qwen3.5 VLM training step, after mlx_stack_available() has already cleared the
+ chat-only gate. Reading the installed zoo's own requirement is what keeps the two in step without
+ naming a zoo version here: it widens on its own the moment a zoo that declares 0.7.1 is installed.
+ """
+ try:
+ from importlib.metadata import requires
+ except ImportError: # pragma: no cover - importlib.metadata is stdlib on every supported Python
+ return ""
+ try:
+ from packaging.requirements import Requirement
+ from packaging.utils import canonicalize_name
+ except ImportError:
+ return ""
+ try:
+ declared = requires("unsloth_zoo") or ()
+ except Exception:
+ # Not installed, or metadata unreadable. Either way there is no zoo constraint to honour.
+ return ""
+ wanted = canonicalize_name(package)
+ for raw in declared:
+ try:
+ requirement = Requirement(raw)
+ except Exception:
+ continue
+ if canonicalize_name(requirement.name) == wanted and str(requirement.specifier):
+ return str(requirement.specifier)
+ return ""
+
+
+def _install_packages() -> tuple[str, ...]:
+ """MLX_PACKAGES, with mlx-vlm narrowed to what the installed unsloth-zoo declares.
+
+ Only mlx-vlm: it is the one whose call shape the zoo has to match, and mlx/mlx-lm are pinned
+ exactly at both ends, so intersecting those would just empty the range on any zoo a patch release
+ behind. Both specifiers are passed and uv intersects them.
+ """
+ packages = []
+ for name, spec in _MLX_INSTALL_SPECS.items():
+ declared = _zoo_declared_specifier(name) if name == "mlx-vlm" else ""
+ packages.append(f"{name}{spec},{declared}" if declared else f"{name}{spec}")
+ return tuple(packages)
+
+
_MLX_REINSTALL_ARGS = tuple(
arg for name in _MLX_PACKAGE_NAMES for arg in ("--reinstall-package", name)
)
@@ -287,12 +338,13 @@ def attempt_mlx_repair(*, timeout: int = _REPAIR_TIMEOUT_S) -> bool:
constraint_path = None
try:
constraint_args, constraint_path = _transformers_constraint_args()
+ packages = _install_packages()
cmd = _uv_install_cmd(
"--upgrade",
_ONLY_BINARY_ARG,
*_MLX_REINSTALL_ARGS,
*constraint_args,
- *MLX_PACKAGES,
+ *packages,
)
if cmd is None:
logger.warning(
@@ -300,7 +352,7 @@ def attempt_mlx_repair(*, timeout: int = _REPAIR_TIMEOUT_S) -> bool:
"staying chat-only. Run `unsloth studio update` to restore uv."
)
return False
- logger.info("MLX self-heal: installing %s", ", ".join(MLX_PACKAGES))
+ logger.info("MLX self-heal: installing %s", ", ".join(packages))
# Before the wait, not after: every package is passed with --reinstall-package, so uv removes and replaces them as it goes and a timeout or a non-zero exit part way through leaves a stack neither the one detection measured nor the one asked for. Nothing before this line touches the environment.
_environment_mutated = True
result = subprocess.run(
@@ -346,7 +398,7 @@ def attempt_mlx_repair(*, timeout: int = _REPAIR_TIMEOUT_S) -> bool:
logger.warning(
"MLX self-heal produced an incomplete or too-old MLX stack "
"(need %s); staying chat-only.",
- # The floors, not MLX_PACKAGES: the gate above tests the floors, so quoting the install pins would tell someone on a usable mlx 0.33 that they need exactly 0.32.1.
+ # The floors, not MLX_PACKAGES: the gate above tests the floors, so quoting the install pins would tell someone on a usable mlx 0.33 that they need exactly 0.32.2.
", ".join(f"{name}>={ver}" for name, ver in _MLX_MIN_VERSIONS.items()),
)
return False
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 7884829c468..67a68855c7e 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -502,7 +502,7 @@ def _macos_release_major() -> "int | None":
# The pinned MLX versions publish macosx_14_0_arm64 wheels, no sdist and no cp39, so
# macOS 13 and Python 3.9 have nothing to resolve to (`uv pip install --python-platform
-# aarch64-apple-darwin mlx==0.32.1`). Asked before the install, like
+# aarch64-apple-darwin mlx==0.32.2`). Asked before the install, like
# _torchcodec_spec_is_installable: pip_install exits on failure, so trying would end an
# install that today just comes up chat-only.
_MLX_MIN_PYTHON = (3, 10)
@@ -8367,10 +8367,10 @@ def _build_pip_cmd(args: tuple[str, ...]) -> list[str]:
# Every current caller also names these as positionals or via -r, but a
# future one might not, and pip would then upgrade nothing.
- # By canonical project name: `--upgrade-package mlx` beside `mlx==0.32.1` is one project,
+ # By canonical project name: `--upgrade-package mlx` beside `mlx==0.32.2` is one project,
# and pip refuses a double requirement where uv does not.
def _project(requirement: str) -> str:
- # _requirement_name stops at "==" and "@"; a range (mlx-vlm>=0.4.4,<0.7.0) needs the
+ # _requirement_name stops at "==" and "@"; a range (mlx-vlm>=0.4.4,<=0.7.1) needs the
# rest.
return _canonical_package_name(
re.split(r"[<>=!~;\[ ]", _requirement_name(requirement), maxsplit = 1)[0]
@@ -9265,11 +9265,43 @@ def _has_working_git() -> bool:
# The MLX stack, one place; test_mlx_install.py compares it with utils/mlx_repair.py's
# _MLX_INSTALL_SPECS.
-_MLX_PINS: tuple[str, ...] = ("mlx==0.32.1", "mlx-metal==0.32.1", "mlx-lm==0.31.3")
-_MLX_VLM_SPEC = "mlx-vlm>=0.4.4,<0.7.0"
+_MLX_PINS: tuple[str, ...] = ("mlx==0.32.2", "mlx-metal==0.32.2", "mlx-lm==0.31.3")
+_MLX_VLM_SPEC = "mlx-vlm>=0.4.4,<=0.7.1"
_MLX_NAMES: tuple[str, ...] = tuple(spec.partition("==")[0] for spec in _MLX_PINS) + ("mlx-vlm",)
+def _mlx_vlm_spec_for_installed_zoo() -> str:
+ """_MLX_VLM_SPEC, intersected with the range the INSTALLED unsloth-zoo declares.
+
+ This step runs before the core phase, and on a fresh install (SKIP_STUDIO_BASE=1) the core
+ phase is skipped entirely, so the zoo install.sh already put down is the one that stays.
+ mlx-vlm 0.7.1 passes `cache` to gated_delta_update and a zoo predating that keyword does not
+ accept it, so admitting 0.7.1 beside such a zoo raises TypeError at the first Qwen3.5 VLM
+ training step, after mlx_stack_available() has cleared the chat-only gate. Reading what the
+ installed zoo itself declares keeps the two in step without naming a zoo version here, and it
+ widens on its own once a zoo declaring 0.7.1 is installed. Mirrors utils/mlx_repair.py's
+ _install_packages, which does the same for the unattended self-heal.
+ """
+ try:
+ from importlib.metadata import requires
+ from packaging.requirements import Requirement
+ from packaging.utils import canonicalize_name
+ except ImportError:
+ return _MLX_VLM_SPEC
+ try:
+ declared = requires("unsloth_zoo") or ()
+ except Exception: # noqa: BLE001 - not installed, or unreadable metadata
+ return _MLX_VLM_SPEC
+ for raw in declared:
+ try:
+ requirement = Requirement(raw)
+ except Exception: # noqa: BLE001 - a requirement string packaging cannot parse
+ continue
+ if canonicalize_name(requirement.name) == "mlx-vlm" and str(requirement.specifier):
+ return f"{_MLX_VLM_SPEC},{requirement.specifier}"
+ return _MLX_VLM_SPEC
+
+
def _mlx_stack_is_current() -> bool:
"""Whether the three exact pins and mlx-vlm's range are all already satisfied.
@@ -9284,7 +9316,14 @@ def _mlx_stack_is_current() -> bool:
return False
try:
from packaging.requirements import Requirement
- if not Requirement(_MLX_VLM_SPEC).specifier.contains(installed, prereleases = True):
+
+ # The narrowed spec, not the static one: with an older zoo beside an already-installed
+ # 0.7.1 the static range reads as satisfied and the step skips the very install that
+ # would put mlx-vlm back where the zoo can drive it.
+ if not Requirement(_mlx_vlm_spec_for_installed_zoo()).specifier.contains(
+ installed,
+ prereleases = True,
+ ):
return False
except Exception: # noqa: BLE001 - no packaging, or a version it cannot parse
return False
@@ -9322,7 +9361,10 @@ def _mlx_closure_unmet() -> bool:
_fd, _name = _tempfile.mkstemp(prefix = "unsloth-mlx-", suffix = ".txt", text = True)
os.close(_fd)
handle = Path(_name)
- handle.write_text("\n".join([*_MLX_PINS, _MLX_VLM_SPEC]) + "\n", encoding = "utf-8")
+ handle.write_text(
+ "\n".join([*_MLX_PINS, _mlx_vlm_spec_for_installed_zoo()]) + "\n",
+ encoding = "utf-8",
+ )
unmet = install_manifest.closure_unmet_requirements(handle, _installed_index())
# An override REPLACES every requirement on the package it names, so the installed
# version is the override's, not the one mlx-vlm's metadata asks for. Read raw, that
@@ -9374,7 +9416,8 @@ _MLX_IMPORTED_DEPENDENCIES = (
def _mlx_health_fingerprint() -> dict:
"""What a recorded MLX verdict is only valid for."""
return {
- "pins": list(_MLX_PINS) + [_MLX_VLM_SPEC],
+ # The narrowed spec, so installing a different zoo invalidates a recorded verdict.
+ "pins": list(_MLX_PINS) + [_mlx_vlm_spec_for_installed_zoo()],
"python": _installer_python_tag(),
"mlx_vlm": _installed_distribution_version("mlx-vlm") or "",
# Versions as installed; an older record without this key is probed once and rewritten.
@@ -10416,6 +10459,10 @@ def install_python_stack() -> int:
base_total += 1 # torch flavor invariant (step 13w), Windows
if IS_MAC_ARM and not NO_TORCH:
base_total += 1 # MLX stack, same gate as the step itself
+ # The re-resolve after the core phase, which may have moved the unsloth-zoo whose
+ # declared mlx-vlm range the step above honoured. Same gate, so the slot is spent on
+ # every Apple Silicon run with torch, including the no-wheel branch.
+ base_total += 1 # MLX stack re-resolve
if NO_TORCH and not skip_base:
# no-torch runtime deps, which this build announces on its own slot inside the core
# step rather than folding into it. Same gate as the step itself.
@@ -10536,6 +10583,9 @@ def install_python_stack() -> int:
# and still needs MLX. Not on --no-torch: it declined the training stack. Pins stay
# aligned with utils/mlx_repair.py and unsloth-zoo; UV_OVERRIDE (set at module load)
# relaxes the mlx-vlm / mlx-lm transformers pin.
+ # None when the MLX step did not run at all, so the re-resolve after the core phase has
+ # nothing to compare against.
+ _mlx_vlm_spec_used: Optional[str] = None
if IS_MAC_ARM and not NO_TORCH:
# Both branches spend the slot, so the denominator does not depend on the host.
if _mlx_pins_are_installable():
@@ -10558,8 +10608,9 @@ def install_python_stack() -> int:
# transitive dependency; _build_pip_cmd translates back for pip.
*[arg for name in _MLX_NAMES for arg in ("--upgrade-package", name)],
*_MLX_PINS,
- _MLX_VLM_SPEC,
+ _mlx_vlm_spec_for_installed_zoo(),
)
+ _mlx_vlm_spec_used = _mlx_vlm_spec_for_installed_zoo()
else:
_progress("MLX stack (skipped, no wheel for this macOS or Python)")
_note(
@@ -10658,6 +10709,26 @@ def install_python_stack() -> int:
"unsloth-zoo",
)
+ # The MLX step ran BEFORE the core phase, so it honoured the mlx-vlm range the OLD
+ # unsloth-zoo declared. A normal update then upgrades the zoo, and without this the machine
+ # keeps the narrower stack indefinitely: the startup self-heal will not correct it either,
+ # since 0.6.x satisfies _MLX_MIN_VERSIONS. Re-resolve only when the declared range actually
+ # moved, so the common update pays a metadata read and nothing else.
+ if IS_MAC_ARM and not NO_TORCH:
+ _mlx_vlm_spec_now = _mlx_vlm_spec_for_installed_zoo()
+ if _mlx_vlm_spec_used is None or _mlx_vlm_spec_now == _mlx_vlm_spec_used:
+ _progress("MLX stack (zoo unchanged, skipped)")
+ else:
+ _progress("MLX stack (re-resolved for the new zoo)")
+ _record_step("mlx", "ran")
+ pip_install(
+ "Installing MLX stack for the upgraded unsloth-zoo",
+ "--no-cache-dir",
+ *[arg for name in _MLX_NAMES for arg in ("--upgrade-package", name)],
+ *_MLX_PINS,
+ _mlx_vlm_spec_now,
+ )
+
if not skip_base:
base_requirements = _shared_base_requirements()
diff --git a/tests/studio/install/test_dependency_pass_skips.py b/tests/studio/install/test_dependency_pass_skips.py
index 09707d024ab..27d54bdc0f9 100644
--- a/tests/studio/install/test_dependency_pass_skips.py
+++ b/tests/studio/install/test_dependency_pass_skips.py
@@ -919,7 +919,7 @@ def test_a_pip_that_cannot_run_is_bootstrapped_again(monkeypatch) -> None:
def test_the_mlx_stack_is_current_only_when_all_four_hold(monkeypatch) -> None:
- versions = {"mlx": "0.32.1", "mlx-metal": "0.32.1", "mlx-lm": "0.31.3", "mlx-vlm": "0.5.0"}
+ versions = {"mlx": "0.32.2", "mlx-metal": "0.32.2", "mlx-lm": "0.31.3", "mlx-vlm": "0.5.0"}
monkeypatch.setattr(stack, "_installed_distribution_version", lambda name: versions.get(name))
# The closure of a stack that is not installed on this host is its own test below.
monkeypatch.setattr(stack, "_mlx_closure_unmet", lambda: False)
@@ -940,7 +940,7 @@ def test_the_mlx_stack_is_current_only_when_all_four_hold(monkeypatch) -> None:
def test_a_satisfied_mlx_pin_with_a_broken_closure_is_not_current(monkeypatch, tmp_path) -> None:
"""This step installs WITH dependencies, so it is what repairs an mlx-vlm whose own
miniaudio or mlx-audio is gone. Versions alone would skip that repair."""
- versions = {"mlx": "0.32.1", "mlx-metal": "0.32.1", "mlx-lm": "0.31.3", "mlx-vlm": "0.5.0"}
+ versions = {"mlx": "0.32.2", "mlx-metal": "0.32.2", "mlx-lm": "0.31.3", "mlx-vlm": "0.5.0"}
monkeypatch.setattr(stack, "_installed_distribution_version", lambda name: versions.get(name))
monkeypatch.setattr(stack, "_mlx_closure_unmet", lambda: True)
assert stack._mlx_stack_is_current() is False
@@ -1045,7 +1045,7 @@ def test_a_resident_codec_inside_the_window_needs_no_install(spec, installed, ex
def test_the_pip_fallback_never_names_one_project_twice() -> None:
- """pip refuses `mlx==0.32.1 mlx` outright with "Double requirement given", which
+ """pip refuses `mlx==0.32.2 mlx` outright with "Double requirement given", which
would fail the very step the fallback exists to rescue."""
cmd = stack._build_pip_cmd(
(
@@ -1053,13 +1053,13 @@ def test_the_pip_fallback_never_names_one_project_twice() -> None:
"mlx",
"--upgrade-package",
"mlx-vlm",
- "mlx==0.32.1",
- "mlx-vlm>=0.4.4,<0.7.0",
+ "mlx==0.32.2",
+ "mlx-vlm>=0.4.4,<=0.7.1",
)
)
assert "--upgrade" in cmd and "--upgrade-package" not in cmd
assert cmd.count("mlx") == 0 and cmd.count("mlx-vlm") == 0
- assert "mlx==0.32.1" in cmd and "mlx-vlm>=0.4.4,<0.7.0" in cmd
+ assert "mlx==0.32.2" in cmd and "mlx-vlm>=0.4.4,<=0.7.1" in cmd
def test_a_package_named_only_by_the_flag_is_still_passed() -> None:
@@ -1476,7 +1476,12 @@ def test_no_evidence_at_all_is_probed(mlx, monkeypatch) -> None:
def test_the_fingerprint_names_everything_a_verdict_depends_on(monkeypatch) -> None:
monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "0.4.5")
fingerprint = stack._mlx_health_fingerprint()
- assert fingerprint["pins"] == list(stack._MLX_PINS) + [stack._MLX_VLM_SPEC]
+ # The narrowed mlx-vlm range, not the static one: the installed zoo is part of what a
+ # recorded verdict is valid for, so changing the zoo must invalidate it.
+ assert fingerprint["pins"] == list(stack._MLX_PINS) + [
+ stack._mlx_vlm_spec_for_installed_zoo()
+ ]
+ assert fingerprint["pins"][-1].startswith(stack._MLX_VLM_SPEC)
assert fingerprint["python"] == stack._installer_python_tag()
assert fingerprint["imports"] == {n: "0.4.5" for n in stack._MLX_IMPORTED_DEPENDENCIES}
assert {"transformers", "tokenizers", "numpy", "huggingface-hub"} <= set(fingerprint["imports"])
diff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.py
index 877bbaebe37..a906c82be63 100644
--- a/tests/studio/install/test_mlx_install.py
+++ b/tests/studio/install/test_mlx_install.py
@@ -108,6 +108,9 @@ def _repair_specs():
def test_mlx_install_respects_platform_mode_and_pins(
monkeypatch, platform, skip_base, no_torch, shared_base
):
+ # What the repository declares, not what the host's installed zoo narrows it to; the
+ # narrowing has its own tests below.
+ monkeypatch.setattr(stack, "_mlx_vlm_spec_for_installed_zoo", lambda: stack._MLX_VLM_SPEC)
calls = _run_to_extras(
monkeypatch,
platform = platform,
@@ -119,9 +122,10 @@ def test_mlx_install_respects_platform_mode_and_pins(
assert len(calls) == int(enabled)
if platform.startswith("macos"):
# An update without torch announces the no-torch runtime deps on their own slot.
+ # Two mac-arm slots: the MLX step, and the re-resolve after the core phase.
assert stack._TOTAL == (
(12 if skip_base and not shared_base else 13)
- + int(enabled)
+ + 2 * int(enabled)
+ int(no_torch and not skip_base)
)
if enabled:
@@ -202,7 +206,7 @@ def test_mlx_command_preserves_pins_and_interpreter_on_fallback(monkeypatch, ret
if len(commands) > 1:
assert "--upgrade" in commands[1]
assert "--upgrade-package" not in commands[1]
- # ...and no project twice: pip refuses "mlx==0.32.1 mlx" with "Double requirement given".
+ # ...and no project twice: pip refuses "mlx==0.32.2 mlx" with "Double requirement given".
projects = [
arg.split(";")[0].split("[")[0].split("=")[0].split("<")[0].split(">")[0].strip()
for arg in commands[1]
@@ -227,7 +231,7 @@ def test_mlx_command_preserves_pins_and_interpreter_on_fallback(monkeypatch, ret
def test_mlx_pin_floor_matches_the_published_wheels(
monkeypatch, python_version, macos_major, installable
):
- """0.32.1 ships macosx_14_0_arm64 wheels, no sdist, and the pinned set starts at cp310."""
+ """0.32.2 ships macosx_14_0_arm64 wheels, no sdist, and the pinned set starts at cp310."""
monkeypatch.setattr(stack.sys, "version_info", python_version)
monkeypatch.setattr(stack, "_macos_release_major", Mock(return_value = macos_major))
assert stack._mlx_pins_are_installable() is installable
@@ -236,9 +240,9 @@ def test_mlx_pin_floor_matches_the_published_wheels(
def test_pin_floor_is_revisited_whenever_the_pins_move():
"""A pin bumped without its floor silently starts failing installs, so tie them here."""
assert _repair_specs() == {
- "mlx": "==0.32.1",
+ "mlx": "==0.32.2",
"mlx-lm": "==0.31.3",
- "mlx-vlm": ">=0.4.4,<0.7.0",
+ "mlx-vlm": ">=0.4.4,<=0.7.1",
}
assert (stack._MLX_MIN_PYTHON, stack._MLX_MIN_MACOS_MAJOR) == ((3, 10), 14)
@@ -265,7 +269,8 @@ def test_unsupported_apple_silicon_skips_mlx_without_failing_the_install(
assert "MLX stack (Apple Silicon)" not in steps
assert "MLX stack (skipped, no wheel for this macOS or Python)" in steps
# A skipped step still spends its slot.
- assert stack._TOTAL == (12 if skip_base and not shared_base else 13) + 1
+ # Two mac-arm slots even with no wheel: the re-resolve slot is spent unconditionally.
+ assert stack._TOTAL == (12 if skip_base and not shared_base else 13) + 2
def test_supported_and_unsupported_hosts_share_one_progress_budget(monkeypatch):
@@ -286,3 +291,83 @@ def test_supported_and_unsupported_hosts_share_one_progress_budget(monkeypatch):
mlx_installable = False,
)
assert stack._TOTAL == supported
+
+
+def test_mlx_vlm_spec_is_intersected_with_the_installed_zoo(monkeypatch):
+ """The MLX step runs before the core phase, and SKIP_STUDIO_BASE=1 skips that phase
+ altogether, so a zoo predating the gated_delta_update fix would be left beside mlx-vlm
+ 0.7.1 and Qwen3.5 VLM training would raise TypeError at its first step."""
+ import importlib.metadata
+
+ monkeypatch.setattr(
+ importlib.metadata,
+ "requires",
+ lambda _name: [
+ 'mlx==0.32.1; sys_platform == "darwin" and platform_machine == "arm64"',
+ 'mlx-vlm<0.7.0,>=0.4.4; sys_platform == "darwin" and platform_machine == "arm64"',
+ ],
+ )
+ spec = stack._mlx_vlm_spec_for_installed_zoo()
+ assert spec.startswith(stack._MLX_VLM_SPEC)
+ assert "<0.7.0" in spec
+
+
+def test_mlx_vlm_spec_is_unchanged_without_an_installed_zoo(monkeypatch):
+ import importlib.metadata
+
+ def _raise(_name):
+ raise importlib.metadata.PackageNotFoundError("unsloth_zoo")
+
+ monkeypatch.setattr(importlib.metadata, "requires", _raise)
+ assert stack._mlx_vlm_spec_for_installed_zoo() == stack._MLX_VLM_SPEC
+
+
+def test_the_skip_predicate_uses_the_narrowed_range(monkeypatch):
+ """0.7.1 already installed beside a zoo declaring <0.7.0 must NOT read as current, or the
+ step skips the install that would put mlx-vlm back where the zoo can drive it."""
+ monkeypatch.setattr(stack, "_exact_distribution_spec_is_installed", lambda _spec: True)
+ monkeypatch.setattr(stack, "_installed_distribution_version", lambda _name: "0.7.1")
+ monkeypatch.setattr(stack, "_mlx_closure_unmet", lambda: [])
+
+ monkeypatch.setattr(stack, "_mlx_vlm_spec_for_installed_zoo", lambda: stack._MLX_VLM_SPEC)
+ assert stack._mlx_stack_is_current() is True
+
+ monkeypatch.setattr(
+ stack, "_mlx_vlm_spec_for_installed_zoo", lambda: f"{stack._MLX_VLM_SPEC},<0.7.0"
+ )
+ assert stack._mlx_stack_is_current() is False
+
+
+def _zoo_spec_sequence(monkeypatch, specs):
+ """_mlx_vlm_spec_for_installed_zoo answering differently before and after the core phase."""
+ remaining = list(specs)
+
+ def spec():
+ return remaining.pop(0) if len(remaining) > 1 else remaining[0]
+
+ monkeypatch.setattr(stack, "_mlx_vlm_spec_for_installed_zoo", spec)
+
+
+def test_the_core_phase_upgrading_the_zoo_re_resolves_mlx(monkeypatch):
+ """The MLX step runs before the core phase, so it honours the OLD zoo's range. Without the
+ re-resolve an update that moves the zoo leaves the machine on the narrower mlx-vlm for good:
+ the startup self-heal will not correct it, since 0.6.x satisfies _MLX_MIN_VERSIONS."""
+ narrow = f"{stack._MLX_VLM_SPEC},<0.7.0"
+ # Twice for the install step, then the widened answer after the core phase.
+ _zoo_spec_sequence(monkeypatch, [narrow, narrow, stack._MLX_VLM_SPEC])
+ calls = _run_to_extras(
+ monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False
+ )
+ assert len(calls) == 2
+ assert "MLX stack (re-resolved for the new zoo)" in _run_to_extras.steps
+ assert narrow in list(calls[0].args[1:])
+ assert stack._MLX_VLM_SPEC in list(calls[1].args[1:])
+
+
+def test_an_unchanged_zoo_does_not_re_resolve_mlx(monkeypatch):
+ _zoo_spec_sequence(monkeypatch, [stack._MLX_VLM_SPEC])
+ calls = _run_to_extras(
+ monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False
+ )
+ assert len(calls) == 1
+ assert "MLX stack (zoo unchanged, skipped)" in _run_to_extras.steps
diff --git a/tests/studio/install/test_windows_torch_flavor_invariant.py b/tests/studio/install/test_windows_torch_flavor_invariant.py
index 5f7460acf05..0664fd78551 100644
--- a/tests/studio/install/test_windows_torch_flavor_invariant.py
+++ b/tests/studio/install/test_windows_torch_flavor_invariant.py
@@ -338,7 +338,8 @@ class TestStepTotals:
[
({}, 17), # Linux, torch
({"NO_TORCH": True}, 15), # Linux, GGUF-only (incl. the no-torch runtime step)
- ({"IS_MACOS": True, "IS_MAC_ARM": True}, 14), # Apple Silicon
+ # Two MLX slots: the install step and the post-core-phase re-resolve.
+ ({"IS_MACOS": True, "IS_MAC_ARM": True}, 15), # Apple Silicon
({"IS_MACOS": True}, 13), # Intel Mac
],
)