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: finish an update with the installer it installs (#11566)
oobabooga6f6d49a448bc
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.pyindex e165ac5597e..62871cf1c92 100644--- a/studio/install_python_stack.py+++ b/studio/install_python_stack.py@@ -10400,7 +10400,11 @@ _COMMIT_REVISION_RE = re.compile(r"[0-9a-fA-F]{7,40}")_GITHUB_ARCHIVE_HOSTS = ("github.com", "www.github.com")-def _github_archive_url(url: str, revision: str, subdirectory: str = "") -> "str | None":+def _github_archive_url(+ url: str,+ revision: str,+ subdirectory: str = "",+) -> "str | None":"""The zip GitHub serves for *revision* of *url*, or None when there is no such URL.This is the route a host with no working git takes. pip fetches a zip over plain https and@@ -10438,6 +10442,16 @@ def _github_archive_url(url: str, revision: str, subdirectory: str = "") -> "strreturn f"https://github.com/{owner}/{repo}/archive/{revision.lower()}.zip"+def _vcs_url_key(url: str) -> str:+ """A git URL without the trailing slash or ``.git``, which uv drops from direct_url.json.++ The requirements files name ``https://github.com/<org>/<repo>.git`` and uv records the URL+ without the suffix, so an exact compare never matched and every pass rebuilt the checkout.+ """+ url = url.rstrip("/")+ return url[: -len(".git")] if url.endswith(".git") else url++def _direct_reference_is_installed(req: Path, dist_name: str) -> bool:"""Whether the resident *dist_name* came from the ref *req* names.@@ -10468,7 +10482,7 @@ def _direct_reference_is_installed(req: Path, dist_name: str) -> bool:and str(payload.get("url") or "") == archive)if not (- str(payload.get("url") or "").rstrip("/") == url.rstrip("/")+ _vcs_url_key(str(payload.get("url") or "")) == _vcs_url_key(url)and str(vcs.get("requested_revision") or "") == revisionand str(payload.get("subdirectory") or "") == subdirectory):@@ -10593,6 +10607,43 @@ def _diffusers_main_supersedes_release() -> bool:return _diffusers_main_requested() and _diffusers_main_resident()+def _diffusers_main_archive(req: Path) -> "str | None":+ """The zip route 11c takes on a host with no working git, or None when it has none."""+ wanted = _direct_reference_in_requirements(req)+ return _github_archive_url(*wanted) if wanted is not None else None+++def _diffusers_main_needs_dependency_pass() -> bool:+ """For the setup fast path: is the resident Diffusers the wrong one for the requested mode?++ The fast path skips this script whenever the core package is current, so without this an+ install that never ran 11c (updated by an installer that predates it, or opted back in) stays+ on the release until the next version bump. The same gates as 11c decide whether the pass+ could install the build at all, so a host with neither git nor the zip route keeps its fast+ path. A pass that tried+ and failed records "failed" and also keeps it: without that, a host that cannot reach+ github.com would repeat the whole dependency pass on every update.+ """+ req = REQ_ROOT / "diffusers-main.txt"+ if not req.is_file():+ return False+ if not _diffusers_main_requested():+ # Opted out while the build is still resident: 11b puts the release back.+ return _diffusers_main_resident(req)+ if sys.version_info < DIFFUSERS_MAIN_MIN_PYTHON:+ return False+ if not _has_working_git() and _diffusers_main_archive(req) is None:+ return False+ if _diffusers_main_resident(req):+ return False+ try:+ manifest = install_manifest.read_manifest() or {}+ last = (manifest.get("step_results") or {}).get("diffusers-main.txt")+ except Exception: # noqa: BLE001 - an unreadable manifest is no record of a failed try+ last = None+ return last != "failed"++def _diffusers_main_step() -> None:"""Install the pinned Diffusers commit, or leave the release pin alone.@@ -10638,8 +10689,7 @@ def _diffusers_main_step() -> None:# over plain https. None when the pin is not a full GitHub commit, which keeps the old skip.archive = Noneif not _has_working_git():- wanted = _direct_reference_in_requirements(req)- archive = _github_archive_url(*wanted) if wanted is not None else None+ archive = _diffusers_main_archive(req)if archive is None:_progress("diffusers main (skipped, no git)")_note(@@ -10679,7 +10729,8 @@ def _diffusers_main_step() -> None:constrain = False,)if not installed:- _record_step("diffusers-main.txt", "skipped")+ # "failed", not "skipped": the fast path reads it to stop forcing a pass that cannot succeed.+ _record_step("diffusers-main.txt", "failed")_note("Could not install the pinned Diffusers main build, so this install keeps the pinned ""Diffusers release. Everything else works; models that need an unreleased Diffusers "@@ -10891,6 +10942,55 @@ def _local_plugin_digest(plugin_dir: Path) -> "str | None":return digest.hexdigest()+def _read_own_source() -> "bytes | None":+ try:+ return Path(__file__).read_bytes()+ except OSError:+ return None+++# This file as it was when the process started. The core-packages step upgrades the package+# that ships it, and the process keeps running the old code while the new copy sits on disk.+_INSTALLER_SOURCE_AT_START = _read_own_source()+# Set on the rerun, so a second replacement cannot loop.+_INSTALLER_RERUN_ENV = "UNSLOTH_INSTALLER_RERUN"+++class _InstallerReplaced(Exception):+ """Raised once the core-packages step has replaced this file with another release's copy."""+++def _installer_replaced() -> bool:+ if os.environ.get(_INSTALLER_RERUN_ENV) == "1" or _INSTALLER_SOURCE_AT_START is None:+ return False+ current = _read_own_source()+ return current is not None and current != _INSTALLER_SOURCE_AT_START+++def _rerun_replaced_installer() -> int:+ """Finish the pass with the installer the update just installed.++ Without this every step a release adds is skipped by the update that installs it: the old+ process upgrades the package in step 3 and completes its own step list. A subprocess rather+ than an exec, because on Windows os.exec* returns to the caller while the child runs. It starts+ after the pass lock is released, so the rerun does not read its parent as a contending peer.+ """+ _note("the update replaced this installer; finishing with the new version")+ try:+ # The child writes to the same descriptors, so anything still buffered here would land+ # after its output.+ sys.stdout.flush()+ sys.stderr.flush()+ except (OSError, ValueError):+ pass+ env = dict(os.environ)+ env[_INSTALLER_RERUN_ENV] = "1"+ return subprocess.run(+ [sys.executable, str(Path(__file__).resolve()), *sys.argv[1:]],+ env = env,+ ).returncode++def _under_pass_lock(func):"""Run the pass holding the pass lock, and record whether a peer already had it."""@@ -11202,6 +11302,11 @@ def install_python_stack() -> int:"unsloth-zoo",)+ # The package just installed may ship a newer copy of this file. Raised rather than rerun+ # here, so the pass lock is released first; the rerun repeats the cheap steps above.+ if _installer_replaced():+ raise _InstallerReplaced+# 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,@@ -11824,8 +11929,14 @@ if __name__ == "__main__":if sys.argv[1:] == ["--missing-torch-needs-dependency-pass"]:# Exit 0 forces the dependency pass; exit 1 keeps the fast path.sys.exit(0 if _missing_torch_needs_dependency_pass() else 1)+ if sys.argv[1:] == ["--diffusers-main-needs-dependency-pass"]:+ # Exit 0 forces the dependency pass; exit 1 keeps the fast path.+ sys.exit(0 if _diffusers_main_needs_dependency_pass() else 1)if any(_arg.startswith("-") for _arg in sys.argv[1:]):# Never let a malformed probe call fall through into a multi-gigabyte install._safe_print(f"Unknown argument: {' '.join(sys.argv[1:])}")sys.exit(2)- sys.exit(install_python_stack())+ try:+ sys.exit(install_python_stack())+ except _InstallerReplaced:+ sys.exit(_rerun_replaced_installer())diff --git a/studio/setup.ps1 b/studio/setup.ps1index 5672c1461bf..705a25e46f4 100644--- a/studio/setup.ps1+++ b/studio/setup.ps1@@ -7225,6 +7225,23 @@ sys.exit(0 if installed is not None and required is not None and installed >= re$SkipPythonDeps = $false}}+ # As setup.sh: the pinned Diffusers main build is installed only by the pass, so an install+ # that never ran that step (updated by an installer that predates it) kept the release.+ if ($SkipPythonDeps) {+ $_diffusersMainMissing = $false+ try {+ & python (Join-Path $PSScriptRoot "install_python_stack.py") --diffusers-main-needs-dependency-pass *> $null+ if ($LASTEXITCODE -eq 0) { $_diffusersMainMissing = $true }+ } catch {}+ if ($_diffusersMainMissing) {+ if ($script:OfflineFastPath -or (Test-UvOfflineRequested)) {+ substep "pinned Diffusers build is not installed but UV_OFFLINE is set -- left for the next online update" "Yellow"+ } else {+ substep "pinned Diffusers build is not installed -- forcing dependency pass..." "Cyan"+ $SkipPythonDeps = $false+ }+ }+ }# ...and for an Intel GPU, or a CPU wheel stays forever. Both escapes reach the XPU install,# gated on $XpuIndexUrl, so $_xpuIsReachable holds them back where a pin or no-torch mode# sends this host elsewhere and they would re-fire forever.diff --git a/studio/setup.sh b/studio/setup.shindex 70260ae0be5..9ae1d09550b 100755--- a/studio/setup.sh+++ b/studio/setup.sh@@ -2831,6 +2831,26 @@ sys.exit(0 if windows and installed not in windows[0] else 1)fifiunset _fpe_missing_torch+ # The pinned Diffusers main build is installed only by the pass, so an install that never ran+ # that step (updated by an installer that predates it) kept the release while current.+ _fpe_diffusers=false+ if command -v timeout >/dev/null 2>&1; then+ timeout -k 5 180 "$VENV_DIR/bin/python" \+ "$SCRIPT_DIR/install_python_stack.py" --diffusers-main-needs-dependency-pass \+ >/dev/null 2>&1 && _fpe_diffusers=true+ elif "$VENV_DIR/bin/python" "$SCRIPT_DIR/install_python_stack.py" \+ --diffusers-main-needs-dependency-pass >/dev/null 2>&1; then+ _fpe_diffusers=true+ fi+ if [ "$_fpe_diffusers" = true ] && [ "$_SKIP_PYTHON_DEPS" = true ]; then+ if [ "${_OFFLINE_FAST_PATH:-false}" = true ] || _uv_offline_requested; then+ substep "pinned Diffusers build is not installed but UV_OFFLINE is set -- left for the next online update"+ else+ substep "pinned Diffusers build is not installed -- forcing dependency pass..."+ _SKIP_PYTHON_DEPS=false+ fi+ fi+ unset _fpe_diffusers# If the desktop app specifies a minimum required backend version and the installed# package is older than that requirement, force the dependency pass to upgrade it.if [ -n "${UNSLOTH_DESKTOP_BACKEND_VERSION:-}" ]; thendiff --git a/tests/studio/install/test_dependency_pass_skips.py b/tests/studio/install/test_dependency_pass_skips.pyindex 6f1756a4aa8..830df6a7d18 100644--- a/tests/studio/install/test_dependency_pass_skips.py+++ b/tests/studio/install/test_dependency_pass_skips.py@@ -428,6 +428,10 @@ def test_a_git_requirement_is_matched_by_ref_not_version(monkeypatch, tmp_path)monkeypatch.setattr(importlib.metadata, "distribution", _distribution(recorded))assert stack._direct_reference_is_installed(req, "triton_kernels") is True+ # uv records the URL without ".git"; before this matched, every pass rebuilt the checkout.+ uv_shape = {**recorded, "url": "https://example.invalid/triton"}+ monkeypatch.setattr(importlib.metadata, "distribution", _distribution(uv_shape))+ assert stack._direct_reference_is_installed(req, "triton_kernels") is Truefor broken in ({**recorded, "vcs_info": {"vcs": "git", "requested_revision": "main"}},diff --git a/tests/studio/install/test_diffusers_pin.py b/tests/studio/install/test_diffusers_pin.pyindex 3aac6a5a26e..ea8217dcc84 100644--- a/tests/studio/install/test_diffusers_pin.py+++ b/tests/studio/install/test_diffusers_pin.py@@ -219,8 +219,7 @@ def test_the_main_build_falls_back_to_the_zip_when_there_is_no_git(monkeypatch):assert len(spec) == 1, argsrevision = _requirements(MAIN_FILE)[0].rpartition("@")[2].strip().lower()assert spec[0] == (- "diffusers @ https://github.com/huggingface/diffusers/archive/"- f"{revision}.zip"+ "diffusers @ https://github.com/huggingface/diffusers/archive/" f"{revision}.zip"), spec@@ -336,8 +335,8 @@ def test_a_failed_main_build_degrades_instead_of_failing_the_install(monkeypatchassert attempted and attempted[0].name == "diffusers-main.txt"assert (- steps["diffusers-main.txt"] == "skipped"- ), "a failed build recorded as 'ran' would report an install that never happened"+ steps["diffusers-main.txt"] == "failed"+ ), "the setup fast path reads 'failed' to stop forcing a pass that cannot succeed"assert notes and "keeps the pinned" in notes[0]@@ -712,3 +711,80 @@ def test_the_full_deps_escape_hatch_reaches_both_diffusers_steps(monkeypatch):assert installed == [], installedassert len(calls) == 1 and "opted out" in calls[0], callsassert module._diffusers_main_supersedes_release() is False+++def _fast_path_probe_module(+ monkeypatch,+ *,+ resident,+ git = True,+ last = None,+ requested = True,+):+ module = _probe_module("install_python_stack_fastpath_probe")+ if requested:+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)+ else:+ monkeypatch.setenv("UNSLOTH_DIFFUSERS_MAIN", "0")+ monkeypatch.setattr(module, "_has_working_git", lambda: git)+ monkeypatch.setattr(module, "_diffusers_main_resident", lambda *a, **k: resident)+ manifest = {"step_results": {"diffusers-main.txt": last}} if last else {}+ monkeypatch.setattr(module.install_manifest, "read_manifest", lambda *a, **k: manifest)+ return module+++def test_the_fast_path_is_forced_when_the_main_build_never_went_in(monkeypatch):+ """An install updated by an installer that predates 11c is current and still on the release."""+ module = _fast_path_probe_module(monkeypatch, resident = False)+ assert module._diffusers_main_needs_dependency_pass() is True+++def test_a_resident_main_build_keeps_the_fast_path(monkeypatch):+ module = _fast_path_probe_module(monkeypatch, resident = True)+ assert module._diffusers_main_needs_dependency_pass() is False+++def test_a_host_without_git_is_forced_only_when_the_zip_route_exists(monkeypatch):+ """11c installs the pinned commit from a zip without git; with no such route it skips, and+ forcing the pass there would repeat it on every update."""+ module = _fast_path_probe_module(monkeypatch, resident = False, git = False)+ assert module._diffusers_main_archive(module.REQ_ROOT / "diffusers-main.txt") is not None+ assert module._diffusers_main_needs_dependency_pass() is True+ monkeypatch.setattr(module, "_diffusers_main_archive", lambda req: None)+ assert module._diffusers_main_needs_dependency_pass() is False+++def test_a_recorded_failed_build_keeps_the_fast_path(monkeypatch):+ """A host that cannot reach github.com would otherwise run the whole pass on every update."""+ module = _fast_path_probe_module(monkeypatch, resident = False, last = "failed")+ assert module._diffusers_main_needs_dependency_pass() is False+ module = _fast_path_probe_module(monkeypatch, resident = False, last = "skipped")+ assert module._diffusers_main_needs_dependency_pass() is True+++def test_opting_out_forces_the_pass_only_while_the_main_build_is_resident(monkeypatch):+ """11b reinstates the release, but only if the pass runs."""+ module = _fast_path_probe_module(monkeypatch, resident = True, requested = False)+ assert module._diffusers_main_needs_dependency_pass() is True+ module = _fast_path_probe_module(monkeypatch, resident = False, requested = False)+ assert module._diffusers_main_needs_dependency_pass() is False++[email protected]("script", ["setup.sh", "setup.ps1"])+def test_both_fast_paths_consult_the_probe(script):+ source = (REPO_ROOT / "studio" / script).read_text(encoding = "utf-8")+ assert "--diffusers-main-needs-dependency-pass" in source+++def test_the_probe_flag_answers_without_a_traceback():+ """A crash also exits 1, which setup.sh reads as 'keep the fast path'."""+ import sys++ result = subprocess.run(+ [sys.executable, str(STACK), "--diffusers-main-needs-dependency-pass"],+ capture_output = True,+ text = True,+ timeout = 120,+ )+ assert result.returncode in (0, 1), result.stderr+ assert "Traceback" not in result.stderr, result.stderrdiff --git a/tests/studio/install/test_installer_rerun_after_upgrade.py b/tests/studio/install/test_installer_rerun_after_upgrade.pynew file mode 100644index 00000000000..0ad8e7647b3--- /dev/null+++ b/tests/studio/install/test_installer_rerun_after_upgrade.py@@ -0,0 +1,87 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""An update must finish with the installer it installs, not the one it started with.++The core-packages step upgrades the package that ships install_python_stack.py. Before this, the+old process completed its own step list, so every step a release added (the pinned Diffusers main+build in 2026.9.8) was skipped by the update that installed it.+"""++from __future__ import annotations++import ast+import importlib.util+import subprocess+import sys+from pathlib import Path++STACK = Path(__file__).resolve().parents[3] / "studio" / "install_python_stack.py"+++def _module(name = "install_python_stack_rerun_probe"):+ spec = importlib.util.spec_from_file_location(name, STACK)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def test_an_unchanged_installer_is_not_rerun(monkeypatch):+ module = _module()+ monkeypatch.delenv(module._INSTALLER_RERUN_ENV, raising = False)+ assert module._installer_replaced() is False+++def test_a_replaced_installer_is_rerun_once(monkeypatch):+ module = _module()+ monkeypatch.delenv(module._INSTALLER_RERUN_ENV, raising = False)+ monkeypatch.setattr(module, "_read_own_source", lambda: b"the next release")+ assert module._installer_replaced() is True+ # The rerun carries the marker, so a second replacement cannot loop.+ monkeypatch.setenv(module._INSTALLER_RERUN_ENV, "1")+ assert module._installer_replaced() is False+++def test_an_unreadable_installer_keeps_the_running_one(monkeypatch):+ module = _module()+ monkeypatch.delenv(module._INSTALLER_RERUN_ENV, raising = False)+ monkeypatch.setattr(module, "_read_own_source", lambda: None)+ assert module._installer_replaced() is False+++def test_the_rerun_runs_the_file_on_disk_and_returns_its_exit_code(monkeypatch):+ module = _module()+ calls = []++ def fake_run(argv, env):+ calls.append((argv, env))+ return subprocess.CompletedProcess(argv, 7)++ monkeypatch.setattr(module.subprocess, "run", fake_run)+ monkeypatch.setattr(module, "_note", lambda *a, **k: None)+ monkeypatch.setattr(sys, "argv", [str(STACK)])+ assert module._rerun_replaced_installer() == 7+ argv, env = calls[0]+ assert argv == [sys.executable, str(STACK.resolve())]+ assert env[module._INSTALLER_RERUN_ENV] == "1"+++def test_the_check_follows_the_core_step_and_the_rerun_starts_outside_the_pass_lock():+ """Raised inside install_python_stack, caught only at the entry point.++ Structural, because driving the real pass needs a venv and the network.+ """+ source = STACK.read_text(encoding = "utf-8")+ tree = ast.parse(source)+ func = next(+ node+ for node in tree.body+ if isinstance(node, ast.FunctionDef) and node.name == "install_python_stack"+ )+ body = ast.get_source_segment(source, func)+ core = body.rindex('"Updating core packages"')+ check = body.index("_installer_replaced()")+ assert core < check < body.index("_mlx_vlm_spec_now = ")+ main = source[source.index('if __name__ == "__main__":') :]+ assert "except _InstallerReplaced:" in main+ assert "_rerun_replaced_installer()" in main