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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 | NoneFEED_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_specspec = f"unsloth>={desktop_min_ver}"marker = Path(sys.prefix) / FEED_CEILING_MARKERtry:@@ -10593,19 +10596,21 @@ def _desktop_unsloth_spec(package_name: str) -> str:except OSError:passif 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 Noneif 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 Noneif 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_spectry:- 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 rerundiff --git a/tests/python/test_install_python_stack.py b/tests/python/test_install_python_stack.pyindex 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 argvout = 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_countdef 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."""