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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Parity of the preflight helpers in setup.ps1 and the standalone copy, plus denied-tree runs."""
import re
from pathlib import Path
import pytest
ROOT = Path(__file__).resolve().parents[3]
INSTALL_PS1 = (ROOT / "install.ps1").read_text(encoding = "utf-8")
SETUP_PS1 = (ROOT / "studio" / "setup.ps1").read_text(encoding = "utf-8")
SETUP_SH = (ROOT / "studio" / "setup.sh").read_text(encoding = "utf-8")
ACL_PS1 = (ROOT / "tests" / "studio" / "test_path_probe_access_denied.ps1").read_text(
encoding = "utf-8"
)
SHARED_BEGIN = "# ── BEGIN SHARED WITH studio/setup.ps1 ──"
SHARED_END = "# ── END SHARED WITH studio/setup.ps1 ──"
# Helpers copied byte-for-byte into install.ps1.
SHARED_FUNCTIONS = (
"Test-AccessDeniedError",
"Get-PathState",
"Get-LlamaCppInstallReadState",
"Get-PathDenialDetail",
"Get-SecuritySoftwareNote",
"Write-PathAccessDenied",
"Get-CanonicalDir",
"Test-StudioHomeIsCustom",
"Get-MasterRootOverride",
"Get-ManagedLlamaCppDir",
"Invoke-ManagedLlamaCppPreflight",
"Test-MirrorConfigured",
"Start-MirrorProbe",
"Wait-MirrorProbe",
"Get-MirrorDnsServers",
"Test-MirrorInChina",
"Invoke-MirrorFallback",
"Get-MirrorName",
"Set-MirrorEnv",
"Pop-MirrorSpare",
"Use-MirrorSpare",
"Get-MirrorFailedHost",
)
def _function_source(text: str, name: str) -> str:
"""Extract a PowerShell function by matching balanced braces."""
match = re.search(rf"(?im)^[ \t]*function[ \t]+{re.escape(name)}\b", text)
assert match, f"{name} is not defined"
start = text.index("{", match.start())
depth = 0
for index in range(start, len(text)):
if text[index] == "{":
depth += 1
elif text[index] == "}":
depth -= 1
if depth == 0:
return text[match.start() : index + 1]
raise AssertionError(f"unbalanced braces in {name}")
def _normalized(source: str) -> str:
"""Remove only the common indentation before comparing helper copies."""
lines = [line.rstrip() for line in source.splitlines()]
body = [line for line in lines if line.strip()]
indent = min(len(line) - len(line.lstrip(" ")) for line in body)
return "\n".join(line[indent:] if line.strip() else "" for line in lines)
@pytest.mark.parametrize("name", SHARED_FUNCTIONS)
def test_installer_copy_matches_setup(name: str) -> None:
"""Edit one file, not the other, and this fails naming the function."""
assert (
_normalized(_function_source(INSTALL_PS1, name))
== _normalized(_function_source(SETUP_PS1, name))
), f"{name} differs between install.ps1 and studio/setup.ps1; run python3 scripts/sync_shared_ps1_helpers.py"
def test_every_function_in_the_shared_block_is_compared() -> None:
"""The parity list cannot silently fall behind the block it guards."""
assert SHARED_BEGIN in INSTALL_PS1
assert SHARED_END in INSTALL_PS1
block = INSTALL_PS1.split(SHARED_BEGIN, 1)[1].split(SHARED_END, 1)[0]
declared = re.findall(r"(?m)^[ \t]*function[ \t]+([A-Za-z-]+)", block)
assert sorted(declared) == sorted(SHARED_FUNCTIONS), declared
def test_the_shared_block_carries_the_drift_note() -> None:
"""A reader who does not know these are copies will paraphrase one of them."""
head = INSTALL_PS1.split(SHARED_BEGIN, 1)[0].rsplit("\n\n", 3)[-1]
assert "byte-identical copies" in head
assert "test_denied_llama_cpp_preflight.py" in head
assert "cannot dot-source" in head
setup_note = SETUP_PS1.split("function Get-LlamaCppInstallReadState", 1)[0]
assert "install.ps1 carries a verbatim copy" in setup_note
def test_setup_and_the_installer_use_the_same_probe() -> None:
"""Both Windows entrypoints must use the shared tri-state probe."""
assert "$llamaDirState = Get-LlamaCppInstallReadState -Path $LlamaCppDir" in SETUP_PS1
assert '$llamaDirState -eq "Denied"' in SETUP_PS1
assert '$llamaDirState -eq "Readable"' in SETUP_PS1
assert '(Get-LlamaCppInstallReadState -Path $dir) -ne "Denied"' in INSTALL_PS1
assert (
"$llamaPreflightFailure = Invoke-ManagedLlamaCppPreflight -StagingRoot $StageRoot"
in SETUP_PS1
)
def test_the_probe_keeps_all_three_answers() -> None:
"""Keep denied, absent, and readable states distinct."""
probe = _function_source(SETUP_PS1, "Get-LlamaCppInstallReadState")
for verdict in ('return "Denied"', 'return "Absent"', 'return "Readable"'):
assert verdict in probe, verdict
assert "Get-ChildItem -LiteralPath $Path -Force -ErrorAction Stop" in probe
assert "Test-AccessDeniedError" in probe
# Regex, not a literal: whitespace alone must not reintroduce the early return.
assert not re.search(r'"Present"\s*\{\s*return\s+"Readable"', probe)
assert probe.index("Get-ChildItem -LiteralPath") < probe.rindex('return "Readable"')
# It runs before anything is installed, so it must not terminate.
assert probe.count("try {") == 1
assert "catch" in probe
def test_the_preflight_runs_before_anything_expensive() -> None:
"""The whole fix is the ordering. Every step below costs network, disk or both."""
call = "$llamaPreflightFailure = Invoke-ManagedLlamaCppPreflight"
assert INSTALL_PS1.count(call) == 1
position = INSTALL_PS1.index(call)
for later in (
'Write-TauriLog "STEP" "Checking system dependencies"',
'Write-TauriLog "STEP" "Installing Python"',
'Write-TauriLog "STEP" "Installing uv package manager"',
'Write-TauriLog "STEP" "Creating virtual environment"',
'Write-TauriLog "STEP" "Installing PyTorch"',
'Write-TauriLog "STEP" "Installing unsloth"',
'Write-TauriLog "STEP" "Running studio setup"',
):
assert position < INSTALL_PS1.index(later), later
relocation = "# ── Leave Windows system directories before installing ──"
assert INSTALL_PS1.index(relocation) < position
def test_direct_setup_and_update_preflight_before_phase_one() -> None:
"""Direct setup, update, and repair must preflight before phase one."""
call = "$llamaPreflightFailure = Invoke-ManagedLlamaCppPreflight"
assert SETUP_PS1.count(call) == 1
position = SETUP_PS1.index(call)
assert SETUP_PS1.index("$LlamaCppDir = Get-ManagedLlamaCppDir") < position
for later in (
"PHASE 1: System-level prerequisites",
"PHASE 2: Frontend build",
"PHASE 3: Python environment + dependencies",
"PHASE 3.4: Prefer prebuilt llama.cpp",
):
assert position < SETUP_PS1.index(later), later
failure = SETUP_PS1[position : SETUP_PS1.index("# Back up User PATH", position)]
assert "Exit-SetupFailure $llamaPreflightFailure" in failure
def test_acl_suite_runs_every_complete_windows_entrypoint() -> None:
"""Windows CI must run every entrypoint and trap expensive work."""
assert '& (Join-Path $repoRoot "install.ps1") --tauri' in ACL_PS1
assert '& (Join-Path $repoRoot "studio/setup.ps1")' in ACL_PS1
assert 'foreach ($mode in @("install", "setup", "update", "repair"))' in ACL_PS1
assert "icacls $entryLocked /deny" in ACL_PS1
assert "else { chmod 000 $entryLocked }" in ACL_PS1
for trap in (
"Invoke-WebRequest",
"Invoke-RestMethod",
"Start-Process",
"winget",
"python",
"uv",
"git",
"npm",
):
assert f'function global:{trap} {{ Stop-EntrypointExpense "{trap}" }}' in ACL_PS1
for marker in (
"Checking system dependencies",
"frontend",
"Installing Python",
"Installing uv package manager",
"Creating virtual environment",
"Installing PyTorch",
"Installing unsloth",
"Unsloth Studio Installed",
):
assert marker in ACL_PS1
assert ".unsloth-studio-owned" in ACL_PS1
assert "unsloth_install_manifest.json" in ACL_PS1
def test_the_preflight_fails_the_install_with_the_shared_reason() -> None:
"""The shared reason must reach the desktop app."""
body = _function_source(INSTALL_PS1, "Invoke-ManagedLlamaCppPreflight")
assert 'Write-PathAccessDenied -Path $dir -Label "llama.cpp install"' in body
assert "Nothing was installed." in body
call = INSTALL_PS1.split("$llamaPreflightFailure = Invoke-ManagedLlamaCppPreflight", 1)[1]
call = call.split("# ── Check winget ──", 1)[0]
assert "Exit-InstallFailure $llamaPreflightFailure" in call
def test_the_preflight_cannot_be_the_thing_that_breaks_the_run() -> None:
"""The early preflight must tolerate an unavailable profile or path."""
body = _function_source(INSTALL_PS1, "Invoke-ManagedLlamaCppPreflight")
guard = "if ([string]::IsNullOrWhiteSpace($env:USERPROFILE)) { return $null }"
assert guard in body
assert body.index(guard) < body.index("Get-ManagedLlamaCppDir")
probe = _function_source(INSTALL_PS1, "Get-LlamaCppInstallReadState")
assert "-ErrorAction Stop" in probe and "catch" in probe
assert "Get-PathState" in probe
def test_a_custom_studio_home_is_never_called_a_cache_we_own() -> None:
"""Do not call an unreadable custom Unsloth home a managed cache."""
body = _function_source(INSTALL_PS1, "Invoke-ManagedLlamaCppPreflight")
assert "$homeIsCustom = (Test-StudioHomeIsCustom) -or [bool](Get-MasterRootOverride)" in body
assert "-OwnershipUnverified:$homeIsCustom" in body
assert (
'Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install"'
" -OwnershipUnverified:$RuntimeRootIsCustom" in SETUP_PS1
)
def test_a_tree_the_user_pointed_at_is_never_called_a_cache_we_own() -> None:
"""Preserve user-supplied wording when an override names the managed path."""
body = _function_source(INSTALL_PS1, "Invoke-ManagedLlamaCppPreflight")
assert "-UserSupplied:$userSupplied" in body
assert (
"$suppliedDir = if ($WithLlamaCppDir) { $WithLlamaCppDir }"
" else { $env:UNSLOTH_LOCAL_LLAMA_CPP_DIR }" in body
)
# Compare canonical paths, and every ancestor of the override: a build inside the
# managed tree is the user's too.
assert "$probe = [string](Get-CanonicalDir -Path $suppliedDir)" in body
assert "if ([string](Get-CanonicalDir -Path $probe) -eq $canonicalDir) {" in body
assert "$LocalIsCanonical = ($ResolvedLocal -eq $LlamaCppDir)" in SETUP_PS1
assert (
"Exit-PathAccessDenied -Path $ResolvedLocal"
' -Label "the UNSLOTH_LOCAL_LLAMA_CPP_DIR build" -UserSupplied' in SETUP_PS1
)
def test_the_managed_path_rule_is_not_duplicated_in_the_installer() -> None:
"""Keep managed path selection in one resolver."""
resolver = _function_source(INSTALL_PS1, "Get-ManagedLlamaCppDir")
assert "param([AllowNull()][string]$StagingRoot = $null)" in resolver
assert 'Join-Path $StagingRoot "llama.cpp"' in resolver
assert "$StageRoot" not in resolver
preflight = _function_source(INSTALL_PS1, "Invoke-ManagedLlamaCppPreflight")
assert "param([AllowNull()][string]$StagingRoot = $null)" in preflight
assert "Get-ManagedLlamaCppDir -StagingRoot $StagingRoot" in preflight
assert "$StageRoot" not in preflight
assert 'Join-Path $env:USERPROFILE ".unsloth\\llama.cpp"' in resolver
assert 'Join-Path (Get-CanonicalDir -Path $StudioHome) "llama.cpp"' in resolver
assert INSTALL_PS1.count('Join-Path $StudioHome "llama.cpp"') == 0
assert INSTALL_PS1.count("$_llamaPath = Get-ManagedLlamaCppDir") == 1
assert "if (-not (Test-StudioHomeIsCustom)) {" in resolver
assert "$legacyStudio" not in resolver
predicate = _function_source(INSTALL_PS1, "Test-StudioHomeIsCustom")
assert predicate.count("Get-CanonicalDir -Path") == 2
canonicalizer = _function_source(INSTALL_PS1, "Get-CanonicalDir")
assert "Resolve-Path -LiteralPath $trimmedPath" in canonicalizer
# A denied path cannot resolve, so compare lexical full paths instead.
assert "GetUnresolvedProviderPathFromPSPath" in canonicalizer
assert "[System.IO.Path]::GetFullPath(" in canonicalizer
# One trim, after both branches: Resolve-Path keeps a trailing separator too.
assert canonicalizer.count("TrimEnd('\\', '/')") == 1
assert canonicalizer.index("Resolve-Path") < canonicalizer.index("TrimEnd")
assert INSTALL_PS1.count("Resolve-Path -LiteralPath $trimmedPath") == 1
def test_both_entrypoints_resolve_and_reuse_the_same_managed_directory() -> None:
"""Both entrypoints must resolve and reuse one managed path."""
assert '$LegacyStudioHome = Join-Path $env:USERPROFILE ".unsloth\\studio"' in SETUP_PS1
assert "$StudioHomeIsCustom = Test-StudioHomeIsCustom" in SETUP_PS1
assert SETUP_PS1.count("$LlamaCppDir = Get-ManagedLlamaCppDir -StagingRoot $StageRoot") == 1
assert "$UnslothHome = Split-Path -Parent $LlamaCppDir" in SETUP_PS1
for name in (
"Get-CanonicalDir",
"Test-StudioHomeIsCustom",
"Get-ManagedLlamaCppDir",
):
assert _normalized(_function_source(INSTALL_PS1, name)) == _normalized(
_function_source(SETUP_PS1, name)
)
phase = SETUP_PS1.split("PHASE 3.4", 1)[1].split("$NeedLlamaSourceBuild", 1)[0]
assert "resolved and preflighted before phase 1" in phase
assert "$LlamaCppDir =" not in phase
_LABELS_OUR_OWN_DIRECTORY = re.compile(r'icacls\.exe "\$dir"(?: /setintegritylevel\b| 2>&1)')
def test_the_installer_never_repairs_permissions_by_itself() -> None:
"""Print ACL repair commands but never run them."""
invocation = re.compile(
r"(^|[&|;=]\s*|\(\s*|Start-Process\s+|Invoke-Expression\s+)(takeown|icacls)\b"
)
for text, label in ((INSTALL_PS1, "install.ps1"), (SETUP_PS1, "setup.ps1")):
for line in text.splitlines():
code = line.split("#", 1)[0].strip()
if "takeown" not in code and "icacls" not in code:
continue
if _LABELS_OUR_OWN_DIRECTORY.search(code):
continue
assert not invocation.search(code), f"{label}: {line.strip()}"
def test_the_label_exemption_is_narrow() -> None:
"""Only our new directory may skip the ACL rule; widening the carve-out would hide a stopped rule."""
forbidden = (
'icacls.exe "$LlamaCppDir" /setintegritylevel (OI)(CI)H',
'icacls.exe "$dir" /grant "$env:USERNAME:(F)"',
'takeown.exe /f "$dir"',
'& icacls "$StudioHome" /reset',
)
for line in forbidden:
assert not _LABELS_OUR_OWN_DIRECTORY.search(line), line
assert _LABELS_OUR_OWN_DIRECTORY.search(
'$null = & icacls.exe "$dir" /setintegritylevel "(OI)(CI)H" 2>&1'
)
assert _LABELS_OUR_OWN_DIRECTORY.search(
'$labelled = ("$(& icacls.exe "$dir" 2>&1)" -match "S-1-16-12288")'
)
def test_setup_sh_reports_a_denied_default_home_cache() -> None:
"""The POSIX prebuilt path must report a denied default cache."""
block = SETUP_SH.split('substep "installing prebuilt llama.cpp..."', 1)[1]
block = block.split("_PREBUILT_CMD=(", 1)[0]
# Listing, not just search: mode 111 passes cd and still breaks the installer.
assert 'if _studio_dir_unreadable "$LLAMA_CPP_DIR"; then' in block
assert '_path_access_denied "$LLAMA_CPP_DIR" "llama.cpp install"' in block
assert block.index("_assert_studio_owned_or_absent") < block.index("_studio_dir_unreadable")
def test_the_denial_detail_survives_a_directory_it_cannot_open() -> None:
"""Get-Item returns nothing for a directory whose ACL denies read, so attributes must come
through an API needing only FILE_READ_ATTRIBUTES, such as [System.IO.File]::GetAttributes."""
for text in (INSTALL_PS1, SETUP_PS1):
body = _function_source(text, "Get-PathDenialDetail")
assert "[System.IO.File]::GetAttributes($Path)" in body
assert body.index("GetAttributes($Path)") < body.index("Get-Item -LiteralPath")
assert "Encrypted" in body
assert "cloud placeholder" in body
assert "ReparsePoint" in body
# On a directory, Encrypted only affects new descendants; listing never needs the key.
assert body.index("FileAttributes]::Directory") < body.index("FileAttributes]::Encrypted")
assert "-not $isDirectory" in body
# RECALL_ON_OPEN and RECALL_ON_DATA_ACCESS are missing from the
# FileAttributes enum on Windows PowerShell 5.1.
assert "0x00040000" in body and "0x00400000" in body
def test_the_security_software_holding_the_folder_is_named() -> None:
"""Denial by a filter driver is not fixed by takeown, icacls or elevation, so name the product."""
for text in (INSTALL_PS1, SETUP_PS1):
body = _function_source(text, "Get-SecuritySoftwareNote")
assert "will not help" not in body
# 0xF000 carries the product run state; a stopped product cannot hold the folder.
assert "productState" in body and "0xF000" in body
assert body.count("1123 and 1124") == 2
assert "Get-Command Get-MpPreference -ErrorAction SilentlyContinue" in body
assert "catch { $mode = $null }" in body
assert "catch { $others = @() }" in body
assert _normalized(body).rstrip().endswith('return ""\n}')
# Only mode 1 blocks file access; 2 only audits; 3 and 4 are disk writes and cannot be the cause
assert "$mode -eq 1" in body
assert "$mode -eq 2" in body
assert "$mode -eq 3" not in body and "$mode -eq 4" not in body
assert "root/SecurityCenter2" in body
assert "AntiVirusProduct" in body
assert "Windows Defender" in body and "Microsoft Defender" in body
reporter = _function_source(text, "Write-PathAccessDenied")
assert "Get-SecuritySoftwareNote" in reporter
assert reporter.index("Antivirus or Controlled folder access") < reporter.index(
"$securitySoftware = Get-SecuritySoftwareNote"
)
def test_a_denied_cache_is_moved_aside_only_when_it_is_ours_to_move() -> None:
"""Directory.Move, not Move-Item, whose copy fallback leaves a llama.cpp.denied-* folder behind."""
for text in (INSTALL_PS1, SETUP_PS1):
body = _function_source(text, "Invoke-ManagedLlamaCppPreflight")
assert "[System.IO.Directory]::Move($dir, $asideDir)" in body
# Code only: a comment above the call names Move-Item to say why it is not used.
code = "\n".join(line.split("#", 1)[0] for line in body.splitlines())
assert "Move-Item" not in code
guard = "if (-not $userSupplied -and -not $homeIsCustom -and -not $isLink) {"
assert guard in body
assert body.index("ReparsePoint") < body.index(guard)
assert "$isLink = $true" in body
assert body.index(guard) < body.index("Write-PathAccessDenied -Path $dir")
assert "Split-Path -Parent $probe" in body
assert body.index("$probe = $parent") < body.index(guard)
# Runs before the install lock, so another run may have moved the folder already.
reprobe = '(Get-LlamaCppInstallReadState -Path $dir) -ne "Denied"'
assert body.count(reprobe) == 2
assert body.rindex(reprobe) < body.index("Write-PathAccessDenied -Path $dir")
def test_the_shared_helpers_have_a_sync_script() -> None:
"""Hand-copying ten helpers between two files is how they drifted before."""
script = (ROOT / "scripts" / "sync_shared_ps1_helpers.py").read_text(encoding = "utf-8")
assert SHARED_BEGIN in script
assert "--check" in script
def test_a_denied_node_cache_gets_the_same_guidance_as_the_llama_cache() -> None:
"""A denied Node cache gets the same guidance as the llama.cpp cache, not a generic network error."""
node = (ROOT / "studio" / "install_node_prebuilt.py").read_text(encoding = "utf-8")
assert "EXIT_DENIED = 4" in node
assert "except PermissionError as exc:" in node
# Windows does not always deliver winerror 5 as PermissionError.
assert 'getattr(exc, "winerror", None) == 5' in node
assert "errno.EACCES" in node
assert "import errno" in node
# The catch-all must stay last, or the classification never runs.
tail = node[node.rindex("def main(") :]
assert tail.index("except PermissionError") < tail.index("except Exception as exc:")
caller = SETUP_PS1.split("install_node_prebuilt.py", 1)[1].split("$env:PATH = ", 1)[0]
assert "$nodeExit -eq 4" in caller
assert 'Exit-PathAccessDenied -Path $NodeDir -Label "Node install"' in caller
assert caller.index("$nodeExit -eq 4") < caller.index("https://nodejs.org/")
# The lock and .staging root live in the parent, so many exit-4 denials are not on the cache.
assert 'DENIED_SCOPE_MARKER = "denied-scope: "' in node
assert 'DENIED_SCOPE_PARENT = "parent"' in node
assert '$nodeOut -match "denied-scope: parent"' in caller
assert "Exit-PathAccessDenied -Path $NodeParent" in caller
assert "-OwnershipUnverified" in caller