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: stop a Windows update deleting the venv it is running from (#11248)

Leo Borcherding22192f7535ef
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 0055030e1fc..4163b952336 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -187,6 +187,57 @@ function Exit-SetupFailure {
exit $Code
}
+# The interpreter this setup was launched from, when it lives inside $VenvDir; $null otherwise.
+# `unsloth studio update` names its own sys.executable as UNSLOTH_SETUP_HOST_PYTHON; the process
+# walk covers an older CLI and any wrapper that runs the venv's python.exe by hand. Windows keeps
+# a running image undeletable, so a stale-venv wipe issued from inside the venv guts Lib\ and
+# then fails on Scripts\python.exe: callers repair such an environment in place instead.
+function Get-SetupHostInterpreterInVenv {
+ param([Parameter(Mandatory = $true)][string]$VenvDir)
+ $root = $null
+ # Not a literal '\': off Windows GetFullPath returns '/' and '\' is an ordinary filename
+ # character, so a hardcoded one builds a prefix nothing matches. The pwsh tests run there.
+ $sep = [System.IO.Path]::DirectorySeparatorChar
+ try { $root = [System.IO.Path]::GetFullPath($VenvDir).TrimEnd('\', '/') + $sep } catch { return $null }
+ $inside = {
+ param([string]$Candidate)
+ if ([string]::IsNullOrWhiteSpace($Candidate)) { return $false }
+ try { $full = [System.IO.Path]::GetFullPath($Candidate) } catch { return $false }
+ if (-not $full.StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)) { return $false }
+ # A path, not a file, is not an interpreter that can be holding anything open. The hint
+ # below is an inherited environment variable and can outlive what it names -- a stale one
+ # pointing inside the venv would otherwise route a venv that genuinely needs rebuilding
+ # into an in-place repair it has no interpreter to perform. A live process's own
+ # ExecutablePath passes this trivially; an unreadable one reads as "not inside", which is
+ # the pre-existing rebuild.
+ return (Test-Path -LiteralPath $full -PathType Leaf)
+ }
+ if (& $inside $env:UNSLOTH_SETUP_HOST_PYTHON) { return $env:UNSLOTH_SETUP_HOST_PYTHON }
+ try {
+ $byPid = @{}
+ foreach ($row in @(Get-CimInstance -ClassName Win32_Process -ErrorAction Stop)) {
+ $byPid[[int]$row.ProcessId] = $row
+ }
+ $cur = [int]$PID
+ # Bounded: ParentProcessId can name a reused id once the real parent is gone.
+ for ($hop = 0; $hop -lt 8 -and $byPid.ContainsKey($cur); $hop++) {
+ $row = $byPid[$cur]
+ if (& $inside $row.ExecutablePath) { return $row.ExecutablePath }
+ $parent = [int]$row.ParentProcessId
+ if ($parent -le 0 -or $parent -eq $cur) { break }
+ # A parent that started AFTER its child is not the parent: Windows reuses process ids
+ # once the real one has exited, and Microsoft's own Win32_Process guidance is to
+ # compare creation dates before trusting ParentProcessId. Unreadable dates on either
+ # side leave the hop alone rather than ending the walk, since the bound already caps it.
+ $parentRow = $byPid[$parent]
+ if ($parentRow -and $row.CreationDate -and $parentRow.CreationDate -and
+ $parentRow.CreationDate -gt $row.CreationDate) { break }
+ $cur = $parent
+ }
+ } catch { }
+ return $null
+}
+
# Detect if running from pip install (no frontend/ dir in studio)
$FrontendDir = Join-Path $ScriptDir "frontend"
$OxcValidatorDir = Join-Path $ScriptDir "backend\core\data_recipe\oxc-validator"
@@ -2732,6 +2783,11 @@ $StageRoot = if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_STAGE_ROO
$RuntimeRoot = if ($StageRoot) { $StageRoot } else { $StudioHome }
$VenvDir = Join-Path $RuntimeRoot "unsloth_studio"
$StudioOwnedMarker = ".unsloth-studio-owned"
+# Dropped into an environment this script has moved aside, so the sweep that removes such copies
+# can tell one it made from a directory that merely wears the same name. Written after the rename
+# and rewritten if the delete that follows fails, because a half-deleted copy can lose everything
+# else that identified it.
+$StudioStaleMarker = ".unsloth-studio-stale"
# Mirrors install_manifest.NO_TORCH_MARKER; keep the two in step.
$NoTorchMarker = ".unsloth-no-torch"
$LegacyStudioHome = Join-Path $env:USERPROFILE ".unsloth\studio"
@@ -6127,6 +6183,70 @@ if ((Test-Path -LiteralPath $VenvDir -PathType Container) -and -not $NoTorchMode
$script:PreservedInstallerTorchTag = $installedTorchTag
}
+ # A direct `unsloth studio update` has the installer-managed shape: the CLI is this script's
+ # parent and runs from the venv's own python.exe, so the wipe below left a venv with no
+ # unsloth_cli and a desktop whose update AND repair both start from it (#11247). Detected, not
+ # assumed: run by hand from a checkout there is no interpreter inside, and the rebuild stands.
+ # LAST of the direct-update escapes: this condition holds for EVERY stale direct update, so
+ # ahead of the narrower ones it consumes $shouldRebuild and they never fire. Ahead of the
+ # nvidia-smi guard specifically, $script:PreservedInstallerTorchTag goes unset and pairs with
+ # the $PinChangedForceReinstall below to force a CPU wheel over a working cu* venv (#9857).
+ if ($shouldRebuild -and -not $InstallerManagedSetup) {
+ $_hostPy = Get-SetupHostInterpreterInVenv -VenvDir $VenvDir
+ if ($_hostPy) {
+ substep "Environment does not match this host ($reason) -- reinstalling PyTorch in place." "Yellow"
+ substep "setup is running from $_hostPy, which cannot be replaced while it runs." "DarkGray"
+ $script:PinChangedForceReinstall = $true
+ $shouldRebuild = $false
+ }
+ }
+
+ # Outside the rebuild branch: an install that moved a venv aside, failed to delete the copy and
+ # thereafter only repairs in place would never reach a sweep that lived inside it.
+ # Validated like install.ps1's rollback sweep (Test-StudioVenvRollbackMustBePreserved), and then
+ # some, because this one deletes on runs that rebuild nothing and runs ahead of the custom-root
+ # guard: a NAME cannot be its whole authority, or the cost of a false positive is paid by a user
+ # who never had a stale venv. Five refusals: a root that does not show it is ours, anything
+ # outside the generated shape, a reparse point, a live owner (a concurrent setup's rescue copy,
+ # not litter), and a directory carrying no sign of an environment we moved aside.
+ $_venvParent = Split-Path -Parent $VenvDir
+ $_venvLeaf = Split-Path -Leaf $VenvDir
+ # Trailing -<n>: the rename below adds one when the destination is taken, as install.sh's
+ # _start_studio_venv_replacement does, so the sweep must recognise it or that copy is permanent.
+ $_staleShape = '^' + [regex]::Escape($_venvLeaf) + '\.stale-[0-9]{14}-([0-9]+)(?:-[0-9]+)?$'
+ # Hoisted out of the rebuild branch below, which asks the same question before its own delete.
+ $_studioRootIsOurs = (
+ -not $StudioHomeIsCustom -or
+ (Test-Path -LiteralPath (Join-Path $VenvDir $StudioOwnedMarker) -PathType Leaf) -or
+ (Test-Path -LiteralPath (Join-Path $StudioHome "share\studio.conf") -PathType Leaf) -or
+ (Test-Path -LiteralPath (Join-Path $StudioHome "bin\unsloth.exe") -PathType Leaf) -or
+ (Test-UnslothCmdShimFile (Join-Path $StudioHome "bin\unsloth.cmd"))
+ )
+ # [regex]::Match, not $Matches: which operator fills it, and on which result, moves between
+ # Windows PowerShell 5.1 and 7.x, and a capture group decides what gets deleted here.
+ foreach ($_old in @(
+ if ($_studioRootIsOurs) { Get-ChildItem -LiteralPath $_venvParent -Directory -Force -ErrorAction SilentlyContinue }
+ )) {
+ $_staleMatch = [regex]::Match($_old.Name, $_staleShape)
+ if (-not $_staleMatch.Success) { continue }
+ if (($_old.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { continue }
+ $_ownerPid = 0
+ if (-not [int]::TryParse($_staleMatch.Groups[1].Value, [ref]$_ownerPid)) { continue }
+ if ($_ownerPid -ne $PID -and $null -ne (Get-Process -Id $_ownerPid -ErrorAction SilentlyContinue)) { continue }
+ # pyvenv.cfg is in every environment `python -m venv` and `uv venv` create, the owned
+ # marker is what install.ps1 and this script write into a root they adopt, and the stale
+ # marker is dropped by the rename below and rewritten whenever the delete after it fails.
+ $_looksMoved = $false
+ foreach ($_sign in @("pyvenv.cfg", $StudioOwnedMarker, $StudioStaleMarker)) {
+ if (Test-Path -LiteralPath (Join-Path $_old.FullName $_sign) -PathType Leaf) { $_looksMoved = $true; break }
+ }
+ if (-not $_looksMoved) {
+ substep "left $($_old.FullName) alone: it matches the stale-copy name but holds no environment." "DarkGray"
+ continue
+ }
+ Remove-Item -LiteralPath $_old.FullName -Recurse -Force -ErrorAction SilentlyContinue
+ }
+
if ($shouldRebuild) {
substep "Stale venv detected ($reason) -- rebuilding..." "Yellow"
# why: mirror install.ps1 env-mode guard so an update against a custom
@@ -6135,24 +6255,44 @@ if ((Test-Path -LiteralPath $VenvDir -PathType Container) -and -not $NoTorchMode
# The .cmd counts too, and for the same reason the uninstaller accepts it: a
# policy's quarantine can take the unsigned .exe and leave a root that is still
# ours. Content-checked, never by name -- this guard gates a recursive delete.
- if (
- $StudioHomeIsCustom -and
- -not (Test-Path -LiteralPath (Join-Path $VenvDir $StudioOwnedMarker) -PathType Leaf) -and
- -not (Test-Path -LiteralPath (Join-Path $StudioHome "share\studio.conf") -PathType Leaf) -and
- -not (Test-Path -LiteralPath (Join-Path $StudioHome "bin\unsloth.exe") -PathType Leaf) -and
- -not (Test-UnslothCmdShimFile (Join-Path $StudioHome "bin\unsloth.cmd"))
- ) {
+ if (-not $_studioRootIsOurs) {
Write-StudioLine "[ERROR] $VenvDir already exists but does not look like an Unsloth Studio install." -ForegroundColor Red
Write-StudioLine " Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." -ForegroundColor Yellow
Exit-SetupFailure "$VenvDir is not an Unsloth Studio environment"
}
+ # Moved aside, then deleted: a rename takes the whole tree or fails and leaves it intact,
+ # where Remove-Item -Recurse stops at the first locked file and leaves an environment that
+ # can neither start nor update itself. Deleting the copy is best-effort, swept next run.
+ # The pid joins the timestamp so two rebuilds in one second cannot collide on a name, and a
+ # taken name still takes a numeric suffix: one process can reach this twice inside a second,
+ # and a copy it left earlier may be on disk because its delete failed. Same shape, and the
+ # same reason, as install.sh's _start_studio_venv_replacement.
+ $_staleStamp = Get-Date -Format 'yyyyMMddHHmmss'
+ $_staleLeaf = "$_venvLeaf.stale-$_staleStamp-$PID"
+ $_staleTry = 0
+ while ((Test-Path -LiteralPath (Join-Path $_venvParent $_staleLeaf)) -and $_staleTry -lt 64) {
+ $_staleTry++
+ $_staleLeaf = "$_venvLeaf.stale-$_staleStamp-$PID-$_staleTry"
+ }
try {
- Remove-Item -LiteralPath $VenvDir -Recurse -Force -ErrorAction Stop
+ Rename-Item -LiteralPath $VenvDir -NewName $_staleLeaf -ErrorAction Stop
} catch {
- Write-StudioLine " [ERROR] Could not remove stale venv: $($_.Exception.Message)" -ForegroundColor Red
- Write-StudioLine " Close any running Unsloth/Python processes and re-run setup." -ForegroundColor Red
+ Write-StudioLine " [ERROR] Could not move the stale venv aside: $($_.Exception.Message)" -ForegroundColor Red
+ Write-StudioLine " The environment was left as it was. Close any running Unsloth/Python processes and re-run setup." -ForegroundColor Red
Exit-SetupFailure "Could not remove the stale environment at $VenvDir"
}
+ $_staleDir = Join-Path $_venvParent $_staleLeaf
+ # Stamped before the delete and again after one fails: the sweep above refuses a copy that
+ # carries no sign of being an environment we moved, and a half-deleted one can have lost
+ # its pyvenv.cfg. Without the rewrite the litter this branch announces would be exactly the
+ # litter the next run declines to touch.
+ try { [System.IO.File]::WriteAllText((Join-Path $_staleDir $StudioStaleMarker), "") } catch {}
+ try {
+ Remove-Item -LiteralPath $_staleDir -Recurse -Force -ErrorAction Stop
+ } catch {
+ try { [System.IO.File]::WriteAllText((Join-Path $_staleDir $StudioStaleMarker), "") } catch {}
+ substep "Could not fully remove the old environment ($($_.Exception.Message)); left at $_staleDir for the next run to sweep." "Yellow"
+ }
}
}
diff --git a/tests/studio/install/test_windows_torch_flavor_invariant.py b/tests/studio/install/test_windows_torch_flavor_invariant.py
index 0664fd78551..a45e39dd995 100644
--- a/tests/studio/install/test_windows_torch_flavor_invariant.py
+++ b/tests/studio/install/test_windows_torch_flavor_invariant.py
@@ -67,10 +67,10 @@ class TestSetupPs1NoWipeEscape:
def test_the_escape_sits_ahead_of_the_wipe(self):
escape = _line_of(_SETUP_SRC, "nvidia-smi did not answer, but this venv holds a")
- wipe = _line_of(_SETUP_SRC, "Remove-Item -LiteralPath $VenvDir -Recurse -Force")
+ wipe = _line_of(_SETUP_SRC, "Rename-Item -LiteralPath $VenvDir")
stale = _line_of(_SETUP_SRC, "Stale venv detected ($reason) -- rebuilding...")
assert escape < stale < wipe, (
- "the no-wipe escape must be evaluated before the stale-venv branch that deletes "
+ "the no-wipe escape must be evaluated before the stale-venv branch that replaces "
f"the venv (escape={escape}, stale={stale}, wipe={wipe})"
)
diff --git a/tests/studio/test_amd_venv_repair_loop.ps1 b/tests/studio/test_amd_venv_repair_loop.ps1
index 5135a828586..a86c897add5 100644
--- a/tests/studio/test_amd_venv_repair_loop.ps1
+++ b/tests/studio/test_amd_venv_repair_loop.ps1
@@ -289,7 +289,7 @@ Check "XPU is judged before ROCm" (
Write-Host "the stale-venv decision has no dead end left in it"
# Starts on `\$null\n`, so a CRLF checkout fails the match instead of returning an empty region.
-$_repairPat = '(?s)(\$reason = \$null\n.*?Remove-Item -LiteralPath \$VenvDir -Recurse)'
+$_repairPat = '(?s)(\$reason = \$null\n.*?Rename-Item -LiteralPath \$VenvDir)'
$_repair = if ($setupText -match $_repairPat) { $Matches[1] } else { "" }
Check "the stale-venv decision was found" ($_repair -ne "")
Check "CRLF is normalised, not tolerated" (-not (($setupText -replace "`n", "`r`n") -match $_repairPat))
@@ -314,7 +314,24 @@ Check "it does not try to wipe the venv it runs from" (-not ($_managed -match 'R
# A direct `unsloth studio update` keeps its own self-repair, and the custom-home guard stays in
# front of the delete.
Check "a direct update still rebuilds" ($_repair -match 'Stale venv detected \(\$reason\) -- rebuilding')
+# ...unless it is running from the venv's own python.exe, which `unsloth studio update` always is
+# on Windows: a running image cannot be deleted, so that run repairs in place like install.ps1.
+Check "a direct update from inside the venv repairs in place" (
+ $_repair -match '(?s)\$_hostPy = Get-SetupHostInterpreterInVenv -VenvDir \$VenvDir.*?\$script:PinChangedForceReinstall = \$true.*?\$shouldRebuild = \$false')
+# And when it does rebuild, the old tree is moved aside first: a rename fails whole where a
+# recursive delete stops at the first locked file and leaves a venv nothing can start.
+Check "the rebuild moves the venv aside before deleting" (
+ $_repair -match 'Rename-Item -LiteralPath \$VenvDir' -and -not ($_repair -match 'Remove-Item -LiteralPath \$VenvDir'))
Check "the custom-home guard still gates the wipe" ($_repair -match '\$StudioHomeIsCustom')
+# The sweep next to the venv deletes on every qualifying run, including one that rebuilds nothing,
+# and it runs ahead of that guard. So it asks the same ownership question the guard asks, and it
+# requires the directory to look like an environment this script moved rather than trusting a name.
+Check "the sweep reads the same ownership guard" ($_repair -match '\$_studioRootIsOurs')
+Check "the sweep wants more than a matching name" (
+ $_repair -match 'foreach \(\$_sign in @\("pyvenv\.cfg", \$StudioOwnedMarker, \$StudioStaleMarker\)\)')
+# A taken destination takes a suffix instead of failing the rename, as install.sh already does.
+Check "a taken stale name takes a suffix" ($_repair -match '\$_staleTry -lt 64')
+Check "the sweep recognises that suffix" ($_repair -match '\(\?:-\[0-9\]\+\)\?\$')
# Why it failed, not just that it failed: this line separates a faulted GPU driver from a missing
# wheel, and the user is about to be told what happened to their environment.
Check "the swallowed probe error is surfaced" ($_repair -match '\$_verProbe\.Error')
diff --git a/tests/test_studio_install_workspace_guard.py b/tests/test_studio_install_workspace_guard.py
index 30ad4716a44..332b1ceb61e 100644
--- a/tests/test_studio_install_workspace_guard.py
+++ b/tests/test_studio_install_workspace_guard.py
@@ -4,7 +4,9 @@ from __future__ import annotations
import os
import re
+import shutil
import subprocess
+import sys
from pathlib import Path
import pytest
@@ -246,23 +248,314 @@ def test_install_ps1_sentinel_uses_pathtype_leaf():
def test_setup_ps1_stale_venv_has_env_mode_guard():
- """setup.ps1 stale-venv branch must gate Remove-Item $VenvDir on a custom-root Unsloth sentinel."""
+ """setup.ps1 stale-venv branch must gate the venv replacement on a custom-root Unsloth sentinel.
+
+ The predicate is computed once, above the sweep, because both destructive operations in this
+ region ask the same question: the rebuild before it renames the venv, and the sweep before it
+ deletes anything beside it."""
src = SETUP_PS1.read_text(encoding = "utf-8")
- idx = src.index("Stale venv detected")
- block = src[idx : idx + 1500]
+ guard = src[src.index("$_studioRootIsOurs = (") : src.index("Stale venv detected")]
assert (
- "$StudioHomeIsCustom" in block
+ "$StudioHomeIsCustom" in guard
), "setup.ps1 stale-venv branch must gate on $StudioHomeIsCustom"
assert (
- 'share\\studio.conf") -PathType Leaf' in block
+ 'share\\studio.conf") -PathType Leaf' in guard
), "setup.ps1 stale-venv guard must check share\\studio.conf with -PathType Leaf"
assert (
- 'bin\\unsloth.exe") -PathType Leaf' in block
+ 'bin\\unsloth.exe") -PathType Leaf' in guard
), "setup.ps1 stale-venv guard must check bin\\unsloth.exe with -PathType Leaf"
- # The guard must fire BEFORE the destructive call.
- guard_idx = block.index("$StudioHomeIsCustom")
- rm_idx = block.index("Remove-Item -LiteralPath $VenvDir")
- assert guard_idx < rm_idx, "custom-root guard must precede Remove-Item -LiteralPath $VenvDir"
+ assert (
+ "Test-UnslothCmdShimFile" in guard
+ ), "setup.ps1 stale-venv guard must still accept a quarantined .exe's .cmd shim"
+ # The guard must fire BEFORE either destructive call.
+ idx = src.index("Stale venv detected")
+ block = src[idx : idx + 2500]
+ assert (
+ "if (-not $_studioRootIsOurs) {" in block
+ ), "the rebuild branch must refuse a root it cannot claim"
+ guard_idx = block.index("if (-not $_studioRootIsOurs) {")
+ rm_idx = block.index("Rename-Item -LiteralPath $VenvDir")
+ assert guard_idx < rm_idx, "custom-root guard must precede Rename-Item -LiteralPath $VenvDir"
+ sweep_idx = src.index("$_staleMatch = [regex]::Match($_old.Name, $_staleShape)")
+ assert (
+ src.index("$_studioRootIsOurs = (") < sweep_idx
+ ), "the sweep must be able to read the guard"
+
+
+def test_setup_ps1_stale_venv_is_moved_aside_not_deleted_in_place():
+ """A rename takes the whole tree or fails and leaves it intact. Remove-Item -Recurse deletes up
+ to the first locked file, and a venv locked by its own running python.exe came out of it with
+ Lib\\ emptied, no unsloth_cli, and Scripts\\python.exe still there: nothing could start or
+ update it afterwards."""
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ idx = src.index("Stale venv detected")
+ block = src[idx : src.index("if (-not (Test-Path -LiteralPath $VenvDir))", idx)]
+ assert (
+ "Remove-Item -LiteralPath $VenvDir" not in block
+ ), "the stale venv must not be deleted in place"
+ rename = block.index("Rename-Item -LiteralPath $VenvDir")
+ remove = block.index("Remove-Item -LiteralPath $_staleDir")
+ assert rename < remove, "the moved copy is what gets deleted"
+ # Same message as before, so the desktop's update/repair reporting keys on nothing new.
+ assert "Could not remove the stale environment at $VenvDir" in block
+
+
+def test_setup_ps1_direct_update_from_inside_the_venv_repairs_in_place():
+ """`unsloth studio update` runs setup.ps1 from the venv's own python.exe, which Windows will
+ not delete while it runs, so that run takes the installer's in-place reinstall route rather
+ than the wipe. A setup.ps1 run by hand from a checkout keeps the full rebuild."""
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ start = src.index(
+ "if ($shouldRebuild -and -not $InstallerManagedSetup) {\n"
+ " $_hostPy = Get-SetupHostInterpreterInVenv -VenvDir $VenvDir"
+ )
+ block = src[start : src.index("\n }\n", start)]
+ assert "$script:PinChangedForceReinstall = $true" in block
+ assert "$shouldRebuild = $false" in block
+ assert start < src.index(
+ "Stale venv detected ($reason) -- rebuilding"
+ ), "the in-place route must be chosen before the rebuild branch runs"
+
+
+def test_setup_ps1_direct_update_in_place_route_is_the_last_escape():
+ """The in-place route holds for EVERY stale direct update, so it must be tested last or it
+ consumes $shouldRebuild before the narrower escapes run. Ahead of the nvidia-smi guard it also
+ leaves $script:PreservedInstallerTorchTag unset, which force-installs a CPU wheel over the
+ working cu* venv that guard protects (#9857)."""
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ in_place = src.index(
+ "if ($shouldRebuild -and -not $InstallerManagedSetup) {\n"
+ " $_hostPy = Get-SetupHostInterpreterInVenv -VenvDir $VenvDir"
+ )
+ nvidia_guard = src.index("nvidia-smi did not answer, but this venv holds a")
+ assert nvidia_guard < in_place, (
+ "the nvidia-smi cu* preservation guard must be tested BEFORE the in-place route, "
+ "or a silent nvidia-smi probe downgrades a working cu* venv to CPU torch"
+ )
+ # Every other escape that can clear $shouldRebuild on a direct update belongs ahead of it too.
+ for earlier in (
+ "Keeping the installed Intel XPU environment",
+ "Torch-index pin changed",
+ "CUDA family $installedTorchTag does not cover this host",
+ ):
+ assert (
+ src.index(earlier) < in_place
+ ), f"{earlier!r} must be tested before the in-place route"
+
+
+def test_setup_ps1_stale_sweep_runs_outside_the_rebuild_branch():
+ """The sweep collects leftovers from an earlier move-aside whose delete a lock cut short. Inside
+ the rebuild branch it would never run for the install that needs it most: one that renamed a
+ venv aside, failed to delete the copy, and thereafter always takes an in-place route."""
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ sweep = src.index("$_staleShape = ")
+ rebuild = src.index("Stale venv detected ($reason) -- rebuilding")
+ assert sweep < rebuild, "the stale-venv sweep must run whether or not this run rebuilds"
+ # Ahead of the custom-root guard, so it must establish ownership itself.
+ block = src[sweep : src.index("if ($shouldRebuild) {", sweep)]
+ assert "ReparsePoint" in block, "the sweep must refuse reparse points"
+ assert "Get-Process -Id $_ownerPid" in block, "the sweep must spare a live owner's rescue copy"
+ assert (
+ "[0-9]{14}-([0-9]+)(?:-[0-9]+)?$" in block
+ ), "the sweep must only match the generated name shape, including a collision suffix"
+ assert (
+ "$_studioRootIsOurs" in block
+ ), "the sweep must refuse a custom root that shows no sign of being ours"
+ # A name is not authority for a recursive delete: the directory has to look like an
+ # environment this script moved aside.
+ assert 'foreach ($_sign in @("pyvenv.cfg", $StudioOwnedMarker, $StudioStaleMarker))' in block
+ # A second rebuild inside the same second must not collide on the destination name.
+ stale_leaf = src[src.index("$_staleLeaf = ") : src.index("\n", src.index("$_staleLeaf = "))]
+ assert "$PID" in stale_leaf, f"stale destination needs a per-process suffix, got {stale_leaf!r}"
+ retry = src[src.index("$_staleTry = 0") : src.index("Rename-Item -LiteralPath $VenvDir")]
+ assert (
+ "Test-Path -LiteralPath (Join-Path $_venvParent $_staleLeaf)" in retry
+ ), "a destination that is already taken must take a suffix rather than fail the rename"
+ assert "$_staleTry -lt 64" in retry, "the collision retry must be bounded"
+
+
[email protected](shutil.which("pwsh") is None, reason = "needs pwsh")
+def test_setup_ps1_stale_sweep_only_removes_its_own_litter(tmp_path):
+ """Runs the shipped sweep, rather than reading it. The wildcard it enumerates under would
+ happily match a user's own `unsloth_studio.stale-backup`, and the sweep runs ahead of the
+ custom-root guard, so nothing downstream would stop it."""
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ start = src.index(" $_venvParent = Split-Path -Parent $VenvDir")
+ sweep = src[start : src.index("\n\n", start)]
+
+ home = tmp_path / "studio"
+ venv = home / "unsloth_studio"
+ (venv / "Lib").mkdir(parents = True)
+ dead_pid = 999999 # no such process; this copy is ours and abandoned
+ ours = home / f"unsloth_studio.stale-20260101000000-{dead_pid}"
+ suffixed = home / f"unsloth_studio.stale-20260101000000-{dead_pid}-1"
+ stamped = home / f"unsloth_studio.stale-20260101000001-{dead_pid}"
+ shaped = home / f"unsloth_studio.stale-20260101000002-{dead_pid}"
+ theirs = home / "unsloth_studio.stale-backup"
+ live = home / f"unsloth_studio.stale-20260101000000-{os.getpid()+0}"
+ for d in (ours, suffixed, stamped, shaped, theirs, live):
+ d.mkdir()
+ # What makes a directory ours: an environment's own pyvenv.cfg, or the marker the rename
+ # drops into the copy it moved. `shaped` wears the name and holds neither, which is what a
+ # user's directory would look like, and it is what this sweep must not delete.
+ (ours / "pyvenv.cfg").write_text("home = /usr\n", encoding = "utf-8")
+ (suffixed / "pyvenv.cfg").write_text("home = /usr\n", encoding = "utf-8")
+ (stamped / ".unsloth-studio-stale").write_text("", encoding = "utf-8")
+ (shaped / "holiday-photos.txt").write_text("not unsloth", encoding = "utf-8")
+ (live / "pyvenv.cfg").write_text("home = /usr\n", encoding = "utf-8")
+ # `live` names this pytest process, which is alive, so it stands in for a concurrent setup's
+ # rescue copy. Our own $PID inside pwsh differs, so the sweep sees a live foreign owner.
+ preamble = (
+ f'$VenvDir = "{venv.as_posix()}"\n'
+ f'$StudioHome = "{home.as_posix()}"\n'
+ "$StudioHomeIsCustom = $false\n"
+ '$StudioOwnedMarker = ".unsloth-studio-owned"\n'
+ '$StudioStaleMarker = ".unsloth-studio-stale"\n'
+ "function Test-UnslothCmdShimFile { param($Path) return $false }\n"
+ "function substep { param([string]$Message, [string]$Color = 'DarkGray') }\n"
+ )
+ script = tmp_path / "sweep.ps1"
+ script.write_text(preamble + sweep + "\n", encoding = "utf-8")
+ subprocess.run(
+ ["pwsh", "-NoProfile", "-File", str(script)],
+ check = True,
+ capture_output = True,
+ )
+
+ assert not ours.exists(), "an abandoned copy in the generated name shape must be swept"
+ assert not suffixed.exists(), "a copy whose name took a collision suffix must be swept too"
+ assert not stamped.exists(), "a copy identified only by the stale marker must be swept"
+ assert shaped.exists(), "a directory wearing the name but holding no environment must be spared"
+ assert theirs.exists(), "a directory outside the generated name shape must be left alone"
+ assert live.exists(), "a copy whose owning process is still alive must be left alone"
+ assert venv.exists(), "the sweep must never touch the live venv"
+
+
[email protected](shutil.which("pwsh") is None, reason = "needs pwsh")
+def test_setup_ps1_stale_sweep_refuses_a_custom_root_it_cannot_claim(tmp_path):
+ """The sweep deletes directories the rebuild guard never sees, because it runs ahead of it and
+ on runs that never rebuild. Under a custom UNSLOTH_STUDIO_HOME with no Unsloth sentinel, the
+ rebuild refuses the venv -- so the sweep must refuse its siblings for the same reason."""
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ start = src.index(" $_venvParent = Split-Path -Parent $VenvDir")
+ sweep = src[start : src.index("\n\n", start)]
+
+ home = tmp_path / "elsewhere"
+ venv = home / "unsloth_studio"
+ (venv / "Lib").mkdir(parents = True)
+ litter = home / "unsloth_studio.stale-20260101000000-999999"
+ litter.mkdir()
+ (litter / "pyvenv.cfg").write_text("home = /usr\n", encoding = "utf-8")
+
+ preamble = (
+ f'$VenvDir = "{venv.as_posix()}"\n'
+ f'$StudioHome = "{home.as_posix()}"\n'
+ "$StudioHomeIsCustom = $true\n"
+ '$StudioOwnedMarker = ".unsloth-studio-owned"\n'
+ '$StudioStaleMarker = ".unsloth-studio-stale"\n'
+ "function Test-UnslothCmdShimFile { param($Path) return $false }\n"
+ "function substep { param([string]$Message, [string]$Color = 'DarkGray') }\n"
+ )
+ script = tmp_path / "sweep_custom.ps1"
+ script.write_text(preamble + sweep + "\n", encoding = "utf-8")
+ subprocess.run(["pwsh", "-NoProfile", "-File", str(script)], check = True, capture_output = True)
+ assert litter.exists(), "an unclaimable custom root must be left entirely alone"
+
+ # Negative control: the same tree with the ownership marker present is swept, so the assertion
+ # above is about ownership and not about some other reason nothing was deleted.
+ (venv / ".unsloth-studio-owned").write_text("", encoding = "utf-8")
+ subprocess.run(["pwsh", "-NoProfile", "-File", str(script)], check = True, capture_output = True)
+ assert not litter.exists(), "a custom root carrying the owned marker is ours to tidy"
+
+
+def _extract_setup_ps1_function(name: str) -> str:
+ src = SETUP_PS1.read_text(encoding = "utf-8")
+ m = re.search(rf"^function {re.escape(name)} \{{.*?\n\}}\n", src, re.DOTALL | re.MULTILINE)
+ assert m, f"setup.ps1 function {name} not found"
+ return m.group(0)
+
+
[email protected](shutil.which("pwsh") is None, reason = "needs pwsh")
+class TestSetupHostInterpreterInVenv:
+ """The shipped helper, run for real: the CLI's hint, a foreign interpreter, and (on Windows)
+ the process walk that finds a venv python.exe above setup when no hint was passed."""
+
+ @pytest.fixture
+ def probe(self, tmp_path):
+ venv = tmp_path / "unsloth_studio"
+ subprocess.run(
+ [sys.executable, "-m", "venv", "--without-pip", str(venv)],
+ check = True,
+ capture_output = True,
+ )
+ script = tmp_path / "probe.ps1"
+ script.write_text(
+ _extract_setup_ps1_function("Get-SetupHostInterpreterInVenv")
+ + "$r = Get-SetupHostInterpreterInVenv -VenvDir $args[0]\n"
+ + "if ($r) { Write-Output \"RESULT=$r\" } else { Write-Output 'RESULT=<null>' }\n",
+ encoding = "utf-8",
+ )
+
+ def run(hint: str | None = None, launcher: str | None = None) -> str:
+ env = {k: v for k, v in os.environ.items() if k != "UNSLOTH_SETUP_HOST_PYTHON"}
+ if hint is not None:
+ env["UNSLOTH_SETUP_HOST_PYTHON"] = hint
+ cmd = [
+ "pwsh",
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ str(script),
+ str(venv),
+ ]
+ if launcher is not None:
+ # setup.ps1's real parent: a python that subprocess-runs PowerShell, as the CLI does.
+ cmd = [
+ launcher,
+ "-c",
+ "import subprocess, sys; sys.exit(subprocess.call(sys.argv[1:]))",
+ *cmd,
+ ]
+ out = subprocess.run(cmd, env = env, text = True, capture_output = True, timeout = 120)
+ assert out.returncode == 0, out.stdout + out.stderr
+ return out.stdout.strip().splitlines()[-1]
+
+ return venv, run
+
+ @staticmethod
+ def _venv_python(venv: Path) -> Path:
+ return venv / "Scripts" / "python.exe" if os.name == "nt" else venv / "bin" / "python"
+
+ def test_the_cli_hint_names_the_venv_interpreter(self, probe):
+ venv, run = probe
+ inside = str(self._venv_python(venv))
+ assert run(hint = inside) == f"RESULT={inside}"
+
+ def test_an_interpreter_outside_the_venv_is_not_reported(self, probe):
+ _venv, run = probe
+ assert run(hint = sys.executable) == "RESULT=<null>"
+ assert run() == "RESULT=<null>"
+
+ def test_a_hint_naming_a_path_that_is_not_there_is_not_an_interpreter(self, probe):
+ """The hint is an inherited environment variable and can outlive what it names. Answering
+ with a path that does not exist would route a venv that genuinely needs rebuilding into an
+ in-place repair with no interpreter to perform it."""
+ venv, run = probe
+ gone = venv / "Scripts" / "python-that-was-deleted.exe"
+ assert run(hint = str(gone)) == "RESULT=<null>"
+ # A directory inside the venv is not an interpreter either.
+ assert run(hint = str(venv)) == "RESULT=<null>"
+ assert run(hint = str(self._venv_python(venv).parent)) == "RESULT=<null>"
+ # Negative control: the same probe answers when the file is really there, so the three
+ # refusals above are about the file and not about the harness.
+ assert run(hint = str(self._venv_python(venv))) == f"RESULT={self._venv_python(venv)}"
+
+ @pytest.mark.skipif(os.name != "nt", reason = "the process walk reads Win32_Process")
+ def test_a_venv_python_parent_is_found_without_the_hint(self, probe):
+ venv, run = probe
+ inside = self._venv_python(venv)
+ assert run(launcher = str(inside)) == f"RESULT={inside}"
def test_setup_sh_prebuilt_llama_cpp_has_ownership_guard():
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index fd9feadb75e..a89b81ddf86 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -3561,6 +3561,11 @@ def _run_setup_script(*, verbose: bool = False, repo_root: Optional[Path] = None
# Where setup runs uv from: setup.sh cds into its own directory, setup.ps1 keeps this cwd.
setup_cwd = None if platform.system() == "Windows" else script.parent
env = _with_studio_uv_cache(env, cwd = setup_cwd)
+ # Saves setup.ps1 the process walk. A HINT, not a promise: only the desktop spawn guarantees
+ # the managed venv's python, while a pip install, a checkout or a staged run puts an
+ # interpreter here that is nowhere near $VenvDir. Get-SetupHostInterpreterInVenv tests
+ # containment itself, so presence of this name is never proof setup runs from the venv.
+ env = {**(env or os.environ), "UNSLOTH_SETUP_HOST_PYTHON": sys.executable}
if platform.system() == "Windows":
# Resolved, not bare: PATH is not trusted here (#9440) and the Popen below has no OSError handler.
diff --git a/unsloth_cli/tests/test_studio_update_host_python.py b/unsloth_cli/tests/test_studio_update_host_python.py
new file mode 100644
index 00000000000..0f6b2397262
--- /dev/null
+++ b/unsloth_cli/tests/test_studio_update_host_python.py
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""`unsloth studio update` must tell setup.ps1 which interpreter launched it.
+
+The CLI runs from the managed venv's own python.exe, and setup.ps1's stale-venv branch
+used to Remove-Item that venv: Windows will not delete a running image, so the delete
+emptied Lib\\ and failed on Scripts\\python.exe, leaving an environment with no unsloth_cli
+and no rollback copy. setup.ps1 now repairs in place when it sees it runs from inside the
+venv, and UNSLOTH_SETUP_HOST_PYTHON is how it sees that without a process walk.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(_REPO_ROOT))
+
+
+def _studio():
+ from unsloth_cli.commands import studio as _studio_mod
+ return _studio_mod
+
+
+def _setup_tree(tmp_path: Path) -> Path:
+ repo_root = tmp_path / "repo"
+ (repo_root / "studio").mkdir(parents = True, exist_ok = True)
+ (repo_root / "studio" / "setup.sh").write_text("")
+ (repo_root / "studio" / "setup.ps1").write_text("")
+ return repo_root
+
+
+class _Result:
+ returncode = 0
+
+
+def _quiet_cache(monkeypatch, studio) -> None:
+ # The uv cache seeding has its own tests; here it must neither spawn uv nor read the machine.
+ monkeypatch.setattr(studio, "_with_studio_uv_cache", lambda env, cwd = None: env)
+ monkeypatch.setattr(studio, "_backfill_uv_cache_marker", lambda env: None)
+
+
+def test_the_posix_update_names_its_own_interpreter(monkeypatch, tmp_path):
+ studio = _studio()
+ _quiet_cache(monkeypatch, studio)
+ monkeypatch.setattr(studio.platform, "system", lambda: "Linux")
+ seen: dict = {}
+
+ def _fake_run(
+ argv,
+ env = None,
+ **kwargs,
+ ):
+ seen["env"] = env
+ return _Result()
+
+ monkeypatch.setattr(studio.subprocess, "run", _fake_run)
+ studio._run_setup_script(repo_root = _setup_tree(tmp_path))
+
+ assert seen["env"] is not None, "env must be materialised to carry the interpreter"
+ assert seen["env"]["UNSLOTH_SETUP_HOST_PYTHON"] == sys.executable
+
+
+def test_the_windows_update_names_its_own_interpreter(monkeypatch, tmp_path):
+ """The PowerShell spawn is the one that matters: setup.ps1 is where the venv was deleted."""
+ studio = _studio()
+ _quiet_cache(monkeypatch, studio)
+ monkeypatch.setattr(studio.platform, "system", lambda: "Windows")
+ monkeypatch.setattr(
+ studio._studio_runtime_gate, "resolve_windows_powershell", lambda: "powershell.exe"
+ )
+ monkeypatch.setattr(studio, "_probe_profile_proxy_defaults", lambda hosts: None)
+ monkeypatch.setattr(studio, "_wait_for_windows_setup_process", lambda process: 0)
+ seen: dict = {}
+
+ class _Process:
+ pass
+
+ def _fake_popen(
+ argv,
+ env = None,
+ **kwargs,
+ ):
+ seen["env"] = env
+ return _Process()
+
+ monkeypatch.setattr(studio.subprocess, "Popen", _fake_popen)
+ studio._run_setup_script(repo_root = _setup_tree(tmp_path))
+
+ assert seen["env"]["UNSLOTH_SETUP_HOST_PYTHON"] == sys.executable
+
+
+def test_the_verbose_flag_survives_alongside_it(monkeypatch, tmp_path):
+ """The verbose branch builds env first; the interpreter must extend it, not replace it."""
+ studio = _studio()
+ _quiet_cache(monkeypatch, studio)
+ monkeypatch.setattr(studio.platform, "system", lambda: "Linux")
+ seen: dict = {}
+
+ def _fake_run(
+ argv,
+ env = None,
+ **kwargs,
+ ):
+ seen["env"] = env
+ return _Result()
+
+ monkeypatch.setattr(studio.subprocess, "run", _fake_run)
+ studio._run_setup_script(verbose = True, repo_root = _setup_tree(tmp_path))
+
+ assert seen["env"]["UNSLOTH_VERBOSE"] == "1"
+ assert seen["env"]["UNSLOTH_SETUP_HOST_PYTHON"] == sys.executable