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.

Studio updater: install a matched unsloth + unsloth-zoo pair when the index lags (#14834)

Daniel Han3cf161740f13
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 8fdc487877c..71e8d2f577b 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -10578,14 +10578,17 @@ def _mirror_retry(args: "tuple[str, ...]", output: bytes, rerun) -> "bool | None
FEED_CEILING_MARKER = "unsloth_feed_ceiling.json"
-def _desktop_unsloth_spec(package_name: str) -> str:
+def _desktop_unsloth_spec(package_name: str) -> "tuple[str, str]":
"""Desktop's backend floor, lowered to a lagging index's newest release (#14031).
- Twin of install.sh's _relax_unsloth_floors_to_index.
+ Returns the (unsloth, unsloth-zoo) requirements to install. A lowered unsloth comes with
+ the zoo it was resolved against, since the no-torch path installs --no-deps and so never
+ reads unsloth's zoo floor. Twin of install.sh's _relax_unsloth_floors_to_index.
"""
+ zoo_spec = "unsloth-zoo"
desktop_min_ver = os.environ.get("UNSLOTH_DESKTOP_BACKEND_VERSION", "").strip()
if not (desktop_min_ver and package_name == "unsloth"):
- return package_name
+ return package_name, zoo_spec
spec = f"unsloth>={desktop_min_ver}"
marker = Path(sys.prefix) / FEED_CEILING_MARKER
try:
@@ -10593,19 +10596,21 @@ def _desktop_unsloth_spec(package_name: str) -> str:
except OSError:
pass
if not USE_UV:
- return spec
+ return spec, zoo_spec
- def newest(requirement: str, name: str = "unsloth") -> "str | None":
+ def resolve(*requirements: str, deps: bool = False) -> "dict[str, str] | None":
# --output-file: a uv.toml output-file would otherwise be overwritten by every probe.
+ # Linux x86_64 is fixed so a host without torch wheels (Intel Mac, no-torch) still resolves.
with tempfile.TemporaryDirectory() as scratch:
out = Path(scratch) / "probe.txt"
- argv = ["uv", "pip", "compile", "--python", sys.executable, "--no-deps"]
+ argv = ["uv", "pip", "compile", "--python", sys.executable]
+ argv += ["--python-platform", "x86_64-manylinux_2_28"] if deps else ["--no-deps"]
argv += ["--resolution", "highest", "--no-header", "--no-annotate", "--quiet"]
argv += ["--output-file", str(out), "-"]
try:
result = subprocess.run(
argv,
- input = requirement + "\n",
+ input = "\n".join(requirements) + "\n",
stdout = subprocess.DEVNULL,
stderr = subprocess.DEVNULL,
text = True,
@@ -10617,29 +10622,52 @@ def _desktop_unsloth_spec(package_name: str) -> str:
return None
if text is None:
return None
- match = re.search(rf"^{name}==([0-9][0-9A-Za-z.+!-]*)", text, re.MULTILINE)
- return match.group(1) if match else None
+ found = dict(
+ re.findall(r"^(unsloth(?:-zoo)?)==([0-9][0-9A-Za-z.+!-]*)", text, re.MULTILINE)
+ )
+ return found or None
- if newest(spec) is not None:
- return spec
+ def newest(requirement: str, name: str = "unsloth") -> "str | None":
+ return (resolve(requirement) or {}).get(name)
+
+ found = resolve(spec, zoo_spec, deps = True) or {}
+ if found.get("unsloth"):
+ # The zoo it resolved against as a floor: the no-torch install is --no-deps, so a bare
+ # unsloth-zoo under UV_RESOLUTION=lowest could pick one below unsloth's own zoo floor.
+ return spec, (f"unsloth-zoo>={found['unsloth-zoo']}" if found.get("unsloth-zoo") else zoo_spec)
+ requested_present = newest(spec) is not None
# The newest zoo, then the newest unsloth not above it (an unsloth never needs a newer zoo).
- zoo = newest("unsloth-zoo", "unsloth-zoo")
+ zoo = newest(zoo_spec, "unsloth-zoo")
available = newest(f"unsloth<={zoo}") if zoo else None
if available is None:
- return spec
- _note(
- f"[WARN] your package index does not have {spec} yet; "
- f"installing unsloth {available}, the newest it has",
- _warn,
- )
+ return spec, zoo_spec
+ # A newer unsloth whose zoo floor the index still meets beats that bound (unsloth patch
+ # releases often ship without a zoo release).
+ pair = resolve(f"unsloth>={available}", zoo_spec, deps = True) or {}
+ if pair.get("unsloth") and pair.get("unsloth-zoo"):
+ available, zoo = pair["unsloth"], pair["unsloth-zoo"]
+ elif requested_present:
+ # The index has the release and nothing older resolves either: not a lag to work around.
+ return spec, zoo_spec
try:
- marker.write_text(
- json.dumps({"requested": desktop_min_ver, "available": available}) + "\n",
- encoding = "utf-8",
+ from packaging.version import Version
+ lowered = Version(available) < Version(desktop_min_ver)
+ except Exception: # noqa: BLE001 - unparseable: treat as lowered, as before
+ lowered = True
+ if lowered:
+ _note(
+ f"[WARN] your package index does not have {spec} with a matching unsloth-zoo yet; "
+ f"installing unsloth {available} + unsloth-zoo {zoo}, the newest pair it has",
+ _warn,
)
- except OSError:
- pass
- return f"unsloth=={available}"
+ try:
+ marker.write_text(
+ json.dumps({"requested": desktop_min_ver, "available": available}) + "\n",
+ encoding = "utf-8",
+ )
+ except OSError:
+ pass
+ return f"unsloth=={available}", f"unsloth-zoo=={zoo}"
def pip_install(
@@ -12895,7 +12923,7 @@ def install_python_stack() -> int:
elif NO_TORCH:
# No-torch update path: --no-deps throughout (PyPI metadata makes torch a hard dep).
_progress("base packages (no torch)")
- unsloth_spec = _desktop_unsloth_spec(package_name)
+ unsloth_spec, zoo_spec = _desktop_unsloth_spec(package_name)
pip_install(
f"Updating {package_name} + unsloth-zoo (no-torch mode)",
"--no-cache-dir",
@@ -12905,7 +12933,7 @@ def install_python_stack() -> int:
"--upgrade-package",
"unsloth-zoo",
unsloth_spec,
- "unsloth-zoo",
+ zoo_spec,
)
# pydantic WITH deps (all torch-free) so pip pins a matching pydantic-core.
pip_install(
@@ -12948,7 +12976,7 @@ def install_python_stack() -> int:
)
else:
_progress("base packages")
- unsloth_spec = _desktop_unsloth_spec(package_name)
+ unsloth_spec, zoo_spec = _desktop_unsloth_spec(package_name)
with _FreezeNewTorchForCoreUpdate():
pip_install(
"Updating core packages",
@@ -12958,7 +12986,7 @@ def install_python_stack() -> int:
"--upgrade-package",
"unsloth-zoo",
unsloth_spec,
- "unsloth-zoo",
+ zoo_spec,
)
# The package just installed may ship a newer copy of this file. Raised rather than rerun
diff --git a/tests/python/test_install_python_stack.py b/tests/python/test_install_python_stack.py
index b61f4c70972..e25064f78a3 100644
--- a/tests/python/test_install_python_stack.py
+++ b/tests/python/test_install_python_stack.py
@@ -2880,23 +2880,52 @@ class TestDesktopBackendVersionConstraint:
"""UNSLOTH_DESKTOP_BACKEND_VERSION floors the unsloth upgrade, lowered only for a lagging index (#14031)."""
@staticmethod
- def _fake_uv(have, zoo = None):
+ def _fake_uv(
+ have,
+ zoo = None,
+ floors = None,
+ ):
+ """uv pip compile over a fake index: unsloth 2026.10.2..have, unsloth-zoo 2026.10.2..zoo.
+
+ Each unsloth requires unsloth-zoo>=its own version unless *floors* says otherwise; the
+ zoo floor is only enforced when the probe resolves dependencies.
+ """
+ from packaging.requirements import Requirement
+
+ def releases(top):
+ return [f"2026.10.{n}" for n in range(2, 10) if Version(f"2026.10.{n}") <= Version(top)]
+
+ unsloth = releases(have)
+ zoos = releases(zoo or have)
+ floor_of = {v: (floors or {}).get(v, v) for v in unsloth}
+
def run(
argv,
input = None,
**kwargs,
):
- assert argv[:3] == ["uv", "pip", "compile"] and "--no-deps" in argv
+ assert argv[:3] == ["uv", "pip", "compile"]
+ deps = "--no-deps" not in argv
out = Path(argv[argv.index("--output-file") + 1])
- floor = re.search(r">=(\S+)", input)
- if floor and Version(floor.group(1)) > Version(have):
- return subprocess.CompletedProcess(argv, 1)
- if input.strip() == "unsloth-zoo":
- out.write_text(f"unsloth-zoo=={zoo or have} \\\n", encoding = "utf-8")
+ reqs = {r.name: r.specifier for r in map(Requirement, input.split())}
+ u_ok = [v for v in unsloth if v in reqs.get("unsloth", v)]
+ z_ok = [v for v in zoos if v in reqs.get("unsloth-zoo", v)]
+ picked = {}
+ if "unsloth" in reqs:
+ for v in sorted(u_ok, key = Version, reverse = True):
+ fit = [z for z in z_ok if not deps or Version(z) >= Version(floor_of[v])]
+ if fit:
+ picked["unsloth"] = v
+ if deps or "unsloth-zoo" in reqs:
+ picked["unsloth-zoo"] = max(fit, key = Version)
+ break
+ else:
+ return subprocess.CompletedProcess(argv, 1)
+ elif z_ok:
+ picked["unsloth-zoo"] = max(z_ok, key = Version)
else:
- cap = re.search(r"<=(\S+)", input)
- pick = min(have, cap.group(1), key = Version) if cap else have
- out.write_text(f"unsloth=={pick}\n", encoding = "utf-8")
+ return subprocess.CompletedProcess(argv, 1)
+ out.write_text("".join(f"{k}=={v} \\\n" for k, v in picked.items()), encoding = "utf-8")
return subprocess.CompletedProcess(argv, 0)
return run
@@ -2908,6 +2937,8 @@ class TestDesktopBackendVersionConstraint:
have = "2026.10.3",
package = "unsloth",
zoo = None,
+ floors = None,
+ full = False,
):
with (
mock.patch.dict(os.environ, env, clear = True),
@@ -2923,17 +2954,22 @@ class TestDesktopBackendVersionConstraint:
"default_index": None,
},
),
- mock.patch.object(ips.subprocess, "run", side_effect = self._fake_uv(have, zoo)) as run,
+ mock.patch.object(
+ ips.subprocess, "run", side_effect = self._fake_uv(have, zoo, floors)
+ ) as run,
):
- return ips._desktop_unsloth_spec(package), run.call_count
+ specs = ips._desktop_unsloth_spec(package)
+ return (specs if full else specs[0]), run.call_count
def test_spec_includes_floor_when_env_set(self, tmp_path):
- spec, calls = self._spec(tmp_path, {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.8.15"})
- assert spec == "unsloth>=2026.8.15"
+ spec, calls = self._spec(
+ tmp_path, {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.8.15"}, full = True
+ )
+ assert spec == ("unsloth>=2026.8.15", "unsloth-zoo>=2026.10.3")
assert calls == 1, "an index that has the release answers the one probe"
def test_spec_bare_when_env_unset(self, tmp_path):
- assert self._spec(tmp_path, {})[0] == "unsloth"
+ assert self._spec(tmp_path, {}, full = True)[0] == ("unsloth", "unsloth-zoo")
assert (
self._spec(tmp_path, {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6"}, package = "x")[0]
== "x"
@@ -2954,6 +2990,48 @@ class TestDesktopBackendVersionConstraint:
assert spec == "unsloth>=2026.10.6"
assert not (tmp_path / ips.FEED_CEILING_MARKER).exists()
+ def test_lowered_unsloth_carries_its_zoo_pin(self, tmp_path):
+ env = {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6"}
+ assert self._spec(tmp_path, env, full = True)[0] == (
+ "unsloth==2026.10.3",
+ "unsloth-zoo==2026.10.3",
+ )
+
+ def test_zoo_behind_requested_unsloth_lowers_to_resolvable_pair(self, tmp_path):
+ # unsloth 2026.10.6 is on the index but its zoo floor is not: the requested floor
+ # cannot resolve, the 2026.10.3 pair can.
+ env = {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6"}
+ spec, _ = self._spec(tmp_path, env, have = "2026.10.6", zoo = "2026.10.3", full = True)
+ assert spec == ("unsloth==2026.10.3", "unsloth-zoo==2026.10.3")
+ marker = json.loads((tmp_path / ips.FEED_CEILING_MARKER).read_text(encoding = "utf-8"))
+ assert marker == {"requested": "2026.10.6", "available": "2026.10.3"}
+
+ def test_unsloth_ahead_of_zoo_with_met_floor_is_untouched(self, tmp_path):
+ env = {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6"}
+ spec, calls = self._spec(
+ tmp_path,
+ env,
+ have = "2026.10.6",
+ zoo = "2026.10.3",
+ floors = {"2026.10.6": "2026.10.3"},
+ full = True,
+ )
+ assert spec == ("unsloth>=2026.10.6", "unsloth-zoo>=2026.10.3")
+ assert calls == 1
+ assert not (tmp_path / ips.FEED_CEILING_MARKER).exists()
+
+ def test_lowered_pair_prefers_newest_unsloth_whose_floor_is_met(self, tmp_path):
+ env = {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6"}
+ spec, _ = self._spec(
+ tmp_path,
+ env,
+ have = "2026.10.6",
+ zoo = "2026.10.3",
+ floors = {"2026.10.5": "2026.10.3"},
+ full = True,
+ )
+ assert spec == ("unsloth==2026.10.5", "unsloth-zoo==2026.10.3")
+
def test_extra_index_beside_pypi_counts(self, tmp_path):
# first-index: a lagging UV_INDEX mirror shadows PyPI for the packages it carries.
env = {
@@ -2972,12 +3050,21 @@ class TestDesktopBackendVersionConstraint:
"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6",
"UV_INDEX": "https://feed.example/simple",
}
- assert self._spec(tmp_path, env, zoo = "2026.10.2")[0] == "unsloth==2026.10.2"
+ assert self._spec(tmp_path, env, zoo = "2026.10.2", full = True)[0] == (
+ "unsloth==2026.10.2",
+ "unsloth-zoo==2026.10.2",
+ )
def test_upload_cutoff_alone_counts(self, tmp_path):
env = {"UNSLOTH_DESKTOP_BACKEND_VERSION": "2026.10.6", "UV_EXCLUDE_NEWER": "2026-10-09"}
assert self._spec(tmp_path, env)[0] == "unsloth==2026.10.3"
+ def test_core_installs_pass_the_zoo_spec(self):
+ src = inspect.getsource(ips)
+ assert src.count("unsloth_spec, zoo_spec = _desktop_unsloth_spec(package_name)") == 2
+ assert src.count(" unsloth_spec,\n zoo_spec,\n") == 1
+ assert src.count(" unsloth_spec,\n zoo_spec,\n") == 1
+
class TestRecordlessDistributionRecovery:
"""pip can't uninstall a .dist-info with no RECORD, and nothing clears that state from a reused venv."""