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.

install.ps1: delete the committed venv rollback in a background process (#16796)

Daniel Han27d9b87e5d78
diff --git a/.github/workflows/cross-platform-parity-ci.yml b/.github/workflows/cross-platform-parity-ci.yml
index 8c60d9cefff..d3961078349 100644
--- a/.github/workflows/cross-platform-parity-ci.yml
+++ b/.github/workflows/cross-platform-parity-ci.yml
@@ -50,6 +50,7 @@ on:
# The only lane that runs this test; the Windows smoke workflow skips it.
- 'tests/studio/test_path_resolver_degrades.ps1'
- 'tests/python/test_windows_python_venv_hardening.py'
+ - 'tests/python/test_windows_rollback_background_delete.py'
- 'tests/python/test_windows_setup_output_encoding.py'
- 'tests/python/test_windows_setup_download_progress.py'
- 'tests/python/test_windows_installer_resolver_fallback.py'
@@ -155,6 +156,7 @@ on:
# The only lane that runs this test; the Windows smoke workflow skips it.
- 'tests/studio/test_path_resolver_degrades.ps1'
- 'tests/python/test_windows_python_venv_hardening.py'
+ - 'tests/python/test_windows_rollback_background_delete.py'
- 'tests/python/test_windows_setup_output_encoding.py'
- 'tests/python/test_windows_setup_download_progress.py'
- 'tests/python/test_windows_installer_resolver_fallback.py'
@@ -237,7 +239,7 @@ jobs:
# concurrency is capped at 5. The non-Windows shell steps cover Intel XPU paths no Mac reaches.
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
- timeout-minutes: 10
+ timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
@@ -256,6 +258,7 @@ jobs:
python -m pytest
tests/python/test_cross_platform_parity.py
tests/python/test_windows_python_venv_hardening.py
+ tests/python/test_windows_rollback_background_delete.py
tests/python/test_windows_setup_output_encoding.py
tests/python/test_windows_setup_download_progress.py
tests/python/test_windows_installer_resolver_fallback.py
diff --git a/install.ps1 b/install.ps1
index 10b945100a9..120bd5188bf 100644
--- a/install.ps1
+++ b/install.ps1
@@ -6999,6 +6999,54 @@ exit 0
}
}
+ # Hands the 30-40 s delete to a hidden process. The tree is parked as rollback.<stamp>.<deleter PID>,
+ # so the sweep skips it while the deleter lives and removes leftovers once it is gone. Started via
+ # the shell so no inherited handle holds a caller's output pipe. $false = nothing changed, delete here.
+ function Start-StudioVenvRollbackBackgroundDelete {
+ param([Parameter(Mandatory = $true)][string]$Path)
+ if ($env:OS -ne 'Windows_NT') { return $false }
+ try {
+ $item = Get-Item -LiteralPath $Path -Force -ErrorAction Stop
+ if (-not $item.PSIsContainer) { return $false }
+ if (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { return $false }
+ $parent = [System.IO.Path]::GetDirectoryName($item.FullName)
+ if (-not $parent) { return $false }
+ $shell = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
+ if (-not (Test-Path -LiteralPath $shell -PathType Leaf)) { return $false }
+ } catch {
+ return $false
+ }
+ $stamp = Get-Date -Format "yyyyMMddHHmmss"
+ $parentLiteral = $parent.Replace("'", "''")
+ # Single quotes only: the command travels as one double-quoted argument.
+ $deleteCommand = @(
+ "`$ErrorActionPreference = 'SilentlyContinue'",
+ "`$p = Join-Path '$parentLiteral' ('unsloth_studio.rollback.$stamp.' + `$PID)",
+ "for (`$i = 0; (`$i -lt 600) -and -not (Test-Path -LiteralPath `$p); `$i++) { Start-Sleep -Milliseconds 100 }",
+ "if (Test-Path -LiteralPath `$p) { try { [System.IO.Directory]::Delete(`$p, `$true) } catch { } }",
+ "if (Test-Path -LiteralPath `$p) { Remove-Item -LiteralPath `$p -Recurse -Force }"
+ ) -join '; '
+ $deleter = $null
+ try {
+ $deleter = Start-Process -FilePath $shell `
+ -ArgumentList "-NoProfile -NonInteractive -Command `"$deleteCommand`"" `
+ -WindowStyle Hidden -PassThru -ErrorAction Stop
+ } catch {
+ return $false
+ }
+ if ($null -eq $deleter) { return $false }
+ $parked = Join-Path $parent "unsloth_studio.rollback.$stamp.$($deleter.Id)"
+ try {
+ if (Test-StudioPathPresent -Path $parked) { throw "$parked already exists" }
+ [System.IO.Directory]::Move($item.FullName, $parked)
+ } catch {
+ try { Stop-Process -Id $deleter.Id -Force -ErrorAction SilentlyContinue } catch { }
+ return $false
+ }
+ try { $deleter.PriorityClass = [System.Diagnostics.ProcessPriorityClass]::BelowNormal } catch { }
+ return $true
+ }
+
function Merge-StudioVenvRollbackTree {
# Moves every entry of $Source into $Destination without ever overwriting or
# deleting what is already there. Returns $true only when $Source ends up
@@ -7137,6 +7185,8 @@ exit 0
return
}
}
+ # Restoration is disarmed above, so nothing reads $backup again.
+ if (Start-StudioVenvRollbackBackgroundDelete -Path $backup) { return }
Remove-StudioVenvTreeWithRetry -Path $backup -Label "environment rollback" | Out-Null
}
diff --git a/tests/python/test_windows_on_arm_python_arch.py b/tests/python/test_windows_on_arm_python_arch.py
index 6bd3ce61937..d5929dabacc 100644
--- a/tests/python/test_windows_on_arm_python_arch.py
+++ b/tests/python/test_windows_on_arm_python_arch.py
@@ -221,6 +221,9 @@ function Remove-StudioVenvTreeWithRetry {{
Remove-Item -LiteralPath $Path -Recurse -Force
return $true
}}
+# Declines the background handoff (as it does off Windows), so the delete is the foreground one
+# above; test_windows_rollback_background_delete.py covers the handoff.
+function Start-StudioVenvRollbackBackgroundDelete {{ param([string]$Path) return $false }}
{_function("Test-StudioPathPresent")}
{_function("Complete-StudioVenvRollback")}
"""
diff --git a/tests/python/test_windows_rollback_background_delete.py b/tests/python/test_windows_rollback_background_delete.py
new file mode 100644
index 00000000000..e3a5b176194
--- /dev/null
+++ b/tests/python/test_windows_rollback_background_delete.py
@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""install.ps1 deletes a committed venv rollback in a separate process.
+
+The foreground delete cost 30-40 s after "Setup Complete" on a Studio-only update. These
+pin that the commit returns at once, prints nothing new, does not hold a caller's output
+pipe open (the desktop app reads the installer's stdout to EOF), that the tree is gone
+shortly after, that a later run's sweep never collides with a running deletion, and that
+the sweep removes what a stopped deletion left behind.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+from unsloth_pwsh_runner import run_pwsh
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+INSTALL_PS1 = REPO_ROOT / "install.ps1"
+POWERSHELLS = [shell for shell in ("pwsh", "powershell") if shutil.which(shell)]
+FUNCTIONS = (
+ "Test-StudioPathPresent",
+ "Remove-StudioVenvTreeWithRetry",
+ "Test-StudioVenvRollbackMustBePreserved",
+ "Remove-StaleStudioVenvRollbacks",
+ "Start-StudioVenvRollbackBackgroundDelete",
+ "Complete-StudioVenvRollback",
+)
+SWEEP_NAME = re.compile(r"^unsloth_studio\.rollback\.[0-9]{14}\.([0-9]+)(?:\.[0-9]+)?$")
+
+windows_only = pytest.mark.skipif(
+ os.name != "nt" or not POWERSHELLS, reason = "Windows PowerShell behaviour"
+)
+
+
+def _blocks() -> str:
+ source = INSTALL_PS1.read_text(encoding = "utf-8")
+ out = []
+ for name in FUNCTIONS:
+ match = re.search(rf" function {name} \{{.*?\n \}}\n", source, flags = re.DOTALL)
+ assert match is not None, f"install.ps1 function not found: {name}"
+ out.append(match.group(0))
+ return "".join(out)
+
+
+def _prelude() -> str:
+ return (
+ '$ErrorActionPreference = "Stop"\n'
+ # Captured stdout = exactly what the installer would print.
+ 'function substep { param([string]$Text, [string]$Color) Write-Output ("SUBSTEP " + $Text) }\n'
+ "function Write-StudioLine { param([string]$Message, [string]$ForegroundColor) "
+ 'Write-Output ("LINE " + $Message) }\n'
+ "$StudioHome = $env:TEST_STUDIO_HOME\n" + _blocks()
+ )
+
+
+def _run(
+ shell: str,
+ script: str,
+ home: Path,
+ timeout: int = 120,
+) -> tuple[str, float]:
+ env = os.environ.copy()
+ env["TEST_STUDIO_HOME"] = str(home)
+ started = time.monotonic()
+ # Piped like Desktop: an inherited handle in the deleter would block this until the delete ends.
+ result = run_pwsh(
+ [shell, "-NoProfile", "-NonInteractive", "-Command", _prelude() + script],
+ capture_output = True,
+ text = True,
+ encoding = "utf-8",
+ errors = "replace",
+ env = env,
+ timeout = timeout,
+ )
+ wall = time.monotonic() - started
+ assert result.returncode == 0, result.stdout + result.stderr
+ return result.stdout, wall
+
+
+def _make_tree(root: Path, dirs: int, files_per_dir: int) -> None:
+ for d in range(dirs):
+ sub = root / "Lib" / "site-packages" / f"pkg{d}"
+ sub.mkdir(parents = True)
+ for f in range(files_per_dir):
+ (sub / f"m{f}.py").write_bytes(b"x = 1\n")
+ (root / "pyvenv.cfg").write_text("home = C:\\nowhere\n", encoding = "utf-8")
+
+
+def _rollbacks(home: Path) -> list[Path]:
+ return sorted(p for p in home.iterdir() if p.name.startswith("unsloth_studio.rollback."))
+
+
+def _dead_pid() -> int:
+ proc = subprocess.Popen([sys.executable, "-c", "pass"])
+ proc.wait()
+ return proc.pid
+
+
+COMMIT = """
+$script:StudioVenvRollbackActive = $true
+$script:StudioVenvRollbackDir = $env:TEST_BACKUP
+$script:StudioVenvRollbackPartial = $false
+$script:StudioVenvRollbackPreserve = $false
+$sw = [System.Diagnostics.Stopwatch]::StartNew()
+Complete-StudioVenvRollback
+$sw.Stop()
+Write-Output ("MARK commit_ms=" + [int]$sw.Elapsed.TotalMilliseconds)
+Write-Output ("MARK active=" + $script:StudioVenvRollbackActive + " committed=" + $script:StudioInstallCommitted)
+Write-Output ("MARK original_present=" + (Test-Path -LiteralPath $env:TEST_BACKUP))
+"""
+
+
+def test_commit_disarms_restore_before_handing_off_the_delete():
+ source = INSTALL_PS1.read_text(encoding = "utf-8")
+ body = re.search(r" function Complete-StudioVenvRollback \{.*?\n \}\n", source, re.DOTALL)
+ assert body is not None
+ text = body.group(0)
+ handoff = text.index("Start-StudioVenvRollbackBackgroundDelete -Path $backup")
+ for disarm in (
+ "$script:StudioInstallCommitted = $true",
+ "$script:StudioVenvRollbackActive = $false",
+ "$script:StudioVenvRollbackDir = $null",
+ ):
+ assert text.index(disarm) < handoff, disarm
+ assert text.index("Remove-StudioVenvTreeWithRetry -Path $backup") > handoff
+
+
+@windows_only
[email protected]("shell", POWERSHELLS)
+def test_rollback_is_deleted_in_the_background(tmp_path: Path, shell: str):
+ home = tmp_path / "studio"
+ home.mkdir()
+ backup = home / "unsloth_studio.rollback.20260101000000.4000001"
+ _make_tree(backup, dirs = 50, files_per_dir = 100)
+
+ os.environ["TEST_BACKUP"] = str(backup)
+ try:
+ out, wall = _run(shell, COMMIT, home)
+ finally:
+ os.environ.pop("TEST_BACKUP", None)
+ returned_at = time.monotonic()
+ parked = _rollbacks(home)
+ commit_ms = int(re.search(r"commit_ms=(\d+)", out).group(1))
+ print(f"[{shell}] commit_ms={commit_ms} wall_s={wall:.2f}")
+
+ assert [l for l in out.splitlines() if l and not l.startswith("MARK ")] == [], out
+ assert "active=False committed=True" in out, out
+ assert "original_present=False" in out, out
+ assert len(parked) == 1, (parked, out)
+ match = SWEEP_NAME.match(parked[0].name)
+ assert match, parked[0].name
+ deleter_pid = int(match.group(1))
+ assert commit_ms < 5000, out
+
+ # A later run sweeping now must not touch the tree while its deleter is alive.
+ sweep_out, _ = _run(shell, "Remove-StaleStudioVenvRollbacks\nWrite-Output 'MARK swept'\n", home)
+ assert [l for l in sweep_out.splitlines() if l and not l.startswith("MARK ")] == [], sweep_out
+
+ deadline = returned_at + 300
+ while time.monotonic() < deadline and parked[0].exists():
+ time.sleep(0.5)
+ gone_after = time.monotonic() - returned_at
+ print(
+ f"[{shell}] background delete finished {gone_after:.1f}s after return (pid {deleter_pid})"
+ )
+ assert not parked[0].exists(), "background delete did not finish in 300 s"
+ assert _rollbacks(home) == []
+
+
+@windows_only
[email protected]("shell", POWERSHELLS)
+def test_a_stopped_delete_is_swept_by_the_next_run(tmp_path: Path, shell: str):
+ home = tmp_path / "studio"
+ home.mkdir()
+ backup = home / "unsloth_studio.rollback.20260101000000.4000002"
+ _make_tree(backup, dirs = 50, files_per_dir = 100)
+ stale = home / f"unsloth_studio.rollback.20250101000000.{_dead_pid()}"
+ _make_tree(stale, dirs = 2, files_per_dir = 5)
+ live = home / f"unsloth_studio.rollback.20250101000000.{os.getpid()}"
+ _make_tree(live, dirs = 1, files_per_dir = 1)
+
+ # The deleter is in the installer's job; a job closed with kill-on-close stops it like this.
+ script = (
+ COMMIT
+ + """
+$parked = @(Get-ChildItem -LiteralPath $StudioHome -Directory -Force |
+ Where-Object { $_.Name -like 'unsloth_studio.rollback.2026*' })
+$deleterPid = [int]($parked[0].Name -split '\\.')[-1]
+Stop-Process -Id $deleterPid -Force
+Wait-Process -Id $deleterPid -Timeout 30 -ErrorAction SilentlyContinue
+Write-Output ("MARK parked=" + $parked[0].FullName)
+"""
+ )
+ os.environ["TEST_BACKUP"] = str(backup)
+ try:
+ out, _ = _run(shell, script, home)
+ finally:
+ os.environ.pop("TEST_BACKUP", None)
+ parked = Path(re.search(r"MARK parked=(.+)", out).group(1).strip())
+ assert parked.exists(), f"deleter finished before it was stopped; nothing to sweep: {out}"
+
+ sweep_out, _ = _run(shell, "Remove-StaleStudioVenvRollbacks\n", home)
+ assert not parked.exists(), sweep_out
+ assert not stale.exists(), sweep_out
+ assert live.exists(), "a rollback owned by a live process must survive the sweep"
+ assert f"SUBSTEP removed stale environment rollback {parked.name}" in sweep_out, sweep_out
+ assert "LINE [WARN]" not in sweep_out, sweep_out
diff --git a/tests/studio/test_install_rollback_lifecycle.ps1 b/tests/studio/test_install_rollback_lifecycle.ps1
index 7bb1a89368b..846352eb5da 100644
--- a/tests/studio/test_install_rollback_lifecycle.ps1
+++ b/tests/studio/test_install_rollback_lifecycle.ps1
@@ -120,6 +120,10 @@ try {
[System.IO.File]::WriteAllText((Join-Path $VenvDir "generation"), "new")
Complete-StudioVenvRollback
Check "new environment remains" ((Get-Content -LiteralPath (Join-Path $VenvDir "generation") -Raw) -eq "new")
+ # On Windows a background process deletes the parked tree after the commit returns.
+ $deadline = (Get-Date).AddSeconds(120)
+ while ((Get-Date) -lt $deadline -and @(Get-ChildItem -LiteralPath $StudioHome -Directory |
+ Where-Object { $_.Name -like "unsloth_studio.rollback.*" })) { Start-Sleep -Milliseconds 200 }
Check "current rollback is removed" (-not @(Get-ChildItem -LiteralPath $StudioHome -Directory |
Where-Object { $_.Name -like "unsloth_studio.rollback.*" }))