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: finish an update with the installer it installs (#11566)

oobabooga6f6d49a448bc
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 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 = "") -> "str
return 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 "") == revision
and 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 = None
if 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.ps1
index 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.sh
index 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)
fi
fi
unset _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:-}" ]; then
diff --git a/tests/studio/install/test_dependency_pass_skips.py b/tests/studio/install/test_dependency_pass_skips.py
index 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 True
for 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.py
index 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, args
revision = _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(monkeypatch
assert 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 == [], installed
assert len(calls) == 1 and "opted out" in calls[0], calls
assert 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.stderr
diff --git a/tests/studio/install/test_installer_rerun_after_upgrade.py b/tests/studio/install/test_installer_rerun_after_upgrade.py
new file mode 100644
index 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