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
#Requires -Version 5.1
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
<#
.SYNOPSIS
Full environment setup for Unsloth Studio on Windows (bundled version).
.DESCRIPTION
Uses an isolated, Unsloth-managed Node.js for the frontend build when the
system Node/npm do not meet requirements (never modifies the system Node).
When running from pip install: skips frontend build (already bundled). When
running from git repo: full setup including frontend build.
Supports NVIDIA GPU (full training + inference) and CPU-only (GGUF chat mode).
.NOTES
Default output is minimal (step/substep), aligned with studio/setup.sh.
FULL / LEGACY LOGGING (defensible audit trail, detailed multi-line output):
unsloth studio setup --verbose
Or: $env:UNSLOTH_VERBOSE='1'; powershell -File .\studio\setup.ps1
Or: .\setup.ps1 --verbose
#>
$ErrorActionPreference = "Stop"
# Windows PowerShell 5.1 progress bar redraws make downloads ~130x slower (38.18s vs 0.29s).
$ProgressPreference = 'SilentlyContinue'
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$PackageDir = Split-Path -Parent $ScriptDir
# The deps pass can replace this file while PowerShell keeps running the parsed copy (rerun below).
$script:SetupSelfPath = $MyInvocation.MyCommand.Path
$script:SetupSelfAtStart = $null
try { $script:SetupSelfAtStart = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($script:SetupSelfPath)) } catch { }
# Node is provisioned before the dependency pass can install a newer pin.
$script:SetupNodePinsPath = Join-Path $ScriptDir 'node_prebuilt_pins.json'
$script:SetupNodePinsAtStart = $null
try { $script:SetupNodePinsAtStart = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($script:SetupNodePinsPath)) } catch { }
$script:SetupArgs = @($args)
$script:SetupStartEnv = $null
try { $script:SetupStartEnv = [System.Environment]::GetEnvironmentVariables() } catch { }
# `unsloth studio update` spawns powershell.exe, which is Windows PowerShell 5.1,
# and the child inherits the caller's PSModulePath. Launched from a PowerShell 7
# prompt that path leads with PowerShell 7's module directories, which ship their
# own Microsoft.PowerShell.Security. 5.1 finds that copy first and cannot load it:
#
# The 'Get-ExecutionPolicy' command was found in the module
# 'Microsoft.PowerShell.Security', but the module could not be loaded.
#
# Any Security cmdlet reached during the run ends it there with exit 1 and no
# further output -- Get-AuthenticodeSignature, which verifies the VC++ runtime
# download, sits on this path. A try/catch does not help, because the failure is
# module loading in this process rather than an error the caller can catch.
#
# Prepended, not appended: the problem is precedence, not absence. Clearing the
# variable so 5.1 rebuilds its default does not help either, because the
# machine-level value on the windows-latest image also leads with PS7.
#
# PowerShell rewrites PSModulePath only for a direct pwsh -> powershell.exe hop,
# so any intermediate process defeats it (PowerShell/PowerShell#18681 is this
# exact chain through Python). install.ps1 carries the same block for the same
# reason; scripts/uninstall.ps1 needs none, as it loads no Security cmdlet.
#
# Not restored afterwards, deliberately. $env: is the process environment, so
# running this script in an interactive console leaves the reordering in place
# for that session. Narrowing the trigger to detect the broken chain would risk
# skipping the fix on a chain this list does not anticipate, and the cost of
# that is the install failing outright, against a session-lived module
# precedence change here. See the matching note in install.ps1.
if ($PSVersionTable.PSEdition -ne 'Core' -and $env:SystemRoot) {
$_UnslothSystemModules = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\Modules'
if (Test-Path $_UnslothSystemModules) {
$_UnslothKept = @(
$env:PSModulePath -split ';' |
Where-Object { $_ -and ($_ -ne $_UnslothSystemModules) }
)
$env:PSModulePath = (@($_UnslothSystemModules) + $_UnslothKept) -join ';'
}
}
# 5.1 writes redirected output in the OEM code page but the desktop app decodes UTF-8.
# Must precede the first write. Keep this file ASCII-only: 5.1 parses BOM-less files as ANSI.
$_UnslothUtf8NoBom = New-Object System.Text.UTF8Encoding $false
try {
[Console]::OutputEncoding = $_UnslothUtf8NoBom
} catch {
# Without a console the setter drops the cached writer before throwing, so bind UTF-8 writers directly.
try {
$_UnslothStdout = New-Object System.IO.StreamWriter -ArgumentList ([Console]::OpenStandardOutput()), $_UnslothUtf8NoBom
$_UnslothStdout.AutoFlush = $true
[Console]::SetOut($_UnslothStdout)
$_UnslothStderr = New-Object System.IO.StreamWriter -ArgumentList ([Console]::OpenStandardError()), $_UnslothUtf8NoBom
$_UnslothStderr.AutoFlush = $true
[Console]::SetError($_UnslothStderr)
} catch { }
}
$OutputEncoding = $_UnslothUtf8NoBom
$env:PYTHONUTF8 = '1'
$env:PYTHONIOENCODING = 'utf-8'
# Resolved once: it picks the output sink in step/substep and must not change mid-run.
$script:StudioStdoutRedirected = $false
try { $script:StudioStdoutRedirected = [Console]::IsOutputRedirected } catch { }
# 5.1's Write-Host uses the OEM code page even when redirected, so use one sink:
# the console handle when redirected, Write-Host (colorized) when interactive.
function Write-StudioLine {
param([string]$Message = "", [string]$ForegroundColor)
if ($script:StudioStdoutRedirected) {
try { [Console]::Out.WriteLine($Message); [Console]::Out.Flush() } catch {}
return
}
if ($PSBoundParameters.ContainsKey('ForegroundColor')) {
Write-Host $Message -ForegroundColor $ForegroundColor
} else {
Write-Host $Message
}
}
function Show-DownloadProgress {
param([Parameter(ValueFromPipeline = $true)][object]$InputObject)
process {
$line = [string]$InputObject
if ((@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE) -and
($line -like 'Downloading *: *% (*) at */s' -or
$line -like 'Downloading *: * downloaded at */s')) {
Write-StudioLine $line
}
$InputObject
}
}
# --------------------------------------------------------------------------
# --------------------------------------------------------------------------
# Maintainer-editable defaults; user env vars always override them.
# Prefer "latest" over "master": master bypasses the prebuilt resolver and forces a source build.
# UNSLOTH_LLAMA_CPP_BACKEND: auto|cpu|cuda|vulkan|hip|rocm; concrete values persist across updates.
$DefaultLlamaPrForce = ""
$DefaultLlamaSource = "https://github.com/ggml-org/llama.cpp"
$DefaultLlamaTag = "latest"
$DefaultLlamaForceCompileRef = "master"
$script:UnslothVerbose = ($env:UNSLOTH_VERBOSE -eq '1')
foreach ($a in $args) {
if ($a -eq '--verbose' -or $a -eq '-v') {
$script:UnslothVerbose = $true
break
}
}
if ($script:UnslothVerbose) {
$env:UNSLOTH_VERBOSE = '1'
}
$script:LlamaCppDegraded = $false
$script:LlamaKeptGpuPrebuilt = $null
$script:NvidiaSmiRejected = $false
$script:NvidiaDriverLibraryOnly = $false
$script:NvidiaLibraryInventoryProbed = $false
$script:NvidiaLibraryInventory = $null
# Initialised for Set-StrictMode and for a dot-sourced rerun in the same session.
$script:OfflineFastPath = $false
$script:SetupVenvChanged = $false
$script:CudaToolkitReady = $false
$script:NvccPath = $null
$script:CudaToolkitRoot = $null
$script:CudaArch = $null
$script:DriverMaxCuda = $null
function Exit-SetupFailure {
param(
[Parameter(Mandatory = $true)][string]$Message,
[int]$Code = 1,
[switch]$NoTauriMarker
)
if (Get-Command Remove-WoaMergedOverrides -CommandType Function -ErrorAction SilentlyContinue) { Remove-WoaMergedOverrides }
if ($Code -eq 0) { $Code = 1 }
# A rerun right after this must not find the old frontend build still writing (#8818).
if ($script:FrontendBuildProc) { Stop-FrontendBuildBackground }
if (-not $NoTauriMarker -and ((@("1", "true") -contains $env:UNSLOTH_TAURI_MODE) -or
(@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE))) {
$singleLine = ($Message -replace '[\r\n]+', ' ').Trim()
[Console]::Out.WriteLine("[TAURI:ERROR] $singleLine")
[Console]::Out.Flush()
}
exit $Code
}
# Frontend build overlapped with the Python and llama.cpp steps (#8818).
$script:FrontendBuildProc = $null
$script:FrontendBuildFiles = @()
$script:FrontendBuildHidden = @()
# Serial for Desktop, staged updates and verbose runs. `tsc -b && vite build` alone peaks near
# 7 GB, so ask for 4 logical CPUs and 12 GiB usable; a failing probe keeps the serial path.
function Test-FrontendBuildInBackground {
if (@("1", "true") -contains $env:UNSLOTH_STUDIO_SERIAL_SETUP) { return $false }
if ($script:UnslothVerbose) { return $false }
if (Get-Variable -Name StageRoot -ValueOnly -ErrorAction SilentlyContinue) { return $false }
if ((@("1", "true") -contains $env:UNSLOTH_TAURI_MODE) -or (@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE)) { return $false }
try {
if ([Environment]::ProcessorCount -lt 4) { return $false }
return ([long](Get-UsableMemoryMb -AvailableOnly) -ge 12288)
} catch { return $false }
}
# Start `npm run build` with its output in files and stdin on an empty file (a Ctrl-C must not
# leave cmd.exe asking "Terminate batch job"). $false when it could not start: build serially.
function Start-FrontendBuildBackground {
param(
[string]$WorkingDirectory,
[object[]]$HiddenGitignores = @(),
[string]$FilePath = $env:ComSpec,
[string[]]$ArgumentList = @("/d", "/c", "npm run build")
)
# cmd.exe finds only npm.cmd / .exe / .bat; a PowerShell-only npm.ps1 keeps the serial path.
if ($FilePath -eq $env:ComSpec -and
-not (Get-Command npm.cmd, npm.exe, npm.bat -CommandType Application -ErrorAction SilentlyContinue)) { return $false }
$files = @()
try {
foreach ($i in 1..3) { $files += (New-UnslothTemporaryFile).FullName }
$proc = Start-Process -FilePath $FilePath -ArgumentList $ArgumentList -WorkingDirectory $WorkingDirectory `
-NoNewWindow -PassThru -RedirectStandardOutput $files[0] -RedirectStandardError $files[1] `
-RedirectStandardInput $files[2] -ErrorAction Stop
# Windows PowerShell only reports ExitCode later if the handle was taken now.
$null = $proc.Handle
} catch {
foreach ($f in $files) { Remove-Item -LiteralPath $f -Force -ErrorAction SilentlyContinue }
return $false
}
$script:FrontendBuildProc = $proc
$script:FrontendBuildFiles = $files
$script:FrontendBuildHidden = @($HiddenGitignores)
try { [System.IO.File]::WriteAllText($FrontendBuildMark, "$($proc.Id) $($proc.StartTime.ToFileTimeUtc())") } catch { }
return $true
}
# Wait (up to 10 min, then stop it) for a build a killed setup left running (marker = id + start time).
function Wait-FrontendBuildOwner {
param([int]$TimeoutSeconds = 600)
try { $owner = @(([System.IO.File]::ReadAllText($FrontendBuildMark)).Trim() -split ' ') } catch { return }
if ($owner.Count -ne 2) { return }
$said = $false
$deadline = (Get-Date).AddSeconds($TimeoutSeconds)
while ($true) {
try {
$p = Get-Process -Id ([int]$owner[0]) -ErrorAction Stop
# Within 1 s: .NET on Linux derives StartTime from boot time and drifts by microseconds.
if ([Math]::Abs($p.StartTime.ToFileTimeUtc() - [long]$owner[1]) -gt 10000000) { return }
} catch { return }
if ((Get-Date) -ge $deadline) { break }
if (-not $said) { substep "waiting for an earlier frontend build in this checkout (pid $($owner[0]))..."; $said = $true }
Start-Sleep -Seconds 1
}
# Still alive after that: hung, so stop its tree rather than share node_modules and dist with it.
try {
$taskkill = if ($env:SystemRoot) { Join-Path $env:SystemRoot "System32\taskkill.exe" } else { $null }
if ($taskkill -and (Test-Path -LiteralPath $taskkill)) {
& $taskkill /T /F /PID $p.Id *> $null
} else {
try { $p.Kill($true) } catch { $p.Kill() }
}
[void]$p.WaitForExit(10000)
} catch { }
}
function Restore-FrontendBuildGitignores {
foreach ($gi in $script:FrontendBuildHidden) {
Rename-Item -Path "$gi._twbuild" -NewName (Split-Path $gi -Leaf) -Force -ErrorAction SilentlyContinue
}
$script:FrontendBuildHidden = @()
}
function Remove-FrontendBuildFiles {
foreach ($f in $script:FrontendBuildFiles) { Remove-Item -LiteralPath $f -Force -ErrorAction SilentlyContinue }
$script:FrontendBuildFiles = @()
}
# Kill the build's process tree and restore what it hid; the mark stays, so the next run rebuilds.
function Stop-FrontendBuildBackground {
$proc = $script:FrontendBuildProc
if (-not $proc) { return }
$script:FrontendBuildProc = $null
try {
if (-not $proc.HasExited) {
$taskkill = if ($env:SystemRoot) { Join-Path $env:SystemRoot "System32\taskkill.exe" } else { $null }
if ($taskkill -and (Test-Path -LiteralPath $taskkill)) {
& $taskkill /T /F /PID $proc.Id *> $null
} else {
try { $proc.Kill($true) } catch { $proc.Kill() }
}
[void]$proc.WaitForExit(10000)
}
} catch { }
Restore-FrontendBuildGitignores
Remove-FrontendBuildFiles
}
# CSS check, the "built" line, and clearing the build mark: shared by the serial path and the join.
function Complete-FrontendBuildOutput {
$CssFiles = Get-ChildItem (Join-Path $DistDir "assets") -Filter "*.css" -ErrorAction SilentlyContinue
$MaxCssSize = ($CssFiles | Measure-Object -Property Length -Maximum).Maximum
if ($MaxCssSize -lt 100000) {
step "frontend" "built (warning: CSS may be truncated)" "Yellow"
} else {
step "frontend" "built"
}
Remove-Item -LiteralPath $FrontendBuildMark -Force -ErrorAction SilentlyContinue
}
# Join the background build; with -IfDone, only when it has already exited.
function Complete-FrontendBuildBackground {
param([switch]$IfDone)
$proc = $script:FrontendBuildProc
if (-not $proc) { return }
if ($IfDone -and -not $proc.HasExited) { return }
if (-not $proc.HasExited) { substep "waiting for the frontend build..." }
$proc.WaitForExit()
$buildExit = $proc.ExitCode
$script:FrontendBuildProc = $null
$output = ""
foreach ($f in $script:FrontendBuildFiles[0..1]) {
$text = Get-Content -LiteralPath $f -Raw -ErrorAction SilentlyContinue
if ($text) { $output += $text }
}
Restore-FrontendBuildGitignores
Remove-FrontendBuildFiles
if ($buildExit -ne 0) {
if ($output) { Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Red }
Write-StudioLine "[ERROR] npm run build failed (exit code $buildExit)" -ForegroundColor Red
Exit-SetupFailure "Frontend build failed (exit code $buildExit)"
}
Complete-FrontendBuildOutput
}
function Test-SetupScriptReplaced {
if ($env:UNSLOTH_SETUP_RERUN -eq '1' -or -not $script:SetupSelfAtStart) { return $false }
try { $now = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($script:SetupSelfPath)) } catch { return $false }
if ($now -cne $script:SetupSelfAtStart) { return $true }
$nowPins = $null
try { $nowPins = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($script:SetupNodePinsPath)) } catch { }
return ($nowPins -cne $script:SetupNodePinsAtStart)
}
function Restore-SetupStartEnvironment {
if (-not $script:SetupStartEnv) { return }
$keep = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase)
foreach ($k in $script:SetupStartEnv.Keys) { [void]$keep.Add([string]$k) }
foreach ($k in @([System.Environment]::GetEnvironmentVariables().Keys)) {
if (-not $keep.Contains([string]$k)) { try { [System.Environment]::SetEnvironmentVariable([string]$k, $null) } catch { } }
}
foreach ($k in $script:SetupStartEnv.Keys) {
try { [System.Environment]::SetEnvironmentVariable([string]$k, [string]$script:SetupStartEnv[$k]) } catch { }
}
}
# 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 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 }
# An inherited hint can outlive what it names; a stale one must not force an in-place repair.
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 }
# Windows reuses process ids, so a parent created after its child is not the parent.
$parentRow = $byPid[$parent]
if ($parentRow -and $row.CreationDate -and $parentRow.CreationDate -and
$parentRow.CreationDate -gt $row.CreationDate) { break }
$cur = $parent
}
} catch { }
return $null
}
$FrontendDir = Join-Path $ScriptDir "frontend"
# Build state, not a source input, so the CI dist cache key rightly leaves it out.
$FrontendBuildMark = Join-Path $FrontendDir ".unsloth-build.local"
$OxcValidatorDir = Join-Path $ScriptDir "backend\core\data_recipe\oxc-validator"
$IsPipInstall = -not (Test-Path $FrontendDir)
# ─────────────────────────────────────────────
# ─────────────────────────────────────────────
function Refresh-Environment {
foreach ($level in @('Machine', 'User')) {
$vars = [System.Environment]::GetEnvironmentVariables($level)
foreach ($key in $vars.Keys) {
# Reloading PSModulePath would undo the normalization at the top of this file.
if ($key -eq 'Path' -or $key -eq 'PSModulePath') { continue }
# Same for the UTF-8 invariant: a registry PYTHONUTF8=0 must not reload over ours.
if ($key -eq 'PYTHONUTF8' -or $key -eq 'PYTHONIOENCODING') { continue }
Set-Item -Path "Env:$key" -Value $vars[$key] -ErrorAction SilentlyContinue
}
}
$machinePath = [System.Environment]::GetEnvironmentVariable('Path', 'Machine')
$userPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
# Order: venv Scripts > active conda > Machine > User > current PATH; deduped raw+expanded.
$venvScripts = if ($env:VIRTUAL_ENV) { Join-Path $env:VIRTUAL_ENV 'Scripts' } else { $null }
# An active conda env lives only in the process PATH; keep it in front. Mirrors install.ps1
# Refresh-SessionPath (parity in tests/python/test_installer_conda_path_guard.py).
$condaFront = @()
if (Test-ActiveCondaEnvironment) {
$prefixes = Get-ActiveCondaPrefixes
if ($prefixes) {
foreach ($entry in ($env:Path -split ";")) {
if (Test-PathUnderCondaPrefix -Path $entry -Prefixes $prefixes) {
$condaFront += $entry
}
}
} else {
# Conda entries cannot be identified, so keep the caller's PATH whole and in front.
$condaFront = @($env:Path)
}
}
$sources = @()
if ($venvScripts) { $sources += $venvScripts }
$sources += $condaFront
$sources += @($machinePath, $userPath, $env:Path)
$merged = ($sources | Where-Object { $_ }) -join ';'
$seen = @{}
$unique = New-Object System.Collections.Generic.List[string]
foreach ($p in $merged -split ";") {
$rawKey = $p.Trim().Trim('"').TrimEnd("\").ToLowerInvariant()
$expKey = [Environment]::ExpandEnvironmentVariables($p).Trim().Trim('"').TrimEnd("\").ToLowerInvariant()
if ($rawKey -and -not $seen.ContainsKey($rawKey) -and -not $seen.ContainsKey($expKey)) {
$seen[$rawKey] = $true
if ($expKey -and $expKey -ne $rawKey) { $seen[$expKey] = $true }
$unique.Add($p)
}
}
$env:Path = $unique -join ";"
}
# ── Helper: is a conda environment ACTIVE in this session? ──
function Test-ActiveCondaEnvironment {
foreach ($condaVar in @($env:CONDA_PREFIX, $env:CONDA_DEFAULT_ENV)) {
if (-not [string]::IsNullOrWhiteSpace($condaVar)) { return $true }
}
return $false
}
# Every prefix the active conda owns (env, stacked envs, base). Mirrors install.ps1.
function Get-ActiveCondaPrefixes {
$prefixes = New-Object System.Collections.Generic.List[string]
if (-not [string]::IsNullOrWhiteSpace($env:CONDA_PREFIX)) { $prefixes.Add($env:CONDA_PREFIX) }
# Enumerated from CONDA_SHLVL, not a fixed list; the ceiling stops a bad value spinning.
$levels = 0
if (-not [string]::IsNullOrWhiteSpace($env:CONDA_SHLVL)) {
[void][int]::TryParse($env:CONDA_SHLVL, [ref]$levels)
}
if ($levels -lt 1) { $levels = 1 }
if ($levels -gt 64) { $levels = 64 }
for ($level = 1; $level -le $levels; $level++) {
$value = [Environment]::GetEnvironmentVariable("CONDA_PREFIX_$level")
if (-not [string]::IsNullOrWhiteSpace($value)) { $prefixes.Add($value) }
}
if (-not [string]::IsNullOrWhiteSpace($env:_CONDA_ROOT)) { $prefixes.Add($env:_CONDA_ROOT) }
if (-not [string]::IsNullOrWhiteSpace($env:CONDA_EXE)) {
# Regex, not Split-Path, which keeps backslashes on the non-Windows pwsh the tests use.
$scripts = $env:CONDA_EXE -replace '[\\/][^\\/]*$', ''
$root = $scripts -replace '[\\/][^\\/]*$', ''
if ($root -and $root -ne $env:CONDA_EXE) { $prefixes.Add($root) }
}
return $prefixes
}
# Directory-boundary match, so C:\conda-backup does not match C:\conda.
function Test-PathUnderCondaPrefix {
param([string]$Path, $Prefixes)
if ([string]::IsNullOrWhiteSpace($Path) -or -not $Prefixes) { return $false }
$candidate = [Environment]::ExpandEnvironmentVariables($Path).Trim().Trim('"').TrimEnd('\')
if (-not $candidate) { return $false }
foreach ($prefix in $Prefixes) {
$normalized = [Environment]::ExpandEnvironmentVariables($prefix).Trim().Trim('"').TrimEnd('\')
if (-not $normalized) { continue }
if ($candidate -ieq $normalized) { return $true }
if ($candidate.StartsWith($normalized + '\', [System.StringComparison]::OrdinalIgnoreCase)) {
return $true
}
}
return $false
}
# A persistent prepend outlives the conda activation and would shadow conda's entries.
# Mirrors install.ps1; parity in tests/python/test_installer_conda_path_guard.py.
function Resolve-UserPathPosition {
param(
[ValidateSet('Append','Prepend')]
[string]$Position = 'Append'
)
if ($Position -eq 'Prepend' -and (Test-ActiveCondaEnvironment)) { return 'Append' }
return $Position
}
# Direct registry access preserves REG_EXPAND_SZ (dotnet/runtime#1442).
function Add-ToUserPath {
param(
[Parameter(Mandatory = $true)][string]$Directory,
[ValidateSet('Append','Prepend')]
[string]$Position = 'Append'
)
if (Get-Variable -Name StageRoot -ValueOnly -ErrorAction SilentlyContinue) { return $false }
# A downgraded request must also MOVE an entry a previous run left at the front.
$requestedPosition = $Position
$Position = Resolve-UserPathPosition -Position $Position
$positionDowngraded = ($Position -ne $requestedPosition)
try {
$regKey = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
try {
$rawPath = $regKey.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
[string[]]$entries = if ($rawPath) { $rawPath -split ';' } else { @() } # string[] prevents scalar collapse
$normalDir = $Directory.Trim().Trim('"').TrimEnd('\').ToLowerInvariant()
$expNormalDir = [Environment]::ExpandEnvironmentVariables($Directory).Trim().Trim('"').TrimEnd('\').ToLowerInvariant()
$kept = New-Object System.Collections.Generic.List[string]
$matchIndices = New-Object System.Collections.Generic.List[int]
for ($i = 0; $i -lt $entries.Count; $i++) {
$stripped = $entries[$i].Trim().Trim('"')
$rawNorm = $stripped.TrimEnd('\').ToLowerInvariant()
$expNorm = [Environment]::ExpandEnvironmentVariables($stripped).TrimEnd('\').ToLowerInvariant()
$isMatch = ($rawNorm -and ($rawNorm -eq $normalDir -or $rawNorm -eq $expNormalDir)) -or
($expNorm -and ($expNorm -eq $normalDir -or $expNorm -eq $expNormalDir))
if ($isMatch) {
$matchIndices.Add($i)
continue
}
$kept.Add($entries[$i])
}
$alreadyPresent = $matchIndices.Count -gt 0
if ($alreadyPresent -and $Position -eq 'Append' -and -not $positionDowngraded) {
return $false
}
if ($alreadyPresent -and $Position -eq 'Prepend' -and # Prepend: no-op if already at front
$matchIndices.Count -eq 1 -and $matchIndices[0] -eq 0) {
return $false
}
if ($rawPath) {
try {
$backupKey = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Software\Unsloth')
try {
$existingBackup = $backupKey.GetValue('PathBackup', $null)
if (-not $existingBackup) {
$backupKey.SetValue('PathBackup', $rawPath, [Microsoft.Win32.RegistryValueKind]::ExpandString)
}
} finally {
$backupKey.Close()
}
} catch { }
}
if (-not $rawPath) {
Write-StudioLine "[WARN] User PATH is empty - initializing with $Directory" -ForegroundColor Yellow
}
$newPath = if ($rawPath) {
if ($Position -eq 'Prepend') {
(@($Directory) + $kept) -join ';'
} else {
($kept + @($Directory)) -join ';'
}
} else {
$Directory
}
if ($newPath -ceq $rawPath) { # no actual change
return $false
}
$regKey.SetValue('Path', $newPath, [Microsoft.Win32.RegistryValueKind]::ExpandString)
# Broadcast WM_SETTINGCHANGE via a dummy env-var roundtrip ([NullString]::Value).
try {
$d = "UnslothPathRefresh_$([guid]::NewGuid().ToString('N').Substring(0,8))"
[Environment]::SetEnvironmentVariable($d, '1', 'User')
[Environment]::SetEnvironmentVariable($d, [NullString]::Value, 'User')
} catch { }
return $true
} finally {
$regKey.Close()
}
} catch {
Write-StudioLine "[WARN] Could not update User PATH: $($_.Exception.Message)" -ForegroundColor Yellow
return $false
}
}
# PowerShell 5.1 lacks New-TemporaryFile.
function New-UnslothTemporaryFile {
$tempPath = [System.IO.Path]::GetTempFileName()
return Get-Item -LiteralPath $tempPath
}
function Remove-AgentInstructionFiles {
param([string[]]$Roots)
foreach ($root in $Roots) {
if (-not $root) { continue }
$item = Get-Item -LiteralPath $root -Force -ErrorAction SilentlyContinue
if (-not $item -or -not $item.PSIsContainer) { continue }
if ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) { continue }
$pending = New-Object System.Collections.Stack
$pending.Push($item)
while ($pending.Count -gt 0) {
$current = $pending.Pop()
foreach ($child in @(Get-ChildItem -LiteralPath $current.FullName -Force -ErrorAction SilentlyContinue)) {
if ($child.PSIsContainer) {
if (-not ($child.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
$pending.Push($child)
}
} elseif ($child.Name -in @("AGENTS.md", "CLAUDE.md")) {
Remove-Item -LiteralPath $child.FullName -Force -ErrorAction SilentlyContinue
}
}
}
}
}
function Test-AccessDeniedError {
param($ErrorRecord)
$ex = if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) { $ErrorRecord.Exception } else { $ErrorRecord }
while ($ex) {
if ($ex -is [System.UnauthorizedAccessException]) { return $true }
# IOException uses HRESULT; Win32Exception uses NativeErrorCode.
if ($ex.HResult -eq -2147024891) { return $true }
if ($ex -is [System.ComponentModel.Win32Exception] -and $ex.NativeErrorCode -eq 5) { return $true }
$ex = $ex.InnerException
}
if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) {
return ($ErrorRecord.CategoryInfo.Category -eq [System.Management.Automation.ErrorCategory]::PermissionDenied)
}
return $false
}
# Keep denied ACLs distinct from absent paths instead of letting Test-Path throw.
function Get-PathState {
param(
[Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path,
[ValidateSet("Any", "Leaf", "Container")][string]$PathType = "Any"
)
if ([string]::IsNullOrWhiteSpace($Path)) { return "Absent" }
try {
if (Test-Path -LiteralPath $Path -PathType $PathType -ErrorAction Stop) { return "Present" }
return "Absent"
} catch {
if (Test-AccessDeniedError $_) { return "Denied" }
# Malformed path, offline drive, dangling link: nothing usable there.
return "Absent"
}
}
function Test-PathQuiet {
param(
[Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path,
[ValidateSet("Any", "Leaf", "Container")][string]$PathType = "Any"
)
return ((Get-PathState -Path $Path -PathType $PathType) -eq "Present")
}
# install.ps1 carries a verbatim copy because it cannot dot-source this file;
# test_denied_llama_cpp_preflight.py enforces parity.
# Dir, marker and listing: no single probe separates readable/absent/denied.
function Get-LlamaCppInstallReadState {
param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path)
$dirState = Get-PathState -Path $Path -PathType Container
if ($dirState -eq "Denied") { return "Denied" }
if ($dirState -ne "Present") { return "Absent" }
switch (Get-PathState -Path (Join-Path $Path "UNSLOTH_PREBUILT_INFO.json") -PathType Leaf) {
"Denied" { return "Denied" }
}
try { $null = @(Get-ChildItem -LiteralPath $Path -Force -ErrorAction Stop | Select-Object -First 1) }
catch {
if (Test-AccessDeniedError $_) { return "Denied" }
# Nonfatal here: nothing has been installed yet.
}
return "Readable"
}
function Get-PathDenialDetail {
param([Parameter(Mandatory = $true)][AllowNull()][AllowEmptyString()][string]$Path)
if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
# Read attributes through the filesystem API rather than Get-Item. Getting
# attributes needs only FILE_READ_ATTRIBUTES, which survives the ACLs that
# deny reading the directory itself, so Get-Item returns nothing in exactly
# the case this detail is meant to describe and the caller silently loses
# every hint below.
$attrs = $null
try { $attrs = [System.IO.File]::GetAttributes($Path) } catch { $attrs = $null }
if ($null -eq $attrs) { return "" }
# Ordered by how much each one changes the fix. takeown/icacls cannot help
# with any of the first three, so name them before falling back to ACLs.
# On a directory this attribute only means new descendants are encrypted
# by default, so listing it never needs the key and a denial there is an
# ACL. Only a file's own streams are unreadable without the certificate.
$isDirectory = ([int]$attrs -band [int][System.IO.FileAttributes]::Directory) -ne 0
if (-not $isDirectory -and ($attrs -band [System.IO.FileAttributes]::Encrypted)) {
return " (it is EFS-encrypted, so it stays unreadable even elevated unless the encrypting account or its recovery certificate is available)"
}
# Offline plus either recall attribute is a cloud placeholder, typically
# OneDrive Files On-Demand that cannot hydrate.
# RECALL_ON_OPEN (0x40000) and RECALL_ON_DATA_ACCESS (0x400000) are absent
# from the FileAttributes enum on Windows PowerShell 5.1, so test the bits.
$offline = ([int]$attrs -band [int][System.IO.FileAttributes]::Offline) -ne 0
$recall = ([int]$attrs -band (0x00040000 -bor 0x00400000)) -ne 0
if ($offline -or $recall) {
return " (it is a cloud placeholder, e.g. OneDrive Files On-Demand, that cannot be hydrated right now)"
}
if ($attrs -band [System.IO.FileAttributes]::ReparsePoint) {
$target = $null
try {
$item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue
if ($item -is [System.IO.FileSystemInfo]) { $target = $item.Target }
} catch { $target = $null }
# PS 5.1 exposes .Target as a collection; PS 7 as a string.
if ($target) { return " (it is a link to $(@($target) -join ', '))" }
return " (it is a link)"
}
return ""
}
# Names security software that might be denying the path; takeown/icacls cannot clear a filter driver.
# No product names here: see tests/studio/test_installer_av_shapes.py. Returns "" when unsure.
function Get-SecuritySoftwareNote {
$mode = $null
try {
if (Get-Command Get-MpPreference -ErrorAction SilentlyContinue) {
$mode = [int](Get-MpPreference -ErrorAction Stop).EnableControlledFolderAccess
}
} catch { $mode = $null }
if ($mode -eq 1) {
return "Controlled folder access is ON here, and it gates writes to protected folders whatever your privileges are, so where it is the cause takeown and icacls will not clear it: Windows Defender Operational events 1123 and 1124 say whether it stopped this path, and Virus & threat protection > Ransomware protection > Allow an app is where to allow Unsloth"
}
# SecurityCenter2 is the registration every consumer antivirus makes, and
# it is absent on Server SKUs, so this stays best-effort. productState
# packs the running state in 0xF000: 0x1000 on, 0x2000 snoozed, 0 off.
# A product that is not running cannot be holding the folder and naming it
# sends the user to the wrong console; a state we cannot read proves
# nothing either way, so it is kept.
$others = @()
try {
$others = @(Get-CimInstance -Namespace "root/SecurityCenter2" -ClassName AntiVirusProduct -ErrorAction Stop |
Where-Object { $state = $_.productState -as [uint32]; ($null -eq $state) -or (($state -band 0xF000) -eq 0x1000) } |
ForEach-Object { [string]$_.displayName } |
Where-Object { $_ -and $_ -notmatch "Windows Defender" -and $_ -notmatch "Microsoft Defender" })
} catch { $others = @() }
if ($others.Count -gt 0) {
$names = ($others | Select-Object -Unique) -join ", "
return "$names is running here, and its ransomware or protected-folder feature can deny a path whatever your privileges are. If takeown and icacls do not clear this, look in $names for a block on this folder, and add an exclusion for it and for Unsloth"
}
if ($mode -eq 2) {
return "Controlled folder access is in audit mode, so it is logging rather than blocking and is not the cause here; Windows Defender Operational events 1123 and 1124 name whatever it did stop"
}
return ""
}
# Prints guidance; returns the failure reason as its only pipeline output.
function Write-PathAccessDenied {
param(
[Parameter(Mandatory = $true)][AllowNull()][AllowEmptyString()][string]$Path,
[Parameter(Mandatory = $true)][AllowEmptyString()][string]$Label,
# Never tell users to delete a build they supplied.
[switch]$UserSupplied,
# Unreadable custom homes cannot be identified as managed caches.
[switch]$OwnershipUnverified
)
step "permissions" "$Label at $Path cannot be read: access is denied$(Get-PathDenialDetail -Path $Path)" "Red"
if ($UserSupplied) {
substep "Unsloth will not touch a directory you pointed it at, so this has to be fixed at the source" "Yellow"
substep "Restore access with these two in an elevated PowerShell, or point UNSLOTH_LOCAL_LLAMA_CPP_DIR at a readable build:" "Yellow"
} elseif ($OwnershipUnverified) {
substep "Unsloth cannot confirm this folder is its own install while it is unreadable, so it will not tell you to remove it" "Yellow"
substep "Restore access with these two in an elevated PowerShell, or move the folder aside and re-run setup:" "Yellow"
} else {
substep "This folder lives outside the app, so reinstalling Unsloth Studio, to any drive, reuses it and fails the same way" "Yellow"
substep "Simplest fix: close Unsloth, delete or rename $Path, then re-run setup (it is a managed cache and gets reinstalled)" "Yellow"
substep "If deleting is also denied, run these two in an elevated PowerShell, then re-run setup:" "Yellow"
}
substep "takeown /F `"$Path`" /R /D Y" "Yellow"
substep "icacls `"$Path`" /reset /T" "Yellow"
substep "Antivirus or Controlled folder access can deny this path too; allow or exclude it, then retry" "Yellow"
# After the generic line, since this one either confirms it or rules it
# out, and an empty answer must leave the generic advice standing.
$securitySoftware = Get-SecuritySoftwareNote
if ($securitySoftware) { substep $securitySoftware "Yellow" }
if ($UserSupplied) {
return "Access denied reading $Label at $Path. Restore access with takeown/icacls, or point UNSLOTH_LOCAL_LLAMA_CPP_DIR at a readable build, then re-run setup."
}
if ($OwnershipUnverified) {
return "Access denied reading $Label at $Path. Unsloth cannot confirm that folder is its own install while it is unreadable: restore access with takeown/icacls, or move it aside, then re-run setup."
}
return "Access denied reading the existing $Label at $Path. Delete or rename that folder (Unsloth reinstalls it) or restore access with takeown/icacls, then re-run setup. Reinstalling the app does not reset it."
}
function Get-CanonicalDir {
param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path)
$trimmedPath = $Path.Trim()
if ([string]::IsNullOrWhiteSpace($trimmedPath)) { return $trimmedPath }
$resolvedPath = $null
if ((Get-PathState -Path $trimmedPath -PathType Container) -eq "Present") {
try { $resolvedPath = (Resolve-Path -LiteralPath $trimmedPath).Path } catch {}
}
if (-not $resolvedPath) {
try {
$resolvedPath =
$ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($trimmedPath)
} catch {
$resolvedPath = [System.Environment]::ExpandEnvironmentVariables($trimmedPath)
}
try { $resolvedPath = [System.IO.Path]::GetFullPath($resolvedPath) } catch {}
}
# Resolve-Path keeps a trailing separator, so trim after both branches (never a root).
try {
$root = [System.IO.Path]::GetPathRoot($resolvedPath)
if ($root -and $resolvedPath.Length -gt $root.Length) { return $resolvedPath.TrimEnd('\', '/') }
} catch {}
return $resolvedPath
}
function Test-StudioHomeIsCustom {
return ((Get-CanonicalDir -Path $StudioHome) -ne
(Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth\studio")))
}
# Only an install.ps1-written shim (trampoline marker) proves the root is ours; the caller may
# delete a venv on that answer. Mirrored in install.ps1 and scripts/uninstall.ps1.
function Test-UnslothCmdShimFile {
param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path)
if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $false }
try {
if ((Get-Item -LiteralPath $Path -ErrorAction Stop).Length -gt 8192) { return $false }
$text = [System.IO.File]::ReadAllText($Path)
} catch {
# Unreadable proves nothing, and "proves nothing" must not mean "deletable".
return $false
}
return ($text -like "*unsloth-studio-managed-launcher*" -and $text -like "*from unsloth_cli import app*")
}
# llama.cpp, node and whisper.cpp sit BESIDE studio\ under the master root, not inside it.
function Get-MasterRootOverride {
if ([string]::IsNullOrWhiteSpace($env:UNSLOTH_HOME)) { return $null }
$value = $env:UNSLOTH_HOME.Trim()
if ($value -eq "~") {
$value = $env:USERPROFILE
} elseif ($value -like "~/*" -or $value -like "~\*") {
$value = (Join-Path $env:USERPROFILE $value.Substring(1).TrimStart('/', '\'))
}
return (Get-CanonicalDir -Path $value)
}
function Get-ManagedLlamaCppDir {
param([AllowNull()][string]$StagingRoot = $null)
if ($StagingRoot) {
return (Join-Path $StagingRoot "llama.cpp")
}
$masterRoot = Get-MasterRootOverride
if ($masterRoot) {
return (Join-Path $masterRoot "llama.cpp")
}
if (-not (Test-StudioHomeIsCustom)) {
return (Join-Path $env:USERPROFILE ".unsloth\llama.cpp")
}
return (Join-Path (Get-CanonicalDir -Path $StudioHome) "llama.cpp")
}
# Failure reason when the managed tree is denied; never touches its ACLs.
function Invoke-ManagedLlamaCppPreflight {
param([AllowNull()][string]$StagingRoot = $null)
# Let the existing profile validation handle a missing USERPROFILE later.
if ([string]::IsNullOrWhiteSpace($env:USERPROFILE)) { return $null }
$dir = Get-ManagedLlamaCppDir -StagingRoot $StagingRoot
if ((Get-LlamaCppInstallReadState -Path $dir) -ne "Denied") { return $null }
Write-StudioLine ""
# A denied custom home cannot be claimed as an Unsloth-managed cache. Computed rather
# than read off $RuntimeRootIsCustom: this runs beside the line that defines it.
$homeIsCustom = (Test-StudioHomeIsCustom) -or [bool](Get-MasterRootOverride)
# Preserve user-supplied wording when either override names this tree, or
# names a build inside it: moving or deleting this folder takes that build
# with it, and the later --with-llama-cpp-dir check then aborts on a path
# we made disappear.
$suppliedDir = if ($WithLlamaCppDir) { $WithLlamaCppDir } else { $env:UNSLOTH_LOCAL_LLAMA_CPP_DIR }
# Walking the ancestors beats comparing the two canonical strings: an
# override that does not exist yet cannot be resolved, so a prefix test
# would compare a resolved path against an unresolved one and miss.
$userSupplied = $false
if (-not [string]::IsNullOrWhiteSpace($suppliedDir)) {
$canonicalDir = [string](Get-CanonicalDir -Path $dir)
$probe = [string](Get-CanonicalDir -Path $suppliedDir)
while (-not [string]::IsNullOrWhiteSpace($probe)) {
if ([string](Get-CanonicalDir -Path $probe) -eq $canonicalDir) {
$userSupplied = $true
break
}
$parent = ""
try { $parent = [string](Split-Path -Parent $probe) } catch { $parent = "" }
if ($parent -eq $probe) { break }
$probe = $parent
}
}
# Only the default branch below tells the user to delete this folder, so
# only that case may move it. A user-supplied build is not ours to touch,
# and an unreadable custom home cannot be confirmed as a managed cache.
# Renaming needs DELETE on the folder plus write on its parent, neither of
# which is read access, so this recovers denials that takeown and icacls
# do not: the folder is a managed cache that setup reinstalls anyway.
# Setup never makes this a link, so a link here is something the user
# arranged, pointing at a build we were not told about. Moving it would
# silently change which tree they run without touching the one they were
# protecting, so it is left alone and named in the guidance instead.
$isLink = $false
try {
$linkAttrs = [System.IO.File]::GetAttributes($dir)
$isLink = ([int]$linkAttrs -band [int][System.IO.FileAttributes]::ReparsePoint) -ne 0
} catch {
# Unreadable attributes prove nothing, and "proves nothing" must not
# mean "movable": fall through to the guidance rather than guess.
$isLink = $true
}
if (-not $userSupplied -and -not $homeIsCustom -and -not $isLink) {
$asideDir = "$dir.denied-$(Get-Date -Format 'yyyyMMddHHmmss')"
$moved = $false
try {
# [System.IO.Directory]::Move, not Move-Item. Move-Item falls back to
# copy-then-delete when the rename fails, which creates $asideDir and then
# dies on the unreadable contents, leaving a stray llama.cpp.denied-* folder
# beside the original on every run. Directory.Move is a bare rename: it
# either moves the tree or throws having created nothing.
# Measured on windows-latest, denying each shape on the folder itself:
# (OI)(CI)(RX) rename refused, Move-Item left a stray folder
# (OI)(CI)(R) rename refused, Move-Item left a stray folder
# (RX) rename refused, Move-Item left a stray folder
# (DE) rename SUCCEEDED, both ways
# So on Windows a read denial always refuses the rename (the open asks for
# SYNCHRONIZE, which every read deny removes) and this recovery cannot fire;
# denying DELETE, which sounds like the blocker, does not stop it. On POSIX
# the rename needs only write+execute on the parent, so the recovery is real
# there and is why this stays rather than being deleted.
[System.IO.Directory]::Move($dir, $asideDir)
$moved = $true
} catch {
# Expected when the denial covers the rename; fall through to guidance.
# Nothing to clean up: Directory.Move creates nothing when it throws.
}
if ($moved) {
step "permissions" "llama.cpp install at $dir could not be read, so it was moved aside" "Yellow"
substep "Moved to $asideDir; it is a managed cache and setup reinstalls it" "Yellow"
substep "Delete the moved folder once access is restored, it is no longer used" "Yellow"
Write-StudioLine ""
return $null
}
# This runs before the install lock, so a second run can have moved
# the folder in between. Re-probe rather than report a denial for a
# path that is no longer there and stop an install that can proceed.
if ((Get-LlamaCppInstallReadState -Path $dir) -ne "Denied") { return $null }
}
$reason = Write-PathAccessDenied -Path $dir -Label "llama.cpp install" `
-UserSupplied:$userSupplied -OwnershipUnverified:$homeIsCustom
substep "Stopping here, before phase 1: nothing has been downloaded or installed" "Yellow"
substep "Fix access, then run the same install, setup, or update command again" "Yellow"
Write-StudioLine ""
return "$reason Nothing was installed."
}
# uv's own boolish set, for every UV_* switch this script reads out of the caller's
# environment. Verified against uv 0.10.7, crates/uv-static/src/lib.rs
# parse_boolish_environment_variable, which restates clap's str_to_bool: true is
# y, yes, t, true, on, 1; false is n, no, f, false, off, 0; case-insensitive, and
# anything else aborts uv rather than being guessed at.
#
# `-notin @("", "0", "false")`, which each of these sites used to spell inline, read
# off, no, n and f as TRUE, the exact opposite of uv's answer for them.
#
# Trimmed where uv is not: uv aborts on a padded value, so the resolve fails whatever
# this returns, and trimming keeps the answer identical to setup.sh's
# _uv_offline_requested and install_python_stack.py's _uv_env_flag, which is the
# property worth having. ToLowerInvariant, not ToLower: a Turkish-locale host
# lowercases "I" to a dotless i and would stop matching.
#
# install.ps1 carries the same function: the two scripts cannot dot-source each other
# (install.ps1 is run straight off the wire by `irm | iex`, with no file and no sibling
# on disk), so the parity is pinned by test instead. Defined ahead of Test-MirrorConfigured,
# which `Invoke-MirrorFallback -SpareOnly` reaches long before the rest of the helpers.
function Test-UvEnvFlag {
param([string]$Name)
$value = [string][Environment]::GetEnvironmentVariable($Name)
return (@("1", "t", "true", "y", "yes", "on") -contains $value.Trim().ToLowerInvariant())
}
# pip's rule, kept separate on purpose: PIP_NO_INDEX is pip's variable and uv never
# reads it, so uv's parser has no authority over it. pip routes it through
# ConfigOptionParser._update_defaults -> strtobool (pip/_internal/utils/misc.py): true
# is y, yes, t, true, on, 1; false is n, no, f, false, off, 0; case-insensitive and
# untrimmed, with anything else exiting pip on "is not a valid value". An empty value
# never reaches strtobool, because _get_ordered_configuration_items drops falsy values
# first, so PIP_NO_INDEX="" is simply not set.
#
# The literals coincide with uv's today. They are restated rather than shared anyway,
# so that the day either project changes its mind this is a one-function edit instead
# of a silent behaviour change in the other resolver.
function Test-PipEnvFlag {
param([string]$Name)
$value = [string][Environment]::GetEnvironmentVariable($Name)
return (@("1", "t", "true", "y", "yes", "on") -contains $value.Trim().ToLowerInvariant())
}
function Test-MirrorConfigured {
param([ValidateSet('uv', 'python', 'pip')][string]$Tool)
if ($Tool -ne 'pip') {
if ($Tool -eq 'python') {
# UV_PYTHON_INSTALL_MIRROR would override UV_ASTRAL_MIRROR_URL; uv rejects a mirror beside a custom manifest.
if ("$env:UV_PYTHON_INSTALL_MIRROR$env:UV_ASTRAL_MIRROR_URL$env:UV_PYTHON_DOWNLOADS_JSON_URL") { return $true }
$pattern = '^\s*(python-install-mirror|python-downloads-json-url)\s*='
} else {
if ("$env:UV_DEFAULT_INDEX$env:UV_INDEX_URL$env:UV_INDEX$env:UV_EXTRA_INDEX_URL") { return $true }
$pattern = '^\s*(\[\[(tool\.uv\.)?index\]\]|(pip\.)?(index|index-url|default-index|extra-index-url|no-index)\s*=)'
}
# uv's discovery: UV_CONFIG_FILE alone (even with UV_NO_CONFIG); relative paths from --directory.
$files = @("$env:APPDATA\uv\uv.toml")
if (-not (Test-UvEnvFlag 'UV_NO_SYSTEM_CONFIG')) { $files += "$env:ProgramData\uv\uv.toml" }
$dir = (Get-Location -PSProvider FileSystem).ProviderPath
$workDir = if ($env:UV_WORKING_DIR) { $env:UV_WORKING_DIR } else { $env:UV_WORKING_DIRECTORY }
if ($workDir) { $dir = [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($dir, $workDir)) }
$configFile = if ($env:UV_CONFIG_FILE) { [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($dir, $env:UV_CONFIG_FILE)) }
if ($env:UV_PROJECT) { $dir = [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($dir, $env:UV_PROJECT)) }
if ($configFile) { $files = @($configFile); $dir = $null }
elseif (Test-UvEnvFlag 'UV_NO_CONFIG') { $files = @(); $dir = $null }
while ($dir) {
$pyproject = Join-Path $dir 'pyproject.toml'
if (Test-Path -LiteralPath (Join-Path $dir 'uv.toml') -PathType Leaf) { $files += Join-Path $dir 'uv.toml'; break }
if ((Test-Path -LiteralPath $pyproject -PathType Leaf) -and
(Select-String -LiteralPath $pyproject -Pattern '^\s*\[+tool\.uv(\.|\])' -Quiet -ErrorAction SilentlyContinue)) { $files += $pyproject; break }
$dir = Split-Path -Parent $dir
}
} else {
if ("$env:PIP_INDEX_URL$env:PIP_EXTRA_INDEX_URL$env:PIP_NO_INDEX") { return $true }
$pattern = '^\s*(index[-_]url|extra[-_]index[-_]url|no[-_]index)\s*[=:]'
$files = @($env:PIP_CONFIG_FILE, $(if ($venv = Get-Variable VenvDir -ValueOnly -ErrorAction SilentlyContinue) { Join-Path $venv 'pip.ini' }), "$env:APPDATA\pip\pip.ini", "$env:USERPROFILE\pip\pip.ini", "$env:ProgramData\pip\pip.ini")
}
foreach ($file in $files) {
if ($file -and (Test-Path -LiteralPath $file -PathType Leaf) -and
(Select-String -LiteralPath $file -Pattern $pattern -Quiet -ErrorAction SilentlyContinue)) {
return $true
}
}
return $false
}
function Start-MirrorProbe {
param([string[]]$Urls, [double]$Seconds, [long]$LastByte)
$state = @{ Urls = $Urls; Seconds = $Seconds; LastByte = $LastByte; Clock = [System.Diagnostics.Stopwatch]::StartNew(); Requests = @{}; Heads = @{}; InTime = @{}; Bodies = @{}; Buffers = @{} }
$deadline = [System.Threading.Tasks.Task]::Delay([int]($Seconds * 1000))
foreach ($url in $Urls) {
$state.Requests[$url] = [System.Net.WebRequest]::Create($url)
# The CERNET mirrors answer 403 to a request without a User-Agent; a fresh connection keeps every probe cold, as curl's are.
$state.Requests[$url].UserAgent = 'unsloth-installer'
$state.Requests[$url].KeepAlive = $false
$state.Requests[$url].AddRange(0, $LastByte)
$state.Heads[$url] = $state.Requests[$url].GetResponseAsync()
$state.InTime[$url] = [System.Threading.Tasks.Task]::WhenAny([System.Threading.Tasks.Task[]]@($state.Heads[$url], $deadline))
}
return $state
}
function Wait-MirrorProbe {
param($Probe)
$results = @{}
$measure = { param($url) @([int]$Probe.Heads[$url].Result.StatusCode, [long]($Probe.Buffers[$url].Position / $Probe.Clock.Elapsed.TotalSeconds)) }
try {
while ($true) {
foreach ($url in $Probe.Urls) {
if ($results.ContainsKey($url) -or -not $Probe.InTime[$url].IsCompleted) { continue }
if (-not [object]::ReferenceEquals($Probe.InTime[$url].Result, $Probe.Heads[$url])) {
$results[$url] = @(0, [long]0)
} elseif ($Probe.Heads[$url].Status -ne 'RanToCompletion') {
$failure = $Probe.Heads[$url].Exception.InnerException -as [System.Net.WebException]
$results[$url] = @($(if ($failure -and $failure.Response) { [int]$failure.Response.StatusCode } else { 0 }), [long]0)
} elseif (-not $Probe.Bodies.ContainsKey($url)) {
$Probe.Buffers[$url] = [System.IO.MemoryStream]::new([byte[]]::new($Probe.LastByte + 65537))
$Probe.Bodies[$url] = $Probe.Heads[$url].Result.GetResponseStream().CopyToAsync($Probe.Buffers[$url], 65536)
} elseif ($Probe.Bodies[$url].IsCompleted) {
$results[$url] = & $measure $url
}
}
$pending = @($Probe.Urls | Where-Object { -not $results.ContainsKey($_) } | ForEach-Object { if ($Probe.Bodies.ContainsKey($_)) { $Probe.Bodies[$_] } else { $Probe.InTime[$_] } })
$left = [int](($Probe.Seconds - $Probe.Clock.Elapsed.TotalSeconds) * 1000)
if ($pending.Count -eq 0 -or $left -le 0) { break }
[void][System.Threading.Tasks.Task]::WaitAny([System.Threading.Tasks.Task[]]$pending, $left)
}
foreach ($url in $Probe.Urls) {
if ($results.ContainsKey($url)) { continue }
$results[$url] = if ($Probe.Buffers.ContainsKey($url)) { & $measure $url } else { @(0, [long]0) }
}
} finally {
foreach ($url in @($Probe.Requests.Keys)) {
$Probe.Requests[$url].Abort()
if ($Probe.Heads[$url].Status -eq 'RanToCompletion') { $Probe.Heads[$url].Result.Dispose() }
}
}
return $results
}
function Get-MirrorDnsServers {
try {
[System.Net.NetworkInformation.NetworkInterface]::GetAllNetworkInterfaces() | Where-Object { $_.OperationalStatus -eq 'Up' } |
ForEach-Object { $_.GetIPProperties().DnsAddresses } | ForEach-Object { "$_" }
} catch {}
}
# No network call: mirrors _mirror_in_china in install.sh.
function Test-MirrorInChina {
try { if ((Get-TimeZone).Id -in 'China Standard Time', 'Asia/Shanghai', 'Asia/Chongqing', 'Asia/Chungking', 'Asia/Harbin', 'Asia/Urumqi', 'Asia/Kashgar', 'PRC') { return $true } } catch {}
return [bool](@(Get-MirrorDnsServers) -match '^(223\.5\.5\.5|223\.6\.6\.6|119\.29\.29\.29|114\.114\.11[45]\.11[0459]|182\.254\.116\.116|119\.28\.28\.28|180\.76\.76\.76|1\.2\.4\.8|210\.2\.4\.8|100\.100\.2\.13[68]|183\.60\.8[23]\.(19|98))$')
}
function Invoke-MirrorFallback {
param([switch]$SpareOnly)
$optIn = "$env:UNSLOTH_MIRROR_FALLBACK".Trim()
# When off, a retry state inherited from a parent is dropped so nothing downstream acts on it.
if ($optIn -match '^(0|false|no|off)$' -or ($optIn -notmatch '^(1|true|yes|on)$' -and -not (Test-MirrorInChina))) {
Remove-Item Env:_UNSLOTH_MIRROR_SPARE -ErrorAction SilentlyContinue
return
}
if ($env:_UNSLOTH_MIRROR_PROBED) { return }
if (-not $SpareOnly) { $env:_UNSLOTH_MIRROR_PROBED = '1' }
$cernet = 'https://tuna.mirrors.cernet.edu.cn'
$npmMirror = 'https://registry.npmmirror.com'
$pypiMirror = "$cernet/pypi/web/simple"
# GitHub-release mirrors keep only the newest Python builds, while a pinned uv asks for the builds it shipped with; npmmirror keeps every release.
$pythonMirror = "$npmMirror/-/binary/python-build-standalone"
$minBps = 1MB
$useUv = -not (Test-MirrorConfigured -Tool uv)
$usePip = -not (Test-MirrorConfigured -Tool pip)
$uvWheel = 'packages/3a/ad/3c2a81d66d1839063662e5b6c0002ec31f8ee987dbc5295747627ca6160a/uv-0.13.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
$torchWheel = 'whl/cpu/torch-2.9.1%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl'
$nodeTarball = 'v24.18.0/node-v24.18.0-linux-x64.tar.gz'
$artifact = @{
'pypi' = "https://files.pythonhosted.org/$uvWheel"; 'cernet-pypi' = "$cernet/pypi/web/$uvWheel"
'torch' = "https://download-r2.pytorch.org/$torchWheel"; 'cernet-torch' = "$cernet/pytorch/$torchWheel"
'node' = "https://nodejs.org/dist/$nodeTarball"; 'npmmirror-node' = "$npmMirror/-/binary/node/$nodeTarball"
'npm' = 'https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz'; 'npmmirror' = "$npmMirror/typescript/-/typescript-5.9.3.tgz"
'astral' = 'https://releases.astral.sh/github/uv/releases/download/0.13.5/uv-x86_64-unknown-linux-gnu.tar.gz'
}
$hosts = [ordered]@{}
if ($useUv -or $usePip) { $hosts['pypi'] = @('pypi', 'cernet-pypi', $pypiMirror, 'https://pypi.org/simple/uv/', "$pypiMirror/uv/") }
if (-not "$env:UNSLOTH_PYTORCH_MIRROR$env:UNSLOTH_TORCH_INDEX_URL") {
$hosts['torch'] = @('torch', 'cernet-torch', "$cernet/pytorch/whl", 'https://download.pytorch.org/whl/cpu/torch/', "$cernet/pytorch/whl/cpu/torch/")
}
if (-not $env:UNSLOTH_NODE_MIRROR) { $hosts['node'] = @('node', 'npmmirror-node', "$npmMirror/-/binary/node", $null, $null) }
if (-not "$env:UNSLOTH_NPM_REGISTRY$env:NPM_CONFIG_REGISTRY") { $hosts['npm'] = @('npm', 'npmmirror', $npmMirror, $null, $null) }
if (-not (Test-MirrorConfigured -Tool python)) { $hosts['python'] = @('astral', 'npmmirror', $pythonMirror, $null, $null) }
if (-not "$env:UNSLOTH_UV_WHEEL_MIRROR$env:UV_DOWNLOAD_URL$env:INSTALLER_DOWNLOAD_URL$env:UV_INSTALLER_GHE_BASE_URL$env:UV_INSTALLER_GITHUB_BASE_URL") {
$hosts['uvbin'] = @('astral', 'cernet-pypi', "$cernet/pypi/web", $null, $null)
}
if ($hosts.Count -eq 0) { return }
$varsOf = {
param($name)
$to = if ($hosts.Contains($name)) { $hosts[$name][2] }
switch ($name) {
'pypi' {
if ($useUv) { "UV_DEFAULT_INDEX=$to" }
if ($usePip) { "PIP_INDEX_URL=$to" }
}
'unsynced' {
# Only for one rerun: uv's unsafe-first-match fetches every package from every index, and fails outright when one is unreachable.
if ($useUv) {
'UV_DEFAULT_INDEX=https://pypi.org/simple'; "UV_INDEX=$pypiMirror"
"UV_INDEX_STRATEGY=$(if ($env:UV_INDEX_STRATEGY) { $env:UV_INDEX_STRATEGY } else { 'unsafe-first-match' })"
}
if ($usePip) { 'PIP_EXTRA_INDEX_URL=https://pypi.org/simple'; "PIP_INDEX_URL=$pypiMirror" }
}
'torch' { "UNSLOTH_PYTORCH_MIRROR=$to" }
'node' { "UNSLOTH_NODE_MIRROR=$to" }
'npm' { "UNSLOTH_NPM_REGISTRY=$to" }
'python' { "UV_PYTHON_INSTALL_MIRROR=$to" }
'uvbin' { "UNSLOTH_UV_WHEEL_MIRROR=$to" }
}
}
$env:_UNSLOTH_MIRROR_SPARE = @($hosts.Keys | ForEach-Object { (@($_) + @(& $varsOf $_)) -join '|' }) -join ' '
if ($SpareOnly -or (Test-UvEnvFlag 'UV_OFFLINE')) { return }
$answered = @{}
$codeOf = { param($index, $result) if ($index -and "$($answered[$index][0])" -notmatch '^2\d\d$') { 0 } else { $result[0] } }
# PS 5.1 may pin TLS 1.0/1.1 (every probed host refuses it; Tls|Tls12 still fails) and queues past 2 connections per host.
$savedProtocol = [System.Net.ServicePointManager]::SecurityProtocol
$savedLimit = [System.Net.ServicePointManager]::DefaultConnectionLimit
if ([int]$savedProtocol -ne 0) { [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 }
[System.Net.ServicePointManager]::DefaultConnectionLimit = [Math]::Max($savedLimit, 16)
try {
$defaults = @($hosts.Values | ForEach-Object { $_[0] } | Select-Object -Unique)
$indexes = Start-MirrorProbe -Urls @($hosts.Values | ForEach-Object { $_[3] } | Where-Object { $_ }) -Seconds 4 -LastByte 1023
$timed = @{}
foreach ($name in $defaults) { $timed[$name] = (Wait-MirrorProbe (Start-MirrorProbe -Urls $artifact[$name] -Seconds 1.5 -LastByte 1048575))[$artifact[$name]] }
$answered = Wait-MirrorProbe $indexes
$slow = @($hosts.Keys | Where-Object {
$code = & $codeOf $hosts[$_][3] $timed[$hosts[$_][0]]
$code -eq 0 -or ($code -ge 300 -and $code -lt 400) -or ($code -ge 200 -and $code -lt 300 -and $timed[$hosts[$_][0]][1] -lt $minBps)
})
if ($slow.Count -eq 0) { return }
$sources = @($slow | ForEach-Object { $hosts[$_][1] } | Select-Object -Unique)
$indexes = Start-MirrorProbe -Urls @($slow | ForEach-Object { $hosts[$_][3]; $hosts[$_][4] } | Where-Object { $_ }) -Seconds 4 -LastByte 1023
$race = Wait-MirrorProbe (Start-MirrorProbe -Urls @(@($slow | ForEach-Object { $artifact[$hosts[$_][0]] }) + @($sources | ForEach-Object { $artifact[$_] }) | Select-Object -Unique) -Seconds 4 -LastByte 1048575)
$sourceIndexes = Wait-MirrorProbe $indexes
foreach ($url in $sourceIndexes.Keys) { $answered[$url] = $sourceIndexes[$url] }
} finally {
[System.Net.ServicePointManager]::SecurityProtocol = $savedProtocol
[System.Net.ServicePointManager]::DefaultConnectionLimit = $savedLimit
}
$used = $false
foreach ($name in $slow) {
$default = $race[$artifact[$hosts[$name][0]]]
$mirror = $race[$artifact[$hosts[$name][1]]]
$how = if ("$(& $codeOf $hosts[$name][3] $default)" -match '^2\d\d$') { 'slow' } else { 'blocked' }
$defaultBps = if ($how -eq 'slow') { $default[1] } else { [long]0 }
if ("$(& $codeOf $hosts[$name][4] $mirror)" -notmatch '^2\d\d$' -or $defaultBps -ge $minBps -or $mirror[1] -le $defaultBps) { continue }
Set-MirrorEnv @(& $varsOf $name)
$env:_UNSLOTH_MIRROR_SPARE = @(-split $env:_UNSLOTH_MIRROR_SPARE | Where-Object { $_ -notlike "$name|*" }) -join ' '
if ($name -eq 'pypi' -and $how -eq 'slow') { $env:_UNSLOTH_MIRROR_SPARE = (@(-split $env:_UNSLOTH_MIRROR_SPARE) + ((@('unsynced') + @(& $varsOf 'unsynced')) -join '|')) -join ' ' }
step "mirror" "$(Get-MirrorName $name) is $how ($($defaultBps -shr 10) KB/s, mirror $($mirror[1] -shr 10) KB/s); using $($hosts[$name][2])" "Yellow"
$used = $true
}
if ($used) { substep "Set UNSLOTH_MIRROR_FALLBACK=0 to always use the default hosts." }
}
function Get-MirrorName {
param([string]$Name)
@{ pypi = 'PyPI'; unsynced = 'The PyPI mirror'; torch = 'download.pytorch.org'; node = 'nodejs.org'; npm = 'registry.npmjs.org'; python = 'releases.astral.sh (Python builds)'; uvbin = 'releases.astral.sh (uv)' }[$Name]
}
function Set-MirrorEnv {
param([string[]]$Pairs)
foreach ($pair in $Pairs) { Set-Item "Env:$($pair.Split('=', 2)[0])" $pair.Split('=', 2)[1] }
}
function Pop-MirrorSpare {
param([string]$Name)
$entry = @(-split $env:_UNSLOTH_MIRROR_SPARE | Where-Object { $_ -like "$Name|*" })
if (-not $entry) { return }
$env:_UNSLOTH_MIRROR_SPARE = @(-split $env:_UNSLOTH_MIRROR_SPARE | Where-Object { $_ -notlike "$Name|*" }) -join ' '
$pairs = @($entry[0].Split('|') | Select-Object -Skip 1)
step "mirror" "$(Get-MirrorName $Name) failed; retrying through $($pairs[0].Split('=', 2)[1])" "Yellow"
return $pairs
}
function Use-MirrorSpare {
param([string]$Name)
$pairs = @(Pop-MirrorSpare $Name)
Set-MirrorEnv $pairs
return $pairs.Count -gt 0
}
function Get-MirrorFailedHost {
param([string]$Output, [string]$Ran)
if ($Output -notmatch 'error sending request|timed out|network timeout|idle timeout|connection (reset|refused|closed|aborted)|network aborted|broken pipe|dns error|failed to lookup address|name resolution|nodename nor servname|network is unreachable|error decoding response body|end of file before message length|unexpected eof|tls handshake|sslerror|certificate verify failed|server error|service unavailable|bad gateway|gateway time-?out|too many requests|max retries exceeded|remotedisconnected|incompleteread|econnreset|etimedout|eidletimeout|eai_again|enotfound|econnrefused|socket hang up') {
if ($Output -match 'only \S+ (.* )?(is|are) available|no versions? of|not found in the package registry|could not find a version that satisfies|no matching distribution found') { 'unsynced' }
return
}
if ($Output -match 'download(-r2)?\.pytorch\.org') { 'torch' }
elseif ($Output -match 'python-build-standalone') { 'python' }
elseif ($Output -match 'registry\.npmjs\.org') { 'npm' }
elseif ($Output -match 'pypi\.org|pythonhosted\.org') { 'pypi' }
elseif ($Ran -and $Output -notmatch 'https?://') { $Ran }
}
function Exit-PathAccessDenied {
param(
[Parameter(Mandatory = $true)][AllowNull()][AllowEmptyString()][string]$Path,
[Parameter(Mandatory = $true)][AllowEmptyString()][string]$Label,
[switch]$UserSupplied,
[switch]$OwnershipUnverified
)
Exit-SetupFailure (Write-PathAccessDenied -Path $Path -Label $Label `
-UserSupplied:$UserSupplied -OwnershipUnverified:$OwnershipUnverified)
}
# Why the prebuilt update failed, for the keep message; twin of the setup.sh fail reason.
function Get-LlamaUpdateFailReason {
param([string]$Output)
if ($Output -match '(?i)429|rate limit') { return "GitHub rate limit" }
if ($Output -match '(?i)timed out|timeout|connection|resol|network|unreachable|50[234]') { return "network error" }
return "download failed"
}
# Mirrors setup.sh _installed_prebuilt_backend: backend, then llama_backend, then asset name.
function Get-PrebuiltMarkerBackend {
param([string]$Marker)
if (-not (Test-PathQuiet $Marker "Leaf")) { return "" }
try { $payload = Get-Content -LiteralPath $Marker -Raw | ConvertFrom-Json } catch { return "" }
if ($null -eq $payload -or $payload -isnot [System.Management.Automation.PSCustomObject]) { return "" }
$field = {
param($name)
if ($payload.PSObject.Properties.Name -ccontains $name -and $payload.$name -is [string]) {
$value = $payload.$name.Trim().ToLowerInvariant()
if ($value -eq "hip") { "rocm" } else { $value }
} else { "" }
}
$answer = & $field "backend"
if (-not $answer -and (& $field "llama_backend") -in @("cuda", "rocm", "vulkan", "cpu")) { $answer = & $field "llama_backend" }
if (-not $answer) {
$asset = & $field "asset"
foreach ($value in @("cuda", "rocm", "vulkan", "cpu")) {
if ($asset -like "*-$value*" -or ($value -eq "rocm" -and $asset -like "*-hip*")) { $answer = $value; break }
}
}
return $answer
}
# Backend of an installed GPU prebuilt still usable on this host, else "". Twin of setup.sh.
function Get-GpuPrebuiltToKeepOverSourceBuild {
param([string]$InstallDir)
if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1" -or $LlamaPr -or $explicitLlamaSourceBackend) { return "" }
if ($env:UNSLOTH_LLAMA_RELEASE_TAG) { return "" }
# "master" is a branch, never a release: it asks for a source build.
if ("$($env:UNSLOTH_LLAMA_TAG)".Trim() -notin @("", "latest")) { return "" }
$backend = Get-PrebuiltMarkerBackend -Marker (Join-Path $InstallDir "UNSLOTH_PREBUILT_INFO.json")
if (-not $backend) { return "" }
$nvidia = $HasNvidiaDriverEvidence -or [bool]$script:NvidiaDriverLibraryOnly
$amd = $HasROCm -or [bool]$script:ROCmGfxArch
$present = switch ($backend) {
"cuda" { $nvidia }
"rocm" { $amd }
# Any Intel adapter runs the Vulkan bundle, not only an XPU part.
"vulkan" { $nvidia -or $amd -or [bool]$script:IsIntelXpu -or (@(Get-IntelRegistryAdapterNames).Count -gt 0) }
default { $false }
}
if (-not $present) { return "" }
$prevEAP = $ErrorActionPreference
$ErrorActionPreference = "Continue"
try { $null = & python "$PSScriptRoot\install_llama_prebuilt.py" --check-installed $InstallDir 2>&1 } catch { return "" }
finally { $ErrorActionPreference = $prevEAP }
if ($LASTEXITCODE -ne 0) { return "" }
return $backend
}
function Get-InstalledLlamaPrebuiltRelease {
param([string]$InstallDir)
$metadataPath = Join-Path $InstallDir "UNSLOTH_PREBUILT_INFO.json"
if (-not (Test-PathQuiet $metadataPath)) {
return $null
}
try {
$payload = Get-Content -LiteralPath $metadataPath -Raw | ConvertFrom-Json
} catch {
return $null
}
# An interrupted write leaves an empty marker; reading a property off $null is fatal under StrictMode.
if ($null -eq $payload -or $payload -isnot [System.Management.Automation.PSCustomObject]) {
return $null
}
if (-not ($payload.PSObject.Properties.Name -ccontains 'published_repo') -or
-not ($payload.PSObject.Properties.Name -ccontains 'release_tag')) {
return $null
}
if (-not $payload.published_repo -or -not $payload.release_tag) {
return $null
}
$message = "installed release: $($payload.published_repo)@$($payload.release_tag)"
$llamaTag = ""
if ($payload.PSObject.Properties.Name -ccontains 'tag') {
$llamaTag = [string]$payload.tag
}
if ($llamaTag -and $llamaTag -ne $payload.release_tag) {
$message += " (tag $llamaTag)"
}
# Older markers lack the field (fatal under StrictMode). Keep byte-identical to the setup.sh twin.
$backendName = ""
if (($payload.PSObject.Properties.Name -ccontains 'backend') -and ($payload.backend -is [string])) {
$backendName = $payload.backend.Trim()
}
if ($backendName -match '^[A-Za-z0-9._+-]{1,32}$') {
$message += " -- $backendName backend"
}
return $message
}
function Find-Nvcc {
param([string]$MaxVersion = "")
$toolkitBase = 'C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA'
if ($MaxVersion -and (Test-Path $toolkitBase)) {
$drMajor = [int]$MaxVersion.Split('.')[0]
$cudaDirs = Get-ChildItem -Directory $toolkitBase | Where-Object {
$_.Name -match '^v(\d+)\.(\d+)'
} | Sort-Object { [version]($_.Name -replace '^v','') } -Descending
foreach ($dir in $cudaDirs) {
if ($dir.Name -match '^v(\d+)\.(\d+)') {
$tkMajor = [int]$Matches[1]
$compatible = ($tkMajor -le $drMajor)
if ($compatible) {
$nvcc = Join-Path $dir.FullName 'bin\nvcc.exe'
if (Test-Path $nvcc) {
return $nvcc
}
}
}
}
return $null
}
$cmd = Get-Command nvcc -ErrorAction SilentlyContinue
if ($cmd) { return $cmd.Source }
$cudaRoot = [Environment]::GetEnvironmentVariable('CUDA_PATH', 'Process')
if (-not $cudaRoot) { $cudaRoot = [Environment]::GetEnvironmentVariable('CUDA_PATH', 'Machine') }
if (-not $cudaRoot) { $cudaRoot = [Environment]::GetEnvironmentVariable('CUDA_PATH', 'User') }
if ($cudaRoot -and (Test-Path (Join-Path $cudaRoot 'bin\nvcc.exe'))) {
return (Join-Path $cudaRoot 'bin\nvcc.exe')
}
if (Test-Path $toolkitBase) {
$latest = Get-ChildItem -Directory $toolkitBase | Where-Object {
$_.Name -match '^v(\d+)\.(\d+)'
} | Sort-Object { [version]($_.Name -replace '^v','') } -Descending | Select-Object -First 1
if ($latest -and (Test-Path (Join-Path $latest.FullName 'bin\nvcc.exe'))) {
return (Join-Path $latest.FullName 'bin\nvcc.exe')
}
}
return $null
}
function Write-CudaDriverToolkitMismatch {
param(
[Parameter(Mandatory = $true)][string]$ToolkitVersion,
[Parameter(Mandatory = $true)][string]$DriverMaxCuda,
[string]$Color = "Yellow"
)
$toolkitMajor = $ToolkitVersion.Split('.')[0]
$driverMajor = $DriverMaxCuda.Split('.')[0]
substep "CUDA Toolkit $ToolkitVersion is a major-version mismatch: toolkit major $toolkitMajor exceeds driver CUDA major $driverMajor ($DriverMaxCuda)." $Color
substep "Update the NVIDIA GPU driver to run CUDA Toolkit $ToolkitVersion, or install a CUDA $driverMajor.x toolkit." $Color
substep "Or let Unsloth use the prebuilt CUDA bundle; it does not need the local toolkit." $Color
}
# ggml's -compress-mode=size (toolkit >= 12.8) does not load on a driver below 12.4 (#12842).
function Test-CudaDriverNeedsUncompressedFatbin {
param([string]$DriverMaxCuda)
if ($DriverMaxCuda -notmatch '^(\d+)\.(\d+)$') { return $false }
$major = [int]$Matches[1]
$minor = [int]$Matches[2]
return (($major -lt 12) -or (($major -eq 12) -and ($minor -lt 4)))
}
function Get-CudaComputeCapability {
# Not rediscovered once detection rejected nvidia-smi: a wedged binary costs a deadline per call.
$smiExe = if ($script:NvidiaSmiExe) { $script:NvidiaSmiExe } elseif ($script:NvidiaSmiRejected) { $null } else {
$cmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
if ($cmd) { $cmd.Source } else { $null }
}
$cap = $null
if ($smiExe) {
try {
$raw = Invoke-NvidiaSmiBounded $smiExe @('--query-gpu=compute_cap', '--format=csv,noheader')
if ($LASTEXITCODE -eq 0 -and $raw) { $cap = ($raw -split "`n")[0].Trim() }
} catch { }
}
if (-not $cap) {
# Without it the source build turns CUDA off; the driver library has it.
$inventory = Get-NvidiaLibraryInventory
if ($inventory) { $cap = $inventory.ComputeCaps[0] }
}
if ($cap -match '^(\d+)\.(\d+)$') { return "$($Matches[1])$($Matches[2])" }
return $null
}
# --list-gpu-code emits sm_* (CUDA 11.6+), --list-gpu-arch compute_*; $false falls back to PTX.
function Test-NvccArchSupport {
param([string]$NvccExe, [string]$Arch)
try {
$listCode = & $NvccExe --list-gpu-code 2>&1 | Out-String
if ($LASTEXITCODE -ne 0) { return $false }
return ($listCode -match "sm_$Arch")
} catch {
return $false
}
}
function Get-NvccMaxArch {
param([string]$NvccExe)
try {
$listCode = & $NvccExe --list-gpu-code 2>&1 | Out-String
if ($LASTEXITCODE -ne 0) { return $null }
$arches = @()
foreach ($line in $listCode -split "`n") {
if ($line.Trim() -match '^sm_(\d+)') {
$arches += [int]$Matches[1]
}
}
if ($arches.Count -gt 0) {
return ($arches | Sort-Object | Select-Object -Last 1).ToString()
}
} catch { }
return $null
}
# MB reserved for the OS and budgeted per compile job. Must match _LLAMA_BUILD_* in setup.sh.
$LlamaBuildReserveMb = 2048
$LlamaBuildMbPerJob = 2048
# cmake -j count. Negative $TotalMb (unreadable) keeps core count; 0 floors at 1.
# UNSLOTH_LLAMA_BUILD_JOBS wins. Pure, so tests can drive it.
function Get-LlamaJobsFor {
param([int]$Cores, [long]$TotalMb)
$override = 0
if ($env:UNSLOTH_LLAMA_BUILD_JOBS -and
[int]::TryParse($env:UNSLOTH_LLAMA_BUILD_JOBS.Trim(), [ref]$override) -and $override -ge 1) {
return $override
}
if ($Cores -lt 1) { $Cores = 4 }
if ($TotalMb -lt 0) { return $Cores }
$jobs = [int][Math]::Floor(($TotalMb - $LlamaBuildReserveMb) / $LlamaBuildMbPerJob)
if ($jobs -lt 1) { $jobs = 1 }
if ($jobs -gt $Cores) { $jobs = $Cores }
return $jobs
}
# Available (not installed) RAM in MB, -1 if unreadable. 0 is a real reading, not a failure.
function Get-UsableMemoryMb {
# -AvailableOnly: -1 rather than installed RAM when free memory cannot be read.
param([switch]$AvailableOnly)
try {
$avail = (Get-CimInstance Win32_PerfRawData_PerfOS_Memory -ErrorAction Stop).AvailableMBytes
if ($null -ne $avail) { return [long]$avail }
} catch { }
if ($AvailableOnly) { return -1 }
try {
$bytes = (Get-CimInstance Win32_ComputerSystem -ErrorAction Stop).TotalPhysicalMemory
if ($bytes -gt 0) { return [long]($bytes / 1MB) }
} catch { }
try {
# TotalVisibleMemorySize is in KB.
$kb = (Get-CimInstance Win32_OperatingSystem -ErrorAction Stop).TotalVisibleMemorySize
if ($kb -gt 0) { return [long]($kb / 1KB) }
} catch { }
return -1
}
function Get-LlamaBuildJobs {
return (Get-LlamaJobsFor -Cores ([Environment]::ProcessorCount) -TotalMb (Get-UsableMemoryMb))
}
# "cu126" when it covers every GPU, "uncovered" for an incompatible mix, else empty.
# Ignores CUDA_VISIBLE_DEVICES: the wheel must support the host. Mirrors install.sh.
function Get-NvidiaCu126Verdict {
# Floor is per-release, not fixed: only 2.11 dropped sm_70 from cu128.
param([string]$SmiExe, [int]$LegacyFloorSm = 75, [string[]]$ComputeCaps = @())
if ($ComputeCaps.Count -gt 0) {
$raw = $ComputeCaps -join "`n"
} elseif ($SmiExe) {
$raw = Invoke-NvidiaSmiBounded $SmiExe @('--query-gpu=compute_cap', '--format=csv,noheader,nounits') -StdoutOnly
if ($LASTEXITCODE -ne 0 -or -not $raw) { return '' }
} else { return '' }
$legacy = $false
$outsideCu126 = $false
$seen = $false
foreach ($line in ($raw -split "`n")) {
$value = $line.Trim()
if (-not $value) { continue }
if ($value -notmatch '^(\d+)\.(\d+)$') { return '' }
$sm = ([int]$Matches[1] * 10) + [int]$Matches[2]
if ($sm -lt $LegacyFloorSm) { $legacy = $true }
if ($sm -lt 50 -or $sm -gt 90) { $outsideCu126 = $true }
$seen = $true
}
if (-not $seen -or -not $legacy) { return '' }
if ($outsideCu126) { return 'uncovered' }
return 'cu126'
}
function Get-CudaFamilyCappedForPreTuring {
param([string]$Family, [string]$SmiExe, [string[]]$ComputeCaps = @())
if ($Family -notin @('cu128', 'cu130')) { return $Family }
# torch 2.11.0+cu128 dropped Volta, so cu128 now strands a pre-Turing host as cu130 does.
$legacyFloorSm = 75
$verdict = Get-NvidiaCu126Verdict $SmiExe $legacyFloorSm $ComputeCaps
if (-not $verdict) { return $Family }
# Runs twice per setup; announce once without polluting pipeline output.
$announce = -not $script:PreTuringCapAnnounced
$script:PreTuringCapAnnounced = $true
if ($verdict -eq 'cu126') {
if ($announce) {
substep "pre-Turing NVIDIA GPUs (sm_<75) are present -- selecting cu126, because PyTorch 2.11's $Family wheels start at sm_75" "Yellow"
}
return 'cu126'
}
if ($announce) {
substep "this host mixes pre-Turing NVIDIA GPUs with GPUs that cu126 cannot serve; no PyTorch 2.11 CUDA family covers both" "Yellow"
substep "keeping $Family, so the pre-Turing GPUs will be unusable; set UNSLOTH_TORCH_INDEX_FAMILY=cu126 to choose the other way" "Yellow"
}
return $Family
}
# Deliberately NOT in the shared region: setup.ps1 uses the venv a previous run built.
function Get-NvidiaProbePythonExe {
if ("$($env:UNSLOTH_EARLY_PYTHON_PROBE)".Trim() -eq "0") { return "" }
if (-not $VenvDir) { return "" }
foreach ($leaf in @("Scripts\python.exe", "bin/python3", "bin/python")) {
$candidate = Join-Path $VenvDir $leaf
if (-not (Test-Path -LiteralPath $candidate -PathType Leaf)) { continue }
return $candidate
}
return ""
}
function Get-StudioSystem32Tool {
param([Parameter(Mandatory = $true)][string]$Name)
if ([string]::IsNullOrWhiteSpace($env:SystemRoot)) { return "" }
$candidate = Join-Path (Join-Path $env:SystemRoot "System32") $Name
if (-not (Test-Path -LiteralPath $candidate -PathType Leaf)) { return "" }
return $candidate
}
function Test-StudioSddlRightsAreWrite {
param([string]$Rights)
if ([string]::IsNullOrWhiteSpace($Rights)) { return $true }
$text = "$Rights".Trim().ToUpper()
if ($text -like "0X*") {
$mask = [long]0
foreach ($ch in $text.Substring(2).ToCharArray()) {
$digit = "0123456789ABCDEF".IndexOf($ch)
if ($digit -lt 0) { return $true }
$mask = ($mask * 16) + $digit
}
return (($mask -band 0x500D0156) -ne 0)
}
foreach ($alias in @("GA", "GW", "WD", "WO", "SD", "DT", "FA", "FW", "KA", "KW",
"CC", "DC", "WP", "SW")) {
if ($text.Contains($alias)) { return $true }
}
return $false
}
function Test-StudioSddlPrincipalIsAdminOnly {
param([string]$Principal)
if ([string]::IsNullOrWhiteSpace($Principal)) { return $false }
$who = "$Principal".Trim().ToUpper()
return (@(
"BA", "SY", "S-1-5-32-544", "S-1-5-18",
"S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464"
) -contains $who)
}
function Test-StudioSddlWritableByNonAdmin {
param([string]$Sddl)
if ([string]::IsNullOrWhiteSpace($Sddl)) { return $true }
$text = "$Sddl".Trim()
if (-not ($text -match '^O:([A-Za-z0-9\-]+?)(?:G:|D:|S:|$)')) { return $true }
if (-not (Test-StudioSddlPrincipalIsAdminOnly -Principal $Matches[1])) { return $true }
$daclAt = $text.IndexOf("D:")
if ($daclAt -lt 0) { return $true }
$dacl = $text.Substring($daclAt)
$saclAt = $dacl.IndexOf("S:")
if ($saclAt -ge 0) { $dacl = $dacl.Substring(0, $saclAt) }
$seen = 0
foreach ($chunk in ($dacl -split '\)')) {
$open = $chunk.IndexOf("(")
if ($open -lt 0) { continue }
$seen++
$fields = $chunk.Substring($open + 1) -split ';'
if ($fields.Count -lt 6) { return $true }
$type = "$($fields[0])".Trim().ToUpper()
$flags = "$($fields[1])".Trim().ToUpper()
if (@("D", "OD", "XD") -contains $type) { continue }
if ($flags.Contains("IO")) { continue }
if (-not (Test-StudioSddlRightsAreWrite -Rights $fields[2])) { continue }
if (-not (Test-StudioSddlPrincipalIsAdminOnly -Principal $fields[5])) { return $true }
}
# A DACL with no ACEs in it is not evidence of anything, and neither is one this did not
# manage to split.
if ($seen -eq 0) { return $true }
return $false
}
function Test-StudioDirectoryIsAdminOnly {
param([string]$Path)
if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
$sddl = ""
try {
# Select-Object -ExpandProperty, not a property read: Constrained Language Mode refuses
# property access on types outside its allowed list, and the security descriptor is one.
$sddl = "$(Get-Acl -LiteralPath $Path -ErrorAction Stop |
Select-Object -ExpandProperty Sddl)"
} catch { return $false }
if ([string]::IsNullOrWhiteSpace($sddl)) { return $false }
return (-not (Test-StudioSddlWritableByNonAdmin -Sddl $sddl))
}
function Get-StudioLexicalParent {
param([string]$Path)
$trimmed = "$Path".TrimEnd('\', '/')
$cut = $trimmed.LastIndexOfAny(@([char]92, [char]47))
if ($cut -lt 0) { return "" }
return $trimmed.Substring(0, $cut)
}
function Test-StudioPathUnderAdminRoot {
param([string]$Path)
if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
# $env: rather than [Environment]::GetEnvironmentVariable: System.Environment is not on
# Constrained Language Mode's allowed type list, and this helper runs on hosts under it.
$roots = @()
foreach ($value in @($env:SystemRoot, $env:ProgramFiles, $env:ProgramW6432, ${env:ProgramFiles(x86)})) {
if (-not [string]::IsNullOrWhiteSpace($value)) { $roots += "$value".TrimEnd('\', '/') }
}
$matchedRoot = ""
foreach ($root in $roots) {
$escapedRoot = $root -replace '([\[\]\*\?])', '`$1'
if (("$Path" -like ($escapedRoot + "\*")) -or ("$Path" -like ($escapedRoot + "/*"))) {
$matchedRoot = $root
break
}
}
if ([string]::IsNullOrWhiteSpace($matchedRoot)) { return $false }
$windowsRoot = "$($env:SystemRoot)".TrimEnd('\', '/')
if (-not [string]::IsNullOrWhiteSpace($windowsRoot)) {
foreach ($leaf in @(
"Temp", "Tasks", "Tracing", "Registration\CRMLog", "debug\WIA",
"System32\Tasks", "System32\spool\drivers\color", "System32\spool\PRINTERS",
"System32\spool\SERVERS", "System32\com\dmp", "System32\FxsTmp",
"SysWOW64\Tasks", "SysWOW64\com\dmp", "SysWOW64\FxsTmp"
)) {
$writable = $windowsRoot + "\" + $leaf
$escapedWritable = $writable -replace '([\[\]\*\?])', '`$1'
if (("$Path" -like ($escapedWritable + "\*")) -or
("$Path" -like ($escapedWritable + "/*"))) { return $false }
}
}
$current = Get-StudioLexicalParent -Path "$Path"
$guard = 0
while (-not [string]::IsNullOrWhiteSpace($current)) {
$guard++
if ($guard -gt 64) { return $false }
if (-not (Test-StudioDirectoryIsAdminOnly -Path $current)) { return $false }
if ("$current".TrimEnd('\', '/') -eq $matchedRoot) { return $true }
$next = Get-StudioLexicalParent -Path "$current"
if ("$next" -eq "$current") { return $false }
$current = $next
}
return $false
}
function Invoke-StudioSystem32ToolBounded {
param([string]$Exe, [string[]]$Arguments = @(), [int]$TimeoutMs = 3000)
# CLM cannot construct ProcessStartInfo. A job captures the trusted system tool's
# output through PowerShell's pipes, without redirect files in an unlabelled directory.
if ("$($ExecutionContext.SessionState.LanguageMode)" -ne "FullLanguage") {
$job = $null
try {
$seconds = ($TimeoutMs - ($TimeoutMs % 1000)) / 1000
if (($TimeoutMs % 1000) -ne 0) { $seconds++ }
if ($seconds -lt 1) { $seconds = 1 }
$job = Start-Job -ScriptBlock {
param($tool, $toolArgs)
$lines = @(& $tool @toolArgs 2>$null)
return @{ Output = ($lines -join "`n"); ExitCode = $LASTEXITCODE }
} -ArgumentList $Exe, (,$Arguments)
if (Wait-Job -Job $job -Timeout $seconds) {
return (Receive-Job -Job $job -ErrorAction SilentlyContinue | Select-Object -Last 1)
}
Stop-Job -Job $job -ErrorAction SilentlyContinue
} catch { return $null }
finally { if ($job) { Remove-Job -Job $job -Force -ErrorAction SilentlyContinue } }
return $null
}
$proc = $null
try {
# If policy forbids these types, decline. The caller treats an unreadable
# token as elevated and uses the inline probe when no private directory is safe.
$clock = [System.Diagnostics.Stopwatch]::StartNew()
$psi = New-Object System.Diagnostics.ProcessStartInfo
$psi.FileName = $Exe
if ($null -ne $psi.PSObject.Properties['ArgumentList']) {
foreach ($arg in $Arguments) { $null = $psi.ArgumentList.Add($arg) }
} else {
# The arguments here are paths and fixed switches; paths cannot contain quotes.
$psi.Arguments = (@($Arguments | ForEach-Object {
'"' + ($_ -replace '(\\+)$', '$1$1') + '"'
}) -join ' ')
}
$psi.UseShellExecute = $false
$psi.RedirectStandardOutput = $true
$psi.RedirectStandardError = $true
$psi.CreateNoWindow = $true
$proc = [System.Diagnostics.Process]::Start($psi)
$stdout = $proc.StandardOutput.ReadToEndAsync()
$null = $proc.StandardError.ReadToEndAsync()
if (-not $proc.WaitForExit($TimeoutMs)) {
try { $proc.Kill() } catch { }
return $null
}
$left = [Math]::Max(0, $TimeoutMs - [int]$clock.ElapsedMilliseconds)
if (-not $stdout.Wait($left)) { return $null }
return @{ Output = "$($stdout.Result)"; ExitCode = $proc.ExitCode }
} catch { return $null }
finally { if ($proc) { try { $proc.Dispose() } catch { } } }
}
function Test-StudioChildScriptDirectoryElevated {
$groups = ""
$whoami = Get-StudioSystem32Tool -Name "whoami.exe"
if (-not $whoami) { return $true }
try {
$result = Invoke-StudioSystem32ToolBounded -Exe $whoami -Arguments @('/groups')
if ($null -eq $result) { return $true }
$groups = "$($result.Output)"
} catch { return $true }
if ([string]::IsNullOrWhiteSpace($groups)) { return $true }
if ($groups -match "S-1-16-(12288|16384)") { return $true }
if ($groups -match "S-1-16-\d+") { return $false }
return $true
}
function New-StudioChildScriptDirectory {
$tempRoot = if ($env:TEMP) { $env:TEMP } elseif ($env:TMPDIR) { $env:TMPDIR } else { "/tmp" }
# Join-Path throws on a TEMP naming a missing drive: decline, like any other unusable root.
try { $dir = Join-Path $tempRoot ("unsloth-child-" + [guid]::NewGuid().ToString("N")) -ErrorAction Stop } catch { return "" }
$made = $false
try {
$createdPath = "$(New-Item -ItemType Directory -Path $dir -ErrorAction Stop |
Select-Object -ExpandProperty FullName)"
$made = (Test-Path -LiteralPath $dir -PathType Container)
if ((-not $made) -and $createdPath) {
Remove-Item -LiteralPath $createdPath -Recurse -Force -ErrorAction SilentlyContinue
}
} catch { }
if ((-not $made) -and $dir -match '[\[\]]') {
$escaped = $dir -replace '([\[\]])', '`$1'
try {
$null = New-Item -ItemType Directory -Path $escaped -ErrorAction Stop
$made = (Test-Path -LiteralPath $dir -PathType Container)
} catch { }
}
# Created by THIS call. New-Item without -Force throws on a directory that already exists,
# which is the point: a pre-created one carrying an attacker's ACL is refused, not adopted.
if (-not $made) { return "" }
if ($env:OS -eq "Windows_NT") {
# Until it is labelled a standard user can swap this directory for a junction: a link is
# never adopted, and cleanup never recurses through one into its target.
$isLink = { try { "$((Get-Item -LiteralPath $dir -Force -ErrorAction Stop).Attributes)" -match 'ReparsePoint' } catch { $true } }
$labelled = $false
$icacls = Get-StudioSystem32Tool -Name "icacls.exe"
if (-not $icacls) {
if (-not (& $isLink)) { try { Remove-Item -LiteralPath $dir -Recurse -Force -ErrorAction SilentlyContinue } catch { } }
return ""
}
try {
$result = Invoke-StudioSystem32ToolBounded -Exe $icacls -Arguments @($dir, '/setintegritylevel', '(OI)(CI)H')
$labelled = ($null -ne $result -and $result.ExitCode -eq 0)
if (-not $labelled -and $null -ne $result) {
$readback = Invoke-StudioSystem32ToolBounded -Exe $icacls -Arguments @($dir)
$labelled = ($null -ne $readback -and "$($readback.Output)" -match "S-1-16-12288|High Mandatory Level")
}
} catch { $labelled = $false }
if ((-not $labelled) -and (Test-StudioChildScriptDirectoryElevated)) {
if (-not (& $isLink)) { try { Remove-Item -LiteralPath $dir -Recurse -Force -ErrorAction SilentlyContinue } catch { } }
return ""
}
if (& $isLink) { return "" }
if ($labelled) {
$planted = $true
try {
$planted = @(Get-ChildItem -LiteralPath $dir -Force -ErrorAction Stop).Count -ne 0
} catch { $planted = $true }
if ($planted) {
if (-not (& $isLink)) { try { Remove-Item -LiteralPath $dir -Recurse -Force -ErrorAction SilentlyContinue } catch { } }
return ""
}
}
}
return $dir
}
# ── BEGIN SHARED WITH install.ps1 (Get-NvidiaLibraryInventory) ──
# Full paths only: a bare name searches PATH, where ZLUDA's nvcuda.dll and nvml.dll pass for NVIDIA.
function Get-NvidiaNvmlLibraryPath {
$dirs = @()
if ($env:SystemRoot) { $dirs += (Join-Path $env:SystemRoot "System32") }
if ($env:ProgramFiles) { $dirs += (Join-Path $env:ProgramFiles "NVIDIA Corporation\NVSMI") }
foreach ($dir in $dirs) {
$candidate = Join-Path $dir "nvml.dll"
if (Test-Path -LiteralPath $candidate) { return $candidate }
}
return (Join-Path (Get-NvidiaSystem32Dir) "nvml.dll")
}
function Get-NvidiaSystem32Dir {
$root = if ($env:SystemRoot) { $env:SystemRoot } else { "C:\Windows" }
return (Join-Path $root "System32")
}
# The same inventory with nothing emitted: CPython's ctypes makes the identical NVML and CUDA
# driver calls, and the interop leaves the scanned surface rather than moving within it.
# available or the probe itself says nothing.
# Get-NvidiaProbePythonExe is deliberately per-file. The installer has its early read-only
# interpreter ladder; setup.ps1 has the venv a previous run already built.
function Read-NvidiaLibraryRawViaPython {
param([int]$TimeoutMs = 10000, [switch]$SkipNvml)
# Set only when the child is killed at the deadline, so a caller can tell a hung driver from
# an empty answer. Reset first: every early return below is an answer, not a timeout.
$script:NvidiaPythonProbeTimedOut = $false
if ("$($env:UNSLOTH_NVIDIA_PYTHON_PROBE)".Trim() -eq "0") { return "" }
$exe = ""
try { $exe = "$(Get-NvidiaProbePythonExe)" } catch { return "" }
if (-not $exe) { return "" }
$windows = ($env:OS -eq "Windows_NT")
$nvmlHint = if ($windows) { Get-NvidiaNvmlLibraryPath } else { "libnvidia-ml.so.1" }
$cudaHint = if ($windows) { Join-Path (Get-NvidiaSystem32Dir) "nvcuda.dll" } else { "libcuda.so.1" }
# Kept byte-identical with studio/nvidia_probe.py's readers by
# tests/studio/test_nvidia_python_probe_parity.ps1. Column 0 on purpose: this is Python.
$probeSource = @'
import ctypes, os, sys
def _names(kind, hint):
if os.name == "nt":
# The driver's full path only: a bare name also finds a CUDA stand-in such as ZLUDA
# beside the interpreter, and that is not an NVIDIA GPU (#11736).
return [hint] if hint and os.path.isabs(hint) else []
if kind == "nvml":
return ["libnvidia-ml.so.1", "libnvidia-ml.so"]
return ["libcuda.so.1", "libcuda.so"]
def _load(kind, hint):
for name in _names(kind, hint):
if not name:
continue
try:
return ctypes.CDLL(name)
except Exception:
continue
return None
def _unpack(packed):
return "%d;%d" % (packed // 1000, (packed % 1000) // 10)
def read_nvml(hint):
lib = _load("nvml", hint)
if lib is None:
return ""
try:
if lib.nvmlInit_v2() != 0:
return ""
except Exception:
return ""
try:
count = ctypes.c_uint(0)
if lib.nvmlDeviceGetCount_v2(ctypes.byref(count)) != 0 or count.value == 0:
return ""
packed = ctypes.c_int(0)
if lib.nvmlSystemGetCudaDriverVersion_v2(ctypes.byref(packed)) != 0 or packed.value < 1000:
return ""
# ctypes defaults every return and every pointer argument to a C int, which truncates a
# 64-bit nvmlDevice_t handle. Declare both before the first call, not after.
handle_of = lib.nvmlDeviceGetHandleByIndex_v2
handle_of.restype = ctypes.c_int
handle_of.argtypes = [ctypes.c_uint, ctypes.POINTER(ctypes.c_void_p)]
cap_of = lib.nvmlDeviceGetCudaComputeCapability
cap_of.restype = ctypes.c_int
cap_of.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_int)]
caps = []
for index in range(count.value):
device = ctypes.c_void_p()
# One unreadable GPU voids the source: a partial list misleads the pre-Turing cap.
if handle_of(index, ctypes.byref(device)) != 0:
return ""
major = ctypes.c_int(0)
minor = ctypes.c_int(0)
if cap_of(device, ctypes.byref(major), ctypes.byref(minor)) != 0:
return ""
caps.append("%d.%d" % (major.value, minor.value))
return "nvml;%s;%s" % (_unpack(packed.value), ",".join(caps))
finally:
try:
lib.nvmlShutdown()
except Exception:
pass
def read_cuda(hint):
lib = _load("cuda", hint)
if lib is None:
return ""
# The driver API honours CUDA_VISIBLE_DEVICES; the inventory must be the physical one, so a
# hidden pre-Turing card still caps the family. cuInit reads the mask once.
saved = os.environ.pop("CUDA_VISIBLE_DEVICES", None)
try:
init = lib.cuInit(0)
except Exception:
return ""
finally:
if saved is not None:
os.environ["CUDA_VISIBLE_DEVICES"] = saved
if init != 0:
return ""
count = ctypes.c_int(0)
if lib.cuDeviceGetCount(ctypes.byref(count)) != 0 or count.value == 0:
return ""
packed = ctypes.c_int(0)
if lib.cuDriverGetVersion(ctypes.byref(packed)) != 0 or packed.value < 1000:
return ""
caps = []
for index in range(count.value):
device = ctypes.c_int(0)
if lib.cuDeviceGet(ctypes.byref(device), index) != 0:
return ""
major = ctypes.c_int(0)
minor = ctypes.c_int(0)
# CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR = 75, _MINOR = 76.
if lib.cuDeviceGetAttribute(ctypes.byref(major), 75, device) != 0:
return ""
if lib.cuDeviceGetAttribute(ctypes.byref(minor), 76, device) != 0:
return ""
caps.append("%d.%d" % (major.value, minor.value))
return "cuda;%s;%s" % (_unpack(packed.value), ",".join(caps))
def main():
nvml_hint = os.environ.get("UNSLOTH_NVML_HINT", "")
cuda_hint = os.environ.get("UNSLOTH_CUDA_HINT", "")
answer = ""
# Set only for the CUDA-only retry that follows a child NVML held past its deadline.
if os.environ.get("UNSLOTH_NVIDIA_PROBE_SKIP_NVML", "") != "1":
try:
answer = read_nvml(nvml_hint)
except Exception:
answer = ""
if not answer:
try:
answer = read_cuda(cuda_hint)
except Exception:
answer = ""
sys.stdout.write(answer)
main()
'@
# Cmdlets only: Constrained Language Mode refuses New-Object ProcessStartInfo and
# [Process]::Start, and this launcher has to work there.
$probeDir = New-StudioChildScriptDirectory
$inline = (-not $probeDir)
if ($inline) {
# Elevated, a shared root lets a standard user plant or swap the redirect files: decline.
try { if (Test-StudioChildScriptDirectoryElevated) { return "" } } catch { return "" }
# The first root that takes a file: a TEMP that declined the directory may refuse this too.
$stem = $null
foreach ($root in @($env:TEMP, $env:TMP, $env:LOCALAPPDATA, $env:TMPDIR, "/tmp")) {
if (-not $root) { continue }
try {
$candidateStem = Join-Path $root ("unsloth-nvprobe-" + [guid]::NewGuid().ToString("N")) -ErrorAction Stop
$null = New-Item -ItemType File -Path "$candidateStem.out" -ErrorAction Stop; $stem = $candidateStem; break
} catch {}
}
if (-not $stem) { return "" }
} else {
$stem = Join-Path $probeDir "nvprobe"
}
$scriptFile = "$stem.py"
$outFile = "$stem.out"
$errFile = "$stem.err"
$raw = ""
try {
if (-not $inline) { Set-Content -LiteralPath $scriptFile -Value $probeSource -Encoding UTF8 -ErrorAction Stop }
# Whole seconds, rounded up, without [math]::Ceiling: CLM blocks it. PowerShell's / is
# floating point and [int] rounds to nearest, so 10000ms must not become 11s.
$seconds = ($TimeoutMs - ($TimeoutMs % 1000)) / 1000
if (($TimeoutMs % 1000) -ne 0) { $seconds = $seconds + 1 }
$seconds = [int]$seconds
if ($seconds -lt 1) { $seconds = 1 }
# Nothing with a space in it reaches the command line. Windows PowerShell 5.1 appends
# each native argument verbatim, so a script under "C:\Users\First Last\AppData\Local\
# Temp" or a hint under "C:\Program Files\NVIDIA Corporation\NVSMI" would split on its
# spaces and the child would run something else. The script arrives on stdin and the two
$savedNvml = $env:UNSLOTH_NVML_HINT
$savedCuda = $env:UNSLOTH_CUDA_HINT
$savedSkip = $env:UNSLOTH_NVIDIA_PROBE_SKIP_NVML
$savedSource = $env:UNSLOTH_NVIDIA_PROBE_SOURCE
$env:UNSLOTH_NVML_HINT = $nvmlHint
$env:UNSLOTH_CUDA_HINT = $cudaHint
# The switch reaches this child only. An inherited value must not make a first child skip NVML.
if ($SkipNvml) { $env:UNSLOTH_NVIDIA_PROBE_SKIP_NVML = "1" }
else { Remove-Item Env:UNSLOTH_NVIDIA_PROBE_SKIP_NVML -ErrorAction SilentlyContinue }
try {
if ($inline) {
$env:UNSLOTH_NVIDIA_PROBE_SOURCE = $probeSource
$proc = Start-Process -FilePath $exe -NoNewWindow -PassThru `
-ArgumentList @("-I", "-S", "-B", "-c", "exec(__import__('os').environ['UNSLOTH_NVIDIA_PROBE_SOURCE'])") `
-RedirectStandardOutput $outFile -RedirectStandardError $errFile -ErrorAction Stop
} else {
$proc = Start-Process -FilePath $exe -ArgumentList @("-I", "-S", "-B", "-") -NoNewWindow -PassThru `
-RedirectStandardInput $scriptFile -RedirectStandardOutput $outFile -RedirectStandardError $errFile -ErrorAction Stop
}
} finally {
if ($null -eq $savedSource) { Remove-Item Env:UNSLOTH_NVIDIA_PROBE_SOURCE -ErrorAction SilentlyContinue }
else { $env:UNSLOTH_NVIDIA_PROBE_SOURCE = $savedSource }
if ($null -eq $savedNvml) { Remove-Item Env:UNSLOTH_NVML_HINT -ErrorAction SilentlyContinue }
else { $env:UNSLOTH_NVML_HINT = $savedNvml }
if ($null -eq $savedCuda) { Remove-Item Env:UNSLOTH_CUDA_HINT -ErrorAction SilentlyContinue }
else { $env:UNSLOTH_CUDA_HINT = $savedCuda }
if ($null -eq $savedSkip) { Remove-Item Env:UNSLOTH_NVIDIA_PROBE_SKIP_NVML -ErrorAction SilentlyContinue }
else { $env:UNSLOTH_NVIDIA_PROBE_SKIP_NVML = $savedSkip }
}
if (-not $proc) { return "" }
# -InputObject and an error variable, never $proc.Id or $proc.HasExited. Constrained
# Language Mode permits property reads only on its allowed type list and
# System.Diagnostics.Process is not on it, so reading either one throws on exactly the
# hosts this rung exists for. Handing the object to a cmdlet keeps the access inside
# compiled code, where the language mode does not reach.
$waitError = $null
Wait-Process -InputObject $proc -Timeout $seconds -ErrorAction SilentlyContinue -ErrorVariable waitError
if ($waitError) {
$script:NvidiaPythonProbeTimedOut = $true
try { Stop-Process -InputObject $proc -Force -ErrorAction SilentlyContinue } catch { }
# Let the killed child release its redirected files before the finally deletes them.
Wait-Process -InputObject $proc -Timeout 2 -ErrorAction SilentlyContinue
return ""
}
$raw = "$(Get-Content -LiteralPath $outFile -Raw -ErrorAction SilentlyContinue)"
} catch { return "" }
finally {
# The directory, not just the three files: it is ours, nothing else may be in it, and
# leaving an empty one behind per probe would litter %TEMP% on every run.
if ($probeDir) { Remove-Item -LiteralPath $probeDir -Recurse -Force -ErrorAction SilentlyContinue }
foreach ($stale in @($scriptFile, $outFile, $errFile)) {
Remove-Item -LiteralPath $stale -Force -ErrorAction SilentlyContinue
}
}
return "$raw".Trim()
}
# "source;cudaMajor;cudaMinor;cap,cap" from NVML, else the CUDA driver API; "" when neither
function Read-NvidiaLibraryRaw {
param([int]$TimeoutMs = 30000)
# One deadline for both children, as the two in-process readers had: the first gets a whole
# bound, and only a hung NVML earns a CUDA-only child with what is left, less the 2 s kept back
# to reap the child it may have to kill. Compared by hand: CLM refuses [math].
$deadline = (Get-Date).AddMilliseconds($TimeoutMs * 2)
$raw = ""
try { $raw = Read-NvidiaLibraryRawViaPython -TimeoutMs $TimeoutMs } catch { return "" }
if (-not $script:NvidiaPythonProbeTimedOut) { return $raw }
$remainingMs = [int]($deadline - (Get-Date)).TotalMilliseconds
if ($remainingMs -lt 3000) { return "" }
$childMs = $remainingMs - 2000; if ($childMs -gt $TimeoutMs) { $childMs = $TimeoutMs }
try { return (Read-NvidiaLibraryRawViaPython -TimeoutMs $childMs -SkipNvml) } catch { return "" }
}
# NVIDIA inventory from the driver's own libraries (NVML, then the CUDA driver API), for a
# host whose nvidia-smi is absent, stale or hangs (#9255). Twin of studio/nvidia_probe.py.
# Cached. $null, or @{ Source; CudaMajor; CudaMinor; ComputeCaps ("8.9" strings); Count }.
function Get-NvidiaLibraryInventory {
param([int]$TimeoutSec = 30)
if ($script:NvidiaLibraryInventoryProbed) { return $script:NvidiaLibraryInventory }
$script:NvidiaLibraryInventoryProbed = $true
$script:NvidiaLibraryInventory = $null
if ("$($env:UNSLOTH_NVIDIA_LIBRARY_PROBE)".Trim() -eq "0") { return $null }
try { $raw = Read-NvidiaLibraryRaw -TimeoutMs ($TimeoutSec * 1000) } catch { return $null }
# The Python probe is the only library reader, so its opt-outs leave nvidia-smi as the only source.
if (-not "$raw" -and ("$($env:UNSLOTH_NVIDIA_PYTHON_PROBE)".Trim() -eq "0" -or "$($env:UNSLOTH_EARLY_PYTHON_PROBE)".Trim() -eq "0")) {
Write-StudioLine " NVIDIA driver libraries not read (Python probe disabled): a GPU without a working nvidia-smi is not detected. Set UNSLOTH_TORCH_INDEX_FAMILY=cu128 (or your CUDA wheel) to choose one." -ForegroundColor Yellow
}
$parts = "$raw".Split(";")
if ($parts.Count -ne 4 -or -not $parts[3] -or [int]$parts[1] -lt 1) { return $null }
$caps = @($parts[3].Split(","))
if (@($caps | Where-Object { $_ -notmatch '^\d+\.\d+$' }).Count -gt 0) { return $null }
$script:NvidiaLibraryInventory = @{
Source = $parts[0]
CudaMajor = [int]$parts[1]
CudaMinor = [int]$parts[2]
ComputeCaps = $caps
Count = $caps.Count
}
return $script:NvidiaLibraryInventory
}
# ── END SHARED WITH install.ps1 (Get-NvidiaLibraryInventory) ──
# Must match install.ps1's Get-TorchIndexUrl ladder exactly (asserted by a test).
# Below CUDA 11 gets "cpu".
function Get-CudaFamilyForVersion {
param([int]$Major, [int]$Minor)
if ($Major -ge 13) { return "cu130" }
elseif ($Major -eq 12 -and $Minor -ge 8) { return "cu128" }
elseif ($Major -eq 12 -and $Minor -ge 6) { return "cu126" }
elseif ($Major -ge 12) { return "cu124" }
elseif ($Major -ge 11) { return "cu118" }
return "cpu"
}
# The tag must not exceed the driver's capability: driver CUDA 12.9 -> cu128, not cu130.
function Get-PytorchCudaTag {
# Not rediscovered once detection rejected nvidia-smi (see Get-CudaComputeCapability).
$smiExe = if ($script:NvidiaSmiExe) { $script:NvidiaSmiExe } elseif ($script:NvidiaSmiRejected) { $null } else {
$cmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
if ($cmd) { $cmd.Source } else { $null }
}
$major = $null
$minor = $null
$caps = @()
if ($smiExe) {
try {
$output = Invoke-NvidiaSmiBounded $smiExe
if ($output -match 'CUDA(?: UMD)? Version:\s+(\d+)\.(\d+)') {
$major = [int]$Matches[1]
$minor = [int]$Matches[2]
}
} catch { }
}
if ($null -eq $major) {
# nvidia-smi absent or hung: ask the driver library. "" means unknown; never guess cu126.
$inventory = Get-NvidiaLibraryInventory
if (-not $inventory) { return "" }
$major = $inventory.CudaMajor
$minor = $inventory.CudaMinor
$caps = $inventory.ComputeCaps
}
$family = Get-CudaFamilyForVersion -Major $major -Minor $minor
if ($family -eq "cpu") { return "cpu" }
return (Get-CudaFamilyCappedForPreTuring $family $smiExe $caps)
}
function Trim-IndexPathSlashes {
param([string]$Url)
$value = $Url.Trim()
$idx = $value.IndexOfAny([char[]]@('?', '#'))
if ($idx -lt 0) {
return $value.TrimEnd('/')
}
return $value.Substring(0, $idx).TrimEnd('/') + $value.Substring($idx)
}
function Get-PinnedTorchIndexUrl {
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_URL)) {
return (Trim-IndexPathSlashes $env:UNSLOTH_TORCH_INDEX_URL)
}
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_FAMILY)) {
$base = if ($env:UNSLOTH_PYTORCH_MIRROR) { $env:UNSLOTH_PYTORCH_MIRROR.TrimEnd('/') } else { "https://download.pytorch.org/whl" }
return "$base/$($env:UNSLOTH_TORCH_INDEX_FAMILY.Trim().Trim('/'))"
}
return $null
}
# Query/fragment dropped first, so .../cu128?token=x classifies as cu128.
function Get-TorchIndexLeaf {
param([string]$Url)
if ([string]::IsNullOrWhiteSpace($Url)) { return $null }
$path = ($Url -split '[?#]', 2)[0]
if ([string]::IsNullOrWhiteSpace($path)) { return $null }
return ($path.TrimEnd('/') -split '/')[-1].ToLowerInvariant()
}
# Redact index-URL credentials from captured output, which echoes --index-url verbatim.
function Redact-InstallOutput {
param([string]$Text)
if (-not $Text) { return $Text }
$Text = $Text -replace '(https?://)[^/@\s`]+@', '$1<redacted>@'
$Text = $Text -replace '([?&][^=\s&`]+)=[^&#\s`]+', '$1=<redacted>'
return $Text -replace '(https?://[^\s`#]+)#[^\s`]+', '$1#<redacted>'
}
# Credential-free identity for an index URL, recorded beside the venv and compared across runs.
function Get-IndexIdentity {
param([string]$Url)
if (-not $Url) { return "" }
$Url = $Url -replace '(https?://)[^/@\s`]+@', '$1'
$Url = ($Url -split '[?#]', 2)[0]
return $Url.TrimEnd('/')
}
# _grouped_mm bug: these leaves need the torch 2.11 floor. Must match the other installers.
function Test-RocmGfx211Leaf {
param([string]$Leaf)
return @('gfx120x-all', 'gfx1151', 'gfx1150', 'gfx1152', 'gfx103x-all', 'gfx110x-all') -contains $Leaf
}
# rocm7.2 only; never floor an unknown newer rocm. Matches _ROCM_KNOWN_TORCH211_VERSIONS.
function Test-RocmKnown211Version {
param([int]$Major, [int]$Minor)
return ($Major -eq 7 -and $Minor -eq 2)
}
# A bare 'cu*' glob would match "custom"/"current" and rebuild the venv every run.
function Test-CudaFamilyLeaf {
param([string]$Leaf)
if ([string]::IsNullOrWhiteSpace($Leaf)) { return $false }
return $Leaf -match '^cu[0-9]+$'
}
# Anchored: rocm-rel-7.2.1 merely starts with rocm and is a custom pin the verbatim path owns.
function Test-PipRocmFamilyLeaf {
param([string]$Leaf)
if ([string]::IsNullOrWhiteSpace($Leaf)) { return $false }
return ($Leaf -match '^gfx[0-9]') -or ($Leaf -match '^rocm[0-9]+(\.[0-9]+)?$')
}
function Get-RocmPinStaleTags {
param([string]$PinLeaf, [string]$TorchVersion)
$_pinRocm = [regex]::Match($PinLeaf, '^rocm(\d+)\.(\d+)')
$_pinVer = if ($_pinRocm.Success) { "$($_pinRocm.Groups[1].Value).$($_pinRocm.Groups[2].Value)" } else { $null }
$_pinMajorOnly = [regex]::Match($PinLeaf, '^rocm(\d+)$') # major-only rocm<d> leaf (rocm7)
$_instRocm = [regex]::Match($TorchVersion, '\+rocm(\d+)\.(\d+)')
$_instVer = if ($_instRocm.Success) { "$($_instRocm.Groups[1].Value).$($_instRocm.Groups[2].Value)" } else { $null }
$_instPerArch = [regex]::IsMatch($TorchVersion, '\+rocm\d+\.\d+\.\d+') # per-arch three-part build
# A ROCm build MUST carry a +rocm tag; an untagged wheel can't satisfy any ROCm pin.
$_instHasRocm = [regex]::IsMatch($TorchVersion, '\+rocm')
$_instRel = [regex]::Match($TorchVersion, '^(\d+)\.(\d+)')
$_instIs211 = $false
if ($_instRel.Success) {
$_instIs211 = ([int]$_instRel.Groups[1].Value -gt 2) -or ([int]$_instRel.Groups[1].Value -eq 2 -and [int]$_instRel.Groups[2].Value -ge 11)
}
if ($PinLeaf -like 'gfx*') {
if (Test-RocmGfx211Leaf $PinLeaf) {
$installed = if ($_instIs211 -and $_instPerArch) { "rocm-perarch(torch>=2.11)" } else { "rocm-generic-or-old" }
return @{ Expected = "rocm-perarch(torch>=2.11)"; Installed = $installed }
}
# Non-2.11 gfx leaf (<2.11 spec): stale on an untagged wheel or a 2.11+ build.
$installed = if (-not $_instHasRocm) { "not-rocm" } elseif ($_instIs211) { "rocm(torch>=2.11)" } else { "rocm(torch<2.11)" }
return @{
Expected = "rocm(torch<2.11)"
Installed = $installed
}
}
if ($_pinMajorOnly.Success) {
$_pinMaj = [int]$_pinMajorOnly.Groups[1].Value
if ($_instVer) {
$_instMaj = [int]$_instRocm.Groups[1].Value
$expected = if ($_instMaj -eq $_pinMaj) { "rocm$_instVer" } else { "rocm$_pinMaj.x" }
return @{ Expected = $expected; Installed = "rocm$_instVer" }
}
# An untagged wheel never satisfies a ROCm pin; an unreadable +rocm version is accepted.
$installed = if ($_instHasRocm) { "rocm" } else { "not-rocm" }
return @{ Expected = "rocm"; Installed = $installed }
}
if ($_pinVer -and $_instVer) {
# A +rocm7.2 wheel drifted to 2.12 shares the tag but violates the spec, so fold both.
$_pinKnown211 = Test-RocmKnown211Version -Major ([int]$_pinRocm.Groups[1].Value) -Minor ([int]$_pinRocm.Groups[2].Value)
$_instOn211 = $_instRel.Success -and [int]$_instRel.Groups[1].Value -eq 2 -and [int]$_instRel.Groups[2].Value -eq 11
if ($_pinKnown211 -and -not $_instOn211) {
return @{ Expected = "rocm$_pinVer(torch2.11)"; Installed = "rocm$_instVer(torch-off-2.11)" }
}
return @{ Expected = "rocm$_pinVer"; Installed = "rocm$_instVer" }
}
$_pinNeeds211 = $false
if ($_pinRocm.Success) {
$_pinNeeds211 = Test-RocmKnown211Version -Major ([int]$_pinRocm.Groups[1].Value) -Minor ([int]$_pinRocm.Groups[2].Value)
}
$installed = if (-not $_instHasRocm) { "not-rocm" } elseif ($_instIs211) { "rocm(torch>=2.11)" } else { "rocm(torch<2.11)" }
return @{
Expected = if ($_pinNeeds211) { "rocm(torch>=2.11)" } else { "rocm(torch<2.11)" }
Installed = $installed
}
}
# Bounded python -c probe: a wedged torch import or Intel driver init would hang forever.
# Both streams drain async; .Error keeps stderr since callers decide venv fate on it. Mirrors install.ps1.
function Invoke-BoundedPythonProbe {
param([string]$PythonExe, [string]$Code, [int]$TimeoutSec = 30)
# TimedOut separates "never answered" from "answered with a failure".
$result = [pscustomobject]@{ Ok = $false; Output = ""; Error = ""; TimedOut = $false }
if (-not $PythonExe -or -not $Code) { return $result }
try {
$psi = New-Object System.Diagnostics.ProcessStartInfo
$psi.FileName = $PythonExe
# -I: the stale-venv probe runs before Enter-StudioVenv drops PYTHONPATH (#11980).
$psi.Arguments = "-I -c `"$Code`""
$psi.RedirectStandardOutput = $true
$psi.RedirectStandardError = $true
$psi.UseShellExecute = $false
$psi.CreateNoWindow = $true
$proc = [System.Diagnostics.Process]::Start($psi)
$outTask = $proc.StandardOutput.ReadToEndAsync()
$errTask = $proc.StandardError.ReadToEndAsync()
if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
try { $proc.Kill() } catch {}
# Synthesised: waiting on a wedged child's reader tasks would reintroduce the hang.
$result.Error = "python did not answer within $TimeoutSec seconds"
$result.TimedOut = $true
return $result
}
$result.Output = $outTask.GetAwaiter().GetResult()
$result.Error = $errTask.GetAwaiter().GetResult()
$result.Ok = ($proc.ExitCode -eq 0)
return $result
} catch {
$result.Error = $_.Exception.Message
return $result
}
}
# True only when an XPU torch build can drive an Intel GPU.
function Test-TorchXpuAvailable {
param([string]$PythonExe)
if (-not $PythonExe) { return $false }
# Line-anchored so a stdout banner cannot hide the answer; a timeout reads as no XPU.
$probe = Invoke-BoundedPythonProbe -PythonExe $PythonExe -Code 'import torch; print(torch.xpu.is_available())'
return ($probe.Ok -and $probe.Output -match '(?m)^\s*True\s*$')
}
# Stale only when the installed +rocm / +xpu wheel ANSWERED it sees no device; doubt keeps the venv.
function Test-NvidiaPresenceStaleGpuWheel {
param([string]$InstalledTag, [string]$PythonExe)
if (-not $script:NvidiaPresenceOnly) { return $false }
if ($InstalledTag -ne "rocm" -and $InstalledTag -ne "xpu") { return $false }
if ($null -ne $script:NvidiaPresenceStaleGpuWheel) { return $script:NvidiaPresenceStaleGpuWheel }
$code = "import torch; x = getattr(torch, 'xpu', None); " +
"print('DEV=' + str(bool(torch.cuda.is_available() or (x is not None and x.is_available()))))"
$probe = Invoke-BoundedPythonProbe -PythonExe $PythonExe -Code $code
$script:NvidiaPresenceStaleGpuWheel = [bool]($probe.Ok -and $probe.Output -match '(?m)^DEV=False\s*$')
return $script:NvidiaPresenceStaleGpuWheel
}
# On an old Intel driver the XPU wheel installs but unsloth raises at import. Warn only.
function Assert-XpuRuntimeReady {
param([string]$PythonExe)
if (Test-TorchXpuAvailable -PythonExe $PythonExe) { return $true }
substep "[WARN] PyTorch XPU is installed but torch.xpu.is_available() is False." "Yellow"
substep " The Intel GPU driver is most likely too old -- PyTorch XPU on Windows" "Yellow"
substep " needs Intel Graphics Driver 32.0.101.6739 (WHQL) or newer." "Yellow"
substep " Update the driver, then re-run. See:" "Yellow"
substep " https://unsloth.ai/docs/get-started/install/intel" "Yellow"
return $false
}
# Win32_VideoController can hang on a broken WMI repository and -OperationTimeoutSec is not
# enforced locally, so run out of process with a wall-clock kill. Mirrors install.ps1.
function Invoke-BoundedVideoControllerScan {
param([int]$TimeoutSec = 15)
# Cached even when Ok = $false: that is the hang case, and a retry would hang again.
if ($null -ne $script:VideoControllerScanResult) { return $script:VideoControllerScanResult }
$result = [pscustomobject]@{ Ok = $false; Names = @(); Adapters = @() }
$job = $null
try {
$job = Start-Job -ScriptBlock {
Get-CimInstance Win32_VideoController -ErrorAction SilentlyContinue |
Select-Object -Property Name, PNPDeviceID, ConfigManagerErrorCode, DriverVersion
}
if (Wait-Job -Job $job -Timeout $TimeoutSec) {
$rows = @(Receive-Job -Job $job -ErrorAction SilentlyContinue)
$result.Adapters = @($rows | Where-Object { $_ })
$names = @($rows | ForEach-Object { $_.Name })
$result.Names = @($names | Where-Object { $_ })
$result.Ok = ($result.Names.Count -gt 0)
} else {
Stop-Job -Job $job -ErrorAction SilentlyContinue
}
} catch {
} finally {
# -ErrorAction does not stop a terminating error, which would abort the run.
if ($job) { try { Remove-Job -Job $job -Force -ErrorAction SilentlyContinue } catch {} }
}
$script:VideoControllerScanResult = $result
return $result
}
# Registry fallback, weaker than WMI (configs outlive hardware), so only a fallback here
# where a false positive installs XPU torch. Mirrors install.ps1.
function Get-IntelRegistryAdapterNames {
$names = @()
$classKey = "HKLM:\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}"
try {
$subs = @(Get-ChildItem -LiteralPath $classKey -ErrorAction SilentlyContinue)
} catch { return @() }
foreach ($sub in $subs) {
# Guarded per subkey, not around the loop: one unreadable entry must not discard the
# adapters found after it. Matches windows_intel_gpu_in_registry()'s per-key skip.
try {
# Numeric subkeys only: "Properties" is ACL-restricted and not an adapter.
if ("$($sub.PSChildName)" -match '^\d+$') {
$props = Get-ItemProperty -LiteralPath $sub.PSPath -ErrorAction SilentlyContinue
if ($props) {
$desc = "$($props.DriverDesc)"
# Callers re-filter on "Intel", so a vendor-ID hit with a localized or
# OEM-branded DriverDesc would be found here and dropped there. Tag it
# instead; still only XPU-capable if the name says Arc / Data Center GPU.
if ("$($props.MatchingDeviceId)" -match '(?i)ven_8086') {
$names += if ($desc -match '(?i)intel') { $desc }
elseif ($desc) { "Intel $desc" }
else { "Intel Graphics" }
} elseif ($desc -match '(?i)intel') {
$names += $desc
}
}
}
} catch { }
}
return $names
}
# Read-only guess at the studio venv dir for the early Intel scan; never creates or validates.
function Get-ProbableStudioVenvDir {
$root = if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) { $env:UNSLOTH_STUDIO_HOME.Trim() }
elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) { $env:STUDIO_HOME.Trim() }
elseif (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_HOME)) { Join-Path $env:UNSLOTH_HOME.Trim() "studio" }
else { $null }
# Expand a leading ~ like the canonical resolver; without it the path stays cwd-relative.
if ($root -and ($root -eq "~" -or $root -like "~/*" -or $root -like "~\*")) {
if ([string]::IsNullOrWhiteSpace($env:USERPROFILE)) { return $null }
$rest = $root.Substring(1).TrimStart('/', '\')
$root = if ($rest) { Join-Path $env:USERPROFILE $rest } else { $env:USERPROFILE }
}
if (-not $root) {
if ([string]::IsNullOrWhiteSpace($env:USERPROFILE)) { return $null }
$root = Join-Path $env:USERPROFILE ".unsloth\studio"
}
$venv = Join-Path $root "unsloth_studio"
if (Test-Path -LiteralPath $venv -PathType Container) { return $venv }
return $null
}
# Read version.py off disk (no import). The dist-info name drops the local label.
function Test-VenvTorchIsXpu {
param([string]$VenvPath)
if (-not $VenvPath) { return $false }
try {
$verPy = Join-Path $VenvPath "Lib\site-packages\torch\version.py"
if (-not (Test-Path -LiteralPath $verPy)) { return $false }
return [bool]((Get-Content -LiteralPath $verPy -TotalCount 40 -ErrorAction Stop) -match "__version__\s*=\s*'[^']*\+xpu")
} catch { return $false }
}
# Read off disk, never imported: a faulted HIP runtime makes import fail, which wiped good venvs.
# Labels are "+rocm"; "gfx" is accepted too in case a per-arch label appears.
function Test-VenvTorchIsRocm {
param([string]$VenvPath)
if (-not $VenvPath) { return $false }
try {
$verPy = Join-Path $VenvPath "Lib\site-packages\torch\version.py"
if (-not (Test-Path -LiteralPath $verPy)) { return $false }
return [bool]((Get-Content -LiteralPath $verPy -TotalCount 40 -ErrorAction Stop) -match "__version__\s*=\s*'[^']*\+(rocm|gfx)")
} catch { return $false }
}
# A wedged display driver can hang import torch; read the CUDA family off disk instead.
function Get-VenvTorchCudaTag {
param([string]$VenvPath)
if (-not $VenvPath) { return $null }
try {
$verPy = Join-Path $VenvPath "Lib\site-packages\torch\version.py"
if (-not (Test-Path -LiteralPath $verPy)) { return $null }
$line = (Get-Content -LiteralPath $verPy -TotalCount 40 -ErrorAction Stop |
Where-Object { $_ -match "__version__\s*=\s*'[^']*\+(cu[0-9]+)" } |
Select-Object -First 1)
if (-not $line) { return $null }
$m = [regex]::Match($line, "__version__\s*=\s*'[^']*\+(cu[0-9]+)")
if ($m.Success) { return $m.Groups[1].Value.ToLowerInvariant() }
return $null
} catch { return $null }
}
function Test-VenvTorchIsCuda {
param([string]$VenvPath)
return [bool](Get-VenvTorchCudaTag -VenvPath $VenvPath)
}
# unsloth raises for XPU on torch < 2.6; 2.11 is the ceiling. Flavour and range only.
function Test-VenvTorchIsXpuSupported {
param([string]$VenvPath)
if (-not $VenvPath) { return $false }
try {
$verPy = Join-Path $VenvPath "Lib\site-packages\torch\version.py"
if (-not (Test-Path -LiteralPath $verPy)) { return $false }
$line = @(Get-Content -LiteralPath $verPy -TotalCount 40 -ErrorAction Stop |
Where-Object { $_ -match "^__version__\s*=\s*'[^']*'" })[0]
if (-not $line -or $line -notmatch "^__version__\s*=\s*'([^']*)'") { return $false }
$label = $Matches[1].ToLowerInvariant()
if ($label -notmatch '\+xpu') { return $false }
if ($label -notmatch '^(\d+)\.(\d+)\b') { return $false }
return ([int]$Matches[1] -eq 2 -and [int]$Matches[2] -ge 6 -and [int]$Matches[2] -lt 11)
} catch { return $false }
}
# Toolset tracks the VS major (18->v180, 17->v170), defaulting to v170.
function Get-VcBuildCustomizationsDir {
param(
[Parameter(Mandatory)][string]$VsInstallPath,
[string]$Generator
)
$toolset = 'v170'
if ($Generator -and ($Generator -match 'Visual Studio (\d+)\b')) {
$toolset = "v$($Matches[1])0"
}
return (Join-Path $VsInstallPath "MSBuild\Microsoft\VC\$toolset\BuildCustomizations")
}
function Get-CmakeVersion {
$raw = & cmake --version 2>$null | Select-Object -First 1
if ($raw -and ($raw -match '(\d+)\.(\d+)(?:\.(\d+))?')) {
$patch = if ($Matches[3]) { $Matches[3] } else { '0' }
return [version]"$($Matches[1]).$($Matches[2]).$patch"
}
return $null
}
# VS 18 2026 generator needs cmake >= 4.2.
function Test-CmakeSupportsGenerator {
param(
[Parameter(Mandatory)][string]$CmakeVersion,
[Parameter(Mandatory)][string]$Generator
)
if ($Generator -match 'Visual Studio 18\b') {
$clean = ($CmakeVersion -replace '[^0-9.].*$', '').TrimEnd('.')
try { $v = [version]$clean } catch { return $false }
return ($v -ge [version]'4.2')
}
return $true
}
function Test-CmakeListsGenerator {
# Probe rather than trust the version: a VS-bundled cmake can drive VS 2026 below 4.2.
param([Parameter(Mandatory)][string]$Generator)
$help = & cmake --help 2>$null | Out-String
if (-not $help) { return $false }
$haystack = ($help -replace '\s+', ' ')
$needle = ($Generator -replace '\s+', ' ')
return $haystack.Contains($needle)
}
function Test-CmakeCanDriveGenerator {
param([Parameter(Mandatory)][string]$Generator)
if (Test-CmakeListsGenerator -Generator $Generator) { return $true }
$verObj = Get-CmakeVersion
$verStr = if ($verObj) { $verObj.ToString() } else { '0.0' }
return (Test-CmakeSupportsGenerator -CmakeVersion $verStr -Generator $Generator)
}
function Add-DefaultCmakeToPath {
$cmakeDefaults = @(
"$env:ProgramFiles\CMake\bin",
"${env:ProgramFiles(x86)}\CMake\bin",
"$env:LOCALAPPDATA\CMake\bin"
)
foreach ($d in $cmakeDefaults) {
if (Test-Path (Join-Path $d "cmake.exe")) {
$env:Path = "$d;$env:Path"
Add-ToUserPath -Directory $d -Position 'Prepend' | Out-Null
return $true
}
}
return $false
}
function Get-FallbackVsGenerator {
# Newest pre-2026 VS whose generator this cmake can drive. vswhere first, for roots like D:\.
$knownEditions = @('BuildTools', 'Community', 'Professional', 'Enterprise', 'Preview')
$tryCandidate = {
param($gen, $installPath)
if (-not $installPath) { return $null }
$vcDir = Join-Path $installPath "VC\Tools\MSVC"
if (-not (Test-Path $vcDir)) { return $null }
$cl = Get-ChildItem -Path $vcDir -Filter "cl.exe" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1
if ($cl) { return @{ Generator = $gen; InstallPath = $installPath } }
return $null
}
$vsw = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
if (Test-Path $vsw) {
$json = & $vsw -all -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -format json 2>$null | Out-String
if ($json) {
try { $instances = @($json | ConvertFrom-Json) } catch { $instances = @() }
$ranked = $instances | ForEach-Object {
$label = if ($_.catalog -and $_.catalog.productLineVersion) { [string]$_.catalog.productLineVersion } else { '' }
[pscustomobject]@{ Gen = (Resolve-VsGeneratorFromLabel $label); Path = [string]$_.installationPath }
} | Where-Object { $_.Gen -and ($_.Gen -notmatch 'Visual Studio 18\b') }
$ranked = $ranked | Sort-Object { switch -regex ($_.Gen) { '17 2022' {0} '16 2019' {1} '15 2017' {2} default {9} } }
foreach ($cand in $ranked) {
if (-not (Test-CmakeListsGenerator -Generator $cand.Gen)) { continue }
$res = & $tryCandidate $cand.Gen $cand.Path
if ($res) { return $res }
}
}
}
$roots = @($env:ProgramFiles, ${env:ProgramFiles(x86)}) | Where-Object { $_ }
$older = @(
@{ Dir = '2022'; Generator = 'Visual Studio 17 2022' },
@{ Dir = '2019'; Generator = 'Visual Studio 16 2019' },
@{ Dir = '2017'; Generator = 'Visual Studio 15 2017' }
)
foreach ($entry in $older) {
if (-not (Test-CmakeListsGenerator -Generator $entry.Generator)) { continue }
foreach ($r in $roots) {
$vsBase = Join-Path $r "Microsoft Visual Studio\$($entry.Dir)"
if (-not (Test-Path $vsBase)) { continue }
foreach ($ed in $knownEditions) {
$candidate = Join-Path $vsBase $ed
if (-not (Test-Path $candidate)) { continue }
$res = & $tryCandidate $entry.Generator $candidate
if ($res) { return $res }
}
}
}
return $null
}
# productLineVersion is the year for VS <= 2022 but "18" for VS 2026.
function Resolve-VsGeneratorFromLabel {
param([string]$Label)
if (-not $Label) { return $null }
$map = @{
'2026' = 'Visual Studio 18 2026'; '18' = 'Visual Studio 18 2026'
'2022' = 'Visual Studio 17 2022'; '17' = 'Visual Studio 17 2022'
'2019' = 'Visual Studio 16 2019'; '16' = 'Visual Studio 16 2019'
'2017' = 'Visual Studio 15 2017'; '15' = 'Visual Studio 15 2017'
}
return $map[$Label.Trim()]
}
# Returns @{ Generator; InstallPath; Source } or $null.
function Find-VsBuildTools {
$vsw = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
if (Test-Path $vsw) {
$info = & $vsw -latest -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property catalog_productLineVersion 2>$null
$path = & $vsw -latest -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath 2>$null
if ($info -and $path) {
$gen = Resolve-VsGeneratorFromLabel $info
if ($gen) {
return @{ Generator = $gen; InstallPath = $path.Trim(); Source = 'vswhere' }
}
}
}
# Filesystem scan handles broken vswhere registration; VS 2026+ dir is "18".
$roots = @($env:ProgramFiles, ${env:ProgramFiles(x86)}) | Where-Object { $_ }
$knownEditions = @('BuildTools', 'Community', 'Professional', 'Enterprise', 'Preview')
$dirs = @('18', '2026', '2022', '2019', '2017')
foreach ($d in $dirs) {
$gen = Resolve-VsGeneratorFromLabel $d
if (-not $gen) { continue }
foreach ($r in $roots) {
$vsBase = Join-Path $r "Microsoft Visual Studio\$d"
if (-not (Test-Path $vsBase)) { continue }
# VS 2026 may use non-standard edition names, so scan every subdir.
if ($d -eq '18' -or $d -eq '2026') {
$editionCandidates = Get-ChildItem -Path $vsBase -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.FullName }
} else {
$editionCandidates = $knownEditions | ForEach-Object { Join-Path $vsBase $_ }
}
foreach ($candidate in $editionCandidates) {
if (-not (Test-Path $candidate)) { continue }
$vcDir = Join-Path $candidate "VC\Tools\MSVC"
if (Test-Path $vcDir) {
$cl = Get-ChildItem -Path $vcDir -Filter "cl.exe" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1
if ($cl) {
$ed = Split-Path $candidate -Leaf
return @{ Generator = $gen; InstallPath = $candidate; Source = "filesystem ($ed)"; ClExe = $cl.FullName }
}
}
}
}
}
return $null
}
# Same ceiling Resolve-CudaToolkit reads: nvidia-smi, else the driver library.
function Get-LlamaDriverMaxCuda {
$smi = ""
if ($NvidiaSmiExe -and (Get-Command Invoke-NvidiaSmiBounded -ErrorAction SilentlyContinue)) {
try { $smi = Invoke-NvidiaSmiBounded $NvidiaSmiExe } catch { }
}
if ($smi -match "CUDA(?: UMD)? Version:\s+(\d+)\.(\d+)") { return "$($Matches[1]).$($Matches[2])" }
if (Get-Command Get-NvidiaLibraryInventory -ErrorAction SilentlyContinue) {
$inv = Get-NvidiaLibraryInventory
if ($inv) { return "$($inv.CudaMajor).$($inv.CudaMinor)" }
}
return $null
}
function Get-NvccMajor {
param([string]$Nvcc)
try { if ((& $Nvcc --version 2>&1 | Out-String) -match 'release\s+(\d+)\.') { return [int]$Matches[1] } } catch { }
return $null
}
function Test-LlamaBuildToolsMissing {
if ($null -eq (Get-Command git -ErrorAction SilentlyContinue)) { return $true }
if ($null -eq (Get-Command cmake -ErrorAction SilentlyContinue)) { return $true }
# A CUDA source build installs the Toolkit (several GB) when no nvcc is found.
$nvccExe = $null
if ($HasNvidiaDriverEvidence) {
# A toolkit newer than the driver is rejected by Resolve-CudaToolkit, which then installs one.
$max = Get-LlamaDriverMaxCuda
$nvccExe = if ($max) { Find-Nvcc -MaxVersion $max } else { $null }
if (-not $nvccExe) {
$nvccExe = Find-Nvcc
$major = if ($nvccExe -and $max) { Get-NvccMajor $nvccExe } else { $null }
if ($max -and ($null -eq $major -or $major -gt [int]$max.Split('.')[0])) { $nvccExe = $null }
}
}
if ($HasNvidiaDriverEvidence -and -not $nvccExe) { return $true }
# Phase 4 upgrades a CMake too old for VS 2026 via winget.
if ($CmakeGenerator -match 'Visual Studio 18\b' -and -not (Test-CmakeCanDriveGenerator -Generator $CmakeGenerator)) { return $true }
# Resolve-CudaToolkit copies missing CUDA .targets into VS, elevating when denied.
$cudaRoot = if ($nvccExe) { Split-Path (Split-Path $nvccExe -Parent) -Parent } else { $null }
if ($cudaRoot -and $script:VsInstallPath) {
$extras = Join-Path $cudaRoot "extras\visual_studio_integration\MSBuildExtensions"
$custom = Get-VcBuildCustomizationsDir -VsInstallPath $script:VsInstallPath -Generator $CmakeGenerator
if ((Test-Path $extras) -and (Test-Path $custom) -and
-not (Get-ChildItem $custom -Filter "CUDA *.targets" -ErrorAction SilentlyContinue)) { return $true }
}
return (-not $script:VsInstallPath) -and (-not (Find-VsBuildTools))
}
function Test-SetupConsoleHeadless {
return (-not [Environment]::UserInteractive) -or [Console]::IsInputRedirected -or [Console]::IsOutputRedirected
}
# A failed prebuilt is not consent to a multi-GB toolchain. No prompt (#8040): headless runs
# outside Desktop keep installing; a terminal or Desktop opts in via UNSLOTH_INSTALL_BUILD_TOOLS.
function Test-LlamaBuildToolsInstallAllowed {
$opt = "$env:UNSLOTH_INSTALL_BUILD_TOOLS".Trim().ToLowerInvariant()
if ($opt -in @("1", "true", "yes")) { return $true }
if ($opt -in @("0", "false", "no")) { return $false }
if ((@("1", "true") -contains $env:UNSLOTH_TAURI_MODE) -or (@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE)) { return $false }
return (Test-SetupConsoleHeadless)
}
# Deferred from Phase 1 so the prebuilt path never pays for the multi-GB install.
function Ensure-BuildToolsForLlamaSourceBuild {
if ($null -eq (Get-Command cmake -ErrorAction SilentlyContinue)) {
Write-StudioLine "CMake not found -- installing via winget (needed for the llama.cpp source build)..." -ForegroundColor Yellow
if ($null -ne (Get-Command winget -ErrorAction SilentlyContinue)) {
try {
Invoke-SetupCommand { winget install Kitware.CMake --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
Refresh-Environment
} catch { }
}
# winget may install cmake without putting it on PATH yet.
if ($null -eq (Get-Command cmake -ErrorAction SilentlyContinue)) {
$cmakeDefaults = @(
"$env:ProgramFiles\CMake\bin",
"${env:ProgramFiles(x86)}\CMake\bin",
"$env:LOCALAPPDATA\CMake\bin"
)
foreach ($d in $cmakeDefaults) {
if (Test-Path (Join-Path $d "cmake.exe")) {
$env:Path = "$d;$env:Path"
Add-ToUserPath -Directory $d -Position 'Prepend' | Out-Null
break
}
}
}
if ($null -ne (Get-Command cmake -ErrorAction SilentlyContinue)) { step "cmake" "installed" }
}
if ($script:VsInstallPath) { return } # already detected by the early probe
$vsResult = Find-VsBuildTools
if (-not $vsResult) {
Write-StudioLine "Visual Studio Build Tools not found -- installing via winget..." -ForegroundColor Yellow
Write-StudioLine " (Needed only for the llama.cpp source build; may take several minutes)" -ForegroundColor Gray
if ($null -ne (Get-Command winget -ErrorAction SilentlyContinue)) {
$prevEAPTemp = $ErrorActionPreference
$ErrorActionPreference = "Continue"
winget install Microsoft.VisualStudio.2022.BuildTools --source winget --accept-package-agreements --accept-source-agreements --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --passive --wait"
$ErrorActionPreference = $prevEAPTemp
# Re-scan after install; do not trust the vswhere catalog.
$vsResult = Find-VsBuildTools
}
}
if ($vsResult) {
$script:CmakeGenerator = $vsResult.Generator
$script:VsInstallPath = $vsResult.InstallPath
step "vs" "$($vsResult.Generator) ($($vsResult.Source))"
if ($vsResult.ClExe) { substep "cl.exe: $($vsResult.ClExe)" }
} else {
Write-StudioLine "[ERROR] Visual Studio Build Tools are required for the llama.cpp source build but could not be found or installed." -ForegroundColor Red
Write-StudioLine " Manual install:" -ForegroundColor Red
Write-StudioLine ' 1. winget install Microsoft.VisualStudio.2022.BuildTools --source winget' -ForegroundColor Yellow
Write-StudioLine ' 2. Open Visual Studio Installer -> Modify -> check "Desktop development with C++"' -ForegroundColor Yellow
Exit-SetupFailure "Visual Studio Build Tools are required for the llama.cpp source build"
}
}
# PROCESSOR_ARCHITECTURE describes the process; PROCESSOR_ARCHITEW6432 is ARM64 under x64 emulation.
function Get-HostMachineArch {
$osArch = ""
try { $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() } catch { }
# Machine scope first: emulated x64 says AMD64, and must not "repair" a cu134 venv to cu130.
$machineArch = ""
try { $machineArch = [string][Environment]::GetEnvironmentVariable("PROCESSOR_ARCHITECTURE", "Machine") } catch { }
foreach ($s in @($machineArch, [string]$env:PROCESSOR_ARCHITEW6432, [string]$env:PROCESSOR_ARCHITECTURE, $osArch)) {
if ($s.ToLowerInvariant() -eq "arm64") { return "arm64" }
}
return "other"
}
# Registry first: System32\vcruntime140_1.dll is arch-blind and may be ARM64-only.
function Test-VCRedistInstalled {
foreach ($k in @(
'HKLM:\SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64',
'HKLM:\SOFTWARE\WOW6432Node\Microsoft\VisualStudio\14.0\VC\Runtimes\x64'
)) {
try {
$r = Get-ItemProperty -Path $k -ErrorAction Stop
if ($r.Installed -eq 1 -and [int]$r.Major -ge 14 -and [int]$r.Minor -ge 20) { return $true }
} catch { }
}
if ((Get-HostMachineArch) -eq "arm64") { return $false }
$sys = $env:SystemRoot
if ($sys -and (Test-Path (Join-Path $sys 'System32\vcruntime140_1.dll'))) { return $true }
return $false
}
# Installs the VC++ runtime if missing (non-fatal): torch cannot import without it.
function Ensure-VCRedist {
if (Test-VCRedistInstalled) { step "vcredist" "present"; return }
if ($StageRoot) { step "vcredist" "missing; unchanged during staging" "Yellow"; return }
# The first pass already tried; the installer prompts for UAC.
if ($env:UNSLOTH_SETUP_RERUN -eq '1') {
step "vcredist" "missing; already tried earlier in this update" "Yellow"
substep "https://aka.ms/vs/17/release/vc_redist.x64.exe" "Yellow"
return
}
Write-StudioLine "Microsoft Visual C++ Redistributable (2015-2022) is missing; the prebuilt llama.cpp and PyTorch need it. Installing the runtime..." -ForegroundColor Yellow
if ($null -ne (Get-Command winget -ErrorAction SilentlyContinue)) {
try {
Invoke-SetupCommand { winget install --id Microsoft.VCRedist.2015+.x64 --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
Refresh-Environment
} catch { substep "VCRedist install failed: $($_.Exception.Message)" "Yellow" }
}
if (-not (Test-VCRedistInstalled)) {
# Always the x64 package: it is the Arm64X superset Microsoft recommends for ARM64 too.
$url = "https://aka.ms/vs/17/release/vc_redist.x64.exe"
$dst = Join-Path ([System.IO.Path]::GetTempPath()) "vc_redist.x64.exe"
substep "winget unavailable or failed; downloading the runtime directly..."
# Old 5.1 images may default to pre-TLS 1.2 protocols, which aka.ms refuses.
$_prevProtocol = $null
try {
$_cur = [System.Net.ServicePointManager]::SecurityProtocol
if ([int]$_cur -ne 0 -and ([int]$_cur -band [int][System.Net.SecurityProtocolType]::Tls12) -eq 0) {
[System.Net.ServicePointManager]::SecurityProtocol = $_cur -bor [System.Net.SecurityProtocolType]::Tls12
$_prevProtocol = $_cur
}
} catch { $_prevProtocol = $null }
try {
Invoke-WebRequest -Uri $url -OutFile $dst -UseBasicParsing -TimeoutSec 300
# Evergreen URL rules out a SHA-256 pin, so verify the publisher, not just Status.
$sig = Get-AuthenticodeSignature -LiteralPath $dst
if ($sig.Status -ne [System.Management.Automation.SignatureStatus]::Valid -or
$null -eq $sig.SignerCertificate -or
$sig.SignerCertificate.Subject -notmatch '(^|,\s*)O="?Microsoft Corporation"?(,|$)') {
throw "the downloaded VC++ runtime is not validly signed by Microsoft (signature status: $($sig.Status))"
}
$p = Start-Process -FilePath $dst -ArgumentList '/quiet', '/norestart' -Wait -PassThru
# 3010 = success, reboot required.
if ($p.ExitCode -notin @(0, 3010)) {
substep "VC++ runtime installer exited $($p.ExitCode)" "Yellow"
}
Refresh-Environment
} catch {
substep "Direct VC++ runtime download failed: $($_.Exception.Message)" "Yellow"
} finally {
if ($null -ne $_prevProtocol) {
try { [System.Net.ServicePointManager]::SecurityProtocol = $_prevProtocol } catch { }
}
Remove-Item -LiteralPath $dst -Force -ErrorAction SilentlyContinue
}
}
if (Test-VCRedistInstalled) { step "vcredist" "installed" }
else {
substep "Could not install the VC++ Redistributable automatically." "Yellow"
substep "If llama-server or torch reports a missing VCRUNTIME140.dll, install:" "Yellow"
substep "https://aka.ms/vs/17/release/vc_redist.x64.exe" "Yellow"
}
}
# ─────────────────────────────────────────────
# ─────────────────────────────────────────────
$Rule = [string]::new([char]0x2500, 52)
function Enable-StudioVirtualTerminal {
if ($env:NO_COLOR) { return $false }
# A redirected stdout is not a console.
if ($script:StudioStdoutRedirected) { return $false }
# The host already enables VT at startup and verifies it; see PR #10984 and
# tests/studio/test_installer_av_shapes.py (AV_SHAPES_RECORD). try/catch for caller StrictMode.
try { return [bool]$Host.UI.SupportsVirtualTerminal } catch { return $false }
}
$script:StudioVtOk = Enable-StudioVirtualTerminal
function Get-StudioAnsi {
param(
[Parameter(Mandatory = $true)]
[ValidateSet('Title', 'Dim', 'Ok', 'Warn', 'Err', 'Reset')]
[string]$Kind
)
$e = [char]27
switch ($Kind) {
'Title' { return "${e}[38;5;150m" }
'Dim' { return "${e}[38;5;245m" }
'Ok' { return "${e}[38;5;108m" }
'Warn' { return "${e}[38;5;136m" }
'Err' { return "${e}[91m" }
'Reset' { return "${e}[0m" }
}
}
function Write-SetupVerboseDetail {
param(
[Parameter(Mandatory = $true)][string]$Message,
[string]$Color = "Gray"
)
if (-not $script:UnslothVerbose) { return }
if ($script:StudioVtOk -and -not $env:NO_COLOR) {
$ansi = switch ($Color) {
'Green' { (Get-StudioAnsi Ok) }
'Gray' { (Get-StudioAnsi Dim) }
'DarkGray' { (Get-StudioAnsi Dim) }
'Yellow' { (Get-StudioAnsi Warn) }
'Cyan' { (Get-StudioAnsi Title) }
'Red' { (Get-StudioAnsi Err) }
default { (Get-StudioAnsi Dim) }
}
Write-StudioLine ($ansi + $Message + (Get-StudioAnsi Reset))
} else {
$fc = switch ($Color) {
'Green' { 'DarkGreen' }
'Gray' { 'DarkGray' }
'Cyan' { 'Green' }
default { $Color }
}
Write-StudioLine $Message -ForegroundColor $fc
}
}
function Invoke-SetupCommand {
param(
[Parameter(Mandatory = $true)][scriptblock]$Command,
[switch]$AlwaysQuiet
)
$prevEap = $ErrorActionPreference
$ErrorActionPreference = "Continue"
try {
$global:LASTEXITCODE = 0
if ($script:UnslothVerbose -and -not $AlwaysQuiet) {
# PS 5.1 turns stderr records into $? = $false even on exit 0; redact per record.
if ($env:_UNSLOTH_MIRROR_SPARE) {
$lines = @()
& $Command 2>&1 | ForEach-Object { "$_" } | Tee-Object -Variable lines | ForEach-Object { Redact-InstallOutput $_ } | Out-Host
$script:SetupCommandOutput = $lines -join "`n"
} else {
& $Command 2>&1 | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$script:SetupCommandOutput = ''
}
} else {
$output = & $Command 2>&1 | Out-String
$script:SetupCommandOutput = $output
if ($LASTEXITCODE -ne 0) {
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Red
}
}
return [int]$LASTEXITCODE
} finally {
$ErrorActionPreference = $prevEap
}
}
function Write-LlamaFailureLog {
param(
[string]$Output,
[int]$MaxLines = 120
)
if (-not $Output) { return }
$lines = @(
($Output -split "`r?`n") | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }
)
if ($lines.Count -eq 0) { return }
if ($lines.Count -gt $MaxLines) {
Write-StudioLine " Showing last $MaxLines lines:" -ForegroundColor DarkGray
$lines = $lines | Select-Object -Last $MaxLines
}
foreach ($line in $lines) {
Write-StudioLine " | $line" -ForegroundColor DarkGray
}
}
# Plain step/substep text on the OS stdout handle. When redirected this is the ONLY sink:
# the CLI runs us with *>&1, so also calling Write-Host printed every step twice.
function Write-StudioStdoutMirror {
param([Parameter(Mandatory = $true)][string]$Line)
try {
if ($script:StudioStdoutRedirected) {
[Console]::Out.WriteLine($Line)
[Console]::Out.Flush()
}
} catch {}
}
function step {
param(
[Parameter(Mandatory = $true)][string]$Label,
[Parameter(Mandatory = $true)][string]$Value,
[string]$Color = "Green"
)
$padded = if ($Label.Length -ge 15) { $Label.Substring(0, 15) } else { $Label.PadRight(15) }
if ($script:StudioStdoutRedirected) {
Write-StudioStdoutMirror (" {0}{1}" -f $padded, $Value)
return
}
if ($script:StudioVtOk -and -not $env:NO_COLOR) {
$dim = Get-StudioAnsi Dim
$rst = Get-StudioAnsi Reset
$val = switch ($Color) {
'Green' { Get-StudioAnsi Ok }
'Yellow' { Get-StudioAnsi Warn }
'Red' { Get-StudioAnsi Err }
'DarkGray' { Get-StudioAnsi Dim }
default { Get-StudioAnsi Ok }
}
Write-Host (" {0}{1}{2}{3}{4}{2}" -f $dim, $padded, $rst, $val, $Value)
} else {
$fc = switch ($Color) {
'Green' { 'DarkGreen' }
'Yellow' { 'Yellow' }
'Red' { 'Red' }
'DarkGray' { 'DarkGray' }
default { 'DarkGreen' }
}
# One record: two Write-Host calls become two lines for a redirected consumer.
Write-Host (" {0}{1}" -f $padded, $Value) -ForegroundColor $fc
}
}
function substep {
param(
[Parameter(Mandatory = $true)][string]$Message,
[string]$Color = "DarkGray"
)
if ($script:StudioStdoutRedirected) {
Write-StudioStdoutMirror (" {0,-15}{1}" -f "", $Message)
return
}
if ($script:StudioVtOk -and -not $env:NO_COLOR) {
$msgCol = switch ($Color) {
'Yellow' { (Get-StudioAnsi Warn) }
default { (Get-StudioAnsi Dim) }
}
$pad = "".PadRight(15)
Write-Host (" {0}{1}{2}{3}" -f $msgCol, $pad, $Message, (Get-StudioAnsi Reset))
} else {
$fc = switch ($Color) {
'Yellow' { 'Yellow' }
default { 'DarkGray' }
}
Write-Host (" {0,-15}{1}" -f "", $Message) -ForegroundColor $fc
}
}
# Match npm's error code line only (cleanup warnings carry EPERM too); runs before the network check.
$script:NpmLocalFailureRe = 'npm (error|ERR!) code (EACCES|EPERM|EBUSY|ENOSPC|ENFILE|EMFILE)|operation was rejected by your operating system'
# Keep in sync with _suggest_npm_registry in studio/setup.sh.
$script:NpmNetworkFailureRe = '40[13]|ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ConnectionRefused|failed to resolve|registry\.npmjs\.org|getaddrinfo|tunneling socket|network|proxy|self.?signed|unable to (get|verify)'
function Show-NpmLocalFailureHint {
# -Socket: FetchError with no path line means the OS refused node.exe's socket.
param([switch]$Socket)
Write-StudioLine ""
if ($Socket) {
$nodePath = try { (Get-Command node -ErrorAction Stop).Source } catch { "node.exe" }
step "frontend" "the OS refused node's connection to the npm registry" "Yellow"
substep "Allow $nodePath in your firewall/antivirus, or use another Node install."
return
}
step "frontend" "npm hit a local file error (permission, lock or disk full)" "Yellow"
substep "Try: npm cache clean --force, or exclude the npm cache from your antivirus."
}
function Invoke-NpmMirrorRetry {
if (-not $env:_UNSLOTH_MIRROR_SPARE) { return $false }
if ((Get-MirrorFailedHost -Output $script:SetupCommandOutput -Ran npm) -ne 'npm') { return $false }
$pairs = @(Pop-MirrorSpare npm)
if (-not $pairs) { return $false }
$registry = $pairs[0].Split('=', 2)[1]
$verb = if (Test-Path "package-lock.json") { "ci" } else { "install" }
if ((Invoke-SetupCommand { npm $verb --registry $registry }) -ne 0) { return $false }
Set-MirrorEnv $pairs
$script:NpmRegistryArgs = @('--registry', $registry)
return $true
}
# install-stamp.mjs check/write; any doubt returns $false so setup runs `npm ci`.
function Invoke-OxcInstallStamp {
param([Parameter(Mandatory = $true)][ValidateSet("check", "write")][string]$Mode)
$helper = Join-Path $OxcValidatorDir "install-stamp.mjs"
if (-not (Test-Path -LiteralPath $helper -PathType Leaf)) { return $false }
# Resolved first: a lookup failure must never read an earlier command's exit code as a pass.
$node = Get-Command node -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
if (-not $node) { return $false }
try {
$global:LASTEXITCODE = 1
& $node.Source $helper $Mode *> $null
return ($LASTEXITCODE -eq 0)
} catch { return $false }
}
function Show-NpmRegistryHint {
param([string]$FailureOutput = "")
if ($FailureOutput) {
$FailureOutput = $FailureOutput -replace "$([char]27)\[[0-9;]*m", ''
if ($FailureOutput -cmatch $script:NpmLocalFailureRe) { Show-NpmLocalFailureHint -Socket:($FailureOutput -cmatch 'FetchError' -and $FailureOutput -cnotmatch 'npm (error|ERR!) path '); return }
if ($FailureOutput -inotmatch $script:NpmNetworkFailureRe) { return }
}
if ($env:UNSLOTH_NPM_REGISTRY) { return }
$mirror = $env:NPM_CONFIG_REGISTRY
if (-not $mirror) {
# Read npm config outside the project so the frontend's pinned registry= does not mask the user's.
$pushed = $false
try {
Push-Location ([System.IO.Path]::GetTempPath()) -ErrorAction Stop
$pushed = $true
$mirror = (& npm config get registry 2>$null | Out-String).Trim()
} catch { $mirror = "" } finally { if ($pushed) { Pop-Location } }
}
if ($mirror -in @("", "undefined", "null", "https://registry.npmjs.org", "https://registry.npmjs.org/")) {
$mirror = ""
}
Write-StudioLine ""
step "frontend" "registry.npmjs.org looks blocked (corporate firewall/proxy?)" "Yellow"
if ($mirror) {
substep "Unsloth pins the public npm registry; your mirror is being ignored."
substep "Detected a registry in your npm config:"
substep " $mirror"
substep "Re-run pointing Unsloth at it:"
substep " `$env:UNSLOTH_NPM_REGISTRY='$mirror'; .\install.ps1 --local"
} else {
substep "If you use a private mirror/proxy, point Unsloth at it and re-run:"
substep " `$env:UNSLOTH_NPM_REGISTRY='https://your-mirror.example/api/npm/'; .\install.ps1 --local"
}
substep "(min-release-age and save-exact stay enforced.)"
}
# ─────────────────────────────────────────────
# Banner
# ─────────────────────────────────────────────
Write-StudioLine ""
if ($script:StudioVtOk -and -not $env:NO_COLOR) {
Write-StudioLine (" " + (Get-StudioAnsi Title) + [char]::ConvertFromUtf32(0x1F9A5) + " Unsloth Studio Setup" + (Get-StudioAnsi Reset))
Write-StudioLine (" {0}{1}{2}" -f (Get-StudioAnsi Dim), $Rule, (Get-StudioAnsi Reset))
} else {
Write-StudioLine (" " + [char]::ConvertFromUtf32(0x1F9A5) + " Unsloth Studio Setup") -ForegroundColor Green
Write-StudioLine " $Rule" -ForegroundColor DarkGray
}
# Clear WebView2 caches (cache only) so the old frontend is not served after an update.
# Called only after the home override is validated.
function Clear-WebViewCaches {
if (-not $env:LOCALAPPDATA) { return }
$wvDefault = Join-Path $env:LOCALAPPDATA "ai.unsloth.studio\EBWebView\Default"
# Drop the version stamp first so the app retries the clear on next launch if removals fail.
Remove-Item -LiteralPath (Join-Path $env:LOCALAPPDATA "ai.unsloth.studio\.webview-cache-cleared") `
-Force -ErrorAction SilentlyContinue
$wvCleared = $false
foreach ($wvSub in @("Cache", "Code Cache", "GPUCache", "Service Worker")) {
$wvPath = Join-Path $wvDefault $wvSub
# Get-Item -Force, not Test-Path: Test-Path throws on ACL denial and reparse points must be unlinked.
$wvItem = Get-Item -LiteralPath $wvPath -Force -ErrorAction SilentlyContinue
if (-not $wvItem) { continue }
try {
if ($wvItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint) { $wvItem.Delete() }
else { Remove-Item -LiteralPath $wvPath -Recurse -Force -ErrorAction Stop }
$wvCleared = $true
} catch { }
}
if ($wvCleared) { substep "cleared stale WebView caches (ai.unsloth.studio); settings and data kept" }
}
# Elevation report; install.ps1 (SKIP_STUDIO_BASE=1) already printed it. Keep in step with its copies.
if ($env:SKIP_STUDIO_BASE -ne "1") {
$ElevationState = "unknown"
try {
$_identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
$_principal = New-Object System.Security.Principal.WindowsPrincipal($_identity)
$ElevationState = if ($_principal.IsInRole(
[System.Security.Principal.WindowsBuiltInRole]::Administrator)) { "true" } else { "false" }
} catch { }
if ($env:UNSLOTH_SETUP_RERUN -ne '1' -and ((@("1", "true") -contains $env:UNSLOTH_TAURI_MODE) -or
(@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE))) {
[Console]::Out.WriteLine("[TAURI:DIAG] elevated=$ElevationState")
[Console]::Out.Flush()
}
function Get-CanonicalRootPath {
param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$Path)
if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
$_p = $Path.Trim()
if (($_p -eq "~" -or $_p -like "~/*" -or $_p -like "~\*") -and
-not [string]::IsNullOrWhiteSpace($env:USERPROFILE)) {
# A bare "~" leaves an empty child path, which Join-Path rejects on PS 5.1.
$_rest = $_p.Substring(1).TrimStart('/', '\')
$_p = if ($_rest) { Join-Path $env:USERPROFILE $_rest } else { $env:USERPROFILE }
}
# GetFullPath anchors a relative path to [Environment]::CurrentDirectory, which
# Set-Location does not move, so it disagreed with the Resolve-Path based resolver
# (PowerShell#10278, by design). It stays as the fallback, never the first answer.
try {
$_p = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($_p)
} catch {
try { $_p = [System.IO.Path]::GetFullPath($_p) } catch { }
}
return $_p.TrimEnd('\', '/')
}
if ($ElevationState -eq "true") {
# USERPROFILE can be unset (service, CI), where a bare Join-Path throws under Stop.
$_unslothRoot = if ([string]::IsNullOrWhiteSpace($env:USERPROFILE)) {
'%USERPROFILE%\.unsloth'
} else {
Join-Path $env:USERPROFILE ".unsloth"
}
$_elevRoot = if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) {
$env:UNSLOTH_STUDIO_HOME.Trim()
} elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) {
$env:STUDIO_HOME.Trim()
} elseif (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_HOME)) {
$env:UNSLOTH_HOME.Trim()
} else {
$_unslothRoot
}
if ((Get-CanonicalRootPath $_elevRoot) -ieq
(Get-CanonicalRootPath (Join-Path $_unslothRoot "studio"))) {
$_elevRoot = $_unslothRoot
}
Write-StudioLine ""
Write-StudioLine " [WARNING] Running as administrator. Unsloth does not need this." -ForegroundColor Yellow
Write-StudioLine " Anything written to $_elevRoot will be owned by Administrators," -ForegroundColor Yellow
Write-StudioLine " and your normal account will not be able to read it afterwards." -ForegroundColor Yellow
Write-StudioLine " That folder outlives an uninstall, so a later install, setup or" -ForegroundColor Yellow
Write-StudioLine " update run normally fails on it." -ForegroundColor Yellow
Write-StudioLine " Stop and start again without 'Run as administrator'." -ForegroundColor Yellow
}
}
# Everything joins onto USERPROFILE; null/empty must fail here (whitespace is accepted).
if ([string]::IsNullOrEmpty($env:USERPROFILE)) {
Write-StudioLine "ERROR: USERPROFILE is not set." -ForegroundColor Red
Exit-SetupFailure "USERPROFILE is not set"
}
$_studioOverrideVar = $null
$_studioOverride = $null
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) {
$_studioOverrideVar = "UNSLOTH_STUDIO_HOME"
$_studioOverride = $env:UNSLOTH_STUDIO_HOME.Trim()
} elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) {
$_studioOverrideVar = "STUDIO_HOME"
$_studioOverride = $env:STUDIO_HOME.Trim()
} elseif (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_HOME)) {
$_studioOverrideVar = "UNSLOTH_HOME (studio child)"
$_studioOverride = Join-Path $env:UNSLOTH_HOME.Trim() "studio"
}
if ($_studioOverride) {
if ($_studioOverride -eq "~" -or $_studioOverride -like "~/*" -or $_studioOverride -like "~\*") {
$_studioOverride = (Join-Path $env:USERPROFILE $_studioOverride.Substring(1).TrimStart('/','\'))
}
if (Test-Path -LiteralPath $_studioOverride -PathType Container) {
$StudioHome = (Resolve-Path -LiteralPath $_studioOverride).Path
# Mirror setup.sh and install.ps1: fail before install work if it is read-only.
$_setupWriteProbe = Join-Path $StudioHome (".unsloth-write-probe-" + [guid]::NewGuid())
try {
[System.IO.File]::WriteAllText($_setupWriteProbe, "")
Remove-Item -LiteralPath $_setupWriteProbe -Force -ErrorAction SilentlyContinue
} catch {
Write-StudioLine "ERROR: $_studioOverrideVar=$StudioHome is not writable." -ForegroundColor Red
Exit-SetupFailure "$_studioOverrideVar=$StudioHome is not writable"
}
} else {
Write-StudioLine "ERROR: $_studioOverrideVar=$_studioOverride does not exist." -ForegroundColor Red
Write-StudioLine " Run install.ps1 to create the install root before 'unsloth studio update'." -ForegroundColor Red
Exit-SetupFailure "$_studioOverrideVar=$_studioOverride does not exist"
}
} else {
$StudioHome = Join-Path $env:USERPROFILE ".unsloth\studio"
}
$StageRoot = if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_STAGE_ROOT)) { $env:UNSLOTH_STUDIO_STAGE_ROOT.Trim() } else { $null }
$RuntimeRoot = if ($StageRoot) { $StageRoot } else { $StudioHome }
$VenvDir = Join-Path $RuntimeRoot "unsloth_studio"
$StudioOwnedMarker = ".unsloth-studio-owned"
# Marks venvs this script moved aside, so the sweep never deletes a lookalike.
$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"
$StudioHomeIsCustom = Test-StudioHomeIsCustom
# Mirrors setup.sh: runtime-root ownership is separate from the Studio home flag.
$RuntimeRootIsCustom = $StudioHomeIsCustom
# Keyed on where runtimes LAND, as setup.sh does. A staged update lands in $StageRoot, so it is excluded.
$_masterRootForOwnership = Get-MasterRootOverride
if ($_masterRootForOwnership -and -not $StageRoot) {
# Canonicalised like Get-MasterRootOverride, compared case-insensitively.
$_legacyRuntimeRoot = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth")
$RuntimeRootIsCustom = ($_masterRootForOwnership -ine $_legacyRuntimeRoot)
}
$LlamaCppDir = Get-ManagedLlamaCppDir -StagingRoot $StageRoot
$UnslothHome = Split-Path -Parent $LlamaCppDir
# Record the master root inside the Studio tree, for the uninstaller: UNSLOTH_HOME can be set
# for a single command, and without the note a later uninstall removed the Studio tree and
# stranded multi-gigabyte runtimes beside it.
#
# Only for a master root (the other branches derive the root from paths the uninstaller already
# knows), and only when a reader will honour it. setup.sh's _master_root_note_is_honoured holds
# the same two rules for the same reasons; keep them together.
function Test-MasterRootNoteIsHonoured {
param([string]$Root, [string]$StudioRoot)
$norm = Get-CanonicalDir -Path $Root
if (-not $norm) { return $false }
$here = Get-CanonicalDir -Path $StudioRoot
if (-not $here) { return $false }
# Never record the legacy default root: readers would then treat every launch as portable.
$legacy = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth")
if ($legacy -and ($norm -ieq $legacy)) { return $false }
# Readers ignore any note inside the legacy Studio tree, so do not write one there.
$legacyStudio = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth\studio")
if ($legacyStudio -and ($here -ieq $legacyStudio)) {
Write-StudioLine " note: the managed runtimes were installed under $norm, but Unsloth Studio is the" -ForegroundColor Yellow
Write-StudioLine " default install at $here, where no reader honours a recorded root." -ForegroundColor Yellow
Write-StudioLine " That root cannot be recorded, so a later launch or uninstall will" -ForegroundColor Yellow
Write-StudioLine " not find them. Set UNSLOTH_STUDIO_HOME to $norm\studio, or re-set" -ForegroundColor Yellow
Write-StudioLine " UNSLOTH_HOME whenever you run Unsloth." -ForegroundColor Yellow
return $false
}
# A note must describe the tree it is written into: every reader requires the Studio
# directory to lie INSIDE the root it names, so a tree copied between master roots cannot aim
# a removal at the original install. A split layout, with the runtimes under the master root
# and Studio outside it, is that shape: say so, rather than leave a note no reader honours.
$sep = [System.IO.Path]::DirectorySeparatorChar
if (($here -ieq $norm) -or $here.StartsWith($norm + $sep, [System.StringComparison]::OrdinalIgnoreCase)) {
return $true
}
Write-StudioLine " note: the managed runtimes were installed under $norm, but Unsloth Studio lives at" -ForegroundColor Yellow
Write-StudioLine " $here, which is outside it. That root cannot be recorded, so a later" -ForegroundColor Yellow
Write-StudioLine " launch or uninstall will not find them. Set UNSLOTH_STUDIO_HOME to" -ForegroundColor Yellow
Write-StudioLine " $norm\studio, or re-set UNSLOTH_HOME whenever you run Unsloth." -ForegroundColor Yellow
return $false
}
if ((Get-MasterRootOverride) -and -not $StageRoot -and
(Test-MasterRootNoteIsHonoured -Root $UnslothHome -StudioRoot $StudioHome)) {
try {
$noteDir = Join-Path $StudioHome "share"
if (-not (Test-Path -LiteralPath $noteDir -PathType Container)) {
[void][System.IO.Directory]::CreateDirectory($noteDir)
}
# Staged then renamed: this note licenses deletions, so it must never be half-written.
$notePath = Join-Path $noteDir ".unsloth-master-root"
$noteBytes = [System.Text.Encoding]::UTF8.GetBytes($UnslothHome + [Environment]::NewLine)
# Move-Item -Force is not atomic, so skip rewriting identical bytes.
$noteCurrent = $null
try {
if (Test-Path -LiteralPath $notePath -PathType Leaf) {
$noteCurrent = [System.IO.File]::ReadAllBytes($notePath)
}
} catch { $noteCurrent = $null }
$noteSame = $false
if ($null -ne $noteCurrent -and $noteCurrent.Length -eq $noteBytes.Length) {
$noteSame = $true
for ($i = 0; $i -lt $noteBytes.Length; $i++) {
if ($noteCurrent[$i] -ne $noteBytes[$i]) { $noteSame = $false; break }
}
}
if (-not $noteSame) {
# Random name opened CreateNew: a predictable temp name could be precreated as a link.
$noteTmp = Join-Path $noteDir (".unsloth-master-root." + [System.IO.Path]::GetRandomFileName())
try {
$noteStream = [System.IO.File]::Open(
$noteTmp,
[System.IO.FileMode]::CreateNew,
[System.IO.FileAccess]::Write,
[System.IO.FileShare]::None
)
try {
$noteStream.Write($noteBytes, 0, $noteBytes.Length)
} finally {
$noteStream.Dispose()
}
# [IO.File]::Move with overwrite is .NET Core only; 5.1 lacks it.
Move-Item -LiteralPath $noteTmp -Destination $notePath -Force
$noteTmp = $null
} finally {
if ($noteTmp) { Remove-Item -LiteralPath $noteTmp -Force -ErrorAction SilentlyContinue }
}
}
} catch {
Write-StudioLine " note: could not record the master root for uninstall: $($_.Exception.Message)" -ForegroundColor DarkGray
}
}
# Clear a stale note naming the legacy root; both uninstallers already refuse that value.
try {
$staleNote = Join-Path (Join-Path $StudioHome "share") ".unsloth-master-root"
if (Test-Path -LiteralPath $staleNote -PathType Leaf) {
# -Encoding UTF8: 5.1 decodes BOM-less input as ANSI.
$staleValue = (Get-Content -LiteralPath $staleNote -TotalCount 1 -Encoding UTF8 -ErrorAction Stop)
if ($staleValue) { $staleValue = $staleValue.Trim() }
if ($staleValue) {
if ($staleValue -eq "~") { $staleValue = $env:USERPROFILE }
elseif ($staleValue -like "~/*" -or $staleValue -like "~\*") {
$staleValue = (Join-Path $env:USERPROFILE $staleValue.Substring(1).TrimStart('/', '\'))
}
$staleNorm = Get-CanonicalDir -Path $staleValue
$legacyNorm = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth")
if ($staleNorm -and $legacyNorm -and ($staleNorm -ieq $legacyNorm)) {
Remove-Item -LiteralPath $staleNote -Force -ErrorAction SilentlyContinue
}
}
}
} catch {
# A note this run cannot read is not ours to delete.
}
$WithLlamaCppDir = $null
$llamaPreflightFailure = Invoke-ManagedLlamaCppPreflight -StagingRoot $StageRoot
if ($llamaPreflightFailure) {
Exit-SetupFailure $llamaPreflightFailure
}
# Back up User PATH under HKCU\Software\Unsloth before any modifications.
if (-not $StageRoot) {
try {
$envKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $false)
if ($envKey) {
try {
$rawPath = $envKey.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
} finally {
$envKey.Close()
}
if ($rawPath) {
$backupKey = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Software\Unsloth')
try {
$existingBackup = $backupKey.GetValue('PathBackup', $null)
if (-not $existingBackup) {
$backupKey.SetValue('PathBackup', $rawPath, [Microsoft.Win32.RegistryValueKind]::ExpandString)
}
} finally {
$backupKey.Close()
}
}
}
} catch {
Write-StudioLine "[DEBUG] Could not back up User PATH: $($_.Exception.Message)" -ForegroundColor DarkGray
}
}
# ==========================================================================
# PHASE 1: System-level prerequisites (winget installs, env vars)
# ==========================================================================
# ============================================
# A wedged driver can block nvidia-smi; WaitForExit bounds it.
# ============================================
function Invoke-NvidiaSmiBounded {
param(
[Parameter(Mandatory = $true, Position = 0)][string]$Exe,
[Parameter(Position = 1)][string[]]$SmiArgs = @(),
[int]$TimeoutSec = 10,
# Driver warnings on stderr would corrupt machine-readable --query-gpu output.
[switch]$StdoutOnly
)
try {
$psi = New-Object System.Diagnostics.ProcessStartInfo
$psi.FileName = $Exe
$psi.Arguments = ($SmiArgs -join ' ')
$psi.UseShellExecute = $false
$psi.RedirectStandardOutput = $true
$psi.RedirectStandardError = $true
$psi.CreateNoWindow = $true
$proc = [System.Diagnostics.Process]::Start($psi)
$outTask = $proc.StandardOutput.ReadToEndAsync()
$errTask = $proc.StandardError.ReadToEndAsync()
if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
try { $proc.Kill() } catch {}
$global:LASTEXITCODE = 124
return ""
}
$global:LASTEXITCODE = $proc.ExitCode
if ($StdoutOnly) { return $outTask.Result }
return ($outTask.Result + "`n" + $errTask.Result)
} catch {
$global:LASTEXITCODE = 1
return ""
}
}
# ── BEGIN SHARED WITH install.ps1 (Get-NvidiaSmiCandidatePaths) ──
# nvidia-smi dirs in preference order, filtered to ones holding the binary (SysNative/ProgramW6432 for
# 32-bit processes, DriverStore). System32 before legacy NVSMI, which may hold an older binary.
function Get-NvidiaSmiCandidatePaths {
$dirs = @()
# Current driver locations first, in BOTH process bitnesses, before any legacy one.
# Both bitness spellings before $env:ProgramFiles, which in a 32-bit process is the x86 tree
# where a stale toolkit copy can sit and answer first.
if ($env:SystemRoot) { $dirs += (Join-Path $env:SystemRoot "System32") }
if ($env:SystemRoot) { $dirs += (Join-Path $env:SystemRoot "SysNative") }
if ($env:ProgramW6432) { $dirs += (Join-Path $env:ProgramW6432 "NVIDIA Corporation\NVSMI") }
if ($env:ProgramFiles) { $dirs += (Join-Path $env:ProgramFiles "NVIDIA Corporation\NVSMI") }
$pfx86 = ${env:ProgramFiles(x86)}
if ($pfx86) { $dirs += (Join-Path $pfx86 "NVIDIA Corporation\NVSMI") }
# Bounded on purpose. FileRepository holds every driver package the machine has ever had.
#
# The bound is applied to directories that ACTUALLY HOLD the binary, not to the nv* matches.
# NVIDIA ships several packages whose names start nv (HD audio, the virtual audio device,
# the network service), so a host with eight of those newer than the display driver would
# otherwise spend the whole allowance on directories with no nvidia-smi in them and report
# the machine as having none. Test-Path is a file existence check, not a process spawn; the
# bound that matters is on the candidates handed back, since each of those costs a probe.
try {
$repos = @()
if ($env:SystemRoot) {
# Both spellings, same WOW64 reason as above. At most one resolves in any given process, so
# this is not a doubled scan.
$repos += (Join-Path $env:SystemRoot "System32\DriverStore\FileRepository")
$repos += (Join-Path $env:SystemRoot "SysNative\DriverStore\FileRepository")
}
$packages = @()
foreach ($repo in $repos) {
if (-not (Test-Path -LiteralPath $repo -PathType Container)) { continue }
$packages += @(Get-ChildItem -LiteralPath $repo -Directory -Filter "nv*" -ErrorAction SilentlyContinue |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "nvidia-smi.exe") -PathType Leaf })
}
# The bound is on the whole DriverStore contribution rather than per root, so adding
# the second spelling cannot double the number of probes this hands back.
foreach ($dir in @($packages | Sort-Object LastWriteTime -Descending | Select-Object -First 8)) {
$dirs += $dir.FullName
}
} catch {}
$paths = @()
$seen = @{}
foreach ($dir in $dirs) {
if ([string]::IsNullOrWhiteSpace($dir)) { continue }
$candidate = Join-Path $dir "nvidia-smi.exe"
# Case-insensitive, because the same directory reached two ways must not be probed twice:
# each probe is a bounded process spawn with a wall-clock timeout behind it.
$key = $candidate.ToLowerInvariant()
if ($seen.ContainsKey($key)) { continue }
$seen[$key] = $true
if (Test-Path -LiteralPath $candidate -PathType Leaf) { $paths += $candidate }
}
return $paths
}
# ── END SHARED WITH install.ps1 (Get-NvidiaSmiCandidatePaths) ──
# A driverless nvidia-smi exits 0 listing no GPU, so require a "GPU <n>:" row.
# 124 means the bounded runner killed the probe; recorded so the banner skips a second query.
$script:NvidiaSmiWedged = $false
# Reset per run: streamed execution shares the caller's script scope.
$script:NvidiaPresenceOnly = $false
$script:NvidiaPresenceCudaFloor = $null
$script:NvidiaPresenceDriverRelease = $null
$script:VideoControllerScanResult = $null
$script:NvidiaPreR450CpuFallback = $false
$script:NvidiaPresenceStaleGpuWheel = $null
function Test-NvidiaSmiHasGpu {
param([Parameter(Mandatory = $true)][string]$Exe)
$out = Invoke-NvidiaSmiBounded $Exe @('-L')
# Assigned, not OR-ed: the fallback loop tries several paths, and what matters is
# whether the binary it settled on answered, not whether an earlier one hung.
$script:NvidiaSmiWedged = ($LASTEXITCODE -eq 124)
return ($LASTEXITCODE -eq 0 -and $out -match '(?m)^GPU\s+\d+:')
}
$HasNvidiaSmi = $false
$NvidiaSmiExe = $null # Absolute path -- survives Refresh-Environment
try {
$nvSmiCmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
if ($nvSmiCmd -and (Test-NvidiaSmiHasGpu $nvSmiCmd.Source)) {
$HasNvidiaSmi = $true
$NvidiaSmiExe = $nvSmiCmd.Source
}
} catch {}
if (-not $HasNvidiaSmi) {
# Prefer a candidate that lists a GPU AND prints a parseable CUDA banner; else the first that lists.
# Get-Date, not Stopwatch (CLM). Candidates are enumerated before the clock starts.
$smiCandidates = @(Get-NvidiaSmiCandidatePaths)
# Soft deadline applies only once a usable answer exists; only the hard one may end with nothing,
# since finding nothing means CPU-only PyTorch.
$probeDeadline = (Get-Date).AddSeconds(30)
$probeHardDeadline = (Get-Date).AddSeconds(60)
$firstListing = $null
# $script:NvidiaSmiWedged describes the LAST binary probed, not necessarily the one selected.
$firstListingWedged = $false
foreach ($p in $smiCandidates) {
if ($null -ne $firstListing -and (Get-Date) -gt $probeDeadline) { break }
if ((Get-Date) -gt $probeHardDeadline) { break }
try {
if (-not (Test-NvidiaSmiHasGpu $p)) { continue }
if (-not $firstListing) {
$firstListing = $p
$firstListingWedged = $script:NvidiaSmiWedged
}
# Rechecked: the listing probe may have used most of its bound.
if ((Get-Date) -gt $probeDeadline) { break }
$banner = Invoke-NvidiaSmiBounded $p
if ($banner -match 'CUDA(?: UMD)? Version:\s+\d+\.\d+') {
$HasNvidiaSmi = $true
$NvidiaSmiExe = $p
Write-StudioLine " Found nvidia-smi at $(Split-Path $p -Parent)" -ForegroundColor Gray
break
}
} catch {}
}
if (-not $HasNvidiaSmi -and $firstListing) {
$HasNvidiaSmi = $true
$NvidiaSmiExe = $firstListing
# Restore the wedged flag for the selected binary, not a later one that timed out.
$script:NvidiaSmiWedged = $firstListingWedged
Write-StudioLine " Found nvidia-smi at $(Split-Path $firstListing -Parent)" -ForegroundColor Gray
}
}
# Returns the entry, not a bool: the version ladder needs its DriverVersion.
function Get-NvidiaRegistryAdapter {
$classKey = "HKLM:\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}"
try {
$subs = @(Get-ChildItem -LiteralPath $classKey -ErrorAction SilentlyContinue)
} catch { return $null }
# These keys outlive hardware, so only a UNANIMOUS release is used; disagreement reads as unknown.
$present = $false
$versions = @()
foreach ($sub in $subs) {
try {
if ("$($sub.PSChildName)" -notmatch '^\d+$') { continue }
$props = Get-ItemProperty -LiteralPath $sub.PSPath -ErrorAction SilentlyContinue
if (-not $props) { continue }
if ("$($props.MatchingDeviceId)" -notmatch '(?i)ven_10de') { continue }
$present = $true
$version = "$($props.DriverVersion)"
if ([string]::IsNullOrWhiteSpace($version)) { continue }
$release = Get-NvidiaDriverRelease -DriverVersion $version
if ($null -eq $release) { continue }
if ($versions -notcontains $release) { $versions += $release }
} catch {}
}
if (-not $present) { return $null }
if ($versions.Count -ne 1) { return [pscustomobject]@{ Release = $null } }
return [pscustomobject]@{ Release = $versions[0] }
}
function Test-NvidiaAdapterWithoutNvidiaDriver {
param($Scan = $null)
if ($null -eq $Scan) { $Scan = Invoke-BoundedVideoControllerScan }
$foreign = $false
foreach ($adapter in @($Scan.Adapters)) {
if ("$($adapter.PNPDeviceID)" -notmatch '(?i)ven_10de') { continue }
if ($null -eq $adapter.ConfigManagerErrorCode) { continue }
if ([int]$adapter.ConfigManagerErrorCode -ne 0) { continue }
$version = "$($adapter.DriverVersion)"
if ([string]::IsNullOrWhiteSpace($version)) { $foreign = $true; continue }
if ($null -ne (Get-NvidiaDriverRelease -DriverVersion $version)) { return $false }
$foreign = $true
}
return $foreign
}
# VEN_10DE and ConfigManagerErrorCode 0 only: a false yes switches off AMD and Intel detection.
function Test-NvidiaAdapterPresent {
param($Scan = $null)
if ($null -eq $Scan) { $Scan = Invoke-BoundedVideoControllerScan }
foreach ($adapter in @($Scan.Adapters)) {
if ("$($adapter.PNPDeviceID)" -notmatch '(?i)ven_10de') { continue }
# $null is not evidence of health.
if ($null -eq $adapter.ConfigManagerErrorCode) { continue }
if ([int]$adapter.ConfigManagerErrorCode -ne 0) { continue }
return $true
}
# No registry fallback: stale class keys would promote a GPU that is gone.
return $false
}
# Must match the Intel route's pattern exactly (asserted by test_nvidia_adapter_presence.ps1).
# A function, since an unset $script: pattern would match every string.
function Get-XpuCapableNameRegex { return "(?i)Intel.*(Arc|Data Center GPU)" }
function Test-IntelXpuRuntimeProven {
param($Scan = $null, [string]$PythonExe = "")
# The Intel route also serves non-Arc Intel GPUs once the existing torch proves XPU works, with no
# WMI precondition, so this asks the same thing. Any failure reads as not proven.
if (-not $PythonExe -or -not (Test-Path -LiteralPath $PythonExe)) { return $false }
try {
$probe = Invoke-BoundedPythonProbe -PythonExe $PythonExe -Code 'import torch; print(torch.xpu.is_available())'
return [bool]($probe.Ok -and $probe.Output -match '(?m)^\s*True\s*$')
} catch {
return $false
}
}
function Test-OtherVendorAdapterPresent {
param($Scan = $null)
if ($null -eq $Scan) { $Scan = Invoke-BoundedVideoControllerScan }
# AMD evidence the AMD route finds without WMI (override, the installer's forwarded arch, HIP SDK,
# opted-in amd-smi) vetoes too.
if ("$env:UNSLOTH_ROCM_GFX_ARCH".Trim() -or "$env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF".Trim()) { return $true }
try {
if (Get-Command hipinfo -CommandType Application -ErrorAction SilentlyContinue) { return $true }
foreach ($hipEnv in @($env:HIP_PATH, $env:HIP_PATH_57, $env:ROCM_PATH)) {
if ($hipEnv -and (Test-Path -LiteralPath (Join-Path $hipEnv "bin\hipinfo.exe"))) { return $true }
}
if ($env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(1|true|yes|on)$' -and
(Get-Command amd-smi -ErrorAction SilentlyContinue)) { return $true }
} catch {}
# Same classification as the Intel route, which ignores PNP ID and status.
if ($Scan.Ok) {
$scanNames = @($Scan.Names | Where-Object { $_ } | ForEach-Object { "$_" })
if (@($scanNames | Where-Object { $_ -match (Get-XpuCapableNameRegex) }).Count -gt 0) { return $true }
try {
foreach ($regName in @(Get-IntelRegistryAdapterNames)) {
if ("$regName" -notmatch (Get-XpuCapableNameRegex)) { continue }
foreach ($wmiName in $scanNames) {
if ("$regName".Contains($wmiName)) { return $true }
}
}
} catch {}
}
foreach ($adapter in @($Scan.Adapters)) {
# AMD vetoes on the AMD route's own test (name or 1002, any status: it keeps parked and
# PNP-less cards). Intel was answered above; UHD/Iris do not block.
if ("$($adapter.Name)" -match "AMD|Radeon" -or "$($adapter.PNPDeviceID)" -match '(?i)ven_1002') { return $true }
}
# Registry fallback here is deliberate: staleness only DECLINES a promotion. Without it, broken WMI
# hid the Arc on a hybrid host and cost it its XPU wheels.
if ($Scan.Ok) { return $false }
# Same normalized names as the Intel route (it prefixes "Intel" to a VEN_8086 DriverDesc).
try {
if (@(Get-IntelRegistryAdapterNames | Where-Object { "$_" -match (Get-XpuCapableNameRegex) }).Count -gt 0) { return $true }
} catch {}
$classKey = "HKLM:\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}"
try {
$subs = @(Get-ChildItem -LiteralPath $classKey -ErrorAction SilentlyContinue)
} catch { return $false }
foreach ($sub in $subs) {
try {
if ("$($sub.PSChildName)" -notmatch '^\d+$') { continue }
$props = Get-ItemProperty -LiteralPath $sub.PSPath -ErrorAction SilentlyContinue
if (-not $props) { continue }
$match = "$($props.MatchingDeviceId)"
if ($match -match '(?i)ven_1002') { return $true }
} catch {}
}
return $false
}
# Ported from studio/nvidia_probe.py's cuda_version_for_driver; the parity test generates the table.
function Get-NvidiaDriverRelease {
param([string]$DriverVersion)
if ([string]::IsNullOrWhiteSpace($DriverVersion)) { return $null }
# NVIDIA's scheme only (32.0.15.6094 is 560.94). Basic Display versions like 10.0.19041.3636 must
# not read as releases, or a working CUDA venv gets replaced with CPU wheels.
$m = [regex]::Match($DriverVersion, '^\s*\d+\.\d+\.(1\d)\.(\d{4})\s*$')
if ($m.Success) {
$digits = ($m.Groups[1].Value + $m.Groups[2].Value)
if ($digits.Length -ge 5) {
$tail = $digits.Substring($digits.Length - 5)
return [int]$tail.Substring(0, 3)
}
return $null
}
# At least three digits: "1.2.3" is malformed, and a low release now selects CPU wheels.
$m2 = [regex]::Match($DriverVersion, '^\s*(\d+)\.')
if ($m2.Success) {
$parsed = [int]$m2.Groups[1].Value
if ($parsed -ge 100) { return $parsed }
}
return $null
}
function Get-NvidiaCudaFloorForRelease {
param($Release)
if ($null -eq $Release) { return $null }
# Same order and values as _DRIVER_MAJOR_CUDA.
foreach ($row in @(
@(580, 13, 0), @(570, 12, 8), @(560, 12, 6), @(555, 12, 5), @(550, 12, 4),
@(545, 12, 3), @(535, 12, 2), @(525, 12, 0), @(450, 11, 0)
)) {
if ([int]$Release -ge $row[0]) { return @($row[1], $row[2]) }
}
return $null
}
function Get-NvidiaDriverCudaFloor {
param([string]$DriverVersion)
return (Get-NvidiaCudaFloorForRelease -Release (Get-NvidiaDriverRelease -DriverVersion $DriverVersion))
}
function Get-NvidiaAdapterDriverRelease {
param($Scan = $null)
if ($null -eq $Scan) { $Scan = Invoke-BoundedVideoControllerScan }
foreach ($adapter in @($Scan.Adapters)) {
if ("$($adapter.PNPDeviceID)" -notmatch '(?i)ven_10de') { continue }
if ($null -eq $adapter.ConfigManagerErrorCode) { continue }
if ([int]$adapter.ConfigManagerErrorCode -ne 0) { continue }
$release = Get-NvidiaDriverRelease -DriverVersion "$($adapter.DriverVersion)"
if ($null -ne $release) { return $release }
}
if (-not $Scan.Ok) {
$registryAdapter = Get-NvidiaRegistryAdapter
if ($registryAdapter) { return $registryAdapter.Release }
}
return $null
}
function Get-NvidiaAdapterCudaFloor {
param($Scan = $null)
if ($null -eq $Scan) { $Scan = Invoke-BoundedVideoControllerScan }
foreach ($adapter in @($Scan.Adapters)) {
if ("$($adapter.PNPDeviceID)" -notmatch '(?i)ven_10de') { continue }
if ($null -eq $adapter.ConfigManagerErrorCode) { continue }
if ([int]$adapter.ConfigManagerErrorCode -ne 0) { continue }
$floor = Get-NvidiaDriverCudaFloor -DriverVersion "$($adapter.DriverVersion)"
if ($floor) { return $floor }
}
if (-not $Scan.Ok) {
$registryAdapter = Get-NvidiaRegistryAdapter
if ($registryAdapter) { return (Get-NvidiaCudaFloorForRelease -Release $registryAdapter.Release) }
}
return $null
}
if (-not $HasNvidiaSmi -and (Get-NvidiaLibraryInventory)) {
# A driver below CUDA 11 cannot serve any wheel; let the Intel and AMD routes try.
if ((Get-NvidiaLibraryInventory).CudaMajor -ge 11) {
$HasNvidiaSmi = $true
$script:NvidiaSmiRejected = $true
Write-StudioLine " NVIDIA GPU found through the driver library; nvidia-smi is unavailable" -ForegroundColor Gray
} else {
$script:NvidiaDriverLibraryOnly = $true
}
}
# Last resort: presence only, gated on no healthy AMD or Intel adapter.
if (-not $HasNvidiaSmi) {
$presenceScan = Invoke-BoundedVideoControllerScan
# Any throw declines the promotion; flags are set only once every answer is in hand.
try {
$_presenceXpuVenvs = @(@($VenvDir, (Get-ProbableStudioVenvDir)) | Where-Object { $_ } | Select-Object -Unique)
if ((Test-NvidiaAdapterPresent -Scan $presenceScan) -and
(Test-NvidiaAdapterWithoutNvidiaDriver -Scan $presenceScan)) {
Write-StudioLine " NVIDIA GPU found without the NVIDIA driver; install the NVIDIA driver and re-run for GPU support" -ForegroundColor Yellow
} elseif ((Test-NvidiaAdapterPresent -Scan $presenceScan) -and
-not (Test-OtherVendorAdapterPresent -Scan $presenceScan) -and
-not (@($_presenceXpuVenvs | Where-Object {
(Test-VenvTorchIsXpu $_) -and
(Test-IntelXpuRuntimeProven -Scan $presenceScan -PythonExe (Join-Path $_ "Scripts\python.exe")) }).Count -gt 0)) {
$_presenceFloor = Get-NvidiaAdapterCudaFloor -Scan $presenceScan
# The floor is $null both for too-old and unreadable, which want opposite answers.
$_presenceRelease = Get-NvidiaAdapterDriverRelease -Scan $presenceScan
$HasNvidiaSmi = $true
$script:NvidiaPresenceOnly = $true
$script:NvidiaSmiRejected = $true
$script:NvidiaPresenceCudaFloor = $_presenceFloor
$script:NvidiaPresenceDriverRelease = $_presenceRelease
Write-StudioLine " NVIDIA GPU found on the PCI bus; nvidia-smi and the driver library are both unavailable" -ForegroundColor Gray
}
} catch {}
}
# Widens TORCH selection only; llama.cpp needs a real driver stack.
$HasNvidiaDriverEvidence = $HasNvidiaSmi -and -not $script:NvidiaPresenceOnly
# Name the GPU for the banner, honouring the visible-device mask. A mask of "" or -1 hides
# every device, so naming is skipped.
$NvidiaGpuName = $null
$NvidiaSmArch = $null
$NvidiaDriverVersion = $null
$nvMaskHidesAll = $false
if ($null -ne $env:CUDA_VISIBLE_DEVICES) {
$nvMask = ($env:CUDA_VISIBLE_DEVICES -replace '\s', '')
$nvMaskHidesAll = ($nvMask -eq '' -or $nvMask -eq '-1')
}
if ($HasNvidiaSmi -and $NvidiaSmiExe -and -not $script:NvidiaSmiWedged -and -not $nvMaskHidesAll) {
try {
# -StdoutOnly: driver warnings on stderr would corrupt the CSV.
$nvOut = Invoke-NvidiaSmiBounded $NvidiaSmiExe @('--query-gpu=name,compute_cap,driver_version', '--format=csv,noheader') -StdoutOnly
$nvRows = @($nvOut -split '\r?\n' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
if ($nvRows.Count -gt 0) {
# nvidia-smi ignores CUDA_VISIBLE_DEVICES; UUID/MIG tokens match on unique prefix.
$nvIdx = 0
$nvTok = if ($env:CUDA_VISIBLE_DEVICES) { ($env:CUDA_VISIBLE_DEVICES -split ',')[0].Trim() } else { '' }
$nvByOrdinal = $true
# Set when an identity mask did not resolve: CUDA selected NO device, so row 0 is no fallback.
$nvUnresolved = $false
if ($nvTok -match '^\d+$') {
$nvIdx = [int]$nvTok
} elseif ($nvTok -like 'MIG-*' -and $nvTok -notlike 'MIG-GPU-*') {
# R470+ MIG UUIDs carry nothing of the parent; nvidia-smi -L nests them under their GPU.
$nvListOut = Invoke-NvidiaSmiBounded $NvidiaSmiExe @('-L') -StdoutOnly
$cur = 0
$nvByOrdinal = $false
$nvFound = $false
foreach ($ln in ($nvListOut -split '\r?\n')) {
if ($ln -match '^GPU\s+(\d+):') { $cur = [int]$Matches[1] }
if ($ln -match [regex]::Escape($nvTok)) { $nvIdx = $cur; $nvFound = $true; break }
}
if (-not $nvFound) { $nvUnresolved = $true }
} elseif ($nvTok) {
# Pre-R470 MIG names embed the parent UUID: MIG-<GPU-UUID>/<gi>/<ci>.
if ($nvTok -like 'MIG-GPU-*') { $nvTok = ($nvTok.Substring(4) -split '/')[0] }
$nvUuidOut = Invoke-NvidiaSmiBounded $NvidiaSmiExe @('--query-gpu=uuid', '--format=csv,noheader') -StdoutOnly
$nvUuids = @($nvUuidOut -split '\r?\n' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
$nvByOrdinal = $false
$nvFound = $false
# A prefix matching two cards selects NO device, so collect all hits.
$nvMatches = @()
for ($i = 0; $i -lt $nvUuids.Count; $i++) {
if ($nvUuids[$i].StartsWith($nvTok, [System.StringComparison]::OrdinalIgnoreCase)) { $nvMatches += $i }
}
if ($nvMatches.Count -eq 1) { $nvIdx = $nvMatches[0]; $nvFound = $true }
if (-not $nvFound) { $nvUnresolved = $true }
}
$nvRow = if ($nvIdx -lt $nvRows.Count) { $nvRows[$nvIdx] } else { $nvRows[0] }
# CUDA's default FASTEST_FIRST order differs from nvidia-smi's PCI order, so an ordinal identifies a
# row only if PCI_BUS_ID is pinned or all rows agree. An ordinal past the last row exposes nothing.
if ($nvByOrdinal -and $nvIdx -ge $nvRows.Count) { $nvUnresolved = $true }
$nvAmbiguous = $nvUnresolved
if ($nvByOrdinal -and -not $nvAmbiguous) {
$nvOrder = (("$env:CUDA_DEVICE_ORDER") -replace '\s', '').ToUpperInvariant()
$nvModels = @($nvRows | ForEach-Object { $_ -replace ',[^,]*$', '' } |
Sort-Object -Unique).Count
$nvAmbiguous = ($nvOrder -ne 'PCI_BUS_ID' -and $nvModels -gt 1)
}
# Split from the right: nvidia-smi does not quote commas in device names.
$nvParts = $nvRow -split ','
if ($nvParts.Count -ge 3) {
$NvidiaDriverVersion = $nvParts[-1].Trim()
$nvComputeCap = $nvParts[-2].Trim()
$NvidiaGpuName = ($nvParts[0..($nvParts.Count - 3)] -join ',').Trim()
if ($nvComputeCap -match '^(\d+)\.(\d+)$') {
$NvidiaSmArch = "sm_" + (([int]$Matches[1] * 10) + [int]$Matches[2])
}
} else {
$NvidiaGpuName = $nvParts[0].Trim()
}
# Old nvidia-smi answers with a placeholder for unknown fields (470 has no compute_cap).
$nvPlaceholders = @('[N/A]', '[Not Supported]', '[Unknown Error]')
if ($nvPlaceholders -contains $NvidiaGpuName) { $NvidiaGpuName = $null }
if ($nvPlaceholders -contains $NvidiaDriverVersion) { $NvidiaDriverVersion = $null }
if ($nvAmbiguous) { $NvidiaGpuName = $null; $NvidiaSmArch = $null }
}
} catch {}
}
# amd-smi auto-elevates and pops a UAC prompt; RunAsInvoker stops it.
function Invoke-AmdSmiNoElevate {
param(
[Parameter(Mandatory = $true, Position = 0)][string]$Exe,
[Parameter(Position = 1)][string[]]$SmiArgs = @(),
[int]$TimeoutSec = 30
)
$prevCompat = [Environment]::GetEnvironmentVariable('__COMPAT_LAYER', 'Process')
$env:__COMPAT_LAYER = 'RunAsInvoker'
try {
# [Process]::Start: Start-Process -PassThru leaves .ExitCode $null on PS 5.1.
$psi = New-Object System.Diagnostics.ProcessStartInfo
$psi.FileName = $Exe
$psi.Arguments = ($SmiArgs -join ' ')
$psi.UseShellExecute = $false
$psi.RedirectStandardOutput = $true
$psi.RedirectStandardError = $true
$psi.CreateNoWindow = $true
$proc = [System.Diagnostics.Process]::Start($psi)
$outTask = $proc.StandardOutput.ReadToEndAsync()
$errTask = $proc.StandardError.ReadToEndAsync()
if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
try { $proc.Kill() } catch {}
$global:LASTEXITCODE = 124
return ""
}
$global:LASTEXITCODE = $proc.ExitCode
return ($outTask.Result + "`n" + $errTask.Result)
} catch {
$global:LASTEXITCODE = 1
return ""
} finally {
if ($null -eq $prevCompat) {
Remove-Item Env:__COMPAT_LAYER -ErrorAction SilentlyContinue
} else {
$env:__COMPAT_LAYER = $prevCompat
}
}
}
# ── AMD ROCm detection (Windows): probe hipinfo/amd-smi for actual GPU ──
$HasROCm = $false
$HipSdkInstalled = $false # HIP SDK binary found (independent of device accessibility)
$ROCmGpuLabel = $null
# Banner-only name; $ROCmGpuLabel doubles as input to the name->arch tables.
$ROCmGpuName = $null
$script:ROCmGpuLabels = @() # every AMD adapter name WMI reported (shadowing-aware inference)
$script:ROCmGfxArch = $null
# Declared here: the ROCm summary reads it unconditionally (StrictMode).
$script:ROCmUnsupportedGfxArch = $null
# APU arches that often shadow a discrete Radeon at HIP index 0. In sync with
# _SHADOWING_INTEGRATED_GFX in studio/install_python_stack.py; Strix arches deliberately absent.
$script:ShadowingIntegratedGfx = @(
"gfx90c", # Renoir / Cezanne
"gfx1013", # Cyan Skillfish
"gfx1033", # Van Gogh
"gfx1035", # Rembrandt
"gfx1036", # Raphael / Mendocino
"gfx1103", # Phoenix / Hawk Point
"gfx1153" # Krackan Point 2
)
# Defined early: Resolve-ShadowingGfxPick runs during detection. In sync with _GFX_TO_AMD_INDEX_ARCH.
$archFamilyMap = @{
"gfx1201" = "gfx120X-all"; "gfx1200" = "gfx120X-all" # RDNA 4
"gfx1151" = "gfx1151"; "gfx1150" = "gfx1150" # RDNA 3.5 (Strix Halo/Point)
"gfx1152" = "gfx1152" # RDNA 3.5 (Krackan Point)
"gfx1103" = "gfx110X-all"; "gfx1102" = "gfx110X-all" # RDNA 3
"gfx1101" = "gfx110X-all"; "gfx1100" = "gfx110X-all"
"gfx1036" = "gfx103X-all"; "gfx1035" = "gfx103X-all" # RDNA 2 (RX 6000)
"gfx1034" = "gfx103X-all"; "gfx1033" = "gfx103X-all"
"gfx1032" = "gfx103X-all"; "gfx1031" = "gfx103X-all"
"gfx1030" = "gfx103X-all"
"gfx90a" = "gfx90a"; "gfx908" = "gfx908" # MI200/MI100
}
# RDNA arches route to AMD's multi-arch index; gfx1033 (miscomputes) and CDNA stay on the family map.
# In sync with _WINDOWS_MULTIARCH_GFX in studio/install_python_stack.py.
$multiArchGfx = @(
"gfx1010", "gfx1011", "gfx1012", # RDNA 1
"gfx1030", "gfx1031", "gfx1032", "gfx1034", "gfx1035", "gfx1036", # RDNA 2, gfx1033 stays per-family
"gfx1100", "gfx1101", "gfx1102", "gfx1103", # RDNA 3
"gfx1150", "gfx1151", "gfx1152", "gfx1153", # RDNA 3.5
"gfx1200", "gfx1201" # RDNA 4
)
$MultiArchIndexBase = if ($env:UNSLOTH_ROCM_WINDOWS_MULTIARCH_MIRROR) { $env:UNSLOTH_ROCM_WINDOWS_MULTIARCH_MIRROR.TrimEnd('/') } else { "https://repo.amd.com/rocm/whl-multi-arch" }
# Not rocm7.14.1: its Windows wheels ship a mismatched AOTriton runtime, so fused SDPA fails.
$MultiArchTag = "rocm7.14.0"
$MultiArchTorchVersion = "2.11.0"
$MultiArchTorchvisionVersion = "0.26.0"
$MultiArchTorchaudioVersion = "2.11.0"
# Mirrors _visible_devices_pinned(): ANY value, "" and "-1" included, is a deliberate selection.
function Test-VisibleDevicesPinned {
foreach ($visEnv in @($env:HIP_VISIBLE_DEVICES, $env:ROCR_VISIBLE_DEVICES, $env:CUDA_VISIBLE_DEVICES)) {
if ($null -ne $visEnv) { return $true }
}
return $false
}
# The single mask -> index resolver; mirrors _pick_visible_index(). First set mask wins;
# unparseable or out-of-range falls back to GPU 0.
function Resolve-VisibleGpuIndex {
param([int]$Count)
foreach ($visEnv in @($env:HIP_VISIBLE_DEVICES, $env:ROCR_VISIBLE_DEVICES, $env:CUDA_VISIBLE_DEVICES)) {
if ($null -eq $visEnv) { continue }
$val = $visEnv.Trim()
if ($val -eq "" -or $val -eq "-1") { return 0 }
$first = ($val -split ',')[0].Trim()
# TryParse, not [int]: overflow or full-width digits would throw a terminating error under Stop.
[int]$parsed = 0
if ([int]::TryParse($first, [ref]$parsed)) {
if ($parsed -ge 0 -and $parsed -lt $Count) { return $parsed }
substep "[WARN] HIP/ROCR/CUDA_VISIBLE_DEVICES index $first is out of range ($Count GPU(s) detected); defaulting to GPU 0 for arch selection" "Yellow"
}
return 0
}
return 0
}
# Mirrors _dedup_pick(): skip a shadowing iGPU here too, since the index URL is built before the
# Python installer runs. Unchanged when pinned or only one distinct arch exists.
function Resolve-ShadowingGfxPick {
param([AllowNull()][string]$Picked, [AllowNull()][string[]]$AllArches)
if (-not $Picked) { return $Picked }
function Test-GfxHasWheels { param([AllowNull()][string]$Arch) return [bool]($Arch -and ($archFamilyMap.ContainsKey($Arch) -or $multiArchGfx -contains $Arch)) }
# A selected device is honoured verbatim.
if (Test-VisibleDevicesPinned) { return $Picked }
if ($script:ShadowingIntegratedGfx -notcontains $Picked) { return $Picked }
$distinctArches = @($AllArches | Select-Object -Unique)
if ($distinctArches.Count -lt 2) { return $Picked }
# Prefer a wheel-backed discrete card; an unsupported one only when the pick has no wheels either.
$pickedHasWheels = Test-GfxHasWheels $Picked
$others = @($AllArches | Where-Object { $script:ShadowingIntegratedGfx -notcontains $_ })
$withWheels = @($others | Where-Object { Test-GfxHasWheels $_ })
$candidates = if ($withWheels.Count -gt 0) { $withWheels }
elseif (-not $pickedHasWheels) { $others }
else { @() }
$discreteArch = $candidates | Select-Object -First 1
if (-not $discreteArch) { return $Picked }
# Not always device 1; the pick can be a later index, e.g. device 2 for gfx1036,gfx803,gfx1200.
$discreteIdx = [array]::IndexOf(@($AllArches), $discreteArch)
if ($discreteIdx -lt 0) { $discreteIdx = 1 }
substep "multiple AMD GPUs detected ($($distinctArches -join ', ')); installing for the discrete $discreteArch instead of the integrated $Picked" "Cyan"
# HIP still enumerates the iGPU as device 0 at runtime, so the mask must persist.
substep "Run 'setx HIP_VISIBLE_DEVICES $discreteIdx' and reopen your terminal so Unsloth uses $discreteArch at runtime too, not just at install time" "Cyan"
return $discreteArch
}
if (-not $HasNvidiaSmi) {
# The venv hipInfo.exe comes from an AMD wheel, not a HIP SDK.
function Test-HipinfoIsVenvInternal {
param([AllowNull()][string]$HipinfoPath)
if ([string]::IsNullOrWhiteSpace($HipinfoPath)) { return $false }
# VenvDir/VIRTUAL_ENV can be unset this early.
$venvRoots = @()
if ($env:VIRTUAL_ENV) { $venvRoots += $env:VIRTUAL_ENV }
$vd = Get-Variable -Name VenvDir -ValueOnly -ErrorAction SilentlyContinue
if ($vd) { $venvRoots += $vd }
if ($env:UNSLOTH_SETUP_PYTHON) {
try { $venvRoots += (Split-Path -Parent (Split-Path -Parent $env:UNSLOTH_SETUP_PYTHON)) } catch {}
}
if ($env:USERPROFILE) { $venvRoots += (Join-Path $env:USERPROFILE ".unsloth\studio\unsloth_studio") }
$studioHomeEnv = if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) { $env:UNSLOTH_STUDIO_HOME.Trim() } elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) { $env:STUDIO_HOME.Trim() } else { $null }
if ($studioHomeEnv) {
# Expand a leading ~ like the canonical resolver; GetFullPath keeps it literal.
if (($studioHomeEnv -eq "~" -or $studioHomeEnv -like "~/*" -or $studioHomeEnv -like "~\*") -and -not [string]::IsNullOrWhiteSpace($env:USERPROFILE)) {
# A bare "~" leaves an empty child path Join-Path rejects on PS 5.1.
$studioHomeRest = $studioHomeEnv.Substring(1).TrimStart('/', '\')
$studioHomeEnv = if ($studioHomeRest) { Join-Path $env:USERPROFILE $studioHomeRest } else { $env:USERPROFILE }
}
$venvRoots += (Join-Path $studioHomeEnv "unsloth_studio")
}
try { $hip = [System.IO.Path]::GetFullPath($HipinfoPath).TrimEnd('\', '/') } catch { return $false }
foreach ($root in $venvRoots) {
if ([string]::IsNullOrWhiteSpace($root)) { continue }
try { $r = [System.IO.Path]::GetFullPath($root).TrimEnd('\', '/') } catch { continue }
# A bare drive root would match every path on that drive.
if ($r -match '^[a-zA-Z]:$') { continue }
if ($hip.Equals($r, [System.StringComparison]::OrdinalIgnoreCase) -or
$hip.StartsWith($r + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)) {
return $true
}
}
return $false
}
# -CommandType Application skips an alias or function named hipinfo.
$hipinfoExe = Get-Command hipinfo -CommandType Application -All -ErrorAction SilentlyContinue |
Where-Object { -not (Test-HipinfoIsVenvInternal $_.Source) } |
Select-Object -First 1
if (-not $hipinfoExe) {
$hipMissingLabel = $null; $hipMissingRoot = $null; $hipMissingCandidate = $null
foreach ($hipEnvLabel in @("HIP_PATH", "HIP_PATH_57", "ROCM_PATH")) {
$hipRoot = [Environment]::GetEnvironmentVariable($hipEnvLabel)
if ([string]::IsNullOrWhiteSpace($hipRoot)) { continue }
$hipinfoCandidate = Join-Path $hipRoot "bin\hipinfo.exe"
if (-not (Test-Path $hipinfoCandidate)) {
if (-not $hipMissingLabel) { $hipMissingLabel = $hipEnvLabel; $hipMissingRoot = $hipRoot; $hipMissingCandidate = $hipinfoCandidate }
continue
}
if (Test-HipinfoIsVenvInternal $hipinfoCandidate) { continue } # venv copy (AMD wheel): not a HIP SDK
substep "[WARN] hipinfo not on PATH -- located via ${hipEnvLabel}: $hipinfoCandidate" "Yellow"
substep " Add '$(Join-Path $hipRoot 'bin')' to your PATH to suppress this warning" "Yellow"
substep " Quick fix: [Environment]::SetEnvironmentVariable('PATH',`$env:PATH+';$(Join-Path $hipRoot 'bin')','User')" "Yellow"
$hipinfoExe = [PSCustomObject]@{ Source = $hipinfoCandidate }
break
}
if ((-not $hipinfoExe) -and $hipMissingLabel) {
substep "[WARN] ${hipMissingLabel}=$hipMissingRoot is set but hipinfo.exe not found at $hipMissingCandidate" "Yellow"
substep " HIP SDK install may be incomplete -- re-install from:" "Yellow"
substep " https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
}
}
if ($hipinfoExe) {
$HipSdkInstalled = $true # binary found → SDK is installed regardless of device state
try {
$hipOut = & $hipinfoExe.Source 2>&1 | Out-String
if ($hipOut -match "(?i)gcnArchName") {
# hipinfo can crash after printing gcnArchName; keep the ROCm path.
$HasROCm = $true
$_hipAllArches = @([regex]::Matches($hipOut, "(?im)^\s*gcnArchName\s*:\s*(\S+)") | ForEach-Object { ($_.Groups[1].Value -split ':')[0].Trim().ToLower() })
# Names trusted only when they line up with the arches, read at the picked index.
$_hipAllNames = @([regex]::Matches($hipOut, "(?im)^\s*Name\s*:\s*(.+?)\s*$") | ForEach-Object { $_.Groups[1].Value.Trim() })
if ($_hipAllArches.Count -gt 0) {
# hipinfo already honours the mask and renumbers from 0, so do not index it again.
$script:ROCmGfxArch = $_hipAllArches[0]
$script:ROCmGfxArch = Resolve-ShadowingGfxPick $script:ROCmGfxArch $_hipAllArches
$ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
if ($_hipAllNames.Count -eq $_hipAllArches.Count) {
$_hipPickIdx = [array]::IndexOf($_hipAllArches, $script:ROCmGfxArch)
if ($_hipPickIdx -ge 0) { $ROCmGpuName = $_hipAllNames[$_hipPickIdx] }
}
} else {
$ROCmGpuLabel = "AMD ROCm"
}
if ($LASTEXITCODE -ne 0) {
substep "[INFO] hipinfo exited with code $LASTEXITCODE but reported gcnArchName -- treating as ROCm-capable (see #6043)" "Cyan"
}
} elseif ($LASTEXITCODE -ne 0) {
$firstLine = ($hipOut -split '\r?\n' | Where-Object { $_.Trim() } | Select-Object -First 1)
substep "[WARN] hipinfo returned a HIP runtime error (exit $LASTEXITCODE)" "Yellow"
substep " $firstLine" "Yellow"
substep " Ensure ROCm drivers are installed: https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
}
} catch {}
}
# amd-smi can pop an unsuppressable UAC prompt, so probe only with a HIP SDK or on opt-in.
$amdSmiOptOut = $env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(0|false|no|off)$'
$amdSmiAllowed = (-not $amdSmiOptOut) -and ($HipSdkInstalled -or ($env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(1|true|yes|on)$'))
if (-not $HasROCm -and $amdSmiAllowed) {
$amdSmiExe = Get-Command "amd-smi" -ErrorAction SilentlyContinue
if ($amdSmiExe) {
try {
$smiOut = Invoke-AmdSmiNoElevate $amdSmiExe.Source @('list')
if ($LASTEXITCODE -eq 0 -and $smiOut -match "(?im)^GPU\s*[:\[]\s*\d") {
$HasROCm = $true
# All gfx tokens in output order, no dedup, so the mask index lines up.
$allGfxArches = @([regex]::Matches($smiOut, '(?i)\b(gfx\d+[a-z]?)\b') |
ForEach-Object { $_.Groups[1].Value.ToLower() })
if ($allGfxArches.Count -gt 0) {
# amd-smi lists every GPU regardless of masks, so resolve the index here.
$_smiPickIdx = Resolve-VisibleGpuIndex $allGfxArches.Count
$script:ROCmGfxArch = $allGfxArches[$_smiPickIdx]
$_smiShadowPick = Resolve-ShadowingGfxPick $script:ROCmGfxArch $allGfxArches
if ($_smiShadowPick -ne $script:ROCmGfxArch) {
$script:ROCmGfxArch = $_smiShadowPick
$_smiPickIdx = [array]::IndexOf($allGfxArches, $_smiShadowPick)
}
$ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
# Carry the index forward: IndexOf on duplicate arches always returns 0.
$_smiNames = @([regex]::Matches($smiOut, "(?im)Market.?Name\s*[:\|]\s*([^\r\n]+)") | ForEach-Object { $_.Groups[1].Value.Trim() })
if ($_smiNames.Count -eq $allGfxArches.Count -and $_smiPickIdx -ge 0) {
$ROCmGpuName = $_smiNames[$_smiPickIdx]
}
} else {
# 'static --asic' exposes the GFX target on ROCm 6+.
$smiAsicOut = ""
try { $smiAsicOut = Invoke-AmdSmiNoElevate $amdSmiExe.Source @('static','--asic') } catch {}
# Every token, not just the first, or a leading iGPU is picked.
$asicGfxArches = @([regex]::Matches($smiAsicOut, '(?i)\b(gfx\d+[a-z]?)\b') |
ForEach-Object { $_.Groups[1].Value.ToLower() })
if ($asicGfxArches.Count -gt 0) {
$_asicPickIdx = Resolve-VisibleGpuIndex $asicGfxArches.Count
$script:ROCmGfxArch = $asicGfxArches[$_asicPickIdx]
$_asicShadowPick = Resolve-ShadowingGfxPick $script:ROCmGfxArch $asicGfxArches
if ($_asicShadowPick -ne $script:ROCmGfxArch) {
$script:ROCmGfxArch = $_asicShadowPick
$_asicPickIdx = [array]::IndexOf($asicGfxArches, $_asicShadowPick)
}
$ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
$_asicNames = @([regex]::Matches($smiAsicOut, "(?im)Market.?Name\s*[:\|]\s*([^\r\n]+)") | ForEach-Object { $_.Groups[1].Value.Trim() })
if ($_asicNames.Count -eq $asicGfxArches.Count -and $_asicPickIdx -ge 0) {
$ROCmGpuName = $_asicNames[$_asicPickIdx]
}
} elseif ($smiAsicOut -match "(?im)Market.?Name\s*[:\|]\s*([^\r\n]+)") {
$ROCmGpuName = $Matches[1].Trim()
$ROCmGpuLabel = "AMD ROCm ($ROCmGpuName)"
} else {
$ROCmGpuLabel = "AMD ROCm"
}
}
}
} catch {}
}
}
# WMI gives a marketing name, never a gfx arch, so $HasROCm stays false.
if (-not $HasROCm) {
try {
# Keep every AMD adapter (a shadowing iGPU can lead). Error code 0 only, so a broken dGPU cannot win.
$amdGpus = @(Get-CimInstance Win32_VideoController -ErrorAction SilentlyContinue |
Where-Object { $_.Name -match "AMD|Radeon" })
$healthyGpus = @($amdGpus | Where-Object {
($null -eq $_.ConfigManagerErrorCode) -or ($_.ConfigManagerErrorCode -eq 0) })
# Fall back to all adapters if none is healthy (code 45 is routine for a parked dGPU).
# @() wraps the WHOLE if: a one-element array unrolls and .Count is $null on 5.1.
$wmiGpus = @(if ($healthyGpus.Count -gt 0) { $healthyGpus } else { $amdGpus })
if ($wmiGpus.Count -gt 0) {
$script:ROCmGpuLabels = @($wmiGpus | ForEach-Object { $_.Name })
$ROCmGpuLabel = $script:ROCmGpuLabels[0]
$ROCmGpuName = $script:ROCmGpuLabels[0]
}
} catch {}
}
# Peer names for the REPORT ONLY; feeding them to inference changed CPU installs to ROCm.
$script:ROCmPeerLabels = @()
if ($HasROCm -and -not $script:ROCmGfxArch) {
try {
$peerGpus = @(Get-CimInstance Win32_VideoController -ErrorAction SilentlyContinue |
Where-Object { $_.Name -match "AMD|Radeon" })
$healthyPeers = @($peerGpus | Where-Object {
($null -eq $_.ConfigManagerErrorCode) -or ($_.ConfigManagerErrorCode -eq 0) })
$usePeers = @(if ($healthyPeers.Count -gt 0) { $healthyPeers } else { $peerGpus })
$script:ROCmPeerLabels = @($usePeers | ForEach-Object { $_.Name })
} catch {}
}
# Name -> arch for generations no ROCm wheel covers; only words a message, never selects an index.
$unsupportedNameArchTable = @(
@{ P = "RX 4[78]0(?!0)|RX 5[789]0(?!0)|Radeon Pro WX 7100|Radeon Pro WX 5100"; A = "gfx803" } # Polaris 10/20/30
)
$script:ROCmUnsupportedGfxArch = $null
# ── Arch resolution: env-var override → name inference ──────────────────
# Runs even without a confirmed runtime: the Adrenalin driver alone runs the per-gfx llama.cpp
# prebuilt, which only needs the arch. PyTorch ROCm wheels stay gated on $HasROCm.
if (-not $script:ROCmGfxArch) {
if ($env:UNSLOTH_ROCM_GFX_ARCH) {
$script:ROCmGfxArch = ($env:UNSLOTH_ROCM_GFX_ARCH.Trim().ToLower() -split ':')[0] # drop HIP feature suffixes (gfx1010:xnack-)
$ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $script:ROCmGfxArch" "Cyan"
}
# Name -> arch, most-specific first; unknown names fall back to CPU.
elseif ($ROCmGpuLabel) {
$nameArchTable = @(
@{ P = "9070|9080|R9700"; A = "gfx1201" } # RDNA 4 (Navi 48: Radeon RX 9070 XT / 9070 GRE / 9070 / 9080, Radeon AI PRO R9700)
@{ P = "9060"; A = "gfx1200" } # RDNA 4 (Navi 44: Radeon RX 9060 XT / 9060)
@{ P = "8065S|8060S|8050S|8040S|Strix Halo|Ryzen AI Max|AI Max"; A = "gfx1151" } # RDNA 3.5 (Strix Halo + Gorgon Halo: Radeon 8065S/8060S/8050S/8040S iGPU, Ryzen AI Max / Max+)
@{ P = "890M|880M|Strix Point|HX 37[05]|AI 9 HX|AI 9 36[05]"; A = "gfx1150" } # RDNA 3.5 (Strix Point: Radeon 890M/880M, Ryzen AI 9 HX 370/375)
@{ P = "860M|840M|Krackan|AI 7 35[05]|AI 5 34[05]|AI 7 PRO 35|AI 5 33"; A = "gfx1152" } # RDNA 3.5 (Krackan Point: Radeon 860M/840M, Ryzen AI 7 350 / AI 5 340)
@{ P = "RX 7900|PRO W7900|PRO W7800"; A = "gfx1100" } # RDNA 3 desktop / workstation (Navi 31)
@{ P = "RX 7800|RX 7700(?!S)|PRO W7700|PRO V710"; A = "gfx1101" } # RDNA 3 (Navi 32)
@{ P = "RX 7600|RX 7700S|RX 7650|PRO W7600|PRO W7500"; A = "gfx1102" } # RDNA 3 (Navi 33)
@{ P = "780M|760M|740M|Phoenix|Hawk Point|Z1 Extreme|Z2 Extreme"; A = "gfx1103" } # RDNA 3 iGPU (Phoenix / Hawk Point)
@{ P = "RX 6950|RX 6900|RX 6850|RX 6800|RX 6750|RX 6700|PRO W6800|PRO W6900"; A = "gfx1030" } # RDNA 2 (Navi 21) -- gfx103X family
@{ P = "RX 6650|RX 6600|PRO W6600|PRO W6650"; A = "gfx1032" } # RDNA 2 (Navi 23) -- gfx103X family
@{ P = "RX 6550|RX 6500|RX 6450|RX 6400|RX 6300|PRO W6400|PRO W6500|PRO W6300"; A = "gfx1034" } # RDNA 2 (Navi 24) -- gfx103X family
@{ P = "Radeon Pro V520|Radeon Pro 5600M"; A = "gfx1011" } # RDNA 1 (Navi 12) -- multi-arch index
@{ P = "RX 5700|RX 5600|Radeon Pro 5600 XT|Radeon Pro 5700|Radeon Pro W5700"; A = "gfx1010" } # RDNA 1 (Navi 10) -- multi-arch index
@{ P = "RX 5500|RX 5300|Radeon Pro W5500|Radeon Pro W5300"; A = "gfx1012" } # RDNA 1 (Navi 14) -- multi-arch index
)
function Get-GfxArchFromGpuName {
param([AllowNull()][string]$Name, [object[]]$Table)
if (-not $Name) { return $null }
foreach ($row in $Table) { if ($Name -match $row.P) { return $row.A } }
return $null
}
# @() wraps the WHOLE if: a one-element branch unrolls to a String and indexing yields a character.
$gpuNames = @(if ($script:ROCmGpuLabels) { @($script:ROCmGpuLabels) } else { @($ROCmGpuLabel) })
# Index over the ADAPTER list, not the shorter inferred-arch list.
$nameIdx = Resolve-VisibleGpuIndex $gpuNames.Count
$nameArches = @()
$nameArchSrc = @()
for ($_gi = 0; $_gi -lt $gpuNames.Count; $_gi++) {
$inferred = Get-GfxArchFromGpuName -Name $gpuNames[$_gi] -Table $nameArchTable
if ($inferred) { $nameArches += $inferred; $nameArchSrc += $_gi }
}
$pickedName = Get-GfxArchFromGpuName -Name $gpuNames[$nameIdx] -Table $nameArchTable
# Borrow another adapter's arch only when unpinned; under a mask that would target a hidden GPU.
$_archSrcIdx = -1
if (-not $pickedName -and -not (Test-VisibleDevicesPinned) -and $nameArches.Count -gt 0) {
$pickedName = $nameArches[0]
$_archSrcIdx = $nameArchSrc[0]
}
# Spelled with -and: a bare `if ($pickedName) {` is TestSetupPs1ShadowingParity's end anchor.
if ($pickedName -and $_archSrcIdx -lt 0) { $_archSrcIdx = $nameIdx }
if ($pickedName) {
# Repick only when every adapter mapped: an unknown name may BE the discrete card.
$script:ROCmGfxArch = if ($nameArches.Count -eq $gpuNames.Count) {
Resolve-ShadowingGfxPick -Picked $pickedName -AllArches $nameArches
} else { $pickedName }
$ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
# Move the banner name onto the adapter the arch actually came from.
if ($nameArches.Count -eq $gpuNames.Count) {
# Keep $nameIdx when its arch is the pick: IndexOf returns the first of duplicate arches.
$_nameArchIdx = if ($nameIdx -lt $nameArches.Count -and $nameArches[$nameIdx] -eq $script:ROCmGfxArch) {
$nameIdx
} else {
[array]::IndexOf($nameArches, $script:ROCmGfxArch)
}
if ($_nameArchIdx -ge 0) { $ROCmGpuName = $gpuNames[$_nameArchIdx] }
} elseif ($_archSrcIdx -ge 0) {
$ROCmGpuName = $gpuNames[$_archSrcIdx]
}
substep "gfx arch inferred from GPU name: $script:ROCmGfxArch" "Cyan"
substep "Tip: set UNSLOTH_ROCM_GFX_ARCH=$script:ROCmGfxArch to skip inference next time" "Cyan"
} else {
# Nothing mapped: maybe a generation ROCm never covered. Wording only, and quiet when a peer is
# covered. HIP/ROCR masks only: CUDA_VISIBLE_DEVICES says nothing about Radeons.
$unsupMasked = @($env:HIP_VISIBLE_DEVICES, $env:ROCR_VISIBLE_DEVICES) |
Where-Object { $null -ne $_ }
$unsupPeerCovered = $false
if ($unsupMasked) {
# Under a mask a peer cannot answer for the named card; an unseen peer gives no verdict.
$unsupPeerCovered = ($script:ROCmPeerLabels.Count -gt $gpuNames.Count)
} else {
foreach ($peerName in $script:ROCmPeerLabels) {
if (Get-GfxArchFromGpuName -Name $peerName -Table $nameArchTable) {
$unsupPeerCovered = $true
break
}
}
}
if (-not $unsupPeerCovered) {
$script:ROCmUnsupportedGfxArch = Get-GfxArchFromGpuName -Name $gpuNames[$nameIdx] -Table $unsupportedNameArchTable
}
}
}
}
# Last resort: the arch install.ps1 just resolved (private handoff, never UNSLOTH_ROCM_GFX_ARCH).
# Skipped under a mask: the installer's scan ignores masks and would name the first adapter.
if (-not $script:ROCmGfxArch -and $env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF -and
-not (Test-VisibleDevicesPinned)) {
$script:ROCmGfxArch = $env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF.Trim().ToLower()
$ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
substep "gfx arch forwarded by the installer: $script:ROCmGfxArch" "Cyan"
}
# hipconfig --version works even when hipinfo sees no device.
if ($HasROCm -or $HipSdkInstalled) {
$script:ROCmVersion = $null
$hipConfigExe = Get-Command hipconfig -ErrorAction SilentlyContinue
if (-not $hipConfigExe) {
$hipRoot = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { $null }
if ($hipRoot) {
$hipConfigCandidate = Join-Path $hipRoot "bin\hipconfig.exe"
if (Test-Path $hipConfigCandidate) {
$hipConfigEnvLabel = if ($env:HIP_PATH) { "HIP_PATH" } else { "ROCM_PATH" }
substep "[WARN] hipconfig not on PATH -- located via ${hipConfigEnvLabel}: $hipConfigCandidate" "Yellow"
$hipConfigExe = [PSCustomObject]@{ Source = $hipConfigCandidate }
}
}
}
if ($hipConfigExe) {
try {
$hipVerOut = & $hipConfigExe.Source --version 2>&1 | Out-String
if ($LASTEXITCODE -eq 0) {
$hipVerLine = ($hipVerOut -split '\r?\n' | Where-Object { $_.Trim() } | Select-Object -First 1).Trim()
if ($hipVerLine -match '(\d+\.\d+)') {
$script:ROCmVersion = $Matches[1]
$script:ROCmVersionFull = $hipVerLine
}
}
} catch {}
}
if (-not $script:ROCmVersion -and $amdSmiAllowed) {
$amdSmiVer = Get-Command "amd-smi" -ErrorAction SilentlyContinue
if ($amdSmiVer) {
try {
$smiVerOut = Invoke-AmdSmiNoElevate $amdSmiVer.Source @('version')
if ($LASTEXITCODE -eq 0 -and $smiVerOut -match 'ROCm version:\s*(\d+\.\d+)') { $script:ROCmVersion = $Matches[1] }
} catch {}
}
}
# Last resort: the SDK root itself is versioned (...\AMD\ROCm\7.1).
if (-not $script:ROCmVersion) {
$hipVersionedRoot = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { $null }
if ($hipVersionedRoot -match '[\\/](\d+\.\d+(?:\.\d+)?)[\\/]?$') { $script:ROCmVersion = $Matches[1] }
}
}
}
# Arches with AMD Windows ROCm wheels. Hoisted above the Intel scan, which needs it.
# test_rocm_arch_table_parity.py keeps it in sync with $archFamilyMap.
$_rocmWheelArches = @(
"gfx1201", "gfx1200", # RDNA 4
"gfx1151", "gfx1150", "gfx1152", "gfx1153", # RDNA 3.5 (Strix Halo/Point, Krackan Point)
"gfx1103", "gfx1102", "gfx1101", "gfx1100", # RDNA 3
"gfx1036", "gfx1035", "gfx1034", "gfx1033", "gfx1032", "gfx1031", "gfx1030", # RDNA 2 (RX 6000)
"gfx1012", "gfx1011", "gfx1010", # RDNA 1 (RX 5000): AMD's multi-arch index (unslothai#11755)
"gfx90a", "gfx908" # MI200 / MI100
)
# "AMD gets GPU wheels", not "AMD GPU present": unmapped arches install CPU torch.
$AmdHasGpuWheels = [bool]($script:ROCmGfxArch -and ($_rocmWheelArches -contains $script:ROCmGfxArch))
# Mirrors install.ps1's Intel scan; self-contained since `studio update` runs setup.ps1 standalone.
$script:IsIntelXpu = $false
# Steers the INSTALL, not the hardware report.
$script:PreservedXpuVenv = $false
# Declared here: read on every run, assigned only on some (StrictMode).
$script:PreservedInstallerTorchTag = $null
$IntelGpuLabel = $null
if (-not $HasNvidiaSmi -and -not $AmdHasGpuWheels) {
try {
# Bounded; registry fallback when WMI does not answer.
$_gpuScan = Invoke-BoundedVideoControllerScan
# @() wraps the WHOLE if: a one-element array unrolls to a String.
$_gpuNames = @(if ($_gpuScan.Ok) { $_gpuScan.Names } else { Get-IntelRegistryAdapterNames })
$_xpuNameRe = "(?i)Intel.*(Arc|Data Center GPU)"
# Non-English WMI names lack "Intel": re-label (never add) adapters via the registry vendor id.
if ($_gpuScan.Ok -and -not ($_gpuNames | Where-Object { $_ -match $_xpuNameRe })) {
foreach ($_reg in @(Get-IntelRegistryAdapterNames)) {
foreach ($_wmiName in $_gpuNames) {
if ($_wmiName -and $_reg.Contains($_wmiName)) { $_gpuNames += $_reg; break }
}
}
}
$xpuGpu = $_gpuNames | Where-Object { $_ -match $_xpuNameRe } | Select-Object -First 1
if ($xpuGpu) { $script:IsIntelXpu = $true; $IntelGpuLabel = $xpuGpu }
} catch {}
# No adapter recognised: an installed +xpu wheel whose runtime works proves the host.
if (-not $script:IsIntelXpu) {
try {
$_probeVenv = Get-ProbableStudioVenvDir
if (Test-VenvTorchIsXpu $_probeVenv) {
$_probePy = Join-Path $_probeVenv "Scripts\python.exe"
if (Test-TorchXpuAvailable -PythonExe $_probePy) {
$script:IsIntelXpu = $true
$IntelGpuLabel = "Intel XPU runtime (reported by PyTorch)"
}
}
} catch {}
}
}
$ROCmGpuDisplay =
if ($ROCmGpuName -and $script:ROCmGfxArch) { "$ROCmGpuName ($script:ROCmGfxArch)" }
elseif ($ROCmGpuName) { $ROCmGpuName }
elseif ($script:ROCmGfxArch) { "AMD ROCm ($script:ROCmGfxArch)" }
else { $ROCmGpuLabel }
$NvidiaGpuDisplay =
if ($NvidiaGpuName -and $NvidiaSmArch) { "$NvidiaGpuName ($NvidiaSmArch)" }
elseif ($NvidiaGpuName) { $NvidiaGpuName }
else { "NVIDIA GPU detected" }
$IntelGpuDisplay = if ($IntelGpuLabel) { $IntelGpuLabel } else { "Intel GPU detected" }
if ($HasNvidiaSmi) {
step "gpu" $NvidiaGpuDisplay
if ($NvidiaDriverVersion) { substep "Driver: $NvidiaDriverVersion" }
} elseif ($script:IsIntelXpu) {
# Only true when AMD gets no GPU wheel, so AMD branches would end on CPU torch.
Write-StudioLine ""
step "gpu" $IntelGpuDisplay "Green"
substep "PyTorch XPU (SYCL) wheels provide training and GPU inference on this GPU." "Cyan"
Write-StudioLine ""
} elseif ($HasROCm -and -not $script:ROCmUnsupportedGfxArch) {
# amd-smi can set $HasROCm without an arch.
step "gpu" $ROCmGpuDisplay
$hipSdkPath = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { "on system PATH" }
substep "HIP SDK: $hipSdkPath"
if ($script:ROCmVersionFull) { substep "hipconfig: $script:ROCmVersionFull" }
} elseif ($HipSdkInstalled -and $ROCmGpuLabel -and -not $script:ROCmUnsupportedGfxArch) {
# HIP SDK installed but ROCm cannot see the device. Excludes known out-of-scope cards.
$sdkVer = if ($script:ROCmVersionFull) { " (HIP $script:ROCmVersionFull)" } else { "" }
Write-StudioLine ""
step "gpu" "AMD GPU detected -- not ROCm-accessible$sdkVer" "Yellow"
substep "Detected: $ROCmGpuLabel" "Yellow"
substep "[WARN] HIP SDK is installed but hipinfo reports no ROCm-capable device." "Yellow"
substep " This is a driver issue, not an SDK issue." "Yellow"
substep " Ensure the ROCm compute driver is installed alongside the display driver:" "Yellow"
substep " https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
} elseif ($script:ROCmGfxArch) {
# Known arch: AMD's ROCm wheels bundle their own runtime, so the HIP SDK is optional.
Write-StudioLine ""
step "gpu" $ROCmGpuDisplay "Cyan"
substep "Detected: $ROCmGpuLabel" "Cyan"
substep "GPU PyTorch uses AMD's bundled-runtime ROCm wheels -- HIP SDK not required (optional)." "Cyan"
Write-StudioLine ""
} elseif ($script:ROCmUnsupportedGfxArch) {
# Detected, identified, out of scope for ROCm PyTorch. Ranks above the "arch
# unknown" arm below: the arch is known here, and that arm's advice cannot succeed
# on this GPU (unslothai#8529).
Write-StudioLine ""
step "gpu" "AMD GPU detected ($script:ROCmUnsupportedGfxArch) -- no ROCm PyTorch wheels Unsloth installs" "Yellow"
substep "Detected: $ROCmGpuLabel" "Yellow"
# Not "training runs on CPU": with no CUDA/XPU visible, unsloth raises
# NotImplementedError at import (unsloth/device_type.py). The Vulkan setter is
# single-quoted so PowerShell prints $env:... rather than expanding it; a pasted
# VAR=value resolves as a command name here and sets nothing.
# Conditional: an explicit index pin is honoured for any arch.
$unsupPinned = (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_URL)) -or `
(-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_FAMILY))
if ($unsupPinned) {
substep "Unsloth ships no ROCm PyTorch wheels for $script:ROCmUnsupportedGfxArch, but the torch" "Yellow"
substep "index you pinned is used as given, so torch is whatever it publishes." "Yellow"
} else {
substep "Unsloth installs no ROCm PyTorch wheels for $script:ROCmUnsupportedGfxArch, so torch stays" "Yellow"
substep "CPU-only: Unsloth training and GPU inference are unavailable. Installing the" "Yellow"
substep "HIP SDK or setting UNSLOTH_ROCM_GFX_ARCH will not change that for it." "Yellow"
}
substep "GGUF chat can still use this GPU through Vulkan: set" "Yellow"
substep '$env:UNSLOTH_LLAMA_CPP_BACKEND = "vulkan" and re-run the installer. It selects' "Yellow"
substep "the llama.cpp bundle at install time, so setting it afterwards has no effect" "Yellow"
substep "until you install or update again." "Yellow"
Write-StudioLine ""
} elseif ($ROCmGpuLabel) {
Write-StudioLine ""
step "gpu" "AMD GPU detected -- arch unknown" "Yellow"
substep "Detected: $ROCmGpuLabel" "Yellow"
substep "Could not determine the GPU arch (gfx...). Install the HIP SDK or set" "Yellow"
substep "UNSLOTH_ROCM_GFX_ARCH to enable GPU ROCm PyTorch:" "Yellow"
substep "https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
Write-StudioLine ""
} else {
Write-StudioLine ""
step "gpu" "none (chat-only / GGUF)" "Yellow"
substep "Training and GPU inference require an NVIDIA, AMD ROCm, or Intel Arc GPU." "Yellow"
Write-StudioLine ""
}
# ============================================
# ============================================
$LongPathsEnabled = $false
try {
$regVal = Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -ErrorAction SilentlyContinue
if ($regVal -and $regVal.LongPathsEnabled -eq 1) {
$LongPathsEnabled = $true
}
} catch {}
if ($LongPathsEnabled) {
step "long paths" "enabled"
} elseif ($StageRoot) {
step "long paths" "disabled; unchanged during staging" "Yellow"
} elseif ($env:UNSLOTH_SETUP_RERUN -eq '1') {
step "long paths" "disabled; already asked earlier in this update" "Yellow"
} elseif ($env:UNSLOTH_SKIP_LONG_PATHS -eq '1') {
# Declined on the desktop app's explainer: no second UAC.
step "long paths" "disabled; skipped at your request" "Yellow"
substep "torch.compile / Triton may fail on very long paths. To enable later, in an Admin terminal:" "Yellow"
substep 'reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f' "Yellow"
} else {
Write-StudioLine "Windows Long Paths not enabled (required for Triton compilation and deep dependency paths)." -ForegroundColor Yellow
Write-StudioLine " This turns on LongPathsEnabled under HKLM, a machine-wide setting, so Windows asks for admin approval." -ForegroundColor Yellow
Write-StudioLine " Windows will show a 'Registry Console Tool' prompt (reg.exe, verified publisher Microsoft Windows)." -ForegroundColor Yellow
Write-StudioLine " Requesting admin access to fix..." -ForegroundColor Yellow
try {
# The system directory itself, not a PATH lookup: this is the binary the prompt names.
$proc = Start-Process -FilePath "$([Environment]::SystemDirectory)\reg.exe" `
-ArgumentList 'add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f' `
-Verb RunAs -Wait -PassThru -ErrorAction Stop
if ($proc.ExitCode -eq 0) {
$LongPathsEnabled = $true
step "long paths" "enabled (via UAC)"
} else {
step "long paths" "failed to enable (exit code: $($proc.ExitCode))" "Yellow"
}
} catch {
step "long paths" "could not enable (UAC declined/unavailable)" "Yellow"
Write-StudioLine " Run this manually in an Admin terminal:" -ForegroundColor Yellow
Write-StudioLine ' reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f' -ForegroundColor Cyan
}
}
# ============================================
# ============================================
# Git is required only for --local / source installs; the consumer path uses neither pip VCS nor npm git.
$HasGit = $null -ne (Get-Command git -ErrorAction SilentlyContinue)
if (-not $HasGit) {
# Fatal only for --local and the opt-in llama.cpp source build, unless a local dir has a binary.
$gitNeeded = ($env:STUDIO_LOCAL_INSTALL -eq '1')
$_localLlamaDir = if ($env:UNSLOTH_LOCAL_LLAMA_CPP_DIR) { $env:UNSLOTH_LOCAL_LLAMA_CPP_DIR.Trim() } else { "" }
$_localLlamaBuilt = $false
if ($_localLlamaDir) {
# Same layout candidates as the reuse check in Phase 4.
foreach ($_c in @("llama-server.exe", "build\bin\llama-server.exe", "build\bin\Release\llama-server.exe")) {
# A denial here must not terminate under Stop.
$_cState = Get-PathState -Path (Join-Path $_localLlamaDir $_c)
if ($_cState -eq "Denied") {
Exit-PathAccessDenied -Path $_localLlamaDir -Label "the UNSLOTH_LOCAL_LLAMA_CPP_DIR build" -UserSupplied
}
if ($_cState -eq "Present") { $_localLlamaBuilt = $true; break }
}
}
if (-not $_localLlamaBuilt) {
$_prForce = if ($env:UNSLOTH_LLAMA_PR_FORCE) { $env:UNSLOTH_LLAMA_PR_FORCE.Trim() } else { $DefaultLlamaPrForce }
$_llamaSrc = $DefaultLlamaSource -replace '\.git$', ''
# Same tag resolution as Phase 4; "master" always builds from source.
$_llamaTag = if ($env:UNSLOTH_LLAMA_TAG) { $env:UNSLOTH_LLAMA_TAG } else { $DefaultLlamaTag }
if ($_llamaTag -eq "master") { $gitNeeded = $true }
if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq '1') { $gitNeeded = $true }
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_LLAMA_PR)) { $gitNeeded = $true }
# Same positive-integer predicate as the PR_FORCE promotion below.
if ($_prForce -match '^\d+$' -and [int]$_prForce -gt 0) { $gitNeeded = $true }
if ($_llamaSrc -ne "https://github.com/ggml-org/llama.cpp") { $gitNeeded = $true }
}
if ($gitNeeded -and $StageRoot) {
Exit-SetupFailure "Background staging cannot install Git; retry with the foreground updater."
}
# Only when something here clones: a machine-wide Git install is not ours to add otherwise.
if ($gitNeeded) {
Write-StudioLine "Git not found -- attempting install via winget..." -ForegroundColor Yellow
$HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
if ($HasWinget) {
try {
Invoke-SetupCommand { winget install Git.Git --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
Refresh-Environment
$HasGit = $null -ne (Get-Command git -ErrorAction SilentlyContinue)
} catch { }
}
}
if (-not $HasGit) {
if ($gitNeeded) {
Write-StudioLine "[ERROR] Git is required for --local and llama.cpp source-build installs but could not be installed." -ForegroundColor Red
Write-StudioLine " --local clones unsloth-zoo, and a source build clones llama.cpp." -ForegroundColor Red
Write-StudioLine " Install Git from https://git-scm.com/download/win and re-run." -ForegroundColor Red
Exit-SetupFailure "Git is required for --local / source-build installs but could not be installed"
}
step "git" "not found (not required)" "Yellow"
substep "Unsloth installs prebuilt binaries and wheels, so git is not needed."
substep "Install it only for --local/source installs: https://git-scm.com/download/win"
} else {
step "git" "$(git --version)"
}
} else {
step "git" "$(git --version)"
}
# ============================================
# Visual C++ Redistributable: runtime for the prebuilt llama.cpp + PyTorch.
# ============================================
Ensure-VCRedist
# ============================================
# CMake detection only; a source build gets it from Ensure-BuildToolsForLlamaSourceBuild.
# ============================================
$HasCmake = $null -ne (Get-Command cmake -ErrorAction SilentlyContinue)
if ($HasCmake) {
step "cmake" "$(cmake --version | Select-Object -First 1)"
} else {
step "cmake" "not detected (only needed if a llama.cpp source build is required)" "Yellow"
}
# ============================================
# ============================================
$CmakeGenerator = $null
$VsInstallPath = $null
$vsResult = Find-VsBuildTools
if ($vsResult) {
$CmakeGenerator = $vsResult.Generator
$VsInstallPath = $vsResult.InstallPath
step "vs" "$CmakeGenerator ($($vsResult.Source)) (only used if a source build is needed)"
if ($vsResult.ClExe) { substep "cl.exe: $($vsResult.ClExe)" }
} else {
step "vs" "not detected (only needed if a llama.cpp source build is required)" "Yellow"
}
# ============================================
# ============================================
# Lazy: the prebuilt path needs no local toolkit. -RequireOrExit hard-fails when none is found.
function Resolve-CudaToolkit {
param([switch]$RequireOrExit)
# Toolkit major must be <= the driver's max CUDA major.
$DriverMaxCuda = $null
try {
# test_resolve_cuda_toolkit.ps1 extracts this function alone, without Invoke-NvidiaSmiBounded.
$smiOut = if (-not $NvidiaSmiExe) {
""
} elseif (Get-Command Invoke-NvidiaSmiBounded -ErrorAction SilentlyContinue) {
Invoke-NvidiaSmiBounded $NvidiaSmiExe
} else {
& $NvidiaSmiExe 2>&1 | Out-String
}
if ($smiOut -match "CUDA(?: UMD)? Version:\s+([\d]+)\.([\d]+)") {
$DriverMaxCuda = "$($Matches[1]).$($Matches[2])"
substep "driver supports up to CUDA $DriverMaxCuda"
}
} catch {}
if (-not $DriverMaxCuda -and (Get-Command Get-NvidiaLibraryInventory -ErrorAction SilentlyContinue)) {
$inventory = Get-NvidiaLibraryInventory
if ($inventory) {
$DriverMaxCuda = "$($inventory.CudaMajor).$($inventory.CudaMinor)"
substep "driver supports up to CUDA $DriverMaxCuda (driver library)"
}
}
$CudaArch = Get-CudaComputeCapability
if ($CudaArch) {
substep "GPU Compute Capability = $($CudaArch.Insert($CudaArch.Length-1, '.')) (sm_$CudaArch)"
}
$IncompatibleToolkit = $null
$NvccPath = $null
if ($DriverMaxCuda) {
$drMajorCuda = [int]$DriverMaxCuda.Split('.')[0]
$existingCudaPath = [Environment]::GetEnvironmentVariable('CUDA_PATH', 'Machine')
if (-not $existingCudaPath) {
$existingCudaPath = [Environment]::GetEnvironmentVariable('CUDA_PATH', 'User')
}
if ($existingCudaPath -and (Test-Path (Join-Path $existingCudaPath 'bin\nvcc.exe'))) {
$candidateNvcc = Join-Path $existingCudaPath 'bin\nvcc.exe'
$verOut = & $candidateNvcc --version 2>&1 | Out-String
if ($verOut -match 'release\s+(\d+)\.(\d+)') {
$tkMaj = [int]$Matches[1]; $tkMin = [int]$Matches[2]
$isCompat = ($tkMaj -le $drMajorCuda)
if ($isCompat) {
$archOk = $true
if ($CudaArch) {
$archOk = Test-NvccArchSupport -NvccExe $candidateNvcc -Arch $CudaArch
if (-not $archOk) {
substep "CUDA_PATH toolkit (CUDA $tkMaj.$tkMin) does not support GPU arch sm_$CudaArch" "Yellow"
substep "Looking for a newer toolkit..." "Yellow"
}
}
if ($archOk) {
$NvccPath = $candidateNvcc
substep "using existing CUDA Toolkit at CUDA_PATH (nvcc: $NvccPath)"
}
} else {
substep "CUDA_PATH ($existingCudaPath) has CUDA $tkMaj.$tkMin with major $tkMaj, which exceeds driver CUDA major $drMajorCuda ($DriverMaxCuda)" "Yellow"
}
}
}
if (-not $NvccPath) {
$NvccPath = Find-Nvcc -MaxVersion $DriverMaxCuda
if ($NvccPath) {
substep "found compatible CUDA Toolkit (nvcc: $NvccPath)"
if ($existingCudaPath) {
$selectedRoot = Split-Path (Split-Path $NvccPath -Parent) -Parent
if ($existingCudaPath.TrimEnd('\') -ne $selectedRoot.TrimEnd('\')) {
substep "overriding CUDA_PATH from $existingCudaPath to $selectedRoot" "Yellow"
}
}
} else {
$AnyNvcc = Find-Nvcc
if ($AnyNvcc) {
$NvccOut = & $AnyNvcc --version 2>&1 | Out-String
if ($NvccOut -match "release\s+(\d+)\.(\d+)") {
$tkMaj = [int]$Matches[1]; $tkMin = [int]$Matches[2]
if ($tkMaj -le $drMajorCuda) {
$NvccPath = $AnyNvcc
substep "found compatible CUDA Toolkit (nvcc: $NvccPath)"
} else {
$IncompatibleToolkit = "$tkMaj.$tkMin"
}
}
}
}
}
} else {
$NvccPath = Find-Nvcc
}
if (-not $NvccPath -and $IncompatibleToolkit) {
Write-CudaDriverToolkitMismatch -ToolkitVersion $IncompatibleToolkit -DriverMaxCuda $DriverMaxCuda
if (-not $RequireOrExit) {
$script:CudaToolkitReady = $false
return
}
# Only a source build reaches here, so fail (setup.sh degrades to CPU instead).
Write-StudioLine "" -ForegroundColor Red
Write-StudioLine "========================================================================" -ForegroundColor Red
Write-StudioLine "[ERROR] CUDA source build cannot use the installed toolkit with this driver." -ForegroundColor Red
Write-StudioLine "========================================================================" -ForegroundColor Red
Exit-SetupFailure "The installed CUDA toolkit is incompatible with the current driver"
}
# -- No toolkit at all: install via winget (only when a source build needs it) --
if (-not $NvccPath -and $RequireOrExit) {
Write-StudioLine "CUDA toolkit (nvcc) not found -- installing via winget..." -ForegroundColor Yellow
$HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
if ($HasWinget) {
if ($DriverMaxCuda) {
$drMajor = [int]$DriverMaxCuda.Split('.')[0]
$AvailableVersions = @()
try {
$rawOutput = winget show Nvidia.CUDA --versions --source winget --accept-source-agreements 2>&1 | Out-String
foreach ($line in $rawOutput -split "`n") {
$line = $line.Trim()
if ($line -match '^\d+\.\d+') {
$AvailableVersions += $line
}
}
} catch {}
$BestVersion = $null
foreach ($ver in $AvailableVersions) {
$parts = $ver.Split('.')
$vMajor = [int]$parts[0]
if ($vMajor -le $drMajor) {
$BestVersion = $ver
break # list is descending, first match is highest compatible
}
}
if ($BestVersion) {
substep "Installing CUDA Toolkit $BestVersion via winget..."
$prevEAPCuda = $ErrorActionPreference
$ErrorActionPreference = "Continue"
Invoke-SetupCommand { winget install --id=Nvidia.CUDA --version=$BestVersion -e --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
$ErrorActionPreference = $prevEAPCuda
Refresh-Environment
$NvccPath = Find-Nvcc -MaxVersion $DriverMaxCuda
if ($NvccPath) {
substep "CUDA Toolkit $BestVersion installed (nvcc: $NvccPath)"
}
} else {
substep "no compatible CUDA Toolkit version found in winget (need CUDA major <= $drMajor)" "Yellow"
}
} else {
substep "Installing CUDA Toolkit (latest) via winget..."
winget install --id=Nvidia.CUDA -e --source winget --accept-package-agreements --accept-source-agreements
Refresh-Environment
$NvccPath = Find-Nvcc
if ($NvccPath) {
substep "CUDA Toolkit installed (nvcc: $NvccPath)"
}
}
}
}
if (-not $NvccPath) {
if (-not $RequireOrExit) {
substep "no driver-compatible CUDA Toolkit found -- skipping; prebuilt llama.cpp needs no local toolkit" "Yellow"
$script:CudaToolkitReady = $false
return
}
Write-StudioLine "[ERROR] CUDA Toolkit (nvcc) is required but could not be found or installed." -ForegroundColor Red
if ($DriverMaxCuda) {
Write-StudioLine " Install a CUDA Toolkit with major version $($DriverMaxCuda.Split('.')[0]) from https://developer.nvidia.com/cuda-toolkit-archive" -ForegroundColor Yellow
} else {
Write-StudioLine " Install CUDA Toolkit from https://developer.nvidia.com/cuda-downloads" -ForegroundColor Yellow
}
Exit-SetupFailure "A compatible CUDA Toolkit could not be found or installed"
}
# -- Set CUDA env vars so cmake AND MSBuild can find the toolkit --
$CudaToolkitRoot = Split-Path (Split-Path $NvccPath -Parent) -Parent
[Environment]::SetEnvironmentVariable('CUDA_PATH', $CudaToolkitRoot, 'Process')
# MSBuild's CUDA .targets need the trailing backslash.
[Environment]::SetEnvironmentVariable('CudaToolkitDir', "$CudaToolkitRoot\", 'Process')
[Environment]::SetEnvironmentVariable('CUDA_PATH', $CudaToolkitRoot, 'User')
substep "Persisted CUDA_PATH=$CudaToolkitRoot to user environment"
# Clear CUDA_PATH_V* so cmake/MSBuild cannot find a conflicting install.
$cudaPathVars = @([Environment]::GetEnvironmentVariables('Process').Keys | Where-Object { $_ -match '^CUDA_PATH_V' })
foreach ($v in $cudaPathVars) {
[Environment]::SetEnvironmentVariable($v, $null, 'Process')
}
$tkDirName = Split-Path $CudaToolkitRoot -Leaf
if ($tkDirName -match '^v(\d+)\.(\d+)') {
$cudaPathVerVar = "CUDA_PATH_V$($Matches[1])_$($Matches[2])"
[Environment]::SetEnvironmentVariable($cudaPathVerVar, $CudaToolkitRoot, 'Process')
substep "Set $cudaPathVerVar (cleared other CUDA_PATH_V* vars)"
}
$nvccBinDir = Split-Path $NvccPath -Parent
if ($env:PATH -notlike "*$nvccBinDir*") {
[Environment]::SetEnvironmentVariable('PATH', "$nvccBinDir;$env:PATH", 'Process')
}
# Prepend so the driver-compatible toolkit wins.
if (Add-ToUserPath -Directory $nvccBinDir -Position 'Prepend') {
substep "Persisted CUDA bin dir to user PATH"
}
# CUDA installed before VS Build Tools leaves .targets missing: "No CUDA toolset found".
if ($VsInstallPath -and $CudaToolkitRoot) {
$vsCustomizations = Get-VcBuildCustomizationsDir -VsInstallPath $VsInstallPath -Generator $CmakeGenerator
$cudaExtras = Join-Path $CudaToolkitRoot "extras\visual_studio_integration\MSBuildExtensions"
if ((Test-Path $cudaExtras) -and (Test-Path $vsCustomizations)) {
$hasTargets = Get-ChildItem $vsCustomizations -Filter "CUDA *.targets" -ErrorAction SilentlyContinue
if (-not $hasTargets) {
substep "CUDA VS integration missing -- copying .targets files..." "Yellow"
try {
Copy-Item "$cudaExtras\*" $vsCustomizations -Force -ErrorAction Stop
substep "CUDA VS integration files installed"
} catch {
try {
$copyCmd = "Copy-Item '$cudaExtras\*' '$vsCustomizations' -Force"
Start-Process powershell -ArgumentList "-NoProfile -Command $copyCmd" -Verb RunAs -Wait -ErrorAction Stop
$hasTargetsRetry = Get-ChildItem $vsCustomizations -Filter "CUDA *.targets" -ErrorAction SilentlyContinue
if ($hasTargetsRetry) {
substep "CUDA VS integration files installed (elevated)"
} else {
throw "Copy did not produce .targets files"
}
} catch {
substep "could not copy CUDA VS integration files" "Yellow"
substep "The llama.cpp build may fail with 'No CUDA toolset found'." "Yellow"
substep "Manual fix: copy contents of" "Yellow"
substep "$cudaExtras"
substep "into:" "Yellow"
substep "$vsCustomizations"
}
}
}
}
}
step "cuda" $NvccPath
substep "CUDA_PATH = $CudaToolkitRoot"
substep "CudaToolkitDir = $CudaToolkitRoot\"
if (-not $CudaArch) {
substep "could not detect compute capability -- cmake will use defaults" "Yellow"
}
$script:NvccPath = $NvccPath
$script:CudaToolkitRoot = $CudaToolkitRoot
$script:CudaArch = $CudaArch
$script:DriverMaxCuda = $DriverMaxCuda
$script:CudaToolkitReady = $true
}
if ($HasROCm -and -not $script:ROCmUnsupportedGfxArch) {
$rocmVerLabel = if ($script:ROCmVersionFull) { "ROCm $script:ROCmVersionFull" } elseif ($script:ROCmVersion) { "ROCm $script:ROCmVersion" } else { "ROCm (version unknown)" }
step "rocm" $rocmVerLabel
} elseif ($script:ROCmGfxArch) {
step "rocm" "GPU via bundled ROCm wheels ($script:ROCmGfxArch) -- HIP SDK optional" "Cyan"
} elseif ($script:ROCmUnsupportedGfxArch) {
# Do not suggest the HIP SDK: these generations have no ROCm PyTorch wheels.
step "rocm" "AMD GPU detected ($script:ROCmUnsupportedGfxArch) -- no ROCm PyTorch wheels Unsloth installs" "Yellow"
} elseif ($ROCmGpuLabel) {
step "rocm" "AMD GPU detected -- arch unknown; HIP SDK not found" "Yellow"
}
# ============================================
# ============================================
function Get-NodeDecision {
param(
[string]$NodeVersion, # `node -v` output, e.g. v22.17.1 (or empty)
[string]$NpmVersion, # `npm -v` output, e.g. 10.9.2 (or empty)
[string]$SkipInstall, # "1" => never auto-install
[bool]$ManagedOnPath = $false
)
# An inherited managed Node must go through the pin check, even when compatible.
if ($ManagedOnPath -and $SkipInstall -ne "1") { return "bundled" }
$node = ($NodeVersion -replace '^v', '').Trim()
$npm = "$NpmVersion".Trim()
if ($node -match '^\d+\.\d+' -and $npm -match '^\d+') {
$nodeMajor = [int]($node.Split('.')[0])
$nodeMinor = [int]($node.Split('.')[1])
$npmMajor = [int]($npm.Split('.')[0])
$nodeOk = ($nodeMajor -eq 20 -and $nodeMinor -ge 19) -or
($nodeMajor -eq 22 -and $nodeMinor -ge 12) -or
($nodeMajor -ge 23)
if ($nodeOk -and $npmMajor -ge 11) { return "system" }
}
if ($SkipInstall -eq "1") { return "skip" }
return "bundled"
}
function Test-ManagedNodeOnPath {
# Only installer metadata marks it managed (wherever NodeDir is); a bare path match may be a user's link.
$command = Get-Command node -ErrorAction SilentlyContinue
if (-not $command -or -not $command.Path) { return $false }
$parent = Split-Path -Parent $command.Path
return (Test-Path -LiteralPath (Join-Path $parent "UNSLOTH_NODE_PREBUILT_INFO.json") -PathType Leaf)
}
function Test-PackagedFrontend {
param([string]$LocalInstall, [string]$IndexPath, [string]$ProjectFilePath)
# PyPI installs (mode 0) use the release-built dist: wheel mtimes are not build order.
# A pyproject.toml beside studio/ means a source checkout (editable overlay): keep mtime rebuilds.
if ($LocalInstall -ne "0") { return $false }
if ($ProjectFilePath -and (Test-Path -LiteralPath $ProjectFilePath -PathType Leaf)) { return $false }
return (Test-Path -LiteralPath $IndexPath -PathType Leaf)
}
$SkipFrontend = ($env:SKIP_STUDIO_FRONTEND -eq "1")
$NodeOverride = $null
$NodeParent = $null
$NodeDir = $null
$SysNodeVersion = ""
$SysNpmVersion = ""
$NodeSource = $null
$NodeOnPathIsManaged = $false
if (-not $IsPipInstall) {
$_masterRoot = Get-MasterRootOverride
if ($StageRoot) {
$NodeParent = $StageRoot
} elseif ($_masterRoot) {
# Beside studio\, not inside it, as in Get-ManagedLlamaCppDir.
$NodeParent = $_masterRoot
} else {
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) { $NodeOverride = $env:UNSLOTH_STUDIO_HOME.Trim() }
elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) { $NodeOverride = $env:STUDIO_HOME.Trim() }
if ($NodeOverride) {
if ($NodeOverride -eq "~") {
$NodeOverride = $env:USERPROFILE
} elseif ($NodeOverride -like "~/*" -or $NodeOverride -like "~\*") {
$NodeOverride = (Join-Path $env:USERPROFILE $NodeOverride.Substring(1).TrimStart('/', '\'))
}
if (-not (Test-Path -LiteralPath $NodeOverride -PathType Container)) {
Write-StudioLine "ERROR: UNSLOTH_STUDIO_HOME/STUDIO_HOME=$NodeOverride does not exist." -ForegroundColor Red
Write-StudioLine " Run install.ps1 to create the install root before 'unsloth studio update'." -ForegroundColor Red
Exit-SetupFailure "UNSLOTH_STUDIO_HOME/STUDIO_HOME=$NodeOverride does not exist"
}
$NodeParent = (Resolve-Path -LiteralPath $NodeOverride).Path
$_legacyStudio = Join-Path $env:USERPROFILE ".unsloth\studio"
if (Test-Path -LiteralPath $_legacyStudio -PathType Container) {
$_legacyStudio = (Resolve-Path -LiteralPath $_legacyStudio).Path
}
if ($NodeParent -eq $_legacyStudio) {
$NodeParent = Join-Path $env:USERPROFILE ".unsloth"
$NodeOverride = $null
}
} else {
$NodeParent = Join-Path $env:USERPROFILE ".unsloth"
}
}
$NodeDir = Join-Path $NodeParent "node"
# Under Stop a bare `node -v` throws past 2>$null.
$SysNodeVersion = try { if (Get-Command node -ErrorAction SilentlyContinue) { (node -v 2>$null) } else { "" } } catch { "" }
$SysNpmVersion = try { if (Get-Command npm -ErrorAction SilentlyContinue) { (npm -v 2>$null) } else { "" } } catch { "" }
$NodeOnPathIsManaged = Test-ManagedNodeOnPath
$NodeSource = Get-NodeDecision -NodeVersion "$SysNodeVersion" -NpmVersion "$SysNpmVersion" `
-SkipInstall "$($env:UNSLOTH_SKIP_NODE_INSTALL)" -ManagedOnPath $NodeOnPathIsManaged
}
if ($IsPipInstall) {
step "frontend" "bundled (pip install)"
} elseif ($SkipFrontend) {
step "frontend" "bundled (Tauri)"
} else {
if ($NodeSource -eq "system") {
substep "Node $SysNodeVersion and npm $SysNpmVersion already meet requirements (system)."
} elseif ($NodeSource -eq "bundled" -and $NodeOnPathIsManaged) {
substep "Checking the isolated Node against the configured version (system Node/npm left untouched)."
} elseif ($NodeSource -eq "bundled") {
substep "Node='$SysNodeVersion' npm='$SysNpmVersion' unsuitable; will use an isolated Node (system left untouched)."
} else {
substep "Node='$SysNodeVersion' npm='$SysNpmVersion' unsuitable and UNSLOTH_SKIP_NODE_INSTALL set; frontend build will be skipped." "Yellow"
}
}
# Conda CPython breaks torch's c10.dll; a venv from it inherits base_prefix, so check both.
$CondaSkipPattern = '(?i)(conda|miniconda|anaconda|miniforge|mambaforge)'
function Test-IsConda {
param([string]$Exe)
if ($Exe -match $CondaSkipPattern) { return $true }
try {
$basePrefix = (& $Exe -c "import sys; print(sys.base_prefix)" 2>$null | Out-String).Trim()
if ($basePrefix -match $CondaSkipPattern) { return $true }
} catch { }
return $false
}
# Python >= 3.11, < 3.14. Prefer the validated venv python over a stub-led PATH probe.
function Resolve-ReusedSetupPython {
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_SETUP_PYTHON) -and
(Test-Path -LiteralPath $env:UNSLOTH_SETUP_PYTHON)) {
return $env:UNSLOTH_SETUP_PYTHON
}
# Root preflight already applied the overrides, including any staged update.
$venvPy = Join-Path $VenvDir "Scripts\python.exe"
if (Test-Path -LiteralPath $venvPy) { return $venvPy }
return $null
}
$ReusedSetupPython = Resolve-ReusedSetupPython
$HasPython = $null -ne (Get-Command python -ErrorAction SilentlyContinue)
$PythonOk = $false
$DetectedPyVer = $null
function Get-CompatiblePythonVersion {
param([string]$PythonExe)
try {
$out = & $PythonExe --version 2>&1 | Out-String
if ($out -match 'Python (3\.(11|12|13)(\.\d+)?)') {
return $Matches[1]
}
} catch { }
return $null
}
function Add-PythonDirToProcessPath {
param([string]$PythonExe)
try {
if ($PythonExe -and (Test-Path -LiteralPath $PythonExe)) {
$resolvedDir = Split-Path -Parent $PythonExe
$alreadyOnPath = ($env:PATH -split ';' | Where-Object { $_.TrimEnd('\') -ieq $resolvedDir.TrimEnd('\') }).Count -gt 0
if (-not $alreadyOnPath) {
$env:PATH = "$resolvedDir;$env:PATH"
}
$script:HasPython = $true
}
} catch { }
}
$ValidatedSetupPython = $null
if ($ReusedSetupPython) {
$_reusedVer = Get-CompatiblePythonVersion $ReusedSetupPython
if ($_reusedVer -and -not (Test-IsConda $ReusedSetupPython)) {
$DetectedPyVer = $_reusedVer
Add-PythonDirToProcessPath $ReusedSetupPython
$PythonOk = $true
$ValidatedSetupPython = $ReusedSetupPython
}
}
# -All: PS 5.1 returns only the first py launcher without it.
$PyLaunchers = if ($PythonOk) { @() } else { @(Get-Command py -All -CommandType Application -ErrorAction SilentlyContinue) }
foreach ($PyLauncher in $PyLaunchers) {
if ($PyLauncher.Source -match $CondaSkipPattern) { continue }
foreach ($minor in @("3.13", "3.12", "3.11")) {
try {
$out = & $PyLauncher.Source "-$minor" --version 2>&1 | Out-String
if ($out -match 'Python (3\.\d+\.\d+)') {
$DetectedPyVer = $Matches[1]
# A py-launcher-only install would crash on bare `python`.
try {
$resolvedExe = (& $PyLauncher.Source "-$minor" -c "import sys; print(sys.executable)" 2>$null | Select-Object -First 1)
if ($resolvedExe -and (Test-Path $resolvedExe)) {
Add-PythonDirToProcessPath $resolvedExe
}
} catch { }
$PythonOk = $true
break
}
} catch { }
}
if ($PythonOk) { break }
}
if (-not $PythonOk -and $HasPython) {
$PyVer = python --version 2>&1
if ($PyVer -match "(\d+)\.(\d+)") {
$PyMajor = [int]$Matches[1]; $PyMinor = [int]$Matches[2]
if ($PyMajor -eq 3 -and $PyMinor -ge 11 -and $PyMinor -lt 14) {
$DetectedPyVer = "$PyMajor.$PyMinor"
$PythonOk = $true
}
}
}
if ($PythonOk) {
substep "Python $DetectedPyVer"
} elseif (-not $HasPython) {
Write-StudioLine "Python 3.11-3.13 not found -- installing Python 3.12 via winget..." -ForegroundColor Yellow
$HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
if ($HasWinget) {
winget install -e --id Python.Python.3.12 --source winget --accept-package-agreements --accept-source-agreements
Refresh-Environment
}
$HasPython = $null -ne (Get-Command python -ErrorAction SilentlyContinue)
if (-not $HasPython) {
Write-StudioLine "[ERROR] Python could not be installed automatically." -ForegroundColor Red
Write-StudioLine " Install Python 3.12 from https://python.org/downloads/" -ForegroundColor Yellow
Exit-SetupFailure "Python could not be installed automatically"
}
step "python" "$(python --version 2>&1)"
$PythonOk = $true
} else {
Write-StudioLine "[ERROR] No supported Python (3.11-3.13) found on this system." -ForegroundColor Red
Write-StudioLine " py.exe could not locate -3.11/-3.12/-3.13 and `python` on PATH is unsupported." -ForegroundColor Yellow
Write-StudioLine " Install Python 3.12 from https://python.org/downloads/" -ForegroundColor Yellow
Exit-SetupFailure "No supported Python 3.11-3.13 was found"
}
# Add user-scheme Python Scripts dir to PATH (nt_user only, no venv fallback).
$ScriptsDir = python -c "import os, sysconfig; p = sysconfig.get_path('scripts', 'nt_user'); print(p if os.path.exists(p) else '')"
if ($LASTEXITCODE -eq 0 -and $ScriptsDir -and (Test-Path $ScriptsDir)) {
# Append: this dir has other pip scripts; the shim handles unsloth.
if (Add-ToUserPath -Directory $ScriptsDir) {
$ProcessPathEntries = $env:PATH.Split(';')
if (-not ($ProcessPathEntries | Where-Object { $_.TrimEnd('\') -eq $ScriptsDir })) {
$env:PATH = "$ScriptsDir;$env:PATH"
}
substep "Persisted Python Scripts dir to user PATH: $ScriptsDir"
}
}
Write-StudioLine ""
step "system" "prerequisites ready"
Write-StudioLine ""
Invoke-MirrorFallback -SpareOnly
$NpmRegistryArgs = @()
if ($env:UNSLOTH_NPM_REGISTRY) {
$NpmRegistryArgs = @('--registry', $env:UNSLOTH_NPM_REGISTRY)
}
# ==========================================================================
# PHASE 2: Frontend build (skip if pip-installed -- already bundled)
# ==========================================================================
$DistDir = Join-Path $FrontendDir "dist"
$PackagedFrontend = Test-PackagedFrontend `
-LocalInstall "$($env:STUDIO_LOCAL_INSTALL)" `
-IndexPath (Join-Path $DistDir "index.html") `
-ProjectFilePath (Join-Path $PackageDir "pyproject.toml")
# Wheel mtimes are not a freshness signal. Tauri is checked first to match setup.sh's reason.
$NeedFrontendBuild = $true
if ($SkipFrontend) {
$NeedFrontendBuild = $false
step "frontend" "bundled (Tauri)"
} elseif ($IsPipInstall -or $PackagedFrontend) {
$NeedFrontendBuild = $false
step "frontend" "bundled (pip install)"
} elseif (Test-Path $DistDir) {
$DistTime = (Get-Item $DistDir).LastWriteTime
$NewerFile = $null
foreach ($subDir in @("src", "public")) {
$subPath = Join-Path $FrontendDir $subDir
if (Test-Path $subPath) {
$NewerFile = Get-ChildItem -Path $subPath -Recurse -File -ErrorAction SilentlyContinue |
Where-Object { $_.LastWriteTime -gt $DistTime } | Select-Object -First 1
if ($NewerFile) { break }
}
}
if (-not $NewerFile) {
$NewerFile = Get-ChildItem -Path $FrontendDir -File -ErrorAction SilentlyContinue |
Where-Object { $_.Name -ne "bun.lock" -and $_.LastWriteTime -gt $DistTime } |
Select-Object -First 1
}
if ($NewerFile) {
substep "Frontend source changed since last build -- rebuilding..." "Yellow"
} elseif (Test-Path -LiteralPath $FrontendBuildMark) {
# An earlier build that never finished (killed, failed) left its mark: redo it.
substep "Previous frontend build did not finish -- rebuilding..." "Yellow"
} else {
$NeedFrontendBuild = $false
step "frontend" "up to date"
}
}
# Provision Node only when the frontend build or OXC needs it; system Node stays read-only.
$NeedNodeForSetup = (-not $IsPipInstall) -and ($NeedFrontendBuild -or (Test-Path $OxcValidatorDir))
if ($NeedNodeForSetup) {
if ($NodeSource -eq "skip") {
if ($NeedFrontendBuild) {
step "frontend" "skipped (no suitable Node; system left untouched)" "Yellow"
}
$NeedFrontendBuild = $false
substep "found Node='$SysNodeVersion' npm='$SysNpmVersion'; Unsloth needs Node >=20.19/22.12/23 and npm >= 11" "Yellow"
substep "install a suitable Node + npm, or unset UNSLOTH_SKIP_NODE_INSTALL to let Unsloth manage an isolated Node" "Yellow"
} elseif ($NodeSource -eq "bundled") {
New-Item -ItemType Directory -Force -Path $NodeParent -ErrorAction SilentlyContinue | Out-Null
# Never let install_node_prebuilt.py replace a user-owned path. Anything at the path counts, and
# Get-Item -Force sees dangling links that 5.1's Test-Path reports as absent.
$nodeEntry = if ($NodeOverride -or $RuntimeRootIsCustom) {
Get-Item -LiteralPath $NodeDir -Force -ErrorAction SilentlyContinue
} else { $null }
if ($nodeEntry) {
$nodeOwnedMarker = Join-Path $NodeDir ".unsloth-studio-owned"
$nodeMeta = Join-Path $NodeDir "UNSLOTH_NODE_PREBUILT_INFO.json"
$nodeIsDir = $nodeEntry.PSIsContainer -and
-not ($nodeEntry.Attributes -band [IO.FileAttributes]::ReparsePoint)
if (-not $nodeIsDir -or (
-not (Test-Path -LiteralPath $nodeOwnedMarker) -and
-not (Test-Path -LiteralPath $nodeMeta))) {
$what = if ($nodeIsDir) { "an Unsloth-owned Node install" } else { "a directory" }
Write-StudioLine "[ERROR] $NodeDir already exists and is not $what." -ForegroundColor Red
Write-StudioLine " Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." -ForegroundColor Yellow
Exit-SetupFailure "$NodeDir is not an Unsloth-owned Node install"
}
}
substep "installing isolated Node (system Node/npm left untouched)..."
# Bare `python` may be a Store stub here.
$NodeInstallPython = if ($ValidatedSetupPython) { $ValidatedSetupPython } else { "python" }
# PS 5.1 turns redirected native stderr (even Python warnings) into errors; the exit code decides.
$prevEAPNode = $ErrorActionPreference
try {
$ErrorActionPreference = "Continue"
$nodeOut = & $NodeInstallPython "$PSScriptRoot\install_node_prebuilt.py" --install-dir $NodeDir 2>&1 | Show-DownloadProgress | Out-String
$nodeExit = $LASTEXITCODE
} finally {
$ErrorActionPreference = $prevEAPNode
}
# A failed download gets one retry through the mirror; 3 is another install holding the lock and 4 an unwritable directory, which no mirror fixes.
if ($nodeExit -notin 0, 3, 4 -and (Use-MirrorSpare node)) {
try {
$ErrorActionPreference = "Continue"
$nodeOut += & $NodeInstallPython "$PSScriptRoot\install_node_prebuilt.py" --install-dir $NodeDir 2>&1 | Show-DownloadProgress | Out-String
$nodeExit = $LASTEXITCODE
} finally {
$ErrorActionPreference = $prevEAPNode
}
}
if ($nodeExit -eq 3) {
Write-StudioLine $nodeOut -ForegroundColor DarkGray
step "node" "install blocked by another active Unsloth install" "Red"
Exit-SetupFailure "Node install is blocked by another active Unsloth install" 3
} elseif ($nodeExit -eq 4) {
Write-StudioLine $nodeOut -ForegroundColor DarkGray
Write-StudioLine ""
# The refused object may be $NodeParent, which holds more than Node: never offer it for deletion.
if ($nodeOut -match "denied-scope: parent") {
Exit-PathAccessDenied -Path $NodeParent -Label "Node install parent directory" `
-OwnershipUnverified
} else {
Exit-PathAccessDenied -Path $NodeDir -Label "Node install"
}
} elseif ($nodeExit -ne 0) {
Write-StudioLine $nodeOut -ForegroundColor DarkGray
Write-StudioLine "[ERROR] Could not install an isolated Node automatically." -ForegroundColor Red
Write-StudioLine " Install Node >= 20.19 (with npm >= 11) from https://nodejs.org/ and re-run, or check your network." -ForegroundColor Yellow
Exit-SetupFailure "Could not install an isolated Node runtime"
} elseif ($nodeOut -match "keeping existing isolated Node") {
if ($nodeOut -match 'takeown /F') {
Write-StudioLine $nodeOut -ForegroundColor DarkGray
}
step "node" "update not applied, existing isolated Node kept" "Yellow"
}
# Same condition as the guard above, or the uninstaller treats the new tree as foreign.
if (($NodeOverride -or $RuntimeRootIsCustom) -and (Test-Path -LiteralPath $NodeDir -PathType Container)) {
New-Item -ItemType File -Force -Path (Join-Path $NodeDir ".unsloth-studio-owned") -ErrorAction SilentlyContinue | Out-Null
}
$env:PATH = "$NodeDir;" + $env:PATH
$env:NPM_CONFIG_PREFIX = $NodeDir
$env:npm_config_prefix = $NodeDir
Remove-Item Env:NODE_PATH -ErrorAction SilentlyContinue
step "node" "$(node -v) | npm $(npm -v) (isolated)"
# Only the frontend build uses bun (as in setup.sh); OXC-only Node (Desktop) skips it.
if (-not (Test-Path (Join-Path $FrontendDir "package-lock.json")) -and -not (Get-Command bun -ErrorAction SilentlyContinue) -and $NeedFrontendBuild) {
substep "installing bun (faster frontend package installs)..."
$prevEAP_bun = $ErrorActionPreference
$ErrorActionPreference = "Continue"
Invoke-SetupCommand { npm install -g bun --allow-scripts=bun @NpmRegistryArgs } | Out-Null
$ErrorActionPreference = $prevEAP_bun
Refresh-Environment
# Refresh-Environment demotes the isolated-Node prepend; re-prepend so it wins.
$env:PATH = "$NodeDir;" + $env:PATH
$env:NPM_CONFIG_PREFIX = $NodeDir
$env:npm_config_prefix = $NodeDir
Remove-Item Env:NODE_PATH -ErrorAction SilentlyContinue
if (Get-Command bun -ErrorAction SilentlyContinue) {
substep "bun installed ($(bun --version))"
} else {
substep "bun install skipped (npm will be used instead)"
}
}
} else {
step "node" "$SysNodeVersion | npm $SysNpmVersion (system)"
}
}
if ($NeedFrontendBuild -and -not $IsPipInstall) {
Write-StudioLine ""
substep "building frontend..."
Wait-FrontendBuildOwner
# Cleared only once the build succeeds, so one that dies at any point is redone next run.
try { [System.IO.File]::WriteAllText($FrontendBuildMark, "$PID") } catch { }
# Tailwind v4's oxide scanner honours parent .gitignore, and a venv's "*" hides the .tsx files.
$HiddenGitignores = @()
$WalkDir = (Get-Item $FrontendDir).Parent.FullName
while ($WalkDir -and $WalkDir -ne [System.IO.Path]::GetPathRoot($WalkDir)) {
$gi = Join-Path $WalkDir ".gitignore"
# A build stopped by Ctrl-C or a closed window never put its hidden file back.
if (-not (Test-Path -LiteralPath $gi) -and (Test-Path -LiteralPath "$gi._twbuild" -PathType Leaf)) {
Rename-Item -LiteralPath "$gi._twbuild" -NewName ".gitignore" -ErrorAction SilentlyContinue
}
if (Test-Path $gi) {
$content = Get-Content $gi -Raw -ErrorAction SilentlyContinue
if ($content -and ($content.Trim() -match '^\*$')) {
$hidden = "$gi._twbuild"
Rename-Item -Path $gi -NewName (Split-Path $hidden -Leaf) -Force
$HiddenGitignores += $gi
substep "Temporarily hiding $gi (venv .gitignore blocks Tailwind scanner)"
}
}
$WalkDir = Split-Path $WalkDir -Parent
}
$prevEAP_npm = $ErrorActionPreference
$ErrorActionPreference = "Continue"
Push-Location $FrontendDir
# package-lock.json always wins (`npm ci`); bun only without one, since bun.lock is gitignored.
$UseBun = -not (Test-Path "package-lock.json") -and (Test-Path "bun.lock") -and ($null -ne (Get-Command bun -ErrorAction SilentlyContinue))
$NpmInstallVerb = if (Test-Path "package-lock.json") { "ci" } else { "install" }
# A corrupt bun cache still exits 0, so validate, clear, retry once, then fall back to npm.
if ($UseBun) {
Write-StudioLine " Using bun for package install (faster)" -ForegroundColor DarkGray
$bunExit = Invoke-SetupCommand { bun install --frozen-lockfile @NpmRegistryArgs }
# .bin/ entries vary by manager (npm: tsc/.cmd/.ps1; bun: .exe/.bunx).
$hasTsc = (Test-Path "node_modules\.bin\tsc") -or (Test-Path "node_modules\.bin\tsc.cmd") -or (Test-Path "node_modules\.bin\tsc.exe") -or (Test-Path "node_modules\.bin\tsc.bunx")
$hasVite = (Test-Path "node_modules\.bin\vite") -or (Test-Path "node_modules\.bin\vite.cmd") -or (Test-Path "node_modules\.bin\vite.exe") -or (Test-Path "node_modules\.bin\vite.bunx")
if ($bunExit -eq 0 -and $hasTsc -and $hasVite) {
} elseif ($bunExit -eq 0) {
Write-StudioLine " bun install exited 0 but critical binaries are missing, clearing cache and retrying..." -ForegroundColor Yellow
if (Test-Path "node_modules") {
Remove-Item "node_modules" -Recurse -Force -ErrorAction SilentlyContinue
}
Invoke-SetupCommand { bun pm cache rm } | Out-Null
$bunExit = Invoke-SetupCommand { bun install --frozen-lockfile @NpmRegistryArgs }
$hasTsc = (Test-Path "node_modules\.bin\tsc") -or (Test-Path "node_modules\.bin\tsc.cmd") -or (Test-Path "node_modules\.bin\tsc.exe") -or (Test-Path "node_modules\.bin\tsc.bunx")
$hasVite = (Test-Path "node_modules\.bin\vite") -or (Test-Path "node_modules\.bin\vite.cmd") -or (Test-Path "node_modules\.bin\vite.exe") -or (Test-Path "node_modules\.bin\vite.bunx")
if ($bunExit -ne 0 -or -not $hasTsc -or -not $hasVite) {
Write-StudioLine " bun retry failed, falling back to npm" -ForegroundColor Yellow
if (Test-Path "node_modules") {
Remove-Item "node_modules" -Recurse -Force -ErrorAction SilentlyContinue
}
$UseBun = $false
}
} else {
substep "bun install failed (exit $bunExit), falling back to npm" "Yellow"
if (Test-Path "node_modules") {
Remove-Item "node_modules" -Recurse -Force -ErrorAction SilentlyContinue
}
$UseBun = $false
}
}
if (-not $UseBun) {
$npmExit = Invoke-SetupCommand { npm $NpmInstallVerb @NpmRegistryArgs }
if ($npmExit -ne 0 -and (Invoke-NpmMirrorRetry)) { $npmExit = 0 }
if ($npmExit -ne 0) {
Pop-Location
$ErrorActionPreference = $prevEAP_npm
foreach ($gi in $HiddenGitignores) { Rename-Item -Path "$gi._twbuild" -NewName (Split-Path $gi -Leaf) -Force -ErrorAction SilentlyContinue }
Write-StudioLine "[ERROR] npm $NpmInstallVerb failed (exit code $npmExit)" -ForegroundColor Red
Write-StudioLine " Try running 'npm $NpmInstallVerb' manually in frontend/ to see errors" -ForegroundColor Yellow
Show-NpmRegistryHint -FailureOutput $script:SetupCommandOutput
Exit-SetupFailure "Frontend dependency installation failed (exit code $npmExit)"
}
}
if ((Test-FrontendBuildInBackground) -and
(Start-FrontendBuildBackground -WorkingDirectory $FrontendDir -HiddenGitignores $HiddenGitignores)) {
Pop-Location
$ErrorActionPreference = $prevEAP_npm
} else {
$buildExit = Invoke-SetupCommand { npm run build }
if ($buildExit -ne 0) {
Pop-Location
$ErrorActionPreference = $prevEAP_npm
foreach ($gi in $HiddenGitignores) { Rename-Item -Path "$gi._twbuild" -NewName (Split-Path $gi -Leaf) -Force -ErrorAction SilentlyContinue }
Write-StudioLine "[ERROR] npm run build failed (exit code $buildExit)" -ForegroundColor Red
Exit-SetupFailure "Frontend build failed (exit code $buildExit)"
}
Pop-Location
$ErrorActionPreference = $prevEAP_npm
# ── Restore hidden .gitignore files ──
foreach ($gi in $HiddenGitignores) {
Rename-Item -Path "$gi._twbuild" -NewName (Split-Path $gi -Leaf) -Force -ErrorAction SilentlyContinue
}
Complete-FrontendBuildOutput
}
}
if ((Test-Path $OxcValidatorDir) -and $NodeSource -ne "skip" -and (Get-Command npm -ErrorAction SilentlyContinue)) {
substep "installing OXC validator runtime..."
$prevEAP_oxc = $ErrorActionPreference
$ErrorActionPreference = "Continue"
Push-Location $OxcValidatorDir
$NpmInstallVerb = if (Test-Path "package-lock.json") { "ci" } else { "install" }
if ($NpmInstallVerb -eq "ci" -and (Invoke-OxcInstallStamp -Mode check)) {
Pop-Location
$ErrorActionPreference = $prevEAP_oxc
step "oxc runtime" "up to date"
} else {
# Gone before npm touches the tree, so an interrupted install is never trusted.
Remove-Item -LiteralPath (Join-Path $OxcValidatorDir "node_modules\.unsloth-install-stamp.json") -Force -ErrorAction SilentlyContinue
$oxcInstallExit = Invoke-SetupCommand { npm $NpmInstallVerb @NpmRegistryArgs }
if ($oxcInstallExit -ne 0 -and (Invoke-NpmMirrorRetry)) { $oxcInstallExit = 0 }
if ($oxcInstallExit -ne 0) {
Pop-Location
$ErrorActionPreference = $prevEAP_oxc
Write-StudioLine "[ERROR] OXC validator npm $NpmInstallVerb failed (exit code $oxcInstallExit)" -ForegroundColor Red
Show-NpmRegistryHint -FailureOutput $script:SetupCommandOutput
Exit-SetupFailure "OXC validator dependency installation failed (exit code $oxcInstallExit)"
}
if ($NpmInstallVerb -eq "ci") { $null = Invoke-OxcInstallStamp -Mode write }
Pop-Location
$ErrorActionPreference = $prevEAP_oxc
step "oxc runtime" "installed"
}
} elseif ((Test-Path $OxcValidatorDir) -and $NodeSource -ne "skip") {
substep "OXC validator runtime skipped (no npm found); code validation degrades until Node is available" "Yellow"
}
Remove-AgentInstructionFiles -Roots @(
(Join-Path $FrontendDir "node_modules"),
(Join-Path $OxcValidatorDir "node_modules")
)
# ==========================================================================
# PHASE 3: Python environment + dependencies
# ==========================================================================
Write-StudioLine ""
substep "setting up Python environment..."
$PythonCmd = $null
if ($ReusedSetupPython) {
try {
$out = & $ReusedSetupPython --version 2>&1 | Out-String
if ($out -match 'Python 3\.(\d+)') {
$pyMinor = [int]$Matches[1]
if ($pyMinor -ge 11 -and $pyMinor -le 13 -and -not (Test-IsConda $ReusedSetupPython)) {
$PythonCmd = $ReusedSetupPython
}
}
} catch { }
}
$PyLaunchersResolve = if ($PythonCmd) { @() } else { @(Get-Command py -All -CommandType Application -ErrorAction SilentlyContinue) }
foreach ($pyLauncher in $PyLaunchersResolve) {
if ($pyLauncher.Source -match $CondaSkipPattern) { continue }
foreach ($minor in @("3.13", "3.12", "3.11")) {
try {
$out = & $pyLauncher.Source "-$minor" --version 2>&1 | Out-String
if ($out -match 'Python 3\.(\d+)') {
$pyMinor = [int]$Matches[1]
if ($pyMinor -ge 11 -and $pyMinor -le 13) {
# Resolve the real executable so venv creation does not re-resolve to conda.
$resolvedExe = (& $pyLauncher.Source "-$minor" -c "import sys; print(sys.executable)" 2>$null | Out-String).Trim()
if ($resolvedExe -and (Test-Path $resolvedExe) -and -not (Test-IsConda $resolvedExe)) {
$PythonCmd = $resolvedExe
break
}
}
}
} catch { }
}
if ($PythonCmd) { break }
}
if (-not $PythonCmd) {
foreach ($candidate in @("python3.13", "python3.12", "python3.11", "python3", "python")) {
foreach ($cmdInfo in @(Get-Command $candidate -All -ErrorAction SilentlyContinue)) {
try {
if (-not $cmdInfo.Source) { continue }
if ($cmdInfo.Source -like "*\WindowsApps\*") { continue }
if (Test-IsConda $cmdInfo.Source) {
substep "skipping $($cmdInfo.Source) (conda Python breaks torch DLL loading)" "Yellow"
continue
}
$ver = & $cmdInfo.Source --version 2>&1
if ($ver -match 'Python 3\.(\d+)') {
$minor = [int]$Matches[1]
if ($minor -ge 11 -and $minor -le 13) {
$PythonCmd = $cmdInfo.Source
break
}
}
} catch { }
}
if ($PythonCmd) { break }
}
}
if (-not $PythonCmd) {
Write-StudioLine "[ERROR] No standalone Python 3.11-3.13 found (conda Python is not supported)." -ForegroundColor Red
Write-StudioLine " Install Python from https://python.org/downloads/ or via:" -ForegroundColor Yellow
Write-StudioLine " winget install -e --id Python.Python.3.12" -ForegroundColor Yellow
Exit-SetupFailure "No standalone Python 3.11-3.13 was found"
}
substep "Python found: $PythonCmd"
# $StudioHome / $VenvDir are resolved and preflighted before phase 1, so only the
# cache clear stays here. Venv-gated: a writable-but-empty override still fails the
# venv check below, and clearing first would cost the cache for a run that then does
# nothing. Still before any install work.
if (-not $StageRoot -and (Test-Path -LiteralPath (Join-Path $VenvDir "Scripts\python.exe") -PathType Leaf)) {
Clear-WebViewCaches
}
# why: in env-override mode $StudioHome is user-chosen; require the
# ownership marker before Remove-Item so unrelated dirs survive. Gated on
# the canonical comparison so an override pointing at the legacy default
# still behaves like a default install.
# Directory-local evidence that Unsloth created $Path, used to adopt a custom-home
# llama.cpp or whisper.cpp predating the .unsloth-studio-owned marker (see
# setup.sh). Only Unsloth prebuilt markers count; source builds are
# indistinguishable from a user clone on Windows and stay under the strict guard.
# "Yes" / "No" / "Denied". A denied marker is not evidence of absence: reading it
# as "No" makes the guard below call an Unsloth tree an unrelated directory and
# tell the user to move it aside, when the real problem is permissions.
function Get-StudioAdoptableState {
param([Parameter(Mandatory = $true)][string]$Path)
$denied = $false
foreach ($marker in @("UNSLOTH_PREBUILT_INFO.json", "UNSLOTH_WHISPER_PREBUILT_INFO.json")) {
switch (Get-PathState -Path (Join-Path $Path $marker) -PathType Leaf) {
"Present" { return "Yes" }
"Denied" { $denied = $true }
}
}
if ($denied) { return "Denied" }
# Windows reports a missing child of an unreadable dir as absent; listing the dir itself can tell.
try { $null = @(Get-ChildItem -LiteralPath $Path -Force -ErrorAction Stop | Select-Object -First 1) }
catch {
if (Test-AccessDeniedError $_) { return "Denied" }
}
return "No"
}
function Test-StudioOwnedAdoptable {
param([Parameter(Mandatory = $true)][string]$Path)
return ((Get-StudioAdoptableState -Path $Path) -eq "Yes")
}
function Assert-StudioOwnedOrAbsent {
param(
[Parameter(Mandatory = $true)][string]$Path,
[Parameter(Mandatory = $true)][string]$Label,
# whisper.cpp is non-fatal by contract, so the denial is returned, not exited on.
[switch]$NonFatal,
[AllowNull()][object]$IsCustom = $null
)
$isCustomRoot = $StudioHomeIsCustom
if ($null -ne $IsCustom) { $isCustomRoot = [bool]$IsCustom }
# Denied is not Absent: an unreadable root cannot be proven ours.
$pathState = Get-PathState -Path $Path -PathType Container
if ($pathState -ne "Present") {
if ($isCustomRoot -and $pathState -eq "Denied") {
if ($NonFatal) { return "Denied" }
Exit-PathAccessDenied -Path $Path -Label $Label -OwnershipUnverified
}
# Get-Item -Force sees files and dangling links that a Container probe misses.
if (-not $isCustomRoot) { return }
if (-not (Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue)) { return }
# Fatal even under -NonFatal: that mode rescues a denial, not somebody else's file.
Write-StudioLine "[ERROR] $Path already exists and is not a directory." -ForegroundColor Red
Write-StudioLine " Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." -ForegroundColor Yellow
Exit-SetupFailure "$Label path is not an Unsloth-owned install: $Path"
}
$markerState = Get-PathState -Path (Join-Path $Path $StudioOwnedMarker) -PathType Leaf
if ($isCustomRoot -and $markerState -eq "Denied") {
if ($NonFatal) { return "Denied" }
Exit-PathAccessDenied -Path $Path -Label $Label -OwnershipUnverified
}
if ($isCustomRoot -and $markerState -ne "Present") {
$adoptState = Get-StudioAdoptableState -Path $Path
if ($adoptState -eq "Denied") {
if ($NonFatal) { return "Denied" }
Exit-PathAccessDenied -Path $Path -Label $Label -OwnershipUnverified
}
if ($adoptState -eq "Yes") {
Mark-StudioOwned $Path
return
}
Write-StudioLine "[ERROR] $Path already exists and is not marked as an Unsloth-owned $Label." -ForegroundColor Red
Write-StudioLine " Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." -ForegroundColor Yellow
Exit-SetupFailure "$Label path is not an Unsloth-owned install: $Path"
}
}
function Mark-StudioOwned {
param([Parameter(Mandatory = $true)][string]$Path)
if (-not (Test-Path -LiteralPath $Path -PathType Container)) { return }
try {
[System.IO.File]::WriteAllText((Join-Path $Path $StudioOwnedMarker), "")
} catch {}
}
# Persisted no-torch mode: manifest key first, then .unsloth-no-torch, which survives an interrupted pass.
function Get-PersistedNoTorch {
param([Parameter(Mandatory = $true)][string]$VenvPath)
$manifestPath = Join-Path $VenvPath "unsloth_install_manifest.json"
if (Test-Path -LiteralPath $manifestPath -PathType Leaf) {
$payload = $null
try {
$payload = Get-Content -LiteralPath $manifestPath -Raw -ErrorAction Stop | ConvertFrom-Json
} catch {
$payload = $null
}
if ($null -ne $payload -and $null -ne $payload.no_torch) {
return ("$($payload.no_torch)" -match '^\s*(?i:true|1|yes|on)\s*$')
}
}
return (Test-Path -LiteralPath (Join-Path $VenvPath $NoTorchMarker) -PathType Leaf)
}
function Get-PersistedWoaTorchIndex {
param([Parameter(Mandatory = $true)][string]$VenvPath)
$manifestPath = Join-Path $VenvPath "unsloth_install_manifest.json"
if (-not (Test-Path -LiteralPath $manifestPath -PathType Leaf)) { return "" }
try {
$payload = Get-Content -LiteralPath $manifestPath -Raw -ErrorAction Stop | ConvertFrom-Json
} catch {
return ""
}
if ($null -eq $payload -or -not $payload.woa_torch_index) { return "" }
$value = "$($payload.woa_torch_index)".Trim().TrimEnd('/')
# Re-checked on read: a hand-edited manifest must not redirect torch.
if ($value -notmatch '^https://pypi\.nvidia\.com(/[A-Za-z0-9._~/-]*)?$') { return "" }
return $value
}
# Parity copies of install.ps1's index probe, kept identical by a parity test.
function Test-WoaWheelTagsParity {
param([string]$Name, [string]$PyTag, [string]$AbiTag)
if (-not $Name) { return $false }
$stem = $Name -replace '(?i)\.whl$', ''
$fields = $stem -split '-'
if ($fields.Count -lt 5) { return $false }
$pyTags = $fields[$fields.Count - 3] -split '\.'
$abiTags = $fields[$fields.Count - 2] -split '\.'
return (($pyTags -contains $PyTag) -and ($abiTags -contains $AbiTag))
}
function Test-WoaPairsWithTorchParity {
param([string]$TorchVersion, [string]$OtherVersion, [string]$Project = "torchvision")
if (-not $TorchVersion -or -not $OtherVersion) { return $false }
$stamp = {
param($v)
$m = [regex]::Match($v, '(?i)\.dev(\d+)')
if ($m.Success) { return $m.Groups[1].Value } else { return "" }
}
$local = {
param($v)
$parts = $v -split '\+', 2
if ($parts.Count -eq 2) { return $parts[1].ToLowerInvariant() } else { return "" }
}
if ((& $stamp $TorchVersion) -ne (& $stamp $OtherVersion)) { return $false }
if ((& $local $TorchVersion) -ne (& $local $OtherVersion)) { return $false }
if (& $stamp $TorchVersion) { return $true }
# Stable releases pair by offset: torchvision 0.(M+15) with torch 2.M.
$rel = {
param($v)
$m = [regex]::Match($v, '^(\d+)\.(\d+)')
if ($m.Success) { return @([int]$m.Groups[1].Value, [int]$m.Groups[2].Value) } else { return $null }
}
$t = & $rel $TorchVersion; $o = & $rel $OtherVersion
if (-not $t -or -not $o) { return $false }
switch (($Project -replace '[-_.]+', '-').ToLowerInvariant()) {
"torchvision" { return (($t[0] -eq 2) -and ($o[0] -eq 0) -and ($o[1] -eq ($t[1] + 15))) }
"torchaudio" { return (($o[0] -eq $t[0]) -and ($o[1] -eq $t[1])) }
default { return $true }
}
}
function New-WoaTorchStepOverrideValueParity {
param([string]$Value, [string]$Dir = "")
$result = @{ Value = $null; Temps = @() }
if (-not $Value) { return $result }
$files = @()
foreach ($entry in ($Value -split '\s+' | Where-Object { $_ })) {
$path = $entry.Trim('"').Trim("'")
if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { continue }
$kept = @()
$dropped = $false
foreach ($line in (Get-RequirementEntries -Path $path)) {
$name = ((($line.Line -split '[\s<>=!~;@\[]', 2)[0]).Trim() -replace '[-_.]+', '-').ToLowerInvariant()
if (@("torch", "torchvision", "torchaudio") -contains $name) { $dropped = $true; continue }
$kept += (Resolve-WoaOverrideLine -Line $line.Line -BaseDir $line.BaseDir)
}
if (-not $dropped) { $files += $path; continue }
$tmp = if ($Dir -and (Test-Path -LiteralPath $Dir -PathType Container)) {
Join-Path $Dir ("torch-step-" + [System.IO.Path]::GetRandomFileName() + ".txt")
} else { [System.IO.Path]::GetTempFileName() }
[System.IO.File]::WriteAllLines($tmp, [string[]]$kept, (New-Object System.Text.UTF8Encoding($false)))
$result.Temps += $tmp
$files += $tmp
}
if (-not $files) { $result.Value = ""; return $result }
$safe = foreach ($f in $files) { Get-UvSafePath $f }
$result.Value = (($safe | ForEach-Object { if ($_ -match '\s') { '"' + $_ + '"' } else { $_ } }) -join " ")
return $result
}
# Parity copies of install.ps1's uv index policy readers.
function Remove-WoaTomlComment {
param([string]$Line)
$inD = $false; $inS = $false
for ($i = 0; $i -lt $Line.Length; $i++) {
$c = $Line[$i]
if ($inD) {
if ($c -eq '\') { $i++; continue }
if ($c -eq '"') { $inD = $false }
continue
}
if ($inS) { if ($c -eq "'") { $inS = $false }; continue }
if ($c -eq '"') { $inD = $true; continue }
if ($c -eq "'") { $inS = $true; continue }
if ($c -eq '#') { return $Line.Substring(0, $i) }
}
return $Line
}
function Split-WoaTomlKey {
param([string]$Text)
$parts = @()
$i = 0
while ($i -lt $Text.Length) {
while ($i -lt $Text.Length -and [char]::IsWhiteSpace($Text[$i])) { $i++ }
if ($i -ge $Text.Length) { return $null }
$c = $Text[$i]
if ($c -eq '"' -or $c -eq "'") {
$q = $c; $i++; $sb = ""
while ($i -lt $Text.Length -and $Text[$i] -ne $q) {
if ($q -eq '"' -and $Text[$i] -eq '\' -and ($i + 1) -lt $Text.Length) { $i++ }
$sb += $Text[$i]; $i++
}
if ($i -ge $Text.Length) { return $null }
$i++
$parts += $sb
} else {
$sb = ""
while ($i -lt $Text.Length -and ([string]$Text[$i]) -match '[A-Za-z0-9_-]') { $sb += $Text[$i]; $i++ }
if (-not $sb) { return $null }
$parts += $sb
}
while ($i -lt $Text.Length -and [char]::IsWhiteSpace($Text[$i])) { $i++ }
if ($i -lt $Text.Length) {
if ($Text[$i] -ne '.') { return $null }
$i++
}
}
if ($parts.Count -eq 0) { return $null }
return ,$parts
}
# uv inline [[index]] reader; $null on ANY doubt. Braces are built from code points because
# the parity tests extract functions by counting braces.
function Read-WoaUvInlineIndexArray {
param([string]$Value)
$lb = [char]0x7B; $rb = [char]0x7D
$v = ([string]$Value).Trim()
if ($v -notmatch '^\[(.*)\]$') { return $null }
$inner = $Matches[1].Trim()
$result = @{ DefaultUrl = $null; Extras = @() }
if (-not $inner) { return $result }
$groups = @()
$depth = 0; $start = -1; $inD = $false; $inS = $false
for ($i = 0; $i -lt $inner.Length; $i++) {
$c = $inner[$i]
if ($inD) { if ($c -eq '\') { $i++ } elseif ($c -eq '"') { $inD = $false }; continue }
if ($inS) { if ($c -eq "'") { $inS = $false }; continue }
# A quote at depth 0 opens a bare entry; tested before string mode starts.
if (($c -eq '"' -or $c -eq "'") -and $depth -eq 0) { return $null }
if ($c -eq '"') { $inD = $true; continue }
if ($c -eq "'") { $inS = $true; continue }
if ($c -eq $lb) { if ($depth -eq 0) { $start = $i + 1 }; $depth++; continue }
if ($c -eq $rb) {
$depth--
if ($depth -lt 0) { return $null }
if ($depth -eq 0) { $groups += $inner.Substring($start, $i - $start); $start = -1 }
continue
}
if ($depth -eq 0 -and ([string]$c) -notmatch '[\s,]') { return $null }
}
if ($depth -ne 0 -or $inD -or $inS -or -not $groups.Count) { return $null }
foreach ($g in $groups) {
if ($g.IndexOf($lb) -ge 0 -or $g.IndexOf('[') -ge 0) { return $null }
$url = $null; $isDefault = $false; $isExplicit = $false
foreach ($pair in ($g -split ',')) {
$pair = $pair.Trim()
if (-not $pair) { continue }
$eq = $pair.IndexOf('=')
if ($eq -lt 1) { return $null }
$k = $pair.Substring(0, $eq).Trim().Trim('"').Trim("'").ToLowerInvariant()
$raw = $pair.Substring($eq + 1).Trim()
$str = if ($raw -match '^"(.*)"$' -or $raw -match "^'(.*)'$") { $Matches[1] } else { $null }
$bool = if ($raw -match '^(true|false)$') { $raw -eq 'true' } else { $null }
if ($k -eq 'url') { if (-not $str) { return $null }; $url = $str }
elseif ($k -eq 'default') { if ($null -eq $bool) { return $null }; $isDefault = $bool }
# An explicit index serves only pinned packages, so it is neither default nor extra.
elseif ($k -eq 'explicit') { if ($null -eq $bool) { return $null }; $isExplicit = $bool }
}
if (-not $url) { return $null }
# explicit AND default also removes PyPI as default: not modelled, so doubt.
if ($isExplicit) { if ($isDefault) { return $null }; continue }
if ($isDefault) { if (-not $result.DefaultUrl) { $result.DefaultUrl = $url } }
else { $result.Extras += $url }
}
return $result
}
function Read-WoaUvTomlIndexKeys {
param([string]$Path, [string]$Top)
try { $lines = [System.IO.File]::ReadAllLines($Path) } catch { return $null }
# uv pip (0.10.7): [pip] scalars beat top-level, [[index]] default = true beats both. Ranked at the end.
$topScope = @{ NoIndex = $null; IndexUrl = $null; Extras = @() }
$pipScope = @{ NoIndex = $null; IndexUrl = $null; Extras = @() }
$section = ""
# A hashtable, because an assignment inside the $flush script block would be local to it.
$inIndex = $false; $idxUrl = $null; $idxDefault = $false; $idxExplicit = $false; $entry = @{ DefaultUrl = $null; Extras = @(); Doubt = $false }
$indexTable = if ($Top) { "$Top.index" } else { "index" }
$pipTable = if ($Top) { "$Top.pip" } else { "pip" }
$flush = {
if ($inIndex -and $idxUrl) {
# Explicit entries are skipped, as in the inline reader; explicit AND default is doubt.
if ($idxExplicit) { if ($idxDefault) { $entry.Doubt = $true } }
elseif ($idxDefault) { if (-not $entry.DefaultUrl) { $entry.DefaultUrl = $idxUrl } }
else { $entry.Extras += $idxUrl }
}
}
foreach ($raw in $lines) {
$line = (Remove-WoaTomlComment $raw).Trim()
if (-not $line) { continue }
if ($line -match '^\[\[(.+?)\]\]$') {
& $flush
$section = $Matches[1].Trim(); $inIndex = ($section -eq $indexTable); $idxUrl = $null; $idxDefault = $false; $idxExplicit = $false
continue
}
if ($line -match '^\[(.+?)\]$') { & $flush; $section = $Matches[1].Trim(); $inIndex = $false; continue }
$eq = -1; $inD = $false; $inS = $false
for ($i = 0; $i -lt $line.Length; $i++) {
$c = $line[$i]
if ($inD) { if ($c -eq '\') { $i++ } elseif ($c -eq '"') { $inD = $false }; continue }
if ($inS) { if ($c -eq "'") { $inS = $false }; continue }
if ($c -eq '"') { $inD = $true; continue }
if ($c -eq "'") { $inS = $true; continue }
if ($c -eq '=') { $eq = $i; break }
}
if ($eq -lt 1) { continue }
$parts = Split-WoaTomlKey $line.Substring(0, $eq)
if (-not $parts) { continue }
$key = $parts[-1]
$prefix = if ($parts.Count -gt 1) { ($parts[0..($parts.Count - 2)] -join '.') } else { "" }
$val = $line.Substring($eq + 1).Trim()
if (-not $val) { continue }
$str = if ($val -match '^"(.*)"$' -or $val -match "^'(.*)'$") { $Matches[1] } else { $null }
$bool = if ($val -match '^(true|false)$') { $val -eq 'true' } else { $null }
if ($inIndex) {
if (-not $prefix) {
if ($key -eq 'url' -and $str) { $idxUrl = $str }
if ($key -eq 'default' -and $null -ne $bool) { $idxDefault = $bool }
if ($key -eq 'explicit' -and $null -ne $bool) { $idxExplicit = $bool }
}
continue
}
$scopeSection = if ($prefix) { if ($section) { "$section.$prefix" } else { $prefix } } else { $section }
$scope = if ($scopeSection -eq $Top) { $topScope } elseif ($scopeSection -eq $pipTable) { $pipScope } else { $null }
if ($null -eq $scope) { continue }
if ($key -eq 'no-index' -and $null -ne $bool -and $null -eq $scope.NoIndex) { $scope.NoIndex = $bool }
if (($key -eq 'default-index' -or $key -eq 'index-url') -and $str -and -not $scope.IndexUrl) { $scope.IndexUrl = $str }
if ($key -eq 'extra-index-url') {
if ($val -match '^\[(.*)\]$') {
foreach ($m in [regex]::Matches($Matches[1], ('"([^"]*)"' + "|'([^']*)'"))) {
$scope.Extras += $(if ($m.Groups[1].Success) { $m.Groups[1].Value } else { $m.Groups[2].Value })
}
} elseif ($str) { $scope.Extras += $str }
}
if ($key -eq 'index') {
$inline = Read-WoaUvInlineIndexArray -Value $val
if ($null -eq $inline) { return $null }
if ($inline.DefaultUrl -and -not $entry.DefaultUrl) { $entry.DefaultUrl = $inline.DefaultUrl }
$entry.Extras += @($inline.Extras)
}
}
& $flush
if ($entry.Doubt) { return $null }
$noIndex = if ($null -ne $pipScope.NoIndex) { $pipScope.NoIndex } else { $topScope.NoIndex }
$defaultIndex = if ($entry.DefaultUrl) { $entry.DefaultUrl } elseif ($pipScope.IndexUrl) { $pipScope.IndexUrl } else { $topScope.IndexUrl }
$extras = @($entry.Extras) + @($pipScope.Extras) + @($topScope.Extras)
return @{ NoIndex = $noIndex; DefaultIndex = $defaultIndex; ExtraIndexes = @($extras | Where-Object { $_ }) }
}
# UV_NO_INDEX is OURS, not uv's, and the distinction is not pedantic: uv 0.10.7 defines
# no such environment variable. `--no-index` exists only as a command-line flag, it is
# absent from `uv pip install --help`'s environment list beside UV_OFFLINE and
# UV_NO_CONFIG, and grepping the 0.10.7 tree for the name returns nothing. uv will
# ignore it however it is spelled. So this is not "what uv was told"; it is the
# operator telling US they want no registry index, and what we do about it is shape the
# arguments we pass.
#
# Read with uv's boolish set deliberately, not by inheritance. A caller sets this
# beside UV_OFFLINE and UV_NO_CONFIG, which uv really does read, and one spelling
# across all three is the entire point. It is a choice, and the test says so.
#
# Deliberately NOT turned into a `--no-index` argument. That would make our behaviour
# and uv's actually agree, which is the honest long-term answer, but it would also turn
# a resolve that works today into one with no index at all. That is a behaviour change
# for existing users and belongs in its own change, not riding along with a truthiness
# fix.
function Test-NoIndexRequested {
return (Test-UvEnvFlag "UV_NO_INDEX")
}
function Get-WoaUvConfigIndexPolicy {
$result = @{ NoIndex = $false; DefaultIndex = $null; Unreadable = $false; UnreadablePath = $null; ExtraIndexes = @() }
if (Test-UvEnvFlag "UV_NO_CONFIG") { return $result }
$files = @()
$cfgFile = [string][Environment]::GetEnvironmentVariable("UV_CONFIG_FILE")
if ($cfgFile) {
$files += @{ Path = $cfgFile; Top = "" }
} else {
$dir = (Get-Location).Path
while ($dir) {
$u = Join-Path $dir "uv.toml"; $pp = Join-Path $dir "pyproject.toml"
if (Test-Path -LiteralPath $u -PathType Leaf) { $files += @{ Path = $u; Top = "" }; break }
if (Test-Path -LiteralPath $pp -PathType Leaf) {
$txt = try { [System.IO.File]::ReadAllText($pp) } catch { "" }
if ($txt -match '(?m)^\s*\[+tool\.uv(\.|\])') { $files += @{ Path = $pp; Top = "tool.uv" }; break }
}
$parent = Split-Path -Parent $dir
if (-not $parent -or $parent -eq $dir) { break }
$dir = $parent
}
if ($env:APPDATA) { $files += @{ Path = (Join-Path $env:APPDATA "uv\uv.toml"); Top = "" } }
if ($env:ProgramData) { $files += @{ Path = (Join-Path $env:ProgramData "uv\uv.toml"); Top = "" } }
}
$noIndexSet = $false
foreach ($f in $files) {
if (-not (Test-Path -LiteralPath $f.Path -PathType Leaf)) { continue }
$policy = Read-WoaUvTomlIndexKeys -Path $f.Path -Top $f.Top
if ($null -eq $policy) {
$result.Unreadable = $true
if (-not $result.UnreadablePath) { $result.UnreadablePath = $f.Path }
continue
}
if (-not $noIndexSet -and $null -ne $policy.NoIndex) { $result.NoIndex = $policy.NoIndex; $noIndexSet = $true }
if (-not $result.DefaultIndex -and $policy.DefaultIndex) { $result.DefaultIndex = $policy.DefaultIndex }
$result.ExtraIndexes = @($result.ExtraIndexes) + @($policy.ExtraIndexes)
}
return $result
}
# Fatal where the caller scrubs UV_* and sets UV_NO_CONFIG: the trio index would be the only source.
function Test-WoaUvIndexPolicyUnreadable {
foreach ($name in @("UV_NO_INDEX", "UV_DEFAULT_INDEX", "UV_INDEX_URL")) {
$v = [string][Environment]::GetEnvironmentVariable($name)
if ($v -and $v.Trim()) { return $false }
}
return [bool](Get-WoaUvConfigIndexPolicy).Unreadable
}
function Get-WoaDependencyIndexArgs {
param([string]$Resolver = "uv")
$pip = ($Resolver -eq "pip")
$defaultNames = if ($pip) { @("PIP_INDEX_URL") } else { @("UV_DEFAULT_INDEX", "UV_INDEX_URL") }
$extraNames = if ($pip) { @("PIP_EXTRA_INDEX_URL") } else { @("UV_INDEX", "UV_EXTRA_INDEX_URL") }
# Each variable by its owner's rule, and they are not symmetric. PIP_NO_INDEX is
# pip's and pip really reads it, so naming no index here matches what pip will
# then do. UV_NO_INDEX is ours alone, so that arm is us honouring the operator.
$noIndexRequested = if ($pip) { Test-PipEnvFlag "PIP_NO_INDEX" } else { Test-NoIndexRequested }
if ($noIndexRequested) { return @() }
$default = $null
foreach ($name in $defaultNames) {
$url = [string][Environment]::GetEnvironmentVariable($name)
if ($url -and $url.Trim()) { $default = $url.Trim(); break }
}
$extras = @()
foreach ($name in $extraNames) {
$list = [string][Environment]::GetEnvironmentVariable($name)
foreach ($u in ($list -split '\s+' | Where-Object { $_ })) { $extras += $u }
}
if (-not $pip -and (-not $default -or -not $extras)) {
$cfg = Get-WoaUvConfigIndexPolicy
if ($cfg.NoIndex) { return @() }
# An unreadable policy with no env default: name nothing, or the PyPI fallback below would silently override whatever mirror the file configured.
if ($cfg.Unreadable -and -not $default) { return @() }
if (-not $default -and $cfg.DefaultIndex) { $default = $cfg.DefaultIndex }
if (-not $extras) { $extras = @($cfg.ExtraIndexes) }
}
if (-not $default) { $default = "https://pypi.org/simple" }
$indexArgs = @()
foreach ($u in @(@($default) + @($extras) | Where-Object { $_ } | Select-Object -Unique)) {
$indexArgs += @("--extra-index-url", $u)
}
return $indexArgs
}
# Parity copy of install.ps1's Test-WoaAudioMatchesTorch.
function Test-WoaAudioMatchesTorchParity {
param([string]$TorchVersion, [string]$AudioVersion)
if (-not $TorchVersion -or -not $AudioVersion) { return $false }
$shorten = {
param($v)
[regex]::Match((($v -split '\+', 2)[0]), '^\d+\.\d+').Value
}
$a = & $shorten $TorchVersion
$b = & $shorten $AudioVersion
return ($a -and $b -and $a -eq $b)
}
function Get-WoaCudaWheelVersionParity {
param([string]$IndexUrl, [string]$PyTag, [string]$AbiTag, [string]$Project = "torch",
[string]$PairWith = "", [string]$Below = "")
if ([string]::IsNullOrWhiteSpace($IndexUrl) -or [string]::IsNullOrWhiteSpace($PyTag)) { return $null }
if (-not $AbiTag) { $AbiTag = $PyTag }
$base = ($IndexUrl -split '[?#]', 2)[0].TrimEnd('/')
$tail = if ($IndexUrl.IndexOfAny([char[]]('?', '#')) -ge 0) { $IndexUrl.Substring($IndexUrl.IndexOfAny([char[]]('?', '#'))) } else { "" }
try {
$body = [string](Invoke-RestMethod -Uri "$base/$Project/$tail" -UseBasicParsing -TimeoutSec 20)
} catch { return $null }
if ([string]::IsNullOrWhiteSpace($body)) { return $null }
$best = $null
$bestKey = $null
# PEP 440 order within one release: dev < a < b < rc < final.
$prerelease = {
param([string]$v)
$r = ($v -split '\+', 2)[0]
if ($r -match '\.dev(\d+)') { return @(0, [long]$Matches[1]) }
if ($r -match '(?i)(a|b|rc)(\d+)') { return @(@{ a = 1; b = 2; rc = 3 }[$Matches[1].ToLowerInvariant()], [long]$Matches[2]) }
return @(4, [long]0)
}
$belowKey = $null; $belowRank = $null
if ($Below) {
$belowNumeric = [regex]::Match((($Below -split '\+', 2)[0]), '^\d+(\.\d+){0,2}').Value
try { $belowKey = [version]$belowNumeric } catch { return $null }
$belowRank = & $prerelease $Below
}
foreach ($match in [regex]::Matches($body, "$Project-[^`"'<>\s]*?win_arm64\.whl")) {
$name = $match.Value
try { $name = [System.Uri]::UnescapeDataString($name) } catch {}
if (-not (Test-WoaWheelTagsParity -Name $name -PyTag $PyTag -AbiTag $AbiTag)) { continue }
if ($name -notmatch '\+cu[0-9]+') { continue }
$version = ($name -split '-')[1]
if ($PairWith -and -not (Test-WoaPairsWithTorchParity -TorchVersion $PairWith -OtherVersion $version -Project $Project)) { continue }
$release = ($version -split '\+', 2)[0]
$numeric = [regex]::Match($release, '^\d+(\.\d+){0,2}').Value
$key = $null
try { $key = [version]$numeric } catch { continue }
if ($belowKey) {
if ($key -gt $belowKey) { continue }
if ($key -eq $belowKey) {
$rank = & $prerelease $version
if (($rank[0] -gt $belowRank[0]) -or (($rank[0] -eq $belowRank[0]) -and ($rank[1] -ge $belowRank[1]))) { continue }
}
}
if ($null -eq $bestKey -or $key -gt $bestKey) { $bestKey = $key; $best = $version }
elseif ($key -eq $bestKey) {
$rankNew = & $prerelease $version; $rankBest = & $prerelease $best
if (($rankNew[0] -gt $rankBest[0]) -or (($rankNew[0] -eq $rankBest[0]) -and ($rankNew[1] -gt $rankBest[1]))) { $best = $version }
}
}
return $best
}
function Get-WoaTorchIndexMarkerPath {
return (Join-Path (Join-Path $StudioHome "woa") "torch-index.txt")
}
function Test-WoaPersistableIndex {
param([string]$IndexUrl)
if (-not $IndexUrl) { return $false }
return ($IndexUrl -match '^https://pypi\.nvidia\.com(/[A-Za-z0-9._~/-]*)?$')
}
function Save-WoaTorchIndexMarker {
param([string]$IndexUrl)
$value = "$IndexUrl".Trim().TrimEnd('/')
if (-not (Test-WoaPersistableIndex $value)) {
# Cleared, not just skipped: a stale marker sent a mirror host back to NVIDIA's index.
Remove-Item -LiteralPath (Get-WoaTorchIndexMarkerPath) -Force -ErrorAction SilentlyContinue
return
}
try {
$dir = Split-Path -Parent (Get-WoaTorchIndexMarkerPath)
if (-not (Test-Path -LiteralPath $dir -PathType Container)) {
New-Item -ItemType Directory -Path $dir -Force | Out-Null
}
[System.IO.File]::WriteAllText(
(Get-WoaTorchIndexMarkerPath), $value, (New-Object System.Text.UTF8Encoding($false)))
} catch {}
}
function Get-WoaTorchIndexMarker {
$path = Get-WoaTorchIndexMarkerPath
if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { return "" }
try { $value = ([System.IO.File]::ReadAllText($path)).Trim().TrimEnd('/') } catch { return "" }
if (-not (Test-WoaPersistableIndex $value)) { return "" }
return $value
}
# A path with a space has to reach uv by its 8.3 short name.
function Get-UvSafePath {
param([string]$Path)
if (-not $Path -or -not $Path.Contains(" ")) { return $Path }
try {
$fso = New-Object -ComObject Scripting.FileSystemObject
$short = if (Test-Path -LiteralPath $Path -PathType Container) {
$fso.GetFolder($Path).ShortPath
} else {
$fso.GetFile($Path).ShortPath
}
# A space-free alias is not necessarily a name that resolves (#11290). This value
# reaches UV_OVERRIDE and --find-links, so a bogus one breaks every later uv call.
if ($short -and -not $short.Contains(" ") -and (Test-Path -LiteralPath $short -ErrorAction SilentlyContinue)) { return $short }
} catch {}
return $Path
}
# PEP 503 normalisation, so brotli / Brotli / brotli_cffi compare as one name.
function Resolve-WoaOverrideLine {
param([string]$Line, [string]$BaseDir)
if (-not $BaseDir -or $Line -match '^\s*(#|$)') { return $Line }
# pip's inline comment is whitespace then "#"; split it off before rebasing the path.
$comment = ""
if ($Line -match '^(.*?)(\s+#.*)$') { $Line = $Matches[1]; $comment = $Matches[2] }
$abs = {
param([string]$p)
if (-not $p -or $p -match '^[A-Za-z][A-Za-z0-9+.-]*://' -or [System.IO.Path]::IsPathRooted($p)) { return $p }
try { return [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($BaseDir, $p)) } catch { return $p }
}
if ($Line -match '^(\s*)(-r|--requirement|-c|--constraint|-f|--find-links)([=\s]+)(.+?)(\s*)$') {
# Copied out FIRST: the -match below replaces $Matches.
$lead = $Matches[1]; $opt = $Matches[2]; $sep = $Matches[3]
$bare = $Matches[4].Trim('"').Trim("'"); $tail = $Matches[5]
$rebased = & $abs $bare
if ($rebased -match '\s') { $rebased = '"' + $rebased + '"' }
return "$lead$opt$sep$rebased$tail$comment"
}
# Extras split off first, or GetFullPath folds ".[dev]" into the parent.
if ($Line -match '^(\s*)(-e|--editable)([=\s]+)(.+?)(\s*)$') {
$lead = $Matches[1]; $opt = $Matches[2]; $sep = $Matches[3]
$bare = $Matches[4].Trim('"').Trim("'"); $tail = $Matches[5]
$extras = ""
if ($bare -match '^(.*?)(\[[^\]]*\])$') { $bare = $Matches[1]; $extras = $Matches[2] }
$rebased = (& $abs $bare) + $extras
if ($rebased -match '\s') { $rebased = '"' + $rebased + '"' }
return "$lead$opt$sep$rebased$tail$comment"
}
if ($Line -match '^(\s*[^\s@]+\s*@\s*)(.+?)(\s*)$') {
$head = $Matches[1]; $target = $Matches[2]; $tail = $Matches[3]
# A PEP 508 marker must be kept aside or it is rebased as part of the path.
$marker = ""
if ($target -match '^(.*?)(\s+;.*)$') { $target = $Matches[1]; $marker = $Matches[2] }
if ($target -match '^file:(?!//)(.*)$') {
$rebasedPath = & $abs $Matches[1]
$uri = try { (New-Object System.Uri -ArgumentList @($rebasedPath, [System.UriKind]::Absolute)).AbsoluteUri } catch { "file:" + $rebasedPath }
return "$head$uri$marker$tail$comment"
}
return "$Line$comment"
}
if ($Line -match '^(\s*)([^\s#;]+\.(?:whl|tar\.gz|zip))(\s*.*)$') {
$lead = $Matches[1]; $path = $Matches[2]; $rest = $Matches[3]
if ($path -match '[\\/]') { return "$lead" + (& $abs $path) + "$rest$comment" }
}
if ($Line -match '^(\s*)(\.{1,2}[^\s#;]*)(\s*(?:[;#].*)?)$') {
$lead = $Matches[1]; $path = $Matches[2]; $rest = $Matches[3]
$extras = ""
if ($path -match '^(.*?)(\[[^\]]*\])$') { $path = $Matches[1]; $extras = $Matches[2] }
return "$lead" + (& $abs $path) + "$extras$rest$comment"
}
return "$Line$comment"
}
function Get-RequirementName {
param([string]$Line)
if (-not $Line -or $Line -match '^\s*(#|-|$)') { return "" }
$name = (($Line -split '[\s<>=!~;@\[]', 2)[0]).Trim()
if (-not $name) { return "" }
return ($name -replace '[-_.]+', '-').ToLowerInvariant()
}
# Includes followed: uv errors when two files name one package.
function Get-RequirementEntries {
param([string]$Path, $Seen = $null, [int]$Depth = 0)
if ($Depth -gt 8) { return @() }
if ($null -eq $Seen) { $Seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase) }
if (-not $Path -or -not (Test-Path -LiteralPath $Path -PathType Leaf)) { return @() }
try { $full = Convert-Path -LiteralPath $Path } catch { return @() }
if (-not $Seen.Add($full)) { return @() }
try { $lines = [System.IO.File]::ReadAllLines($full) } catch { return @() }
$dir = [System.IO.Path]::GetDirectoryName($full)
$entries = @()
foreach ($line in $lines) {
if ($line -match '^\s*(?:-r|--requirement)[=\s]+(.+?)\s*$') {
# pip needs whitespace before an inline "#": "-r a#b.txt" keeps its hash.
$nested = ($Matches[1] -replace '\s+#.*$', '').Trim().Trim('"', "'")
if (-not [System.IO.Path]::IsPathRooted($nested)) { $nested = Join-Path $dir $nested }
$entries += @(Get-RequirementEntries -Path $nested -Seen $Seen -Depth ($Depth + 1))
continue
}
$entries += , @{ Line = $line; BaseDir = $dir }
}
return $entries
}
function Get-RequirementNames {
param([string]$Path)
$names = @()
foreach ($entry in (Get-RequirementEntries -Path $Path)) {
$name = Get-RequirementName -Line $entry.Line
if ($name) { $names += $name }
}
return @($names | Sort-Object -Unique)
}
# The merged override file can carry caller credentials, so it lives for one run only.
function Remove-WoaMergedOverrides {
if ($script:WoaMergedOverrides) {
Remove-Item -LiteralPath $script:WoaMergedOverrides -Force -ErrorAction SilentlyContinue
$script:WoaMergedOverrides = $null
}
}
function Restore-WoaResolverEnvironment {
if (-not (Test-WinArm64Venv)) { return }
$woaDir = Join-Path $StudioHome "woa"
$overrides = Join-Path $woaDir "overrides.txt"
$wheels = Join-Path $woaDir "wheels"
Remove-Item -LiteralPath (Join-Path $woaDir "overrides.merged.txt") -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath (Join-Path $woaDir "overrides.session.txt") -Force -ErrorAction SilentlyContinue
if (-not (Test-Path -LiteralPath $overrides -PathType Leaf)) {
if (-not $env:UV_OVERRIDE) {
substep "windows on arm: $overrides is missing, so the win_arm64 requirement" "Yellow"
substep "overrides cannot be restored. Re-run install.ps1 if this pass fails to resolve." "Yellow"
}
} else {
$safeOverrides = Get-UvSafePath $overrides
if ($safeOverrides -match '\s') {
substep "windows on arm: $overrides contains a space and has no 8.3 short name," "Yellow"
substep "which uv cannot read. Re-run install.ps1 if this pass fails to resolve." "Yellow"
} elseif (-not $env:UV_OVERRIDE) {
$env:UV_OVERRIDE = $safeOverrides
substep "windows on arm: restored requirement overrides from $overrides"
} else {
# uv COMBINES override files and errors on a duplicate, so only a conflict is merged.
$_woaOursNames = Get-RequirementNames -Path $overrides
$_woaCallerFiles = @($env:UV_OVERRIDE -split '\s+' | Where-Object { $_ })
$_woaConflict = $false
foreach ($_woaFile in $_woaCallerFiles) {
foreach ($_woaName in (Get-RequirementNames -Path $_woaFile)) {
if ($_woaOursNames -contains $_woaName) { $_woaConflict = $true; break }
}
if ($_woaConflict) { break }
}
if (-not $_woaConflict) {
$env:UV_OVERRIDE = "$safeOverrides $($env:UV_OVERRIDE)"
substep "windows on arm: added the win_arm64 requirement overrides alongside yours"
} else {
$_woaMerged = Join-Path $woaDir "overrides.merged.txt"
$_woaLines = @([System.IO.File]::ReadAllLines($overrides))
foreach ($_woaFile in $_woaCallerFiles) {
foreach ($_woaEntry in (Get-RequirementEntries -Path $_woaFile)) {
if ((Get-RequirementName -Line $_woaEntry.Line) -in $_woaOursNames) { continue }
# Rebased: uv resolves these against the file containing the line.
$_woaLines += (Resolve-WoaOverrideLine -Line $_woaEntry.Line -BaseDir $_woaEntry.BaseDir)
}
}
try {
[System.IO.File]::WriteAllLines($_woaMerged, [string[]]$_woaLines, (New-Object System.Text.UTF8Encoding($false)))
$script:WoaMergedOverrides = $_woaMerged
$_woaSafeMerged = Get-UvSafePath $_woaMerged
if ($_woaSafeMerged -match '\s') { throw "merged override path is unreadable by uv" }
$env:UV_OVERRIDE = $_woaSafeMerged
substep "windows on arm: merged your requirement overrides with the win_arm64 drop list"
substep " (this platform's entries win where both name the same package)"
} catch {
substep "windows on arm: could not merge requirement overrides ($($_.Exception.Message))." "Yellow"
substep " keeping yours; the dependency pass may reach a win_arm64 sdist." "Yellow"
}
}
}
}
if (Test-Path -LiteralPath $wheels -PathType Container) {
# Prepended, never skipped, or the staged win_arm64 wheels are left out.
$_woaSafeWheels = Get-UvSafePath $wheels
if (-not $env:UV_FIND_LINKS) { $env:UV_FIND_LINKS = $wheels }
elseif (($env:UV_FIND_LINKS -split '[,\s]+') -notcontains $wheels) {
$env:UV_FIND_LINKS = "$wheels,$($env:UV_FIND_LINKS)"
}
if (-not $env:PIP_FIND_LINKS) { $env:PIP_FIND_LINKS = $_woaSafeWheels }
elseif (($env:PIP_FIND_LINKS -split '[,\s]+') -notcontains $_woaSafeWheels) {
$env:PIP_FIND_LINKS = "$_woaSafeWheels $($env:PIP_FIND_LINKS)"
}
}
}
# Written before anything interruptible; cleared when torch is wanted.
function Set-PersistedNoTorch {
param(
[Parameter(Mandatory = $true)][string]$VenvPath,
[Parameter(Mandatory = $true)][bool]$NoTorch
)
if (-not (Test-Path -LiteralPath $VenvPath -PathType Container)) { return }
$markerPath = Join-Path $VenvPath $NoTorchMarker
try {
if ($NoTorch) {
[System.IO.File]::WriteAllText($markerPath, "")
} elseif (Test-Path -LiteralPath $markerPath -PathType Leaf) {
Remove-Item -LiteralPath $markerPath -Force -ErrorAction Stop
}
} catch {}
}
$NoTorchMode = $env:UNSLOTH_NO_TORCH -match '^\s*(?i:true|1|yes|on)\s*$'
# No env var means a direct update; without the manifest fallback a GGUF-only venv reads as stale.
if (-not $NoTorchMode -and [string]::IsNullOrWhiteSpace($env:UNSLOTH_NO_TORCH)) {
$NoTorchMode = Get-PersistedNoTorch -VenvPath $VenvDir
if ($NoTorchMode) {
substep "no-torch install detected -- keeping this environment GGUF-only." "Yellow"
}
}
Set-PersistedNoTorch -VenvPath $VenvDir -NoTorch $NoTorchMode
# Hand install_python_stack.py the resolved answer: it drops the manifest before reading it.
$env:UNSLOTH_NO_TORCH = if ($NoTorchMode) { "true" } else { "false" }
$InstallerManagedSetup = $env:UNSLOTH_INSTALL_ROLLBACK_MANAGED -match '^(?i:true|1|yes)$'
# $null means unknown (older installer, --no-torch, custom index), not a mismatch.
# IsNullOrWhiteSpace: 7.5+ keeps an empty assignment as a present blank value.
$InstallerTorchTag = if ([string]::IsNullOrWhiteSpace($env:UNSLOTH_INSTALLER_TORCH_TAG)) { $null }
else { $env:UNSLOTH_INSTALLER_TORCH_TAG.Trim().ToLowerInvariant() }
# Asked of the INTERPRETER, not the machine: an emulated x64 python is win-amd64.
$script:_winArm64Venv = $null
function Test-WinArm64Venv {
if ($null -ne $script:_winArm64Venv) { return $script:_winArm64Venv }
# Before any interpreter launch: a corrupt python could hang.
if ((Get-HostMachineArch) -ne "arm64") {
$script:_winArm64Venv = $false
return $false
}
$candidates = @()
$managed = Join-Path $VenvDir "Scripts\python.exe"
if (Test-Path -LiteralPath $managed) { $candidates += $managed }
$candidates += "python"
foreach ($exe in $candidates) {
$platform = ""
try {
$platform = (& $exe -c "import sysconfig; print(sysconfig.get_platform())" 2>$null | Out-String).Trim().ToLowerInvariant()
} catch { $platform = "" }
if ($platform) {
# Do not cache a failure.
$script:_winArm64Venv = ($platform -eq "win-arm64")
return $script:_winArm64Venv
}
}
return $false
}
# Declared for StrictMode: a fresh install never assigns it but the XPU install reads it.
$installedTorchTag = $null
# Hoisted for StrictMode, like the variable above.
$script:PinChangedForceReinstall = $false
$script:TorchImportDefinitivelyFailed = $false
if ((Test-Path -LiteralPath $VenvDir -PathType Container) -and -not $NoTorchMode) {
$VenvPyExe = Join-Path $VenvDir "Scripts\python.exe"
$installedTorchTag = $null
$_verProbe = $null
$shouldRebuild = $false
$script:PinChangedForceReinstall = $false
if (Test-Path -LiteralPath $VenvPyExe) {
# Bounded: a wedged `import torch` would hang setup. An unreadable flavor rebuilds.
$_verProbe = Invoke-BoundedPythonProbe -PythonExe $VenvPyExe -Code 'import torch; print(torch.__version__)'
$torchVer = $_verProbe.Output.Trim()
if ($_verProbe.Ok -and $torchVer) {
if ($torchVer -match '\+(cu\d+)') {
$installedTorchTag = $Matches[1]
} elseif ($torchVer -match '\+rocm') {
$installedTorchTag = "rocm"
} elseif ($torchVer -match '\+xpu') {
# Without this a +xpu wheel reads as cpu. Matches ConvertTo-TorchFlavorTag.
$installedTorchTag = "xpu"
} elseif ($torchVer -match '\+cpu') {
$installedTorchTag = "cpu"
} else {
$installedTorchTag = "cpu"
}
} elseif (Test-VenvTorchIsXpu -VenvPath $VenvDir) {
# A stalled Arc driver times out the import; trust version.py rather than delete the venv.
$installedTorchTag = "xpu"
substep "PyTorch did not respond in time but this venv holds an XPU build -- keeping it." "Yellow"
substep "If training fails, update the Intel GPU compute driver." "Yellow"
} elseif (Test-VenvTorchIsRocm -VenvPath $VenvDir) {
# Same on AMD: a faulted HIP runtime breaks the import while the wheel is fine; trust version.py.
$installedTorchTag = "rocm"
substep "PyTorch did not respond but this venv holds a ROCm build -- keeping it." "Yellow"
substep "If training fails, reboot and update the AMD Adrenalin / HIP SDK driver." "Yellow"
} elseif (Test-VenvTorchIsCuda -VenvPath $VenvDir) {
# Keep the CUDA FAMILY, or the no-wipe escape below sees nothing to preserve.
$installedTorchTag = Get-VenvTorchCudaTag -VenvPath $VenvDir
substep "PyTorch did not respond but this venv holds a $installedTorchTag build -- keeping it." "Yellow"
substep "If training fails, reboot and update the NVIDIA driver." "Yellow"
# A half-written torch leaves a +cu* version.py too; force the reinstall.
if ($_verProbe -and -not $_verProbe.TimedOut) {
$script:TorchImportDefinitivelyFailed = $true
substep "PyTorch failed to import rather than timing out -- reinstalling the same family in place." "Yellow"
}
} else {
$shouldRebuild = $true
}
} else {
# Missing python.exe means the venv is incomplete -- rebuild it.
$shouldRebuild = $true
}
if (-not $shouldRebuild) {
# The WMI scan can miss an XPU host; torch.xpu.is_available() proves it before the stale decision.
if ($installedTorchTag -eq "xpu" -and -not $script:IsIntelXpu -and
-not $HasNvidiaSmi -and -not $AmdHasGpuWheels -and
(Test-TorchXpuAvailable -PythonExe $VenvPyExe)) {
$script:IsIntelXpu = $true
substep "Intel XPU runtime confirmed by PyTorch -- keeping this XPU environment." "Cyan"
}
$_pinnedIdx = Get-PinnedTorchIndexUrl
$_expectedKnown = $true
if ($_pinnedIdx) {
$_pinLeaf = Get-TorchIndexLeaf $_pinnedIdx
# Digit-gated: custom rocm-* leaves are not a ROCm family.
if (Test-PipRocmFamilyLeaf $_pinLeaf) {
# Keep the pinned leaf specific: a generic "rocm" masks a rocm6.4 -> gfx1151 change.
$_rocmTags = Get-RocmPinStaleTags -PinLeaf $_pinLeaf -TorchVersion $torchVer
$expectedTorchTag = $_rocmTags.Expected
$installedTorchTag = $_rocmTags.Installed
} elseif ((Test-CudaFamilyLeaf $_pinLeaf) -or $_pinLeaf -eq 'cpu' -or $_pinLeaf -eq 'xpu') {
$expectedTorchTag = $_pinLeaf
} else {
$_expectedKnown = $false
$expectedTorchTag = $installedTorchTag
}
} elseif ($HasNvidiaSmi) {
$expectedTorchTag = Get-PytorchCudaTag
if (-not $expectedTorchTag) {
$_expectedKnown = $false
$expectedTorchTag = $installedTorchTag
}
} elseif ($script:IsIntelXpu) {
# Before the AMD arm: both can be true, and xpu is what gets installed. A CPU wheel is upgraded in place.
$expectedTorchTag = if ($installedTorchTag -eq "cpu") { "cpu" } else { "xpu" }
} elseif ($HasROCm -or $script:ROCmGfxArch) {
# Only arches mapped to a repo.amd.com index get ROCm torch; others expect cpu.
if ($AmdHasGpuWheels) {
# A CPU wheel on a supported AMD arch is upgraded in place, not wiped.
if ($installedTorchTag -eq "cpu") {
$expectedTorchTag = "cpu"
} else {
$expectedTorchTag = "rocm"
}
} else {
$expectedTorchTag = "cpu"
}
} else {
$expectedTorchTag = "cpu"
}
if ($_expectedKnown -and $installedTorchTag -and $installedTorchTag -ne $expectedTorchTag) {
$shouldRebuild = $true
}
}
# download.pytorch.org does not publish this family tag, so only explicit pins are compared.
if ((Test-WinArm64Venv) -and $installedTorchTag -and (Test-CudaFamilyLeaf $installedTorchTag) -and
-not $_pinnedIdx) {
if ($shouldRebuild) {
substep "windows on arm: keeping the installed CUDA torch ($installedTorchTag); it is the only win_arm64 CUDA build published." "Cyan"
}
$shouldRebuild = $false
$script:PinChangedForceReinstall = $false
}
if ($shouldRebuild -and $_pinnedIdx -and $installedTorchTag) {
substep "Torch-index pin changed ($installedTorchTag) -- reinstalling torch from the pin in place." "Cyan"
$script:PinChangedForceReinstall = $true
$shouldRebuild = $false
}
# Only install.ps1 creates venvs, so a direct update must not wipe on a cu* -> cu* move.
if ($shouldRebuild -and -not $_pinnedIdx -and $installedTorchTag -and
(Test-CudaFamilyLeaf $installedTorchTag) -and (Test-CudaFamilyLeaf $expectedTorchTag)) {
substep "CUDA family $installedTorchTag does not cover this host -- reinstalling $expectedTorchTag in place." "Cyan"
$script:PinChangedForceReinstall = $true
$shouldRebuild = $false
}
# A direct update never wipes a +xpu venv: on hybrid NVIDIA+Arc the expected tag is cu*.
if ($shouldRebuild -and -not $InstallerManagedSetup -and $installedTorchTag -eq "xpu") {
substep "Keeping the installed Intel XPU environment (this host expects $expectedTorchTag)." "Yellow"
substep "Re-run install.ps1 to replace it -- that path rebuilds with a rollback copy." "Yellow"
$shouldRebuild = $false
# Stay on the xpu index, or triton-windows lands over torch's XPU triton.
$script:PreservedXpuVenv = $true
}
# Never force-reinstall a different family over a GPU wheel install.ps1 just selected
# ($env:UNSLOTH_INSTALLER_TORCH_TAG); a rescan disagreeing is setup's probe failing, not new hardware.
# $expectedTorchTag is read only in the message: it is unset when torch did not import (StrictMode).
if ($shouldRebuild -and $InstallerManagedSetup -and
$installedTorchTag -and $installedTorchTag -ne "cpu" -and
((-not $InstallerTorchTag) -or $installedTorchTag -eq $InstallerTorchTag)) {
substep "This host rescanned as $expectedTorchTag but the installer just placed a $installedTorchTag build here -- keeping it." "Yellow"
substep "Set UNSLOTH_TORCH_INDEX_URL to move this environment onto another PyTorch build on purpose." "DarkGray"
$shouldRebuild = $false
# The index selection rescans and its AMD/XPU arms force-reinstall regardless, so record the keep.
$script:PreservedInstallerTorchTag = $installedTorchTag
if ($installedTorchTag -eq "xpu") { $script:PreservedXpuVenv = $true }
}
$reason = $null
if ($shouldRebuild) {
$reason = if ($installedTorchTag) { "torch $installedTorchTag != required $expectedTorchTag" } else { "torch could not be imported" }
# Print python's last stderr line so a WinError 126 reads as a driver problem.
if ($_verProbe -and -not $_verProbe.Ok -and $_verProbe.Error) {
# No @(...)[0]: indexing an empty array is fatal under StrictMode.
$_probeErrLine = $_verProbe.Error -split "`r?`n" |
Where-Object { $_.Trim() } | Select-Object -Last 1
if ($_probeErrLine) { substep "PyTorch reported: $($_probeErrLine.Trim())" "DarkGray" }
}
}
# Repair in place: install.ps1 is the caller and already did its rollback, and the venv's
# python.exe running this script is locked, so aborting or deleting could never converge.
if ($shouldRebuild -and $InstallerManagedSetup) {
substep "Environment does not match this host ($reason) -- reinstalling PyTorch in place." "Yellow"
substep "install.ps1 keeps a rollback copy of the previous environment until this run succeeds." "DarkGray"
$script:PinChangedForceReinstall = $true
$shouldRebuild = $false
}
# A direct update never wipes a cu* venv just because nvidia-smi did not answer. The -and order
# keeps reads legal under StrictMode.
if ($shouldRebuild -and -not $InstallerManagedSetup -and
$installedTorchTag -and (Test-CudaFamilyLeaf $installedTorchTag) -and
-not $_pinnedIdx -and -not $HasNvidiaSmi -and $expectedTorchTag -eq "cpu") {
substep "nvidia-smi did not answer, but this venv holds a $installedTorchTag build -- keeping it." "Yellow"
substep "If training runs on CPU, re-run install.ps1: irm https://unsloth.ai/install.ps1 | iex" "Yellow"
$shouldRebuild = $false
# Otherwise the index selection rescans and routes to /cpu.
$script:PreservedInstallerTorchTag = $installedTorchTag
}
# A direct `studio update` runs from the venv's python.exe, so wiping breaks the CLI.
# Must stay LAST of the direct-update escapes: it matches every stale direct update.
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: sweep moved-aside venvs. Strictly validated: ours root, generated
# name shape, no reparse point, no live owner, and a sign of a moved environment.
$_venvParent = Split-Path -Parent $VenvDir
$_venvLeaf = Split-Path -Leaf $VenvDir
# Trailing -<n> matches the rename suffix, as in install.sh's _start_studio_venv_replacement.
$_staleShape = '^' + [regex]::Escape($_venvLeaf) + '\.stale-[0-9]{14}-([0-9]+)(?:-[0-9]+)?$'
$_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: its filling differs between 5.1 and 7.x, and it decides deletes.
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 }
$_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"
# Custom UNSLOTH_STUDIO_HOME: require the ownership marker (content-checked) before a recursive delete.
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"
}
# Rename, then delete: a rename is all-or-nothing, Remove-Item can stop half-way.
# pid plus timestamp plus suffix avoids name collisions.
$_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 {
Rename-Item -LiteralPath $VenvDir -NewName $_staleLeaf -ErrorAction Stop
} catch {
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 and after a failed delete, or the sweep refuses the half-deleted copy.
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"
}
}
}
if (-not (Test-Path -LiteralPath $VenvDir)) {
Write-StudioLine "[ERROR] Virtual environment not found at $VenvDir" -ForegroundColor Red
Write-StudioLine " Run install.ps1 first to create the environment:" -ForegroundColor Yellow
Write-StudioLine " irm https://unsloth.ai/install.ps1 | iex" -ForegroundColor Yellow
Exit-SetupFailure "Virtual environment not found at $VenvDir"
} else {
substep "reusing existing virtual environment at $VenvDir"
$_venvPyExe = Join-Path $VenvDir "Scripts\python.exe"
$_venvActivate = Join-Path $VenvDir "Scripts\Activate.ps1"
if (Test-Path -LiteralPath $_venvPyExe) {
# Activate.ps1 missing would silently install into PATH's python and exit 0.
if (-not (Test-Path -LiteralPath $_venvActivate)) {
Write-StudioLine "[ERROR] $VenvDir has no activation script at Scripts\Activate.ps1." -ForegroundColor Red
Write-StudioLine " The environment is incomplete rather than out of date. Re-run the installer" -ForegroundColor Yellow
Write-StudioLine " to rebuild it: irm https://unsloth.ai/install.ps1 | iex" -ForegroundColor Yellow
Exit-SetupFailure "No activation script at $_venvActivate"
}
try {
$_venvPyVer = (& $_venvPyExe --version 2>&1 | Out-String).Trim()
if ($_venvPyVer) { substep $_venvPyVer }
} catch {}
} else {
# Stop here: with no python.exe, setup would install the whole stack on PATH python and exit 0.
Write-StudioLine "[ERROR] $VenvDir has no interpreter at Scripts\python.exe." -ForegroundColor Red
Write-StudioLine " The environment is incomplete rather than out of date. Re-run the installer" -ForegroundColor Yellow
Write-StudioLine " to rebuild it: irm https://unsloth.ai/install.ps1 | iex" -ForegroundColor Yellow
Exit-SetupFailure "No interpreter at $_venvPyExe"
}
}
# pip/python write to stderr even on success, which -ErrorAction Stop makes terminating on PS 5.1.
$prevEAP = $ErrorActionPreference
$ErrorActionPreference = "Continue"
# A truncated or unparseable Activate.ps1 silently leaves the ambient python first on PATH, and
# install.ps1 would then commit over its rollback. Assert the post-condition, not VIRTUAL_ENV.
function Assert-VenvActivated {
param([Parameter(Mandatory = $true)][string]$VenvDir)
# Normalise both sides through Get-Item as Activate.ps1 does. Return unless provably wrong.
$venvRoot = $null
try { $venvRoot = (Get-Item -LiteralPath $VenvDir -Force -ErrorAction Stop).FullName.TrimEnd('\', '/') } catch { $venvRoot = $null }
if (-not $venvRoot) { return }
$_pyCmd = Get-Command python -ErrorAction SilentlyContinue | Select-Object -First 1
# Only an Application resolved off PATH is decidable.
if ($_pyCmd -and $_pyCmd.CommandType -ne 'Application') { return }
$_pyPath = $null
if ($_pyCmd -and $_pyCmd.Source) {
try { $_pyPath = (Get-Item -LiteralPath $_pyCmd.Source -Force -ErrorAction Stop).FullName } catch { $_pyPath = $_pyCmd.Source }
}
if ($_pyPath) {
foreach ($_sep in @('\', '/')) {
if ($_pyPath.StartsWith($venvRoot + $_sep, [System.StringComparison]::OrdinalIgnoreCase)) { return }
}
}
$_where = if ($_pyPath) { $_pyPath } else { "nothing on PATH" }
Write-StudioLine "[ERROR] Activating $VenvDir did not take effect: python resolves to $_where." -ForegroundColor Red
Write-StudioLine " The activation script is present but did not put the environment on PATH," -ForegroundColor Yellow
Write-StudioLine " so the environment is incomplete rather than out of date. Re-run the installer" -ForegroundColor Yellow
Write-StudioLine " to rebuild it: irm https://unsloth.ai/install.ps1 | iex" -ForegroundColor Yellow
Exit-SetupFailure "Activating $VenvDir did not put its interpreter on PATH (python resolves to $_where)"
}
# Mirrors install.ps1's Install-UvFromRelease with a pinned SHA-256 instead of remote script.
# tests/studio/test_installer_av_shapes.py (AV_SHAPES_RECORD)
# Bumping the version means bumping all 3 hashes, and each Wheel/WheelSha256 as in install.ps1:
# curl -sL https://github.com/astral-sh/uv/releases/download/<ver>/uv-<arch>-pc-windows-msvc.zip.sha256
$UvPinnedVersion = "0.13.5"
$UvPinnedAssets = @{
"x86_64" = @{ Asset = "uv-x86_64-pc-windows-msvc.zip"; Sha256 = "A38B8D1902B7CFBC76B423BA1BB456F623F42064CDC72628B6075B89AFD1019A"
Wheel = "packages/32/ea/771744a784b16aa21d195cb5d5d5a2878d72fa00fc26f11ea3f9646994fe/uv-0.13.5-py3-none-win_amd64.whl"; WheelSha256 = "1FB29FC46BA12033E2EF95A95AC79D649E71BBB1358419BBBCBD19D86026EF2F" }
"arm64" = @{ Asset = "uv-aarch64-pc-windows-msvc.zip"; Sha256 = "09F47EDF90726084A70F9426F6E3CA4F46E9BF7CBF23B1716EC64D60B055FAE3"
Wheel = "packages/52/67/1f31243f75ece410f2db1afdfc9a9f9722fdee2385e4a347c3ca1dee6d13/uv-0.13.5-py3-none-win_arm64.whl"; WheelSha256 = "0548460D46C8667488B1F089E936F29F0EDFB1CC753F9152FFBD8BC84A46AA20" }
"x86" = @{ Asset = "uv-i686-pc-windows-msvc.zip"; Sha256 = "96228420D0A89A64757AFBA59932C1E58C4977E4122F2CC9F8615A51BA2D3084"
Wheel = "packages/00/7c/e38b312abaae1bd59ff5886126f48e9e223fbb9a8edf9e236ede976f67cb/uv-0.13.5-py3-none-win32.whl"; WheelSha256 = "F4E55A6E2A1089FE74ED50FBDF2DF0F6F336EE148AD232B05932DB5DEEE8007E" }
}
# Not Get-HostMachineArch: "other" cannot pick between x86_64 and i686.
function Get-UvHostArch {
$osArch = ""
try { $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() } catch { $osArch = "" }
$machineArch = ""
try { $machineArch = [string][Environment]::GetEnvironmentVariable("PROCESSOR_ARCHITECTURE", "Machine") } catch { $machineArch = "" }
$signals = @($machineArch, [string]$env:PROCESSOR_ARCHITEW6432, [string]$env:PROCESSOR_ARCHITECTURE, $osArch)
foreach ($s in $signals) {
if ($s.ToLowerInvariant() -eq "arm64") { return "arm64" }
}
foreach ($s in $signals) {
if ([string]::IsNullOrWhiteSpace($s)) { continue }
switch ($s.ToLowerInvariant()) {
"amd64" { return "x86_64" }
"x64" { return "x86_64" }
"x86" { return "x86" }
}
}
return "unknown"
}
function Get-SetupUvExecutableVerdict {
# Mirrors install.ps1 Get-UvExecutableVerdict: "ok", "failed" or "unknown". Returns ONLY the verdict;
# only a non-zero exit is "failed".
param([string]$Path)
# Which uv answered, without a second pipeline value.
$script:SetupUvVersionLine = ""
if (-not $Path -or -not (Test-Path -LiteralPath $Path)) { return "failed" }
$outFile = [System.IO.Path]::GetTempFileName()
$errFile = [System.IO.Path]::GetTempFileName()
try {
$proc = Start-Process -FilePath $Path -ArgumentList "--version" -NoNewWindow -PassThru `
-RedirectStandardOutput $outFile -RedirectStandardError $errFile -ErrorAction Stop
if (-not $proc.WaitForExit(20000)) {
try { $proc.Kill() } catch {}
substep "uv did not answer --version within 20s; installing it unprobed."
return "unknown"
}
# The timed wait can return before the exit code is cached; the parameterless wait settles it.
try { $proc.WaitForExit() } catch {}
$answer = ""
try { $answer = Get-Content -LiteralPath $outFile -Raw -ErrorAction SilentlyContinue } catch {}
if ($answer) { $script:SetupUvVersionLine = $answer.Trim() }
$code = $null
try { $code = $proc.ExitCode } catch {}
if ($null -eq $code -or "$code" -eq "") {
if ($answer -and ($answer.Trim() -match '^uv \d+\.\d+')) { return "ok" }
substep "uv --version gave no exit code; installing it unprobed."
return "unknown"
}
if ($code -eq 0) { return "ok" }
$detail = ""
try {
$detail = Get-Content -LiteralPath $errFile -Raw -ErrorAction SilentlyContinue
} catch {}
if ($detail) { $detail = " " + (($detail.Trim()) -replace '\s+', ' ') }
substep "uv --version exited $code.$detail"
return "failed"
} catch {
substep "could not probe uv: $($_.Exception.Message); installing it unprobed."
return "unknown"
} finally {
Remove-Item -LiteralPath $outFile -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath $errFile -Force -ErrorAction SilentlyContinue
}
}
function Get-UvInstallDir {
# astral's destination priority, shared so install and lookup cannot drift.
foreach ($candidate in @($env:UV_INSTALL_DIR, $env:UV_UNMANAGED_INSTALL, $env:XDG_BIN_HOME)) {
if ($candidate) { return $candidate }
}
# Join-Path returns null for a nonexistent drive under Continue.
if ($env:XDG_DATA_HOME) {
$fromData = Join-Path $env:XDG_DATA_HOME "../bin" -ErrorAction SilentlyContinue
if ($fromData) { return $fromData }
}
$userHome = if ($env:USERPROFILE) { $env:USERPROFILE } else { $HOME }
if (-not $userHome) { return $null }
return (Join-Path $userHome ".local\bin")
}
function Install-UvFromPinnedRelease {
$script:UvPinnedUnfetched = $false
$arch = Get-UvHostArch
if (-not $UvPinnedAssets.ContainsKey($arch)) {
Write-Output "No uv build is published for this architecture ($arch)."
return $false
}
$asset = $UvPinnedAssets[$arch].Asset
$wanted = $UvPinnedAssets[$arch].Sha256
$remote = $asset
$wheelDir = $null
$destDir = Get-UvInstallDir
if (-not $destDir) {
Write-Output "Could not determine a home directory to install uv into."
return $false
}
# astral's sources in astral's order, each exclusive when set; the digest still applies.
$uvBase = if ($env:UV_DOWNLOAD_URL) {
@("$($env:UV_DOWNLOAD_URL.TrimEnd('/'))")
} elseif ($env:INSTALLER_DOWNLOAD_URL) {
@("$($env:INSTALLER_DOWNLOAD_URL.TrimEnd('/'))")
} elseif ($env:UV_INSTALLER_GHE_BASE_URL) {
@("$($env:UV_INSTALLER_GHE_BASE_URL.TrimEnd('/'))/astral-sh/uv/releases/download/$UvPinnedVersion")
} elseif ($env:UV_INSTALLER_GITHUB_BASE_URL) {
@("$($env:UV_INSTALLER_GITHUB_BASE_URL.TrimEnd('/'))/astral-sh/uv/releases/download/$UvPinnedVersion")
} elseif ($env:UNSLOTH_UV_WHEEL_MIRROR) {
$remote = $UvPinnedAssets[$arch].Wheel
$wanted = $UvPinnedAssets[$arch].WheelSha256
$wheelDir = "uv-$UvPinnedVersion.data/scripts"
@("$($env:UNSLOTH_UV_WHEEL_MIRROR.TrimEnd('/'))")
} else {
@("https://releases.astral.sh/github/uv/releases/download/$UvPinnedVersion",
"https://github.com/astral-sh/uv/releases/download/$UvPinnedVersion")
}
$work = Join-Path ([System.IO.Path]::GetTempPath()) ("unsloth-uv-" + [guid]::NewGuid().ToString('N').Substring(0, 8))
$zip = Join-Path $work $asset
try {
[System.IO.Directory]::CreateDirectory($work) | Out-Null
# Digest per mirror: a proxy can answer 200 with its own body.
$downloaded = $false
$script:UvPinnedUnfetched = $true
foreach ($base in $uvBase) {
Write-Output "downloading uv $UvPinnedVersion ($arch) from $base..."
try {
Invoke-WebRequest -UseBasicParsing -OutFile $zip -Uri "$base/$remote"
} catch {
Write-Output "uv download failed: $($_.Exception.Message)"
continue
}
$script:UvPinnedUnfetched = $false
$actual = ""
try { $actual = (Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash } catch {}
if ($actual -eq $wanted) {
$downloaded = $true
break
}
Write-Output "uv download failed checksum verification -- discarding it."
Write-Output "expected $wanted, got $actual"
Remove-Item -LiteralPath $zip -Force -ErrorAction SilentlyContinue
}
if (-not $downloaded) { return $false }
Expand-Archive -LiteralPath $zip -DestinationPath $work -Force
[System.IO.Directory]::CreateDirectory($destDir) | Out-Null
$srcRoot = if ($wheelDir) { Join-Path $work $wheelDir } else { $work }
$stagedUv = Join-Path $srcRoot "uv.exe"
if (-not (Test-Path -LiteralPath $stagedUv)) {
Write-Output "uv.exe was not present in $asset."
return $false
}
# Run the staged binary first: policy may refuse it while an older uv works.
if ((Get-SetupUvExecutableVerdict -Path $stagedUv) -eq "failed") {
Write-Output "the downloaded uv $UvPinnedVersion could not run on this machine."
return $false
}
# uvw.exe has no console to probe; the staged uv.exe stands for the verified set.
$haveUv = $true
foreach ($exe in @("uv.exe", "uvx.exe", "uvw.exe")) {
$src = Join-Path $srcRoot $exe
if (-not (Test-Path -LiteralPath $src)) { continue }
$dst = Join-Path $destDir $exe
try {
Copy-Item -LiteralPath $src -Destination $dst -Force -ErrorAction Stop
} catch {
$haveUv = $false
break
}
if ($exe -eq "uv.exe") {
# Invoke-SetupCommand uses Continue, so compare against the archive: a stale uv.exe must not pass.
$copied = $false
try {
$copied = (Test-Path -LiteralPath $dst) -and
(Get-FileHash -LiteralPath $dst -Algorithm SHA256).Hash -eq
(Get-FileHash -LiteralPath $src -Algorithm SHA256).Hash
} catch { $copied = $false }
if (-not $copied) { $haveUv = $false; break }
}
}
if (-not $haveUv) {
Write-Output "uv.exe was not present in $asset."
return $false
}
} finally {
Remove-Item -LiteralPath $work -Recurse -Force -ErrorAction SilentlyContinue
}
# astral's PATH opt-outs: an unmanaged install implies no-modify-path.
if (-not $env:UV_NO_MODIFY_PATH -and -not $env:UV_UNMANAGED_INSTALL) {
Add-ToUserPath -Directory $destDir -Position Prepend | Out-Null
}
$env:PATH = "$destDir;$env:PATH"
# Invoke-SetupCommand returns $LASTEXITCODE, not the pipeline value, so record on script scope.
$script:UvPinnedInstalled = $true
return $true
}
$ActivateScript = Join-Path $VenvDir "Scripts\Activate.ps1"
function Enter-StudioVenv {
if ($StageRoot) {
$env:VIRTUAL_ENV = $VenvDir
$env:PATH = (Join-Path $VenvDir "Scripts") + ";" + $env:PATH
Remove-Item Env:PYTHONHOME -ErrorAction SilentlyContinue
Remove-Item Env:PYTHONPATH -ErrorAction SilentlyContinue
return
}
. $ActivateScript
Remove-Item Env:PYTHONPATH -ErrorAction SilentlyContinue
}
Enter-StudioVenv
Assert-VenvActivated -VenvDir $VenvDir
function Find-InstalledUv {
# Find a uv a previous run installed but this PATH lacks, to avoid re-downloading every update.
# .NET Combine, not the path cmdlet: it terminates on a missing drive under Stop.
$installerDest = $null
try { $installerDest = Get-UvInstallDir } catch { $installerDest = $null }
$candidates = @($installerDest, $env:UV_INSTALL_DIR, $env:UV_UNMANAGED_INSTALL, $env:XDG_BIN_HOME)
if ($env:XDG_DATA_HOME) { $candidates += [System.IO.Path]::Combine($env:XDG_DATA_HOME, "..", "bin") }
$userHome = if ($env:USERPROFILE) { $env:USERPROFILE } else { $HOME }
if ($userHome) { $candidates += [System.IO.Path]::Combine($userHome, ".local", "bin") }
# winget's alias dir reaches PATH only via the registry.
if ($env:LOCALAPPDATA) { $candidates += [System.IO.Path]::Combine($env:LOCALAPPDATA, "Microsoft", "WinGet", "Links") }
$script:InstalledUvLooked = @()
# Assigned even when no uv.exe exists (StrictMode).
$script:InstalledUvProbeMiss = $null
$script:InstalledUvTooOld = $null
$seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase)
foreach ($dir in $candidates) {
if (-not $dir) { continue }
if (-not $seen.Add([string]$dir)) { continue }
$exe = [System.IO.Path]::Combine($dir, "uv.exe")
$script:InstalledUvLooked += $exe
if (-not (Test-Path -LiteralPath $exe -PathType Leaf -ErrorAction SilentlyContinue)) { continue }
# "ok" only, asked twice: no digest vouches for a found binary, and one miss downgraded uv.
if ((Get-InstalledUvVerdict -Path $exe) -ne "ok") { continue }
if (-not (Test-SetupUvVersionAtLeast -VersionLine $script:SetupUvVersionLine -Minimum $SetupUvMinVersion)) {
$script:InstalledUvTooOld = $exe
continue
}
return $dir
}
return $null
}
# The floor a found uv has to clear: install.ps1's UvMinVersion, so reuse accepts exactly what
# the Windows installer accepts. Below 0.13.4 uv's bundled roots still trust the compromised
# emSign CAs (GHSA-hq85-5cpj-mr62).
$SetupUvMinVersion = "0.13.4"
function Test-SetupUvVersionAtLeast {
# Unparseable is $false.
param([string]$VersionLine, [string]$Minimum)
if (-not $VersionLine) { return $false }
if ($VersionLine -notmatch '(?m)^\s*uv\s+(\d+(?:\.\d+){0,2})([-+]\S*)?') { return $false }
$found = $Matches[1]
# Reading an absent group throws under StrictMode.
$pre = if ($Matches.ContainsKey(2)) { $Matches[2] } else { "" }
try {
if ([version]$found -gt [version]$Minimum) { return $true }
# A prerelease of the floor does not clear it, as install.sh's _uv_version_ok.
if ([version]$found -eq [version]$Minimum) { return (-not $pre) }
return $false
} catch { return $false }
}
function Get-InstalledUvVerdict {
param([string]$Path)
$verdict = @(Get-SetupUvExecutableVerdict -Path $Path)[-1]
if ($verdict -eq "ok") { return "ok" }
Start-Sleep -Seconds 2
$verdict = @(Get-SetupUvExecutableVerdict -Path $Path)[-1]
if ($verdict -ne "ok") { $script:InstalledUvProbeMiss = "$Path ($verdict)" }
return $verdict
}
# Try to use uv (much faster than pip), fall back to pip if unavailable
# A uv on PATH below the floor is passed over like an installed one, and kept only when the
# download fails (offline). One that hangs, fails or answers no version counts as old. A staged run
# never downloads: it keeps the old uv, as before, behind the Windows trust store.
function Get-SetupPathUvTooOld {
$pathUv = Get-Command uv -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
if (-not $pathUv) { return $null }
# Timed: a uv that hangs on --version must not stall every setup before the pinned one installs.
$verdict = @(Get-SetupUvExecutableVerdict -Path $pathUv.Source)[-1]
if ($verdict -ne "ok") { return $pathUv.Source }
$line = $script:SetupUvVersionLine
if ("$line" -notmatch '^\s*uv\s' -or
-not (Test-SetupUvVersionAtLeast -VersionLine "$line" -Minimum $SetupUvMinVersion)) {
return $pathUv.Source
}
return $null
}
$UseUv = $false
$installedUvDir = $null
$pathUvOld = Get-SetupPathUvTooOld
if ((Get-Command uv -ErrorAction SilentlyContinue) -and -not $pathUvOld) {
$UseUv = $true
} elseif (($installedUvDir = Find-InstalledUv)) {
# Appended: a python.exe beside uv must not step in front of the staged interpreter.
$env:PATH = "$env:PATH;$installedUvDir"
if ($pathUvOld) {
# Re-entering the venv restores the pre-venv PATH first, so it goes before the current uv
# is put in front of the old one, right behind the venv's Scripts.
Enter-StudioVenv
$env:PATH = (Join-Path $VenvDir "Scripts") + ";$installedUvDir;$env:PATH"
}
substep "reusing the uv installed at $installedUvDir (it was not on PATH)"
$UseUv = $true
} elseif (-not $StageRoot) {
if (-not $script:InstalledUvTooOld) { $script:InstalledUvTooOld = $pathUvOld }
if ($script:InstalledUvTooOld) {
substep "the uv at $($script:InstalledUvTooOld) is older than $SetupUvMinVersion; installing the pinned release"
} elseif ($script:InstalledUvProbeMiss) {
substep "the uv at $($script:InstalledUvProbeMiss) did not answer --version twice; installing the pinned release"
} elseif ($script:InstalledUvLooked) {
substep "no installed uv at $($script:InstalledUvLooked -join ', '); installing the pinned release"
}
substep "installing uv package manager..."
try {
$script:UvPinnedInstalled = $false
Invoke-SetupCommand { Install-UvFromPinnedRelease } | Out-Null
if (-not $script:UvPinnedInstalled -and $script:UvPinnedUnfetched -and (Use-MirrorSpare uvbin)) {
Invoke-SetupCommand { Install-UvFromPinnedRelease } | Out-Null
}
# Fallback to winget after a failed pinned install, never the remote installer script.
if (-not $script:UvPinnedInstalled -and (Get-Command winget -ErrorAction SilentlyContinue)) {
Invoke-SetupCommand {
winget install --id astral-sh.uv --source winget --accept-source-agreements `
--accept-package-agreements --silent
} | Out-Null
}
Refresh-Environment
# Refresh-Environment drops the venv's Scripts dir from PATH.
Enter-StudioVenv
# Refresh-Environment may drop the uv dir; without it the run falls back to pip.
$uvDir = Get-UvInstallDir
if ($uvDir -and (Test-Path -LiteralPath (Join-Path $uvDir "uv.exe"))) {
$env:PATH = $uvDir + ";" + $env:PATH
}
if (Get-Command uv -ErrorAction SilentlyContinue) { $UseUv = $true }
} catch { }
# No download (offline): the old uv on PATH still beats pip, as it did before the floor moved.
if ($pathUvOld -and -not $UseUv -and (Get-Command uv -ErrorAction SilentlyContinue)) { $UseUv = $true }
# Still on a uv below the floor: its bundled roots trust the compromised emSign CA, so the
# Windows store decides instead. A download that failed while online lands here too.
if ($UseUv -and -not $script:UvPinnedInstalled) {
$activeUv = Get-Command uv -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
if ($activeUv) {
$null = Get-SetupUvExecutableVerdict -Path $activeUv.Source
if (-not (Test-SetupUvVersionAtLeast -VersionLine "$($script:SetupUvVersionLine)" -Minimum $SetupUvMinVersion)) {
if (-not $env:UV_SYSTEM_CERTS) { $env:UV_SYSTEM_CERTS = "1" }
if (-not $env:UV_NATIVE_TLS) { $env:UV_NATIVE_TLS = "1" }
}
}
}
} elseif ($pathUvOld) {
# Staged runs never download: the old uv on PATH still beats pip, behind the Windows store.
$UseUv = $true
if (-not $env:UV_SYSTEM_CERTS) { $env:UV_SYSTEM_CERTS = "1" }
if (-not $env:UV_NATIVE_TLS) { $env:UV_NATIVE_TLS = "1" }
}
# The re-activation above sits in a catch that swallows failures; re-check before Fast-Install.
Assert-VenvActivated -VenvDir $VenvDir
# Only --prerelease allow maps to pip (--pre); other uv resolver flags and values are dropped.
function Remove-UvOnlyResolverFlags {
param([object[]]$Arguments)
$kept = @()
$valueOf = ""
foreach ($arg in @($Arguments)) {
$token = [string]$arg
if ($valueOf) {
if ($valueOf -eq '--prerelease' -and $token -eq 'allow') { $kept += '--pre' }
$valueOf = ""
continue
}
if ($token -eq '--index-strategy' -or $token -eq '--prerelease') { $valueOf = $token; continue }
if ($token -like '--index-strategy=*') { continue }
if ($token -like '--prerelease=*') {
if ($token -eq '--prerelease=allow') { $kept += '--pre' }
continue
}
$kept += $token
}
return ,$kept
}
function Fast-Install {
param([Parameter(ValueFromRemainingArguments=$true)]$Args_)
# An explicit --index-url must win: inherited index vars pull CPU torch over GPU.
$saved = @{}
$pinned = @($Args_) -contains '--index-url'
if ($pinned) {
foreach ($n in 'UV_DEFAULT_INDEX', 'UV_INDEX_URL', 'UV_INDEX', 'UV_EXTRA_INDEX_URL',
'UV_TORCH_BACKEND', 'UV_FIND_LINKS', 'PIP_EXTRA_INDEX_URL', 'PIP_FIND_LINKS',
'PIP_NO_INDEX', 'PIP_INDEX_URL',
'UV_CONFIG_FILE', 'UV_NO_CONFIG', 'PIP_CONFIG_FILE') {
$saved[$n] = [Environment]::GetEnvironmentVariable($n)
Remove-Item "Env:$n" -ErrorAction SilentlyContinue
}
$env:UV_NO_CONFIG = '1'
# 'nul' stops a `pip config` extra-index-url reaching the pip fallback.
$env:PIP_CONFIG_FILE = 'nul'
}
try {
if ($UseUv) {
$VenvPy = (Get-Command python).Source
$result = & uv pip install --python $VenvPy @Args_ 2>&1
if ($LASTEXITCODE -eq 0) { return }
}
$pipArgs = Remove-UvOnlyResolverFlags -Arguments $Args_
& python -m pip install @pipArgs 2>&1
}
finally {
if ($pinned) {
Remove-Item "Env:UV_NO_CONFIG" -ErrorAction SilentlyContinue
Remove-Item "Env:PIP_CONFIG_FILE" -ErrorAction SilentlyContinue
}
foreach ($n in $saved.Keys) { if ($null -ne $saved[$n]) { Set-Item "Env:$n" $saved[$n] } }
}
}
function Fast-Uninstall {
param([Parameter(ValueFromRemainingArguments=$true)]$Args_)
if ($UseUv) {
$VenvPy = (Get-Command python).Source
& uv pip uninstall --python $VenvPy @Args_ 2>&1
if ($LASTEXITCODE -eq 0) { return }
}
& python -m pip uninstall -y @Args_ 2>&1
}
# pip only: uv has no `pip download`. Scrubbed like Fast-Install.
function Fast-Download {
param([Parameter(ValueFromRemainingArguments=$true)]$Args_)
$saved = @{}
foreach ($n in 'PIP_EXTRA_INDEX_URL', 'PIP_FIND_LINKS', 'PIP_NO_INDEX', 'PIP_INDEX_URL', 'PIP_CONFIG_FILE') {
$saved[$n] = [Environment]::GetEnvironmentVariable($n)
Remove-Item "Env:$n" -ErrorAction SilentlyContinue
}
$env:PIP_CONFIG_FILE = 'nul'
try {
& python -m pip download @Args_ 2>&1
}
finally {
Remove-Item "Env:PIP_CONFIG_FILE" -ErrorAction SilentlyContinue
foreach ($n in $saved.Keys) { if ($null -ne $saved[$n]) { Set-Item "Env:$n" $saved[$n] } }
}
}
# ── Check if Python deps need updating ──
# One definition of a verified install for the incomplete-install guard and the offline rule.
function Test-StudioInstallVerified {
try {
& python -c "
import os, sys
sys.path.insert(0, sys.argv[1])
try:
import install_manifest
except Exception:
# Present but unimportable is damage, not an old release, and this is the
# one file whose damage silences every check below. Absent keeps the old
# escape: separating it from an old tree needs a RECORD walk here, and the
# CLI already reports studio_install_manifest_missing.
sys.exit(1 if os.path.isfile(os.path.join(sys.argv[1], 'install_manifest.py')) else 0)
import inspect
# Only skip the payload scan on a tree too old to offer it. Catching TypeError instead
# also swallowed one raised inside verify_install, and retried shallow on real damage.
deep = {'deep': True} if 'deep' in inspect.signature(install_manifest.verify_install).parameters else {}
sys.exit(0 if install_manifest.verify_install(**deep)['ok'] else 1)
" "$PSScriptRoot" 2>$null | Out-Null
# Out-Null: stdout left in the success stream would make the return value truthy.
return ($LASTEXITCODE -eq 0)
} catch { return $false }
}
function Test-UvOfflineRequested {
# Mirrors _uv_offline_requested in setup.sh.
return (Test-UvEnvFlag "UV_OFFLINE")
}
function Invoke-FastPathEscapes {
# Every reason an up-to-date package is still not a working install. Function assignments are
# local, so the flag is copied in and published on the way out.
$SkipPythonDeps = $script:SkipPythonDeps
# UNSLOTH_STUDIO_FULL_DEPS must work here: install_python_stack.py never runs once the compare skips.
$_fullDepsRequested = "$($env:UNSLOTH_STUDIO_FULL_DEPS)".Trim()
if (@('1', 'true', 'yes', 'on') -contains $_fullDepsRequested.ToLowerInvariant()) {
substep "UNSLOTH_STUDIO_FULL_DEPS is set -- forcing dependency pass..." "Cyan"
$SkipPythonDeps = $false
}
# Pre-pin installs stuck on anyio>=4.14 need the repair.
$_anyioBad = $false
try {
& python -c "
import re, sys
from importlib.metadata import version, PackageNotFoundError
try:
parts = version('anyio').split('.')
major = int(parts[0])
minor = int(re.sub(r'[^0-9].*', '', parts[1])) if len(parts) > 1 else 0
except (PackageNotFoundError, ValueError, IndexError):
sys.exit(1)
sys.exit(0 if (major, minor) >= (4, 14) else 1)
" 2>$null
if ($LASTEXITCODE -eq 0) { $_anyioBad = $true }
} catch {}
if ($_anyioBad) {
substep "anyio >=4.14 found (#6483) -- forcing dependency pass to repair..." "Cyan"
$SkipPythonDeps = $false
}
# A pre-pin tokenizers breaks `import transformers`; ask the metadata, not the import.
$_tokenizersBad = $false
try {
& python -c "
import sys
from importlib.metadata import PackageNotFoundError, requires, version
try:
from packaging.requirements import Requirement
installed = version('tokenizers')
windows = [
req.specifier
for req in (Requirement(raw) for raw in (requires('transformers') or []))
if req.name == 'tokenizers' and req.marker is None
]
except (PackageNotFoundError, ImportError, ValueError, IndexError):
sys.exit(1)
sys.exit(0 if windows and installed not in windows[0] else 1)
" 2>$null
if ($LASTEXITCODE -eq 0) { $_tokenizersBad = $true }
} catch {}
if ($_tokenizersBad) {
substep "installed transformers rejects the installed tokenizers -- forcing dependency pass to repair..." "Cyan"
$SkipPythonDeps = $false
}
if ($env:UNSLOTH_DESKTOP_BACKEND_VERSION) {
# Cleared only on a confirmed exit 0, as setup.sh does.
$_desktopVerBad = $true
try {
& python -c "
import re, sys
try:
from packaging.version import parse as parse_v
except ImportError:
def parse_v(v):
match = re.fullmatch(r'(\d+)\.(\d+)\.(\d+)', (v or '').strip())
return (int(match.group(1)), int(match.group(2)), int(match.group(3))) if match else None
installed = parse_v(sys.argv[1])
required = parse_v(sys.argv[2])
sys.exit(0 if installed is not None and required is not None and installed >= required else 1)
" "$InstalledVer" "$env:UNSLOTH_DESKTOP_BACKEND_VERSION" 2>$null | Out-Null
if ($LASTEXITCODE -eq 0) { $_desktopVerBad = $false }
} catch {}
if ($_desktopVerBad) {
substep "$_PkgName $InstalledVer < $env:UNSLOTH_DESKTOP_BACKEND_VERSION (required by desktop app) -- forcing dependency pass to update..." "Cyan"
$SkipPythonDeps = $false
}
}
# The pinned Diffusers build is installed only by the pass.
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
}
}
}
# Intel GPU escapes, gated on the XPU index being reachable or they re-fire forever.
$_pinLeafNow = Get-TorchIndexLeaf (Get-PinnedTorchIndexUrl)
$_xpuIsReachable = (-not $NoTorchMode) -and ((-not $_pinLeafNow) -or ($_pinLeafNow -eq "xpu"))
if ($script:IsIntelXpu -and $SkipPythonDeps -and $_xpuIsReachable) {
# The WHEEL, not the runtime: the pass cannot repair a driver.
if (-not (Test-VenvTorchIsXpuSupported -VenvPath $VenvDir)) {
substep "Intel GPU detected but installed PyTorch is not a supported XPU build -- reinstalling XPU PyTorch" "Cyan"
$SkipPythonDeps = $false
}
}
# The promotion runs after the fast path, so clear $SkipPythonDeps here or CPU torch is kept.
$_nvidiaIsReachable = (-not $NoTorchMode) -and
((-not $_pinLeafNow) -or (Test-CudaFamilyLeaf $_pinLeafNow))
$_nvidiaPreR450 = ($null -ne $script:NvidiaPresenceDriverRelease -and
$script:NvidiaPresenceDriverRelease -lt 450)
if ($SkipPythonDeps -and $script:NvidiaPresenceOnly -and $_nvidiaIsReachable -and
(-not $_nvidiaPreR450) -and $installedTorchTag -eq "cpu") {
substep "NVIDIA GPU found on the PCI bus but the installed PyTorch is a CPU build -- reinstalling CUDA PyTorch" "Cyan"
$SkipPythonDeps = $false
}
if ($SkipPythonDeps -and $script:NvidiaPresenceOnly -and $_nvidiaIsReachable -and
(Test-NvidiaPresenceStaleGpuWheel -InstalledTag $installedTorchTag -PythonExe (Join-Path $VenvDir "Scripts\python.exe"))) {
substep "NVIDIA GPU found on the PCI bus but the installed PyTorch is a $installedTorchTag build that sees no GPU -- running the dependency pass" "Cyan"
$SkipPythonDeps = $false
}
# An explicit xpu pin can leave IsIntelXpu false, so check the installed wheel too.
if ($SkipPythonDeps -and $_xpuIsReachable -and ($script:IsIntelXpu -or $installedTorchTag -eq "xpu")) {
# Name lookups exclude pip's interrupted-replacement backups.
$_xpuDepsCode = "import importlib.metadata as m; " +
"print('BNB=' + next(((d.version or '') for d in m.distributions(name='bitsandbytes')), '')); " +
"print('TRITONWIN=' + next(((d.version or '?') for d in m.distributions(name='triton-windows')), ''))"
$_xpuDeps = Invoke-BoundedPythonProbe -PythonExe "python" -Code $_xpuDepsCode
if (-not $_xpuDeps.Ok) {
substep "Intel XPU dependencies could not be read -- running the dependency pass" "Cyan"
$SkipPythonDeps = $false
} else {
$_bnbVer = if ($_xpuDeps.Output -match '(?m)^BNB=(\S+)\s*$') { $Matches[1] } else { "" }
# Unreadable is stale, the safe direction.
$_bnbNum = ($_bnbVer -replace '[^0-9.].*$', '').TrimEnd('.')
$_bnbStale = $true
if ($_bnbNum -match '^\d+\.\d+') {
try { $_bnbStale = [version]$_bnbNum -lt [version]"0.50.0" } catch {}
}
$_tritonWinPresent = $_xpuDeps.Output -match '(?m)^TRITONWIN=\S+\s*$'
$_xpuTritonRepair = $false
if (-not $_bnbStale -and -not $_tritonWinPresent) {
$_xpuTritonNow = Get-XpuTritonState
$_xpuTritonRepair = (-not $_xpuTritonNow.Known) -or ($_xpuTritonNow.XpuSpec -match '(?i)xpu' -and
(-not $_xpuTritonNow.XpuOk -or -not (Get-TritonRuntimeState).Healthy))
}
$_xpuDepsWhy = if ($_bnbStale -or $_tritonWinPresent) { "Intel XPU dependencies are stale" }
elseif ($_xpuTritonRepair) { "torch's Intel XPU triton is missing, the wrong version or does not import" }
else { "" }
if ($_xpuDepsWhy -and -not $_bnbStale -and ($script:OfflineFastPath -or (Test-UvOfflineRequested))) {
substep "$_xpuDepsWhy but UV_OFFLINE is set -- left for the next online update" "Yellow"
} elseif ($_xpuDepsWhy) {
substep "$_xpuDepsWhy -- running the dependency pass" "Cyan"
$SkipPythonDeps = $false
}
}
}
$script:SkipPythonDeps = $SkipPythonDeps
}
# AMD ROCm: triton-windows paired with torch. The stack resolves unsloth's unpinned triton-windows. 3.9 removed the
# block pointers that torch 2.11 / 2.12's flex_decoding template builds: the first decode fails to compile and flex
# attention then runs unfused for the rest of the process (gpt-oss 4k prefill 0.1 -> 6.7 GB on gfx1151). 3.6 has no
# HIP headers; 3.8 is the verified build. Used by the fast-path escape and the post-stack repair.
function Get-TritonWindowsRocmSpec {
param([string]$TorchVersion)
if ($TorchVersion -match '^2\.(\d+)\.' -and @(11, 12) -contains [int]$Matches[1]) { return "triton-windows>=3.8,<3.9" }
return $null
}
function Get-TritonRuntimeState {
# Judged by the imported runtime, not metadata: a dist-info can say 3.8 while the files are 3.9 or half removed.
# Healthy = triton and a real (non-namespace) triton.language import with their core API, whatever the version.
# Paired = healthy, a final 3.8.x release (no dev / rc) and make_block_ptr present, not 3.9's raise-only stub
# (its message is a constant of the function body; a docstring that mentions the removal does not count).
# A failing import exits non-zero, which reads as neither. No double quotes: the probe helper wraps $Code in them.
$code = "import importlib, inspect, re; t = importlib.import_module('triton'); tl = importlib.import_module('triton.language'); " +
"v = getattr(t, '__version__', '') or ''; " +
"h = getattr(tl, '__file__', None) is not None and callable(getattr(t, 'jit', None)) and callable(getattr(tl, 'program_id', None)); " +
"f = getattr(tl, 'make_block_ptr', None); c = getattr(inspect.unwrap(f), '__code__', None) if callable(f) else None; " +
"d = getattr(inspect.unwrap(f), '__doc__', None) if callable(f) else None; " +
"bp = c is not None and not any(isinstance(k, str) and k != d and 'have been removed' in k for k in c.co_consts); " +
"print('TRITONVER=' + v); print('HEALTHY=' + str(int(bool(h)))); " +
"print('PAIRED=' + str(int(bool(h and bp and re.fullmatch(r'3\.8\.\d+(\.post\d+)?(\+[\w.]+)?', v)))))"
$probe = Invoke-BoundedPythonProbe -PythonExe "python" -Code $code
return @{
Healthy = [bool]($probe.Ok -and $probe.Output -match '(?m)^HEALTHY=1\s*$')
Paired = [bool]($probe.Ok -and $probe.Output -match '(?m)^PAIRED=1\s*$')
}
}
function Get-RocmTritonPairing {
# Reads the venv as it is now; nothing cached from before the install decides. No double quotes:
# Invoke-BoundedPythonProbe wraps $Code in them. ROCm = torch.version.hip, read from torch/version.py without
# importing torch (an untagged ROCm build has no +rocm). The name lookup skips the ~riton_windows-* backup an
# interrupted pip replacement leaves. Triton is only what the metadata reports (a 3.8 record wins over a
# leftover one, a record without Version is skipped); whether the pair is stale comes from the runtime.
$code = "import importlib.metadata as m, importlib.util as u, os, re; " +
"print('TORCH=' + m.version('torch')); " +
"ds = list(m.distributions(name='triton-windows')); vs = [d.version for d in ds if d.version]; " +
"print('TRITONWIN=' + next((x for x in vs if x.startswith('3.8')), vs[0] if vs else '')); " +
"print('TRITONDISTS=' + str(len(ds))); " +
"s = u.find_spec('torch'); p = os.path.join(os.path.dirname(s.origin), 'version.py') if s and s.origin else ''; " +
"t = open(p, encoding='utf-8').read() if p and os.path.isfile(p) else ''; " +
"h = re.search(r'^hip\b[^=\n]*=\s*.([0-9][^\x27\x22\n]*)', t, re.M); " +
"print('HIP=' + (h.group(1) if h else ''))"
$probe = Invoke-BoundedPythonProbe -PythonExe "python" -Code $code
$torch = if ($probe.Ok -and $probe.Output -match '(?m)^TORCH=(\S+)\s*$') { $Matches[1] } else { "" }
$triton = if ($probe.Ok -and $probe.Output -match '(?m)^TRITONWIN=(\S+)\s*$') { $Matches[1] } else { "" }
$dists = if ($probe.Ok -and $probe.Output -match '(?m)^TRITONDISTS=(\d+)\s*$') { [int]$Matches[1] } else { 0 }
$hip = if ($probe.Ok -and $probe.Output -match '(?m)^HIP=(\S+)\s*$') { $Matches[1] } else { "" }
$spec = if ($hip -or $torch -match '\+rocm') { Get-TritonWindowsRocmSpec -TorchVersion $torch } else { $null }
$runtime = if ($spec) { Get-TritonRuntimeState } else { @{ Healthy = $false; Paired = $false } }
# Known is false when the probe itself failed: nothing about the venv was read, so nothing is verified.
return @{ Torch = $torch; Triton = $triton; Dists = $dists; Spec = $spec; Stale = [bool]($spec -and -not $runtime.Paired);
Healthy = $runtime.Healthy; Known = [bool]$probe.Ok }
}
function Test-RocmTritonPairingNeedsPass {
# The same probe as the post-stack repair, so the two never disagree. Only a ROCm torch 2.11 / 2.12 is stale,
# which the pass repairs, so the check cannot re-fire on CUDA, CPU or XPU.
$pair = Get-RocmTritonPairing
if (-not $pair.Stale) { return $false }
if ($script:OfflineFastPath -or (Test-UvOfflineRequested)) {
substep "triton-windows does not pair with torch $($pair.Torch) but UV_OFFLINE is set -- left for the next online update" "Yellow"
return $false
}
substep "triton-windows does not pair with torch $($pair.Torch) -- forcing dependency pass to repair..." "Cyan"
return $true
}
function Enter-TritonInstallEnv {
$saved = @{}
foreach ($n in 'UV_OVERRIDE', 'UV_EXCLUDE', 'UV_CONSTRAINT', 'PIP_CONSTRAINT', 'UV_REQUIRE_HASHES', 'PIP_REQUIRE_HASHES') {
$saved[$n] = [Environment]::GetEnvironmentVariable($n)
Remove-Item "Env:$n" -ErrorAction SilentlyContinue
}
$env:PIP_REQUIRE_HASHES = "0"
return $saved
}
function Exit-TritonInstallEnv {
param([hashtable]$Saved)
foreach ($n in $Saved.Keys) {
if ($null -ne $Saved[$n]) { Set-Item "Env:$n" $Saved[$n] }
else { Remove-Item "Env:$n" -ErrorAction SilentlyContinue }
}
}
function Get-XpuTritonState {
# No double quotes: Invoke-BoundedPythonProbe wraps $Code in them.
$code = "import importlib, importlib.metadata as m, importlib.util as u, re; " +
"print('TRITONWIN=' + next(((d.version or '?') for d in m.distributions(name='triton-windows')), '')); " +
"q = next((r.split(';')[0].strip() for r in (m.requires('torch') or []) if 'triton' in r.lower()), ''); " +
"print('TRITONXPU=' + q); n = re.match(r'[A-Za-z0-9._-]+', q); " +
"v = next(((d.version or '') for d in m.distributions(name=n.group(0))), None) if n else None; " +
"print('XPUDIST=' + ('' if v is None else (v or '?'))); " +
"exec('''def accepted(q, v):\n for p in ('packaging', 'pip._vendor.packaging'):\n try:\n rq = importlib.import_module(p + '.requirements'); vm = importlib.import_module(p + '.version')\n except Exception:\n continue\n try:\n return bool(re.fullmatch(vm.VERSION_PATTERN, v, re.VERBOSE | re.IGNORECASE)) and rq.Requirement(q).specifier.contains(v, prereleases=True)\n except Exception:\n return False\n return q.partition('==')[2].strip().split('+')[0] == v.split('+')[0]'''); " +
"ok = bool(v) and accepted(q, v); " +
"print('XPUOK=' + str(int(bool(ok))))"
$probe = Invoke-BoundedPythonProbe -PythonExe "python" -Code $code
$win = if ($probe.Output -match '(?m)^TRITONWIN=(\S+)\s*$') { $Matches[1] } else { "" }
$spec = if ($probe.Output -match '(?m)^TRITONXPU=([^\r\n]+)') { $Matches[1].Trim() } else { "" }
$dist = if ($probe.Output -match '(?m)^XPUDIST=(\S+)\s*$') { $Matches[1] } else { "" }
$ok = [bool]($probe.Ok -and $probe.Output -match '(?m)^XPUOK=1\s*$')
if ($ok) {
# Generic triton can share Intel's version; verify backend registration without activating a device.
$base = ($dist -split '\+')[0] -replace '[^0-9A-Za-z._-]', ''
$rt = Invoke-BoundedPythonProbe -PythonExe "python" -Code ("import importlib; t = importlib.import_module('triton'); " +
"from triton.backends import backends; from triton.backends.compiler import GPUTarget; " +
"target = GPUTarget('xpu', {}, 32); " +
"xpu = any(b.compiler.supports_target(target) and callable(b.driver) for b in backends.values()); " +
"v = (getattr(t, '__version__', '') or '').split('+')[0]; " +
"print('XPURT=' + str(int(v == '$base' and xpu)))")
$ok = [bool]($rt.Ok -and $rt.Output -match '(?m)^XPURT=1\s*$')
}
return @{ TritonWin = $win; XpuSpec = $spec; XpuDist = $dist; XpuOk = $ok; Known = [bool]$probe.Ok }
}
# End of the AMD ROCm triton-windows pairing helpers.
$_PkgName = if ($env:STUDIO_PACKAGE_NAME) { $env:STUDIO_PACKAGE_NAME } else { "unsloth" }
$SkipPythonDeps = $false
if ($env:SKIP_STUDIO_BASE -ne "1" -and $env:STUDIO_LOCAL_INSTALL -ne "1") {
$_InstalledVersionProbeExit = 1
$InstalledVer = try {
$_installedVersionOutput = & python -c "
import sys
sys.path.insert(0, sys.argv[2])
import install_manifest
version, conflict = install_manifest.installed_version_probe(sys.argv[1], ('unsloth-zoo',))
print(version)
sys.exit(2 if conflict else (0 if version else 1))
" $_PkgName $PSScriptRoot 2>$null
$_InstalledVersionProbeExit = $LASTEXITCODE
($_installedVersionOutput | Out-String).Trim()
} catch { "" }
$LatestVer = ""
try {
$pypiJson = Invoke-RestMethod -Uri "https://pypi.org/pypi/$_PkgName/json" -TimeoutSec 5 -ErrorAction Stop
$LatestVer = "$($pypiJson.info.version)".Trim()
} catch { }
if ($_InstalledVersionProbeExit -eq 2) {
substep "duplicate metadata found for a core package -- forcing package repair..." "Cyan"
} elseif ($InstalledVer -and $LatestVer -and ($InstalledVer -eq $LatestVer)) {
step "python" "$_PkgName $InstalledVer is up to date"
$SkipPythonDeps = $true
# An interrupted install leaves the package current but studio.txt unfinished.
$_studioInstallIncomplete = -not (Test-StudioInstallVerified)
if ($_studioInstallIncomplete) {
substep "studio install incomplete -- forcing dependency pass to repair..." "Cyan"
$SkipPythonDeps = $false
}
Invoke-FastPathEscapes
} elseif ($InstalledVer -and $LatestVer) {
substep "$_PkgName $InstalledVer -> $LatestVer available, updating..."
} elseif (-not $LatestVer) {
# PyPI unreachable updates anyway, but UV_OFFLINE keeps a verified tree.
if ($InstalledVer -and (Test-UvOfflineRequested) -and (Test-StudioInstallVerified)) {
substep "PyPI is unreachable and UV_OFFLINE is set -- keeping the verified install"
$SkipPythonDeps = $true
$script:OfflineFastPath = $true
Invoke-FastPathEscapes
} else {
substep "could not reach PyPI, updating to be safe..."
}
}
# After the chain, as setup.sh keeps it, so it also covers the UV_OFFLINE branch.
if ($SkipPythonDeps) {
# A current package can still have CPU torch on an AMD host; force the pass for ROCm wheels.
if ($script:ROCmGfxArch) {
# Bounded: on a faulted HIP runtime the import never returns. No answer forces one pass.
$_rocmTorchProbe = Invoke-BoundedPythonProbe -PythonExe "python" `
-Code "import torch, sys; sys.exit(0 if torch.cuda.is_available() else 1)"
$_torchIsCpu = -not $_rocmTorchProbe.Ok
if ($_torchIsCpu) {
substep "AMD GPU ($script:ROCmGfxArch) detected but installed PyTorch is CPU-only -- reinstalling ROCm PyTorch" "Cyan"
$SkipPythonDeps = $false
}
# A ROCm torch whose device extra lost a family kernel pack still sees the GPU.
if ($SkipPythonDeps) {
try {
& python (Join-Path $PSScriptRoot "install_python_stack.py") --windows-rocm-device-packs-need-dependency-pass *> $null
if ($LASTEXITCODE -eq 0) {
substep "AMD device packs are incomplete or mismatched -- forcing dependency pass to repair..." "Cyan"
$SkipPythonDeps = $false
}
} catch {}
}
}
# A verified install skips the post-stack pairing. Outside the gfx checks: a pinned ROCm index or a hybrid host
# can hold a ROCm torch with no detected gfx.
if ($SkipPythonDeps -and -not $NoTorchMode -and (Test-RocmTritonPairingNeedsPass)) {
$SkipPythonDeps = $false
}
}
}
# A pin change or a torch that will not import needs the pass: every --force-reinstall lives inside it.
if ($script:PinChangedForceReinstall -or $script:TorchImportDefinitivelyFailed) {
$SkipPythonDeps = $false
}
# Remove the unparseable (apostrophe) torch cache path older setups wrote to the USER environment.
# Outside the dependency block, which the fast paths skip.
function Test-UnparseableManagedTorchCache {
param([string]$Value, [string]$Managed)
if (-not $Value) { return $false }
$trimmed = $Value.Trim().Replace('/', '\').TrimEnd('\')
# A path the builders CAN read is never touched.
if ($trimmed -notmatch '[\s'']') { return $false }
# Only clear the exact value this installer would have written.
return $trimmed -ieq $Managed.Trim().Replace('/', '\').TrimEnd('\')
}
function Clear-UnparseableTorchCacheEnv {
$managedTorchCache = Join-Path (Join-Path $StudioHome "cache") "torchinductor"
if (-not $StageRoot) {
$persisted = [Environment]::GetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', 'User')
if (Test-UnparseableManagedTorchCache $persisted $managedTorchCache) {
[Environment]::SetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', [NullString]::Value, 'User')
substep "cleared the persisted TORCHINDUCTOR_CACHE_DIR ($persisted): an earlier setup wrote it before the character was refused"
}
}
if (Test-UnparseableManagedTorchCache $env:TORCHINDUCTOR_CACHE_DIR $managedTorchCache) {
Remove-Item -LiteralPath Env:TORCHINDUCTOR_CACHE_DIR -ErrorAction SilentlyContinue
}
}
Clear-UnparseableTorchCacheEnv
if (-not $SkipPythonDeps) {
if (-not ($env:STUDIO_LOCAL_INSTALL -eq '1' -and (Test-Path -LiteralPath (Join-Path $VenvDir 'Scripts\python.exe') -PathType Leaf))) { Invoke-MirrorFallback }
# Before the manifest is dropped below: recovery reads that file.
$WinArm64Venv = Test-WinArm64Venv
# Read before the re-export overwrites it.
$_woaHandoffIndex = if ($env:UNSLOTH_WOA_SELECTED_TORCH_INDEX) { $env:UNSLOTH_WOA_SELECTED_TORCH_INDEX.Trim().TrimEnd('/') } else { "" }
$WinArm64TorchIndexUrl = if ($WinArm64Venv -and $env:UNSLOTH_WOA_TORCH_INDEX_URL) {
$env:UNSLOTH_WOA_TORCH_INDEX_URL.Trim().TrimEnd('/')
} elseif ($WinArm64Venv -and $env:UNSLOTH_WOA_SELECTED_TORCH_INDEX) {
$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX.Trim().TrimEnd('/')
} elseif ($WinArm64Venv) {
$_woaFromManifest = Get-PersistedWoaTorchIndex -VenvPath $VenvDir
if ($_woaFromManifest) { $_woaFromManifest } else { Get-WoaTorchIndexMarker }
} else { "" }
# Re-exported: the manifest rewrite reads it, so a fresh-shell update would erase the index.
$_woaPinnedIndex = if ($WinArm64Venv) { Get-PinnedTorchIndexUrl } else { $null }
if ($WinArm64TorchIndexUrl -or $_woaPinnedIndex) {
# Record the index the torch steps will USE in BOTH records; an unpersistable pin is refused.
$_woaMarkerIndex = $_woaPinnedIndex
if ($_woaMarkerIndex) { $_woaMarkerIndex = $_woaMarkerIndex.Trim().TrimEnd('/') }
else { $_woaMarkerIndex = $WinArm64TorchIndexUrl }
# install.ps1's flags were measured on the index it probed, so a moved pin invalidates them.
if ($_woaMarkerIndex -ne $_woaHandoffIndex) {
Remove-Item Env:UNSLOTH_WOA_HAS_TORCHAUDIO -ErrorAction SilentlyContinue
Remove-Item Env:UNSLOTH_WOA_TORCH_PRERELEASE -ErrorAction SilentlyContinue
}
$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex
# Before the manifest is dropped, so an interrupted run still leaves this index.
Save-WoaTorchIndexMarker -IndexUrl $_woaMarkerIndex
}
# The merged override file can carry credentials; the trap removes it on a terminating error.
trap { Remove-WoaMergedOverrides; break }
Restore-WoaResolverEnvironment
# Drop the manifest now: pip, torch and triton are replaced before the dependency pass.
$_ManifestDropped = $true
try {
& python -c "
import sys
sys.path.insert(0, sys.argv[1])
try:
import install_manifest
except Exception:
sys.exit(0) # older tree without the manifest helper
sys.exit(0 if install_manifest.remove_manifest() else 1)
" "$PSScriptRoot" 2>$null
if ($LASTEXITCODE -ne 0) { $_ManifestDropped = $false }
} catch { $_ManifestDropped = $false }
if (-not $_ManifestDropped) {
Write-StudioLine "[ERROR] Could not remove the stale unsloth_install_manifest.json." -ForegroundColor Red
Write-StudioLine " Refusing to install behind a marker that still reports this venv as complete." -ForegroundColor Red
Exit-SetupFailure "Could not remove the stale unsloth_install_manifest.json"
}
if ($script:UnslothVerbose) {
Fast-Install --upgrade pip
} else {
Fast-Install --upgrade pip | Out-Null
}
# Triton/inductor paths can exceed MAX_PATH (260): use the Unsloth home with long paths on,
# else a short drive-root dir. Persisted to USER env, so it must match the resolver's choice.
# Whitespace or an apostrophe is refused as storage_roots.toolchain_path_unparseable does.
$TorchCacheDir = $null
$TorchCacheUnparseable = $false
if ($StageRoot) {
$TorchCacheDir = Join-Path $RuntimeRoot "TORCHINDUCTOR_CACHE_DIR"
} elseif ($LongPathsEnabled) {
$candidate = Join-Path (Join-Path $StudioHome "cache") "torchinductor"
if ($candidate -notmatch '[\s'']') {
$TorchCacheDir = $candidate
} elseif ($candidate -notmatch '\s') {
# Apostrophe only; a spaced path keeps the drive-root dir it always used.
$TorchCacheUnparseable = $true
}
}
# C:\tc is predictable and creatable by any account, so never publish it for the apostrophe case.
if (-not $TorchCacheDir -and -not $TorchCacheUnparseable) {
$TorchCacheDir = "C:\tc"
}
if (-not $TorchCacheDir) {
substep "TORCHINDUCTOR_CACHE_DIR left unset: $candidate holds a character the C++ builders cannot paste into a command line, and the shared fallback is not account-private"
}
if ($TorchCacheDir) {
if (-not (Test-Path -LiteralPath $TorchCacheDir)) { [System.IO.Directory]::CreateDirectory($TorchCacheDir) | Out-Null }
$env:TORCHINDUCTOR_CACHE_DIR = $TorchCacheDir
if (-not $StageRoot) {
[Environment]::SetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', $TorchCacheDir, 'User')
}
substep "TORCHINDUCTOR_CACHE_DIR set to $TorchCacheDir (avoids MAX_PATH issues)"
}
$PinnedTorchIndexUrl = Get-PinnedTorchIndexUrl
$TorchIndexPinned = [bool]$PinnedTorchIndexUrl
# Only a definitive no-device XPU answer permits the presence-only CUDA conversion.
if (-not $TorchIndexPinned -and $script:NvidiaPresenceOnly -and $installedTorchTag -eq "xpu" -and
-not (Test-NvidiaPresenceStaleGpuWheel -InstalledTag $installedTorchTag -PythonExe (Join-Path $VenvDir "Scripts\python.exe"))) {
$script:PreservedXpuVenv = $true
}
if ($PinnedTorchIndexUrl) {
$CuTag = Get-TorchIndexLeaf $PinnedTorchIndexUrl
} elseif ($script:PreservedXpuVenv) {
# Kept +xpu venv on hybrid NVIDIA+Arc: stay on xpu ahead of the NVIDIA arm. install.ps1 converts.
$CuTag = "xpu"
} elseif ($script:PreservedInstallerTorchTag) {
# Select the family the stale check kept, so the AMD and XPU arms do not force-reinstall over it.
$CuTag = if (Test-CudaFamilyLeaf $script:PreservedInstallerTorchTag) { $script:PreservedInstallerTorchTag } else { "cpu" }
} elseif ($HasNvidiaSmi) {
$CuTag = Get-PytorchCudaTag
if (-not $CuTag -and $null -ne $script:NvidiaPresenceDriverRelease -and
$script:NvidiaPresenceDriverRelease -lt 450) {
# Pre-R450: CPU, matching install.ps1; cu126 would not load.
$CuTag = "cpu"
# An installed +cu wheel satisfies the bare CPU range, so force the reinstall.
if (Test-CudaFamilyLeaf $installedTorchTag) { $script:NvidiaPreR450CpuFallback = $true }
if (Test-NvidiaPresenceStaleGpuWheel -InstalledTag $installedTorchTag -PythonExe (Join-Path $VenvDir "Scripts\python.exe")) {
$script:NvidiaPreR450CpuFallback = $true
}
substep "an NVIDIA GPU is present but its driver ($script:NvidiaPresenceDriverRelease series) predates R450 and carries no usable CUDA runtime; installing CPU wheels. Update the NVIDIA driver and re-run to get CUDA" "Yellow"
}
if (-not $CuTag -and -not (Test-CudaFamilyLeaf $installedTorchTag) -and
$script:NvidiaPresenceCudaFloor) {
# Fresh installs only: an existing cu* venv must not be pulled back to the floor.
$floorMajor = [int]$script:NvidiaPresenceCudaFloor[0]
$floorMinor = [int]$script:NvidiaPresenceCudaFloor[1]
# Same pre-Turing cap as install.ps1: unknown capability stops at cu126.
if ($floorMajor -gt 12 -or ($floorMajor -eq 12 -and $floorMinor -gt 6)) {
$floorMajor = 12; $floorMinor = 6
}
# Never "cu$major$minor": CUDA 11.0 is served by cu118; cu110 does not exist.
$CuTag = Get-CudaFamilyForVersion -Major $floorMajor -Minor $floorMinor
substep "nvidia-smi and the NVIDIA driver library are both unavailable; the display driver supports at least CUDA $floorMajor.$floorMinor, installing torch $CuTag" "Yellow"
}
if (-not $CuTag) {
$CuTag = if (Test-CudaFamilyLeaf $installedTorchTag) { $installedTorchTag } else { "cu126" }
substep "could not read the CUDA driver version; installing torch $CuTag" "Yellow"
}
} elseif ($script:IsIntelXpu) {
# XPU wheels ship under the /xpu leaf, so TorchInstallIndexUrl resolves to mirror/xpu.
$CuTag = "xpu"
} else {
$CuTag = "cpu"
}
$ROCmGfxArch = $script:ROCmGfxArch
$ROCmIndexUrl = $null
$script:ROCmMultiArch = $false
# Also on a name-inferred gfx: the wheels bundle the runtime, so no HIP SDK is needed.
if (-not $TorchIndexPinned -and ($HasROCm -or $ROCmGfxArch) -and $CuTag -eq "cpu") {
$amdIndexBase = if ($env:UNSLOTH_ROCM_WINDOWS_MIRROR) { $env:UNSLOTH_ROCM_WINDOWS_MIRROR.TrimEnd('/') } else { "https://repo.amd.com/rocm/whl" }
# gfx120X, Strix, gfx103X, gfx110X: null _grouped_mm on torch <2.11.0; mirrors install.ps1 floor.
$torchFloorMap = @{
"gfx1201" = "torch>=2.11.0,<2.12.0"; "gfx1200" = "torch>=2.11.0,<2.12.0"
"gfx1151" = "torch>=2.11.0,<2.12.0"; "gfx1150" = "torch>=2.11.0,<2.12.0"
"gfx1152" = "torch>=2.11.0,<2.12.0"
"gfx1030" = "torch>=2.11.0,<2.12.0"; "gfx1031" = "torch>=2.11.0,<2.12.0"
"gfx1032" = "torch>=2.11.0,<2.12.0"; "gfx1033" = "torch>=2.11.0,<2.12.0"
"gfx1034" = "torch>=2.11.0,<2.12.0"; "gfx1035" = "torch>=2.11.0,<2.12.0"
"gfx1036" = "torch>=2.11.0,<2.12.0"; "gfx1100" = "torch>=2.11.0,<2.12.0"
"gfx1101" = "torch>=2.11.0,<2.12.0"; "gfx1102" = "torch>=2.11.0,<2.12.0"
"gfx1103" = "torch>=2.11.0,<2.12.0"
}
# Companions bounded to the torch ceiling for a consistent trio.
$torchvisionFloorMap = @{
"gfx1201" = "torchvision>=0.26.0,<0.27.0"; "gfx1200" = "torchvision>=0.26.0,<0.27.0"
"gfx1151" = "torchvision>=0.26.0,<0.27.0"; "gfx1150" = "torchvision>=0.26.0,<0.27.0"
"gfx1152" = "torchvision>=0.26.0,<0.27.0"
"gfx1030" = "torchvision>=0.26.0,<0.27.0"; "gfx1031" = "torchvision>=0.26.0,<0.27.0"
"gfx1032" = "torchvision>=0.26.0,<0.27.0"; "gfx1033" = "torchvision>=0.26.0,<0.27.0"
"gfx1034" = "torchvision>=0.26.0,<0.27.0"; "gfx1035" = "torchvision>=0.26.0,<0.27.0"
"gfx1036" = "torchvision>=0.26.0,<0.27.0"; "gfx1100" = "torchvision>=0.26.0,<0.27.0"
"gfx1101" = "torchvision>=0.26.0,<0.27.0"; "gfx1102" = "torchvision>=0.26.0,<0.27.0"
"gfx1103" = "torchvision>=0.26.0,<0.27.0"
}
$torchaudioFloorMap = @{
"gfx1201" = "torchaudio>=2.11.0,<2.12.0"; "gfx1200" = "torchaudio>=2.11.0,<2.12.0"
"gfx1151" = "torchaudio>=2.11.0,<2.12.0"; "gfx1150" = "torchaudio>=2.11.0,<2.12.0"
"gfx1152" = "torchaudio>=2.11.0,<2.12.0"
"gfx1030" = "torchaudio>=2.11.0,<2.12.0"; "gfx1031" = "torchaudio>=2.11.0,<2.12.0"
"gfx1032" = "torchaudio>=2.11.0,<2.12.0"; "gfx1033" = "torchaudio>=2.11.0,<2.12.0"
"gfx1034" = "torchaudio>=2.11.0,<2.12.0"; "gfx1035" = "torchaudio>=2.11.0,<2.12.0"
"gfx1036" = "torchaudio>=2.11.0,<2.12.0"; "gfx1100" = "torchaudio>=2.11.0,<2.12.0"
"gfx1101" = "torchaudio>=2.11.0,<2.12.0"; "gfx1102" = "torchaudio>=2.11.0,<2.12.0"
"gfx1103" = "torchaudio>=2.11.0,<2.12.0"
}
$archFamily = if ($ROCmGfxArch -and $archFamilyMap.ContainsKey($ROCmGfxArch)) { $archFamilyMap[$ROCmGfxArch] } else { $null }
$ROCmTorchSpec = if ($ROCmGfxArch -and $torchFloorMap.ContainsKey($ROCmGfxArch)) { $torchFloorMap[$ROCmGfxArch] } else { "torch" }
$ROCmVisionSpec = if ($ROCmGfxArch -and $torchvisionFloorMap.ContainsKey($ROCmGfxArch)) { $torchvisionFloorMap[$ROCmGfxArch] } else { "torchvision" }
$ROCmAudioSpec = if ($ROCmGfxArch -and $torchaudioFloorMap.ContainsKey($ROCmGfxArch)) { $torchaudioFloorMap[$ROCmGfxArch] } else { "torchaudio" }
$_familyMirrorPinned = [bool]($env:UNSLOTH_ROCM_WINDOWS_MIRROR) -and -not [bool]($env:UNSLOTH_ROCM_WINDOWS_MULTIARCH_MIRROR)
$script:ROCmMultiArch = [bool]($ROCmGfxArch -and $multiArchGfx -contains $ROCmGfxArch -and -not ($archFamily -and $_familyMirrorPinned))
if ($script:ROCmMultiArch) {
$ROCmIndexUrl = "$MultiArchIndexBase/"
$ROCmTorchSpec = "torch[device-$ROCmGfxArch]==$MultiArchTorchVersion+$MultiArchTag"
$ROCmVisionSpec = "torchvision[device-$ROCmGfxArch]==$MultiArchTorchvisionVersion+$MultiArchTag"
$ROCmAudioSpec = "torchaudio==$MultiArchTorchaudioVersion+$MultiArchTag"
substep "$ROCmGfxArch -- AMD multi-arch index, pinned to $MultiArchTorchVersion+$MultiArchTag (torch, torchvision, torchaudio)" "Cyan"
} elseif ($archFamily) {
$ROCmIndexUrl = "$amdIndexBase/$archFamily/"
} elseif ($ROCmGfxArch) {
substep "[WARN] AMD GPU ($ROCmGfxArch) not in supported arch list -- falling back to CPU-only PyTorch" "Yellow"
substep " Supported: gfx1200/1201 (RDNA 4), gfx1150/1151/1152 (RDNA 3.5), gfx1100-1103 (RDNA 3), gfx1030-1036 (RDNA 2), gfx1010-1012 (RDNA 1), gfx90a, gfx908 (RDNA parts: AMD multi-arch index)" "Yellow"
} else {
substep "[WARN] AMD GPU detected (HIP SDK present) but GPU arch could not be read -- falling back to CPU-only PyTorch" "Yellow"
substep " Arch detection requires hipinfo to report gcnArchName. Re-install the HIP SDK if this is unexpected." "Yellow"
}
}
# A pinned gfx*/rocm index skips the reroute; CUDA would resolve a known-bad wheel there.
if ($TorchIndexPinned -and -not $ROCmIndexUrl -and $PinnedTorchIndexUrl) {
$_pinLeaf = Get-TorchIndexLeaf $PinnedTorchIndexUrl
$_pinRocm211 = $false
# Anchored so a suffixed custom leaf (rocm7.2-private) installs verbatim.
if ($_pinLeaf -match '^rocm(\d+)\.(\d+)$') {
$_pinRocm211 = Test-RocmKnown211Version -Major ([int]$Matches[1]) -Minor ([int]$Matches[2])
}
# Reuse Test-RocmGfx211Leaf so this and the stale-venv check cannot diverge.
$_pinGfx211 = Test-RocmGfx211Leaf $_pinLeaf
if ($_pinGfx211 -or $_pinRocm211) {
$ROCmIndexUrl = $PinnedTorchIndexUrl
$ROCmTorchSpec = "torch>=2.11.0,<2.12.0"
$ROCmVisionSpec = "torchvision>=0.26.0,<0.27.0"
$ROCmAudioSpec = "torchaudio>=2.11.0,<2.12.0"
substep "pinned ROCm index ($_pinLeaf) -- enforcing $ROCmTorchSpec" "Cyan"
} elseif (Test-PipRocmFamilyLeaf $_pinLeaf) {
$ROCmIndexUrl = $PinnedTorchIndexUrl
$ROCmTorchSpec = "torch"
$ROCmVisionSpec = "torchvision"
$ROCmAudioSpec = "torchaudio"
}
}
$PyTorchWhlBase = if ($env:UNSLOTH_PYTORCH_MIRROR) { $env:UNSLOTH_PYTORCH_MIRROR.TrimEnd('/') } else { "https://download.pytorch.org/whl" }
# On a ROCm-install failure the fallback uses the CPU index, not the ROCm pin.
$TorchInstallIndexUrl = if ($ROCmIndexUrl) { "$PyTorchWhlBase/cpu" } elseif ($PinnedTorchIndexUrl) { $PinnedTorchIndexUrl } else { "$PyTorchWhlBase/$CuTag" }
# Declared outside the guard: later passes read it and no-torch mode never assigns it.
$XpuIndexUrl = $null
$_effectiveTorchIndexUrl = $TorchInstallIndexUrl
if (-not $NoTorchMode) {
# Windows on ARM has no torchaudio wheel on any index; absent install.ps1's answer, assume none.
$WinArm64EffectiveTorchIndexUrl = if ($PinnedTorchIndexUrl) { ([string]$PinnedTorchIndexUrl).Trim().TrimEnd('/') }
elseif ($WinArm64TorchIndexUrl) { $WinArm64TorchIndexUrl }
else { "" }
$WinArm64HandoffApplies = [bool]($WinArm64EffectiveTorchIndexUrl -and $_woaHandoffIndex -and
$WinArm64EffectiveTorchIndexUrl.Equals($_woaHandoffIndex, [System.StringComparison]::OrdinalIgnoreCase))
$WinArm64NoAudio = $WinArm64Venv -and -not ($WinArm64HandoffApplies -and $env:UNSLOTH_WOA_HAS_TORCHAUDIO -eq "1")
if ($WinArm64NoAudio) { substep "windows on arm: skipping torchaudio (no win_arm64 wheel on this index)" }
elseif ($WinArm64Venv) { substep "windows on arm: this index publishes torchaudio; keeping it in the torch trio" }
# The ceilings below are for x64 wheels; win_arm64 builds sit above them, so floors only.
$WinArm64TorchSpec = "torch>=2.4"
$WinArm64VisionSpec = "torchvision>=0.19"
$WinArm64AudioSpec = "torchaudio>=2.4"
# Pinned to what this index publishes: under best-match a floor asks the higher-numbered index.
if ($WinArm64Venv -and $WinArm64EffectiveTorchIndexUrl) {
$_woaTags = ""
try {
$_woaTags = (& (Join-Path $VenvDir "Scripts\python.exe") -c "import sys, sysconfig; t = 'cp%d%d' % sys.version_info[:2]; print(t + '|' + t + ('t' if sysconfig.get_config_var('Py_GIL_DISABLED') else ''))" 2>$null | Out-String).Trim()
} catch { $_woaTags = "" }
if ($_woaTags -match '^(cp\d+)\|(cp\d+t?)$') {
$_woaPyTag = $Matches[1]; $_woaAbi = $Matches[2]
$_woaTorchV = Get-WoaCudaWheelVersionParity -IndexUrl $WinArm64EffectiveTorchIndexUrl -PyTag $_woaPyTag -AbiTag $_woaAbi
if ($_woaTorchV) {
$WinArm64TorchSpec = "torch==$_woaTorchV"
$_woaVisionV = Get-WoaCudaWheelVersionParity -IndexUrl $WinArm64EffectiveTorchIndexUrl -PyTag $_woaPyTag -AbiTag $_woaAbi -Project "torchvision" -PairWith $_woaTorchV
$_woaBacktracks = 0
while (-not $_woaVisionV -and $_woaBacktracks -lt 5) {
$_woaOlderTorch = Get-WoaCudaWheelVersionParity -IndexUrl $WinArm64EffectiveTorchIndexUrl -PyTag $_woaPyTag -AbiTag $_woaAbi -Below $_woaTorchV
if (-not $_woaOlderTorch) { break }
substep "windows on arm: this index pairs no torchvision with torch $_woaTorchV; trying torch $_woaOlderTorch" "Yellow"
$_woaTorchV = $_woaOlderTorch
$WinArm64TorchSpec = "torch==$_woaTorchV"
$_woaVisionV = Get-WoaCudaWheelVersionParity -IndexUrl $WinArm64EffectiveTorchIndexUrl -PyTag $_woaPyTag -AbiTag $_woaAbi -Project "torchvision" -PairWith $_woaTorchV
$_woaBacktracks++
}
if ($_woaVisionV) {
$WinArm64VisionSpec = "torchvision==$_woaVisionV"
} else {
# Keep the installed pair rather than pin a torch whose torchvision would resolve wrong.
$_woaInstalledPair = ""
try {
$_woaInstalledPair = (& (Join-Path $VenvDir "Scripts\python.exe") -c "import importlib.metadata as m; print(m.version('torch') + '|' + m.version('torchvision'))" 2>$null | Out-String).Trim()
} catch { $_woaInstalledPair = "" }
$_woaKeptTorch = ""; $_woaKeptVision = ""
if ($_woaInstalledPair -match '^(\S+)\|(\S+)$') { $_woaKeptTorch = $Matches[1]; $_woaKeptVision = $Matches[2] }
if ($_woaKeptTorch -and $_woaKeptVision -and (Test-WoaPairsWithTorchParity -TorchVersion $_woaKeptTorch -OtherVersion $_woaKeptVision -Project "torchvision")) {
substep "windows on arm: this index pairs no torchvision with torch $_woaTorchV; keeping the installed torch $_woaKeptTorch and torchvision $_woaKeptVision" "Yellow"
$_woaTorchV = $_woaKeptTorch
$WinArm64TorchSpec = "torch==$_woaKeptTorch"
$WinArm64VisionSpec = "torchvision==$_woaKeptVision"
} else {
substep "windows on arm: this index pairs no torchvision with torch $_woaTorchV and no installed pair can be kept; leaving torchvision at its floor" "Yellow"
}
}
$_woaAudioV = Get-WoaCudaWheelVersionParity -IndexUrl $WinArm64EffectiveTorchIndexUrl -PyTag $_woaPyTag -AbiTag $_woaAbi -Project "torchaudio" -PairWith $_woaTorchV
if ($_woaAudioV) { $WinArm64AudioSpec = "torchaudio==$_woaAudioV" }
$_woaProbeHasAudio = [bool]($_woaAudioV -and (Test-WoaAudioMatchesTorchParity -TorchVersion $_woaTorchV -AudioVersion $_woaAudioV))
if ($WinArm64NoAudio -eq $_woaProbeHasAudio) {
$WinArm64NoAudio = -not $_woaProbeHasAudio
if ($WinArm64NoAudio) { substep "windows on arm: this index pairs no torchaudio with torch $_woaTorchV; leaving it out of the trio" }
else { substep "windows on arm: this index pairs torchaudio $_woaAudioV with torch $_woaTorchV; keeping it in the trio" }
}
substep "windows on arm: pinning the CUDA build this index publishes ($_woaTorchV)."
}
}
}
# win_arm64's first triton-windows wheel is 3.8.0.post28.
$_tritonSpec = if ($WinArm64Venv) { "triton-windows>=3.8.0.post28" } else { "triton-windows<3.7" }
# triton-windows follows the Triton each torch pins: 2.12 and 2.13 -> 3.7 (2.12.0 -> 3.7.0), 2.14 -> 3.8, older keeps <3.7.
function Get-TritonWindowsSpec {
param([string]$TorchVersion, [bool]$WinArm64 = $false)
if ($WinArm64) { return "triton-windows>=3.8.0.post28" }
if ($TorchVersion -match '^2\.(\d+)\.(\d+)') {
switch ([int]$Matches[1]) {
12 { if ([int]$Matches[2] -eq 0) { return "triton-windows>=3.7,<3.7.1" } return "triton-windows>=3.7,<3.8" }
13 { return "triton-windows>=3.7,<3.8" }
14 { return "triton-windows>=3.8,<3.9" }
}
}
return "triton-windows<3.7"
}
# The win_arm64 index publishes only the trio, so a dependency index rides beside it (the caller's configured one, public PyPI by default). Not gated on $UseUv: pip needs the extra index too.
$WinArm64IndexArgs = if ($WinArm64Venv) {
$_woaResolver = if ($UseUv) { "uv" } else { "pip" }
# Fast-Install scrubs UV_* with --index-url, so an unreadable uv policy would leave only the trio index.
if ($_woaResolver -eq "uv" -and (Test-WoaUvIndexPolicyUnreadable)) {
$_woaCfgPath = [string](Get-WoaUvConfigIndexPolicy).UnreadablePath
if (-not $_woaCfgPath) { $_woaCfgPath = "your uv configuration" }
Write-StudioLine "[ERROR] Cannot read the index policy in $_woaCfgPath" -ForegroundColor Red
Write-StudioLine " Windows on ARM installs torch's dependencies from the index that file names, and this" -ForegroundColor Red
Write-StudioLine " step cannot ask uv to read it. Continuing would silently use public PyPI instead." -ForegroundColor Red
Write-StudioLine " The inline form 'index = [{ url = \"...\", default = true }]' is only read when every" -ForegroundColor Red
Write-StudioLine " entry is a flat table on one line. Either rewrite it as an [[index]] block:" -ForegroundColor Red
Write-StudioLine " [[index]]" -ForegroundColor Red
Write-StudioLine " url = \"https://your-mirror/simple\"" -ForegroundColor Red
Write-StudioLine " default = true" -ForegroundColor Red
Write-StudioLine " or name the index in the environment instead, which wins over the file:" -ForegroundColor Red
Write-StudioLine " `$env:UV_DEFAULT_INDEX = 'https://your-mirror/simple'" -ForegroundColor Red
Exit-SetupFailure "Unreadable uv index policy in $_woaCfgPath"
}
$_woaIndexArgs = @("--index-strategy", "unsafe-best-match") + @(Get-WoaDependencyIndexArgs -Resolver $_woaResolver)
# Fast-Install clears *_FIND_LINKS with --index-url; uv fails on a missing directory.
$_woaWheels = Join-Path (Join-Path $StudioHome "woa") "wheels"
if (Test-Path -LiteralPath $_woaWheels -PathType Container) {
$_woaIndexArgs += @("--find-links", (Get-UvSafePath $_woaWheels))
}
if (($WinArm64HandoffApplies -and $env:UNSLOTH_WOA_TORCH_PRERELEASE -eq "1") -or
($WinArm64EffectiveTorchIndexUrl -match 'nightly')) {
$_woaIndexArgs = @("--prerelease=allow") + $_woaIndexArgs
}
$_woaIndexArgs
} else { @() }
$ROCmCpuFallback = $false
if ($ROCmIndexUrl) {
substep "installing PyTorch (AMD ROCm, $ROCmGfxArch)..."
if ($script:ROCmMultiArch) {
substep " pinned $ROCmTorchSpec $ROCmVisionSpec $ROCmAudioSpec (AMD multi-arch index, one release tag)" "Cyan"
} elseif ($ROCmTorchSpec -ne "torch") {
substep " enforcing $ROCmTorchSpec $ROCmVisionSpec $ROCmAudioSpec (known _grouped_mm bug in older wheels)" "Cyan"
}
$_rocmKeptActive = $false
$_rocmOrigTorch = $ROCmTorchSpec; $_rocmOrigVision = $ROCmVisionSpec; $_rocmOrigAudio = $ROCmAudioSpec
if (-not $script:ROCmMultiArch -and $env:UNSLOTH_KEPT_TORCH -match '^\d+\.\d+(\.\d+)?$') {
$_keptMinor = [int](($env:UNSLOTH_KEPT_TORCH -split '\.')[1])
if (-not ($ROCmTorchSpec -match 'torch>=2\.11' -and $_keptMinor -lt 11)) {
$ROCmTorchSpec = "torch==$($env:UNSLOTH_KEPT_TORCH)"
$ROCmVisionSpec = "torchvision==0.$($_keptMinor + 15).*"
$ROCmAudioSpec = "torchaudio==2.$([Math]::Min($_keptMinor, 11)).*"
$_rocmKeptActive = $true
}
}
# Force only on a family change, pin move or failed import; always forcing re-resolved every update.
$rocmForce = @()
if (@("1", "true", "yes", "on") -contains "$($env:UNSLOTH_STUDIO_FULL_DEPS)".Trim().ToLowerInvariant()) { $rocmForce = @("--force-reinstall") }
if ($installedTorchTag -ne "rocm") { $rocmForce = @("--force-reinstall") }
if ($script:PinChangedForceReinstall) { $rocmForce = @("--force-reinstall") }
if ($script:TorchImportDefinitivelyFailed) { $rocmForce = @("--force-reinstall") }
# +rocm names the family, not the arch, so record the index the trio came from.
$script:RocmIndexRecord = Join-Path $VenvDir ".unsloth-rocm-index"
$_rocmIndexIdentity = Get-IndexIdentity $ROCmIndexUrl
$_recordedRocmIndex = ""
if (Test-Path -LiteralPath $script:RocmIndexRecord -PathType Leaf) {
try { $_recordedRocmIndex = Get-IndexIdentity ((Get-Content -LiteralPath $script:RocmIndexRecord -Raw -ErrorAction Stop).Trim()) } catch { $_recordedRocmIndex = "" }
}
if ($installedTorchTag -eq "rocm" -and $rocmForce.Count -eq 0 -and $_recordedRocmIndex -ne $_rocmIndexIdentity) {
if ($_recordedRocmIndex) {
substep "the ROCm trio was installed from $_recordedRocmIndex, this run selects $_rocmIndexIdentity; reinstalling the trio" "Yellow"
} else {
substep "no record of the index the ROCm trio came from; reinstalling the trio once to record it" "Yellow"
}
$rocmForce = @("--force-reinstall")
}
if ($installedTorchTag -eq "rocm" -and $rocmForce.Count -eq 0 -and $VenvPyExe -and (Test-Path -LiteralPath $VenvPyExe)) {
# torch alone names the family: companions from PyPI satisfy their pins without ROCm. Also check
# payload (RECORD rows) and ROCm release. No answer forces the trio.
$_companionNames = if ($WinArm64NoAudio) { "('torchvision',)" } else { "('torchvision', 'torchaudio')" }
$_companionProbe = Invoke-BoundedPythonProbe -PythonExe $VenvPyExe -Code "import csv, io, re, importlib.util as u, importlib.metadata as m, os`ndef rocmver(s):`n hit = re.search(r'rocm(\d+(?:\.\d+)*)', s.lower())`n return hit.group(1) if hit else ''`ntry:`n torchrocm = rocmver(m.distribution('torch').version)`nexcept m.PackageNotFoundError:`n torchrocm = ''`nout = []`nfor n in $($_companionNames):`n try:`n d = m.distribution(n)`n except m.PackageNotFoundError:`n continue`n v = d.version`n if u.find_spec(n) is None:`n out.append(n + '==' + v + ' (payload missing)')`n continue`n rec = d.read_text('RECORD')`n damaged = not rec`n for row in csv.reader(io.StringIO(rec or '')):`n if damaged or len(row) < 3 or not row[0] or row[0].endswith('.pyc') or not row[2]:`n continue`n try:`n damaged = os.stat(d.locate_file(row[0])).st_size != int(row[2])`n except (OSError, ValueError):`n damaged = True`n if damaged:`n out.append(n + '==' + v + ' (payload damaged)')`n continue`n t = (v.split('+', 1) + [''])[1].lower()`n if not t or t.startswith('cpu') or t.startswith('cu') or t.startswith('xpu'):`n out.append(n + '==' + v)`n elif torchrocm and rocmver(t) and rocmver(t) != torchrocm:`n out.append(n + '==' + v + ' (rocm' + rocmver(t) + ' beside torch rocm' + torchrocm + ')')`nprint(' '.join(out))"
$_companionMismatch = if ($_companionProbe.Ok) { $_companionProbe.Output.Trim() } else { "probe did not answer" }
if ($_companionMismatch) {
substep "torchvision/torchaudio do not match the ROCm torch ($_companionMismatch); reinstalling the trio" "Yellow"
$rocmForce = @("--force-reinstall")
}
}
while ($true) {
# A splat assigned only in the verbose branch is unset on the other path.
$_rocmTrio = @($ROCmTorchSpec, $ROCmVisionSpec, $ROCmAudioSpec)
if ($WinArm64NoAudio -or -not $ROCmAudioSpec) { $_rocmTrio = @($ROCmTorchSpec, $ROCmVisionSpec) }
if ($script:UnslothVerbose) {
Fast-Install @_rocmTrio @rocmForce --index-url $ROCmIndexUrl | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$torchInstallExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install @_rocmTrio @rocmForce --index-url $ROCmIndexUrl | Out-String
$torchInstallExit = $LASTEXITCODE
}
if ($torchInstallExit -eq 0 -or -not $_rocmKeptActive) { break }
substep "[WARN] torch==$($env:UNSLOTH_KEPT_TORCH) not installable on this ROCm index -- using the supported release" "Yellow"
$ROCmTorchSpec = $_rocmOrigTorch; $ROCmVisionSpec = $_rocmOrigVision; $ROCmAudioSpec = $_rocmOrigAudio
Remove-Item Env:UNSLOTH_KEPT_TORCH -ErrorAction SilentlyContinue
$_rocmKeptActive = $false
}
if ($torchInstallExit -ne 0) {
Write-StudioLine "[WARN] AMD ROCm PyTorch install failed -- falling back to CPU" -ForegroundColor Yellow
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Yellow
$ROCmIndexUrl = $null
$ROCmCpuFallback = $true
} else {
$env:UNSLOTH_ROCM_TORCH_INSTALLED = "1"
try {
if ($script:RocmIndexRecord) { Set-Content -LiteralPath $script:RocmIndexRecord -Value (Get-IndexIdentity $ROCmIndexUrl) -Encoding ascii -NoNewline }
} catch { }
substep "GPU ROCm PyTorch installed ($ROCmGfxArch) -- training and GPU inference will use the GPU" "Cyan"
}
}
# ── Intel XPU (SYCL) ─────────────────────────────────────────────────────────
# Intel XPU has its own index leaf and must not fall into the CUDA branch.
$XpuCpuFallback = $false
if (-not $ROCmIndexUrl -and $CuTag -eq "xpu") { $XpuIndexUrl = $TorchInstallIndexUrl }
if ($XpuIndexUrl) {
substep "installing PyTorch (Intel XPU)..."
# unsloth raises at import for XPU below torch 2.6, so the floor is 2.6.
$_xpuTrio = @("torch>=2.6,<2.11.0", "torchvision>=0.21,<0.26.0", "torchaudio>=2.6,<2.11.0")
if ($WinArm64NoAudio) { $_xpuTrio = @("torch>=2.6,<2.11.0", "torchvision>=0.21,<0.26.0") }
# Force only on a flavor change: install.ps1 already installed the XPU trio.
$xpuForce = @()
if ($installedTorchTag -ne "xpu") { $xpuForce = @("--force-reinstall") }
if ($script:PinChangedForceReinstall) { $xpuForce = @("--force-reinstall") }
# A +xpu wheel that no longer imports still satisfies the range.
if ($script:TorchImportDefinitivelyFailed) { $xpuForce = @("--force-reinstall") }
if ($script:UnslothVerbose) {
Fast-Install @_xpuTrio @xpuForce --index-url $XpuIndexUrl | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$torchInstallExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install @_xpuTrio @xpuForce --index-url $XpuIndexUrl | Out-String
$torchInstallExit = $LASTEXITCODE
}
if ($torchInstallExit -ne 0) {
Write-StudioLine "[WARN] Intel XPU PyTorch install failed -- falling back to CPU" -ForegroundColor Yellow
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Yellow
$XpuIndexUrl = $null
$XpuCpuFallback = $true
$TorchInstallIndexUrl = "$PyTorchWhlBase/cpu"
} else {
substep "GPU XPU PyTorch installed -- training and GPU inference will use the GPU" "Cyan"
Assert-XpuRuntimeReady -PythonExe "python" | Out-Null
}
}
if (-not $ROCmIndexUrl -and -not $XpuIndexUrl -and ($CuTag -eq "cpu" -or $ROCmCpuFallback -or $XpuCpuFallback)) {
substep "installing PyTorch (CPU-only)..."
# Build the array directly: an @splat of a string enumerates chars.
$cpuForce = @()
if ($ROCmCpuFallback) { $cpuForce = @("--force-reinstall") }
# A partial +xpu torch satisfies the CPU torch>= range.
if ($XpuCpuFallback) { $cpuForce = @("--force-reinstall") }
# A stale +cu / +rocm wheel still satisfies the CPU torch>= range.
if ($script:PinChangedForceReinstall) { $cpuForce = @("--force-reinstall") }
if ($script:TorchImportDefinitivelyFailed) { $cpuForce = @("--force-reinstall") }
if ($script:NvidiaPreR450CpuFallback) { $cpuForce = @("--force-reinstall") }
# A pinned cpu index installs the bounded trio (parity with _CPU_TORCH_PKG_SPEC).
$cpuTorchSpec = "torch"; $cpuVisionSpec = "torchvision"; $cpuAudioSpec = "torchaudio"
if ($TorchIndexPinned) {
$cpuTorchSpec = "torch>=2.4,<2.12.0"
$cpuVisionSpec = "torchvision>=0.19,<0.27.0"
$cpuAudioSpec = "torchaudio>=2.4,<2.12.0"
}
if ($XpuCpuFallback) {
$cpuTorchSpec = "torch>=2.4,<2.12.0"
$cpuVisionSpec = "torchvision>=0.19,<0.27.0"
$cpuAudioSpec = "torchaudio>=2.4,<2.12.0"
}
$_cpuKeptActive = $false
$_cpuOrigTorch = $cpuTorchSpec; $_cpuOrigVision = $cpuVisionSpec; $_cpuOrigAudio = $cpuAudioSpec
if ($env:UNSLOTH_KEPT_TORCH -match '^\d+\.\d+(\.\d+)?$') {
$_keptMinor = [int](($env:UNSLOTH_KEPT_TORCH -split '\.')[1])
$cpuTorchSpec = "torch==$($env:UNSLOTH_KEPT_TORCH)"
$cpuVisionSpec = "torchvision==0.$($_keptMinor + 15).*"
$cpuAudioSpec = "torchaudio==2.$([Math]::Min($_keptMinor, 11)).*"
$_cpuKeptActive = $true
}
while ($true) {
$_torchTrio = @($cpuTorchSpec, $cpuVisionSpec, $cpuAudioSpec)
if ($WinArm64NoAudio) { $_torchTrio = @($cpuTorchSpec, $cpuVisionSpec) }
if ($script:UnslothVerbose) {
Fast-Install @_torchTrio @cpuForce --index-url $TorchInstallIndexUrl | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$torchInstallExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install @_torchTrio @cpuForce --index-url $TorchInstallIndexUrl | Out-String
$torchInstallExit = $LASTEXITCODE
}
if ($torchInstallExit -eq 0 -or -not $_cpuKeptActive) { break }
substep "[WARN] torch==$($env:UNSLOTH_KEPT_TORCH) not installable from the CPU index -- using the supported release" "Yellow"
$cpuTorchSpec = $_cpuOrigTorch; $cpuVisionSpec = $_cpuOrigVision; $cpuAudioSpec = $_cpuOrigAudio
Remove-Item Env:UNSLOTH_KEPT_TORCH -ErrorAction SilentlyContinue
$_cpuKeptActive = $false
}
if ($torchInstallExit -ne 0) {
Write-StudioLine "[FAILED] PyTorch install failed (exit code $torchInstallExit)" -ForegroundColor Red
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Red
Exit-SetupFailure "PyTorch installation failed (exit code $torchInstallExit)"
}
} elseif (-not $ROCmIndexUrl -and -not $XpuIndexUrl) {
substep "installing PyTorch with CUDA support ($CuTag)..."
substep "(This download is ~2.8 GB -- may take a few minutes)"
# PEP 440 ignores +cuXXX, so a cu126 -> cu128 change needs --force-reinstall.
$cudaForce = @()
if ($script:PinChangedForceReinstall -or $script:TorchImportDefinitivelyFailed) {
$cudaForce = @("--force-reinstall")
}
if ($script:NvidiaPresenceOnly -and $installedTorchTag -eq "cpu") {
$cudaForce = @("--force-reinstall")
}
if (Test-NvidiaPresenceStaleGpuWheel -InstalledTag $installedTorchTag -PythonExe (Join-Path $VenvDir "Scripts\python.exe")) {
$cudaForce = @("--force-reinstall")
}
# Unknown-leaf custom pins: bound the trio so a mirror cannot pull an ABI-newer companion.
$cudaTorchSpec = "torch"
$cudaVisionSpec = "torchvision"
$cudaAudioSpec = "torchaudio"
if ($TorchIndexPinned -and -not (Test-CudaFamilyLeaf $CuTag)) {
$cudaTorchSpec = "torch>=2.4,<2.12.0"
$cudaVisionSpec = "torchvision>=0.19,<0.27.0"
$cudaAudioSpec = "torchaudio>=2.4,<2.12.0"
}
# Not on win_arm64: NVIDIA's channel does not publish the kept release.
$_cudaKeptActive = $false
$_cudaKeptRelease = $env:UNSLOTH_KEPT_TORCH
$_cudaKeptFromResident = $false
# No installer handoff (`studio update`, the startup repair, a re-run of setup): keep the resident
# release like install.sh, forced or not. Unpinned, a missing torchvision alone resolves the
# newest one and drags torch up with it. UPGRADE=1 asks for newer.
if (-not $WinArm64Venv -and -not $_cudaKeptRelease -and $env:UNSLOTH_TORCH_UPGRADE -ne "1") {
$_residentProbe = Invoke-BoundedPythonProbe -PythonExe "python" -Code "import importlib.metadata as m; print(m.version('torch'))"
# Only a release this index publishes, so a CUDA family change never pins an unservable one.
# download.pytorch.org win_amd64: cu126 2.6-2.14, cu128 2.7-2.11, cu129 2.8-2.9, cu130 2.9-2.14.
$_keptRange = @{ "cu126" = @(6, 14); "cu128" = @(7, 11); "cu129" = @(8, 9); "cu130" = @(9, 14) }[[string]$CuTag]
if ($_keptRange -and $_residentProbe.Ok -and ($_residentProbe.Output -match '(?m)^(2\.(\d+)\.\d+)(\+\S*)?\s*$') -and
[int]$Matches[2] -ge $_keptRange[0] -and [int]$Matches[2] -le $_keptRange[1]) {
$_cudaKeptRelease = $Matches[1]
$_cudaKeptFromResident = $true
}
}
if (-not $WinArm64Venv -and $_cudaKeptRelease -match '^\d+\.\d+(\.\d+)?$') {
$_keptMinor = [int](($_cudaKeptRelease -split '\.')[1])
$cudaTorchSpec = "torch==$_cudaKeptRelease"
$cudaVisionSpec = "torchvision==0.$($_keptMinor + 15).*"
# torchaudio 2.11 is the last release (stable ABI), so newer torch minors pair with it.
$cudaAudioSpec = "torchaudio==2.$([Math]::Min($_keptMinor, 11)).*"
$_cudaKeptActive = $true
}
while ($true) {
$_cudaTrio = @($cudaTorchSpec, $cudaVisionSpec, $cudaAudioSpec)
if ($WinArm64Venv) {
$_cudaTrio = @($WinArm64TorchSpec, $WinArm64VisionSpec)
if (-not $WinArm64NoAudio) { $_cudaTrio += $WinArm64AudioSpec }
} elseif ($WinArm64NoAudio) {
$_cudaTrio = @($cudaTorchSpec, $cudaVisionSpec)
}
$_cudaIndexUrl = if ($PinnedTorchIndexUrl) { $TorchInstallIndexUrl }
elseif ($WinArm64TorchIndexUrl) { $WinArm64TorchIndexUrl }
else { $TorchInstallIndexUrl }
$_effectiveTorchIndexUrl = $_cudaIndexUrl
$_woaStepSaved = $null; $_woaStepSwapped = $false; $_woaStepTemps = @(); $_woaCutoffSaved = @{}
if ($WinArm64Venv -and $env:UV_OVERRIDE) {
$_woaStepSaved = $env:UV_OVERRIDE
$_woaStep = New-WoaTorchStepOverrideValueParity -Value $_woaStepSaved -Dir (Join-Path $StudioHome "woa")
$env:UV_OVERRIDE = $_woaStep.Value
$_woaStepTemps = @($_woaStep.Temps)
$_woaStepSwapped = $true
}
if ($WinArm64Venv) {
# The pins are exact and the index page carries no upload dates: a cutoff would reject them outright.
foreach ($_woaCutoffName in @("UV_EXCLUDE_NEWER", "UV_EXCLUDE_NEWER_PACKAGE")) {
$_woaCutoffValue = [string][Environment]::GetEnvironmentVariable($_woaCutoffName)
if ($_woaCutoffValue) {
$_woaCutoffSaved[$_woaCutoffName] = $_woaCutoffValue
Remove-Item "Env:$_woaCutoffName" -ErrorAction SilentlyContinue
substep "windows on arm: $_woaCutoffName is not applied to the exact CUDA pins (the index carries no upload dates)."
}
}
# UV_NO_INDEX is our convention; the CUDA trio exists nowhere else, so it yields for this command.
$_woaNoIndexValue = [string][Environment]::GetEnvironmentVariable("UV_NO_INDEX")
if (Test-NoIndexRequested) {
$_woaCutoffSaved["UV_NO_INDEX"] = $_woaNoIndexValue
Remove-Item "Env:UV_NO_INDEX" -ErrorAction SilentlyContinue
substep "windows on arm: UV_NO_INDEX yields for the CUDA trio, which only the selected index carries; its dependencies still come from the wheelhouse."
}
}
try {
if ($script:UnslothVerbose) {
Fast-Install @_cudaTrio @cudaForce @WinArm64IndexArgs --index-url $_cudaIndexUrl | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$torchInstallExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install @_cudaTrio @cudaForce @WinArm64IndexArgs --index-url $_cudaIndexUrl | Out-String
$torchInstallExit = $LASTEXITCODE
}
} finally {
if ($_woaStepSwapped) { $env:UV_OVERRIDE = $_woaStepSaved }
foreach ($_woaTmp in $_woaStepTemps) { Remove-Item -LiteralPath $_woaTmp -Force -ErrorAction SilentlyContinue }
foreach ($_woaCutoffName in @($_woaCutoffSaved.Keys)) { Set-Item "Env:$_woaCutoffName" $_woaCutoffSaved[$_woaCutoffName] }
}
if ($torchInstallExit -eq 0 -or -not $_cudaKeptActive) { break }
# Nothing forced and the pin was only ours: retry exactly what an unpinned run would have done.
if ($_cudaKeptFromResident -and $cudaForce.Count -eq 0) {
$cudaTorchSpec = "torch"; $cudaVisionSpec = "torchvision"; $cudaAudioSpec = "torchaudio"
$_cudaKeptActive = $false
continue
}
# Otherwise stop, like install_python_stack.py: a second resolve under another range would
# download a different torch (usually after a transient failure) and move the release unasked.
substep "[WARN] torch==$_cudaKeptRelease could not be reinstalled; re-run, or set UNSLOTH_TORCH_UPGRADE=1 to move to the supported release" "Yellow"
break
}
if ($torchInstallExit -ne 0) {
Write-StudioLine "[FAILED] PyTorch CUDA install failed (exit code $torchInstallExit)" -ForegroundColor Red
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Red
Exit-SetupFailure "PyTorch CUDA installation failed (exit code $torchInstallExit)"
}
# Otherwise uv leaves torchaudio linked against the previous libtorch.
if ($WinArm64Venv -and $WinArm64NoAudio) {
$_woaAudioCode = "import importlib.metadata as m; " +
"print('T=' + next((d.version for d in m.distributions() " +
"if (d.metadata['Name'] or '').lower() == 'torch'), '')); " +
"print('A=' + next((d.version for d in m.distributions() " +
"if (d.metadata['Name'] or '').lower() == 'torchaudio'), ''))"
$_woaAudioProbe = Invoke-BoundedPythonProbe -PythonExe "python" -Code $_woaAudioCode
if ($_woaAudioProbe.Ok) {
$_woaTorchVer = if ($_woaAudioProbe.Output -match '(?m)^T=(\S+)\s*$') { $Matches[1] } else { "" }
$_woaAudioVer = if ($_woaAudioProbe.Output -match '(?m)^A=(\S+)\s*$') { $Matches[1] } else { "" }
# The extension is linked against one libtorch, so compare the full build too.
if ($_woaAudioVer -and $_woaTorchVer -and -not (
(Test-WoaAudioMatchesTorchParity -TorchVersion $_woaTorchVer -AudioVersion $_woaAudioVer) -and
(Test-WoaPairsWithTorchParity -TorchVersion $_woaTorchVer -OtherVersion $_woaAudioVer -Project "torchaudio"))) {
substep "windows on arm: removing torchaudio $_woaAudioVer (torch is now $_woaTorchVer)" "Yellow"
Fast-Uninstall torchaudio | Out-Null
}
}
}
# Triton for Windows enables torch.compile (without it training can hang). Paired with the
# installed torch, read from metadata.
$_tritonTorchProbe = Invoke-BoundedPythonProbe -PythonExe "python" -Code "import importlib.metadata as m; print(m.version('torch'))"
if ($_tritonTorchProbe.Ok) {
$_tritonTorchVer = @($_tritonTorchProbe.Output -split "`r?`n" | ForEach-Object { $_.Trim() } | Where-Object { $_ })
if ($_tritonTorchVer.Count -gt 0) { $_tritonSpec = Get-TritonWindowsSpec -TorchVersion $_tritonTorchVer[-1] -WinArm64 ([bool]$WinArm64Venv) }
}
substep "installing Triton for Windows..."
if ($script:UnslothVerbose) {
Fast-Install $_tritonSpec
$tritonInstallExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install $_tritonSpec | Out-String
$tritonInstallExit = $LASTEXITCODE
}
if ($tritonInstallExit -ne 0) {
substep "Triton install failed -- torch.compile may not work" "Yellow"
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Yellow
} else {
substep "Triton for Windows installed (enables torch.compile)"
}
}
} else {
substep "skipping direct PyTorch and Triton installation (no-torch mode)." "Yellow"
}
# No unsloth.exe rename needed: install.ps1 runs the CLI through python.exe and the base is not
# reinstalled. Duplicate metadata repair is wrapped in the CLI launcher transaction.
# ── Publish the torch flavor this run settled on ──
# so install_python_stack.py can enforce it; PyPI's Windows torch wheel is +cpu.
if (-not $NoTorchMode) {
$_expectedLeaf = Get-TorchIndexLeaf $_effectiveTorchIndexUrl
# On the AMD path $TorchInstallIndexUrl still points at /cpu.
$_expectedTag = if ($ROCmIndexUrl) { "rocm" }
elseif (Test-CudaFamilyLeaf $_expectedLeaf) { $_expectedLeaf }
elseif ($_expectedLeaf -eq "cpu" -or $_expectedLeaf -eq "xpu") { $_expectedLeaf }
elseif (Test-PipRocmFamilyLeaf $_expectedLeaf) { "rocm" }
else { $null }
# Remove-Item, NOT `= ""`: PowerShell 7.5 keeps a name assigned an empty string.
if ($_expectedTag) {
$env:UNSLOTH_EXPECTED_TORCH_TAG = $_expectedTag
} else {
Remove-Item Env:\UNSLOTH_EXPECTED_TORCH_TAG -ErrorAction SilentlyContinue
}
if ($_effectiveTorchIndexUrl) {
$env:UNSLOTH_TORCH_INSTALL_INDEX_URL = $_effectiveTorchIndexUrl
} else {
Remove-Item Env:\UNSLOTH_TORCH_INSTALL_INDEX_URL -ErrorAction SilentlyContinue
}
}
# Ordered heavy dependency installation -- shared cross-platform script
substep "running ordered dependency installation..."
python "$PSScriptRoot\install_python_stack.py"
$stackExit = $LASTEXITCODE
$script:SetupVenvChanged = $true
# AMD ROCm: pair triton-windows with torch (Get-RocmTritonPairing, defined before the fast path). Decided from the
# venv the stack left, whatever index or earlier tag produced it.
if ($stackExit -eq 0 -and -not $NoTorchMode) {
$_rocmPair = Get-RocmTritonPairing
$_rocmTritonFrom = if ($_rocmPair.Triton) { "triton-windows $($_rocmPair.Triton)" } else { "no triton-windows" }
if ($_rocmPair.Stale -and ($script:OfflineFastPath -or (Test-UvOfflineRequested))) {
# As on the fast path: the repair needs the index, so an offline run leaves it for the next online update.
substep "$_rocmTritonFrom does not pair with torch $($_rocmPair.Torch) but UV_OFFLINE is set -- left for the next online update" "Yellow"
} elseif ($_rocmPair.Stale) {
substep "pairing Triton for Windows with torch $($_rocmPair.Torch) ($_rocmTritonFrom -> $($_rocmPair.Spec))..." "Cyan"
$_rocmImportedBefore = $_rocmPair.Healthy
# Set the install manifest aside until the pair is verified, so a failed replacement is never certified
# complete and the next update re-runs the dependency pass. As in the XPU swap: a manifest that cannot be
# moved stays valid through the replacement, so nothing is installed then.
$_rocmManifest = Join-Path $VenvDir "unsloth_install_manifest.json"
$_rocmHeld = "$_rocmManifest.triton-pending"
$_rocmHasHeld = $false
$_rocmBlocked = $false
if (Test-Path -LiteralPath $_rocmManifest -PathType Leaf) {
try {
Move-Item -LiteralPath $_rocmManifest -Destination $_rocmHeld -Force -ErrorAction Stop
$_rocmHasHeld = $true
} catch {
$_rocmBlocked = $true
}
# A move can report success while the original remains; confirm it is gone.
if (Test-Path -LiteralPath $_rocmManifest -PathType Leaf) {
if ($_rocmHasHeld) { Remove-Item -LiteralPath $_rocmHeld -Force -ErrorAction SilentlyContinue }
$_rocmHasHeld = $false
$_rocmBlocked = $true
}
}
if ($_rocmBlocked) {
substep "[WARN] could not set the install manifest aside; $_rocmTritonFrom left in place -- flex attention decode may run unfused." "Yellow"
} else {
# Inherited uv / pip inputs that would drop or replace the pin while still reporting success, and
# require-hashes, which the unhashed pin can only fail.
$_rocmSavedEnv = Enter-TritonInstallEnv
# A broken 3.8, or a record with no version, already satisfies the pin as far as the installer can
# tell, so only a forced reinstall restores its files.
$_rocmArgs = @($_rocmPair.Spec)
if ($_rocmPair.Triton -match '^3\.8(\.|$)' -or ($_rocmPair.Dists -gt 0 -and -not $_rocmPair.Triton)) {
$_rocmArgs = @('--force-reinstall', '--no-deps') + $_rocmArgs
}
try {
$_rocmTritonOut = Fast-Install @_rocmArgs | Out-String
$_rocmTritonExit = $LASTEXITCODE
} finally {
Exit-TritonInstallEnv -Saved $_rocmSavedEnv
}
# Exit 0 is not enough: an override-dependencies entry in a uv config keeps the old version, and a
# probe that could not read the venv verifies nothing.
$_rocmAfter = Get-RocmTritonPairing
if ($_rocmAfter.Known -and $_rocmAfter.Spec -and -not $_rocmAfter.Stale) {
if ($_rocmHasHeld) {
try {
Move-Item -LiteralPath $_rocmHeld -Destination $_rocmManifest -Force -ErrorAction Stop
} catch {
# Without the manifest the next update re-runs the dependency pass; nothing is lost.
substep "[WARN] could not restore the install manifest ($($_.Exception.Message)); the next update re-runs the dependency pass." "Yellow"
}
}
} else {
$_rocmHave = if (-not $_rocmAfter.Known) { "the venv could not be read" } elseif ($_rocmAfter.Triton) { "triton-windows $($_rocmAfter.Triton) installed" } else { "no triton-windows installed" }
substep "[WARN] could not pair $($_rocmPair.Spec) (exit $_rocmTritonExit, $_rocmHave); flex attention decode may run unfused. Check uv override-dependencies / constraints if this repeats." "Yellow"
Write-StudioLine (Redact-InstallOutput $_rocmTritonOut) -ForegroundColor Yellow
if ($_rocmImportedBefore -and -not (Get-TritonRuntimeState).Healthy) {
Write-StudioLine "[ERROR] the Triton replacement failed part way and triton no longer works -- torch.compile is broken." -ForegroundColor Red
Write-StudioLine " Repair with: python -m pip install --force-reinstall --no-deps `"$($_rocmPair.Spec)`"" -ForegroundColor Red
# Fail, or install.ps1 commits this venv over its rollback copy.
$stackExit = if ($_rocmTritonExit -ne 0) { $_rocmTritonExit } else { 1 }
}
if ($_rocmHasHeld) { Remove-Item -LiteralPath $_rocmHeld -Force -ErrorAction SilentlyContinue }
}
}
}
}
# ── Intel XPU: bitsandbytes must carry XPU kernels ──
# Only bitsandbytes' XPU library exports the 4-bit kernels; floor 0.50.0 (<=0.49.2 NaNs on AMD).
# Never the unsloth[intel-gpu-torch*] extra. Must stay above the EAP restore below (5.1 needs Continue).
if ($stackExit -eq 0 -and $XpuIndexUrl) {
substep "installing bitsandbytes with Intel XPU kernels..."
if ($script:UnslothVerbose) {
Fast-Install --no-deps "bitsandbytes>=0.50.0" | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$bnbXpuExit = $LASTEXITCODE
$bnbOutput = ""
} else {
$bnbOutput = Fast-Install --no-deps "bitsandbytes>=0.50.0" | Out-String
$bnbXpuExit = $LASTEXITCODE
}
if ($bnbXpuExit -ne 0) {
substep "[WARN] could not install an XPU-capable bitsandbytes (exit $bnbXpuExit); 4-bit QLoRA may be unavailable." "Yellow"
Write-StudioLine (Redact-InstallOutput $bnbOutput) -ForegroundColor Yellow
}
}
# ── Intel XPU: triton-windows must not shadow torch's XPU triton ──
# Both own the `triton` package. Run after the stack (it reinstalls triton-windows); always
# pair the uninstall with a reinstall.
if ($stackExit -eq 0 -and $XpuIndexUrl) {
$_tritonProbe = Get-XpuTritonState
$_tritonWinVer = $_tritonProbe.TritonWin
$_tritonXpuSpec = $_tritonProbe.XpuSpec
$_tritonImportedBefore = $true
$_tritonXpuWrong = $false
if ($_tritonXpuSpec -match '(?i)xpu') {
$_tritonImportedBefore = (Get-TritonRuntimeState).Healthy
$_tritonXpuWrong = -not $_tritonProbe.XpuOk
}
$_tritonWanted = $_tritonXpuSpec -match '(?i)xpu' -and ($_tritonWinVer -or -not $_tritonImportedBefore -or $_tritonXpuWrong)
if ($_tritonWanted -and ($script:OfflineFastPath -or (Test-UvOfflineRequested))) {
substep "torch's Intel XPU triton $_tritonXpuSpec is not in place but UV_OFFLINE is set -- left for the next online update" "Yellow"
} elseif ($_tritonWanted) {
if ($_tritonWinVer) {
substep "replacing triton-windows $_tritonWinVer with $_tritonXpuSpec (Intel XPU)..." "Cyan"
$_tritonLeft = "triton-windows $_tritonWinVer left in place -- it still shadows torch XPU triton, so torch.compile will not use the XPU."
} elseif (-not $_tritonImportedBefore) {
substep "triton does not import -- reinstalling $_tritonXpuSpec (Intel XPU)..." "Cyan"
$_tritonLeft = "triton still does not import, so torch.compile will not work."
} else {
$_tritonXpuHave = if ($_tritonProbe.XpuDist) { "Intel XPU triton $($_tritonProbe.XpuDist)" } else { "no Intel XPU triton" }
substep "$_tritonXpuHave installed, but torch requires $_tritonXpuSpec -- reinstalling it..." "Cyan"
$_tritonLeft = "$_tritonXpuHave left in place, and torch requires $_tritonXpuSpec."
}
# Redacted: a mirror pin can carry a token.
$_tritonRepairUrl = Redact-InstallOutput $XpuIndexUrl
$_tritonRepair = "python -m pip install --force-reinstall --no-deps `"$_tritonXpuSpec`" --index-url $_tritonRepairUrl"
# test_intel_registry_fallback.ps1 asserts this literal matches MANIFEST_NAME.
$_manifestPath = Join-Path $VenvDir "unsloth_install_manifest.json"
# Fetch, then uninstall, then install, so a dead mirror cannot strand the venv between steps.
$_tritonTmp = Join-Path ([System.IO.Path]::GetTempPath()) "unsloth_triton_xpu_$([guid]::NewGuid().ToString('N').Substring(0,8))"
# Inherited UV_EXCLUDE can make installation report success without installing the replacement.
$_tritonSavedEnv = Enter-TritonInstallEnv
try {
New-Item -ItemType Directory -Force -Path $_tritonTmp -ErrorAction SilentlyContinue | Out-Null
# Advanced function: PowerShell binds `-d` to -Debug, so use `--dest`.
if ($script:UnslothVerbose) {
Fast-Download --no-deps --only-binary=:all: --dest $_tritonTmp $_tritonXpuSpec --index-url $XpuIndexUrl | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$tritonDlExit = $LASTEXITCODE
$tritonDlOutput = ""
} else {
$tritonDlOutput = Fast-Download --no-deps --only-binary=:all: --dest $_tritonTmp $_tritonXpuSpec --index-url $XpuIndexUrl | Out-String
$tritonDlExit = $LASTEXITCODE
}
$_tritonWheel = @(Get-ChildItem -LiteralPath $_tritonTmp -Filter "*.whl" -ErrorAction SilentlyContinue) | Select-Object -First 1 -ExpandProperty FullName
if ($tritonDlExit -ne 0 -or -not $_tritonWheel) {
if (-not $_tritonImportedBefore -and (Test-Path -LiteralPath $_manifestPath -PathType Leaf)) {
try {
Remove-Item -LiteralPath $_manifestPath -Force -ErrorAction Stop
} catch {
Write-StudioLine "[ERROR] triton does not import and the install manifest could not be removed: $($_.Exception.Message)" -ForegroundColor Red
$stackExit = 1
}
}
substep "[WARN] could not fetch $_tritonXpuSpec (exit $tritonDlExit); $_tritonLeft" "Yellow"
Write-StudioLine (Redact-InstallOutput $tritonDlOutput) -ForegroundColor Yellow
} else {
# Move (never rewrite) the manifest aside during the swap: 5.1 encodings would corrupt it.
$_manifestHeld = $null
$_manifestBlocked = $false
$_uninstallExit = 0
if ($_manifestPath -and (Test-Path -LiteralPath $_manifestPath -PathType Leaf)) {
$_held = Join-Path $_tritonTmp "held_manifest.json"
try {
Move-Item -LiteralPath $_manifestPath -Destination $_held -Force -ErrorAction Stop
# Cross-volume Move-Item can report success while the original remains; confirm it is gone.
if (Test-Path -LiteralPath $_manifestPath -PathType Leaf) {
Remove-Item -LiteralPath $_held -Force -ErrorAction SilentlyContinue
$_manifestBlocked = $true
} else {
$_manifestHeld = $_held
}
} catch { $_manifestBlocked = $true }
}
if ($_manifestBlocked) {
# An unmovable manifest stays valid through the destructive window, so skip the swap.
substep "[WARN] could not set the install manifest aside; $_tritonLeft" "Yellow"
} elseif ($_tritonWinVer) {
Fast-Uninstall "triton-windows" | Out-Null
$_uninstallExit = $LASTEXITCODE
}
# A failed uninstall can still remove files; recheck imports before restoring the manifest.
if (-not $_manifestBlocked -and $_uninstallExit -ne 0) {
if ((Get-TritonRuntimeState).Healthy) {
substep "[WARN] could not remove triton-windows $_tritonWinVer (exit $_uninstallExit); it still shadows torch XPU triton, so torch.compile will not use the XPU." "Yellow"
if ($_manifestHeld) {
try { Move-Item -LiteralPath $_manifestHeld -Destination $_manifestPath -Force -ErrorAction Stop } catch {}
}
} elseif ($_tritonImportedBefore) {
Write-StudioLine "[ERROR] removing triton-windows $_tritonWinVer failed part way (exit $_uninstallExit) and triton no longer imports -- torch.compile is broken." -ForegroundColor Red
Write-StudioLine " Repair with: $_tritonRepair" -ForegroundColor Red
# Fail, or install.ps1 commits this venv over its rollback copy.
$stackExit = $_uninstallExit
} else {
substep "[WARN] could not remove triton-windows $_tritonWinVer (exit $_uninstallExit); $_tritonLeft" "Yellow"
}
} elseif (-not $_manifestBlocked) {
if ($script:UnslothVerbose) {
Fast-Install --force-reinstall --no-deps $_tritonWheel | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
$tritonXpuExit = $LASTEXITCODE
$tritonOutput = ""
} else {
$tritonOutput = Fast-Install --force-reinstall --no-deps $_tritonWheel | Out-String
$tritonXpuExit = $LASTEXITCODE
}
$_tritonAfter = Get-XpuTritonState
$_tritonPresent = ($tritonXpuExit -eq 0 -and $_tritonAfter.Known -and $_tritonAfter.XpuOk -and
-not $_tritonAfter.TritonWin -and (Get-TritonRuntimeState).Healthy)
if (-not $_tritonPresent) {
$_tritonXpuWhy = if ($tritonXpuExit -ne 0) { "exit $tritonXpuExit" } else { "exit 0, but it is not installed or triton does not import" }
# A stale XPU RECORD can later delete the generic fallback's shared files.
Fast-Uninstall ($_tritonXpuSpec -replace '^([A-Za-z0-9._-]+).*$', '$1') | Out-Null
Fast-Install --force-reinstall --no-deps $_tritonSpec | Out-Null
$tritonBackExit = $LASTEXITCODE
$_tritonBack = Get-XpuTritonState
$_tritonPresent = ($tritonBackExit -eq 0 -and $_tritonBack.Known -and -not $_tritonBack.XpuDist -and $_tritonBack.TritonWin -and
(Get-TritonRuntimeState).Healthy)
Write-StudioLine (Redact-InstallOutput $tritonOutput) -ForegroundColor Yellow
if ($_tritonPresent -and $InstallerManagedSetup -and -not $_tritonWinVer) {
Write-StudioLine "[ERROR] could not install $_tritonXpuSpec ($_tritonXpuWhy); the triton-windows fallback would drop the Intel XPU triton -- keeping the installer's rollback copy." -ForegroundColor Red
Write-StudioLine " Repair with: $_tritonRepair" -ForegroundColor Red
$stackExit = 1
} elseif ($_tritonPresent) {
substep "[WARN] could not install $_tritonXpuSpec ($_tritonXpuWhy); fell back to triton-windows, so triton imports -- but torch.compile will not use the XPU." "Yellow"
} elseif ($_tritonImportedBefore -or $InstallerManagedSetup) {
$_tritonBackWhy = if ($_tritonBack.XpuDist) { "the Intel XPU distribution is still recorded over the fallback files" }
else { "the fallback distribution or runtime could not be verified" }
Write-StudioLine "[ERROR] could not verify the triton-windows fallback: $_tritonBackWhy." -ForegroundColor Red
Write-StudioLine " Repair with: $_tritonRepair" -ForegroundColor Red
$stackExit = if ($tritonBackExit -ne 0) { $tritonBackExit } else { 1 }
} else {
substep "[WARN] could not install $_tritonXpuSpec ($_tritonXpuWhy) and the triton-windows fallback could not be verified. Repair with: $_tritonRepair" "Yellow"
}
}
# Restore only once a triton imports; a lost manifest makes the next update repair.
if ($_manifestHeld -and $_tritonPresent) {
try { Move-Item -LiteralPath $_manifestHeld -Destination $_manifestPath -Force -ErrorAction Stop } catch {}
if (-not (Test-Path -LiteralPath $_manifestPath -PathType Leaf)) {
substep "[WARN] could not restore the install manifest; the next update will re-run the dependency pass." "Yellow"
}
}
}
}
} finally {
Exit-TritonInstallEnv -Saved $_tritonSavedEnv
Remove-Item -Recurse -Force -LiteralPath $_tritonTmp -ErrorAction SilentlyContinue
}
}
# Managed setup must preserve rollback even when triton was already broken or its requirement is unreadable.
if ($stackExit -eq 0 -and $InstallerManagedSetup -and ($_tritonXpuSpec -match '(?i)xpu' -or -not $_tritonProbe.Known) -and
-not (Get-TritonRuntimeState).Healthy) {
$_tritonRepairUrl = Redact-InstallOutput $XpuIndexUrl
$_tritonRepairSpec = if ($_tritonXpuSpec) { $_tritonXpuSpec } else { "pytorch-triton-xpu" }
Write-StudioLine "[ERROR] triton does not import -- torch.compile is broken; keeping the installer's rollback copy." -ForegroundColor Red
Write-StudioLine " Repair with: python -m pip install --force-reinstall --no-deps `"$_tritonRepairSpec`" --index-url $_tritonRepairUrl" -ForegroundColor Red
$stackExit = 1
}
}
$ErrorActionPreference = $prevEAP
if ($stackExit -ne 0) {
Write-StudioLine "[FAILED] Python dependency installation failed (exit code $stackExit)" -ForegroundColor Red
Write-StudioLine " Re-run the installer or check the error above for details." -ForegroundColor Red
Exit-SetupFailure "Python dependency installation failed (exit code $stackExit)"
}
# ── Finish with the setup script this update installed ──
# Phases a release adds below would be skipped by the update installing it. A module scope keeps this
# run's variables from the new copy; it cannot see $PSDefaultParameterValues, so those are passed in.
if (Test-SetupScriptReplaced) {
Complete-FrontendBuildBackground
step "setup" "the update changed setup or its Node pin; finishing with the new version"
$_setupRerunArgs = $script:SetupArgs
Restore-SetupStartEnvironment
Remove-Item Env:UNSLOTH_STUDIO_FULL_DEPS -ErrorAction SilentlyContinue
$env:UNSLOTH_SETUP_RERUN = '1'
$_setupRerunner = New-Module -ScriptBlock { $script:Ok = $false; $script:Code = 1 }
try {
& $_setupRerunner {
param($Path, [object[]]$Arguments, $Defaults)
$PSDefaultParameterValues = $Defaults
& $Path @Arguments
$script:Ok = $?
$script:Code = $global:LASTEXITCODE
} $script:SetupSelfPath $_setupRerunArgs $PSDefaultParameterValues
$_setupRerunOk = & $_setupRerunner { $script:Ok }
$_setupRerunCode = & $_setupRerunner { $script:Code }
} finally {
Remove-Item Env:UNSLOTH_SETUP_RERUN -ErrorAction SilentlyContinue
Remove-WoaMergedOverrides
}
# $? first: under -Command a run that fell off its end succeeded whatever its last native exit.
if ($_setupRerunOk) { return }
Exit-SetupFailure -Message "the updated setup script failed (exit code $_setupRerunCode)" -Code $_setupRerunCode -NoTauriMarker
}
} else {
step "python" "dependencies up to date"
$ErrorActionPreference = $prevEAP
}
Complete-FrontendBuildBackground -IfDone
# Windows MXC Preview is an optional, pinned prebuilt like the other native
# runtimes. Keep this outside the Python dependency fast path: a missing or
# corrupt runtime must be installed or repaired even when the venv is current.
if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) {
$_mxcInstaller = Join-Path $PSScriptRoot "install_mxc_prebuilt.py"
# Must match mxc_runtime._installed_package_root(): ARM64 PCs get Microsoft's ARM64 build.
$_mxcArchDir = if ((Get-UvHostArch) -eq "arm64") { "windows-arm64" } else { "windows-x86_64" }
$_mxcInstallDir = Join-Path $StudioHome "mxc-runtime\$_mxcArchDir"
if (Test-Path -LiteralPath $_mxcInstaller -PathType Leaf) {
substep "installing Windows MXC Preview runtime..."
# Optional: a nonzero exit or stderr must reach the fallback, not stop setup.
$_mxcPrevEAP = $ErrorActionPreference
$ErrorActionPreference = "Continue"
$_mxcRestoreNative = $PSVersionTable.PSVersion.Major -ge 7
if ($_mxcRestoreNative) {
$_mxcPrevNative = $PSNativeCommandUseErrorActionPreference
$PSNativeCommandUseErrorActionPreference = $false
}
try {
$_mxcOutput = & python $_mxcInstaller --install-dir $_mxcInstallDir 2>&1 | Out-String
$_mxcExit = $LASTEXITCODE
} finally {
$ErrorActionPreference = $_mxcPrevEAP
if ($_mxcRestoreNative) {
$PSNativeCommandUseErrorActionPreference = $_mxcPrevNative
}
}
if ($_mxcExit -eq 0) {
if ($_mxcOutput -match "already matches") {
step "MXC Preview" "prebuilt up to date and validated"
} else {
step "MXC Preview" "prebuilt installed and validated"
}
} elseif ($_mxcExit -eq 3) {
step "MXC Preview" "install blocked by an active MXC process; existing runtime kept" "Yellow"
} else {
step "MXC Preview" "prebuilt unavailable; Unsloth Studio will use software safeguards" "Yellow"
}
if ($script:UnslothVerbose -and $_mxcOutput) {
Write-StudioLine $_mxcOutput.Trim() -ForegroundColor $(if ($_mxcExit -eq 0) { "DarkGray" } else { "Yellow" })
}
}
}
# ── Pre-install transformers 5.x into .venv_t5_530/, .venv_t5_550/, and .venv_t5_510/ ──
# Runs outside the deps fast-path gate so that upgrades from the legacy
# single .venv_t5 are always migrated to the tiered layout.
# T5 sidecar venvs live under the resolved $StudioHome so custom installs are self-contained.
$VenvT5_530Dir = Join-Path $RuntimeRoot ".venv_t5_530"
$VenvT5_550Dir = Join-Path $RuntimeRoot ".venv_t5_550"
$VenvT5_510Dir = Join-Path $RuntimeRoot ".venv_t5_510"
$VenvT5Legacy = Join-Path $StudioHome ".venv_t5"
function Test-TargetPackageVersion {
param(
[Parameter(Mandatory = $true)][string]$TargetDir,
[Parameter(Mandatory = $true)][string]$PackageName,
[Parameter(Mandatory = $true)][string]$ExpectedVersion
)
if (-not (Test-Path -LiteralPath $TargetDir -PathType Container)) { return $false }
$packageNorm = $PackageName.Replace("-", "_")
foreach ($pattern in @("$packageNorm-*.dist-info", "$PackageName-*.dist-info")) {
foreach ($distInfo in @(Get-ChildItem -LiteralPath $TargetDir -Directory -Filter $pattern -ErrorAction SilentlyContinue)) {
$metadata = Join-Path $distInfo.FullName "METADATA"
if (-not (Test-Path -LiteralPath $metadata -PathType Leaf)) { continue }
foreach ($line in (Get-Content -LiteralPath $metadata -ErrorAction SilentlyContinue)) {
if ($line -eq "Version: $ExpectedVersion") { return $true }
}
}
}
return $false
}
# Mirrors _SIDECAR_COMMON_PINS in setup.sh.
$SidecarCommonPins = @("huggingface_hub==1.8.0", "hf_xet==1.4.2")
# An inherited UV_OVERRIDE would replace the pin and force rebuilds.
function Fast-Install-Sidecar {
param([Parameter(ValueFromRemainingArguments=$true)]$Args_)
$savedOverride = $env:UV_OVERRIDE
$savedUnsynced = @{}
try {
Remove-Item Env:UV_OVERRIDE -ErrorAction SilentlyContinue
Fast-Install @Args_
# A pin the PyPI mirror has not synced yet: one rerun against pypi.org.
$unsynced = @(-split "$env:_UNSLOTH_MIRROR_SPARE" | Where-Object { $_ -like 'unsynced|*' })
if ($LASTEXITCODE -ne 0 -and $unsynced) {
foreach ($pair in @($unsynced[0].Split('|') | Select-Object -Skip 1)) {
$name, $value = $pair.Split('=', 2)
$savedUnsynced[$name] = [Environment]::GetEnvironmentVariable($name)
Set-Item "Env:$name" $value
}
Fast-Install @Args_
}
} finally {
foreach ($name in $savedUnsynced.Keys) {
if ($null -eq $savedUnsynced[$name]) { Remove-Item "Env:$name" -ErrorAction SilentlyContinue } else { Set-Item "Env:$name" $savedUnsynced[$name] }
}
if ($null -ne $savedOverride) { $env:UV_OVERRIDE = $savedOverride }
}
}
function Remove-SidecarTiktoken {
# Remnants of a failed tiktoken install shadow the ambient copy.
param([Parameter(Mandatory = $true)][string]$TargetDir)
foreach ($name in @("tiktoken", "tiktoken_ext", "tiktoken.libs")) {
$entry = Join-Path $TargetDir $name
if (Test-Path -LiteralPath $entry) { Remove-Item -LiteralPath $entry -Recurse -Force -ErrorAction SilentlyContinue }
}
Get-ChildItem -LiteralPath $TargetDir -Directory -Filter "tiktoken-*.dist-info" -ErrorAction SilentlyContinue |
ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction SilentlyContinue }
foreach ($name in @("tiktoken", "tiktoken_ext", "tiktoken.libs")) {
if (Test-Path -LiteralPath (Join-Path $TargetDir $name)) { return $false }
}
$left = @(Get-ChildItem -LiteralPath $TargetDir -Directory -Filter "tiktoken-*.dist-info" -ErrorAction SilentlyContinue)
return ($left.Count -eq 0)
}
function Retire-SidecarAfterFailedTiktoken {
param(
[Parameter(Mandatory = $true)][string]$TargetDir,
[Parameter(Mandatory = $true)][string]$DirName
)
Remove-Item -LiteralPath $TargetDir -Recurse -Force -ErrorAction SilentlyContinue
substep "$DirName/ kept part of a failed tiktoken install; retired, rebuilt on the next update" "Yellow"
}
function Repair-SidecarTiktoken {
param(
[Parameter(Mandatory = $true)][string]$TargetDir,
[Parameter(Mandatory = $true)][string]$DirName
)
# Offline keep: Fast-Install's pip fallback would reach the network.
if ($script:OfflineFastPath) { return }
if (Test-UvOfflineRequested) { return }
# RECORD is written last; a recordless dist-info goes first since uv cannot uninstall it.
Get-ChildItem -LiteralPath $TargetDir -Directory -Filter "tiktoken-*.dist-info" -ErrorAction SilentlyContinue |
Where-Object { -not (Test-Path -LiteralPath (Join-Path $_.FullName "RECORD") -PathType Leaf) } |
ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction SilentlyContinue }
$present = @(Get-ChildItem -LiteralPath $TargetDir -Directory -Filter "tiktoken-*.dist-info" -ErrorAction SilentlyContinue |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "RECORD") -PathType Leaf })
$payload = Join-Path $TargetDir "tiktoken"
if ($present.Count -gt 0 -and (Test-Path -LiteralPath (Join-Path $payload "__init__.py") -PathType Leaf)) { return }
# Dropping the metadata makes uv reinstall instead of calling the pin satisfied.
Get-ChildItem -LiteralPath $TargetDir -Directory -Filter "tiktoken-*.dist-info" -ErrorAction SilentlyContinue |
ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction SilentlyContinue }
Invoke-MirrorFallback
# Cleared first, or a stale nonzero would retire the sidecar.
$global:LASTEXITCODE = 0
$output = Fast-Install-Sidecar --target $TargetDir --no-deps --upgrade tiktoken 2>&1 | Out-String
if ($LASTEXITCODE -ne 0) {
if (Remove-SidecarTiktoken -TargetDir $TargetDir) {
substep "Could not install tiktoken into $DirName/ -- Qwen tokenizers may fail" "Yellow"
} else {
Retire-SidecarAfterFailedTiktoken -TargetDir $TargetDir -DirName $DirName
}
}
}
function Test-SidecarCurrent {
param(
[Parameter(Mandatory = $true)][string]$TargetDir,
[Parameter(Mandatory = $true)][string]$Version
)
if (-not (Test-Path -LiteralPath $TargetDir -PathType Container)) { return $false }
$shim = Join-Path $PSScriptRoot "install_manifest.py"
if (-not (Test-Path -LiteralPath $shim -PathType Leaf)) {
return (Test-TargetPackageVersion -TargetDir $TargetDir -PackageName "transformers" -ExpectedVersion $Version)
}
$pins = @("transformers==$Version") + $SidecarCommonPins
$out = ""
# Bounded process: a native nonzero exit can terminate under $PSNativeCommandUseErrorActionPreference.
# argv is base64; venv interpreter first since PATH python can be the Store stub.
$pythonExe = $null
$probe = $null
if ($VenvPyExe -and (Test-Path -LiteralPath $VenvPyExe -PathType Leaf)) {
$pythonExe = $VenvPyExe
} else {
try { $pythonExe = (Get-Command python -ErrorAction Stop).Source } catch { $pythonExe = $null }
}
if ($pythonExe) {
$argv = (@($shim, "sidecar", $TargetDir) + $pins) -join [char]0
$encoded = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($argv))
$code = "import sys, runpy, base64; sys.argv = base64.b64decode('$encoded').decode('utf-8').split(chr(0)); runpy.run_path(sys.argv[0], run_name='__main__')"
$probe = Invoke-BoundedPythonProbe -PythonExe $pythonExe -Code $code -TimeoutSec 60
if ($probe.TimedOut) {
$out = "sidecar: audit did not answer within 60 seconds"
} else {
$out = ([string]$probe.Output).Trim()
}
}
if ($out -eq "sidecar: current") { return $true }
if ($out -like "sidecar:*") {
if ($script:UnslothVerbose) { substep "sidecar $TargetDir`: $($out -replace '^sidecar:\s*', '')" }
return $false
}
if ($null -ne $probe -and -not $probe.Ok) {
if ($script:UnslothVerbose) { substep "sidecar $TargetDir`: audit failed" }
return $false
}
# An old shim exits 0 silently: fall back to the version grep.
return (Test-TargetPackageVersion -TargetDir $TargetDir -PackageName "transformers" -ExpectedVersion $Version)
}
function Install-T5Sidecar {
param(
[Parameter(Mandatory = $true)][string]$TargetDir,
[Parameter(Mandatory = $true)][string]$Version,
[Parameter(Mandatory = $true)][string]$Label,
[Parameter(Mandatory = $true)][string]$DirName,
[Parameter(Mandatory = $true)][string]$Reason
)
substep "pre-installing transformers $Version $Reason..."
Invoke-MirrorFallback
Assert-StudioOwnedOrAbsent -Path $TargetDir -Label "transformers $Label sidecar venv"
if (Test-Path -LiteralPath $TargetDir) { Remove-Item -LiteralPath $TargetDir -Recurse -Force }
[System.IO.Directory]::CreateDirectory($TargetDir) | Out-Null
Mark-StudioOwned -Path $TargetDir
foreach ($pkg in @("transformers==$Version") + $SidecarCommonPins) {
if ($script:UnslothVerbose) {
Fast-Install-Sidecar --target $TargetDir --no-deps $pkg
$t5PkgExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install-Sidecar --target $TargetDir --no-deps $pkg | Out-String
$t5PkgExit = $LASTEXITCODE
}
if ($t5PkgExit -ne 0) {
Write-StudioLine "[FAIL] Could not install $pkg into $DirName/" -ForegroundColor Red
Write-StudioLine (Redact-InstallOutput $output) -ForegroundColor Red
$ErrorActionPreference = $script:PrevEAP_T5
Exit-SetupFailure "Could not install $pkg into $DirName"
}
}
if ($script:UnslothVerbose) {
Fast-Install-Sidecar --target $TargetDir --no-deps tiktoken
$tiktokenInstallExit = $LASTEXITCODE
$output = ""
} else {
$output = Fast-Install-Sidecar --target $TargetDir --no-deps tiktoken | Out-String
$tiktokenInstallExit = $LASTEXITCODE
}
if ($tiktokenInstallExit -ne 0) {
if (Remove-SidecarTiktoken -TargetDir $TargetDir) {
substep "Could not install tiktoken into $DirName/ -- Qwen tokenizers may fail" "Yellow"
} else {
Retire-SidecarAfterFailedTiktoken -TargetDir $TargetDir -DirName $DirName
}
}
step "transformers" "$Version pre-installed"
}
$_NeedT5_530 = $false
$_NeedT5_550 = $false
$_NeedT5_510 = $false
# The migration needs the network; under UV_OFFLINE it waits for the next online update.
if ((Test-Path -LiteralPath $VenvT5Legacy) -and ($script:OfflineFastPath -or (Test-UvOfflineRequested))) {
substep "legacy transformers sidecar left in place -- UV_OFFLINE is set, migration waits for the next online update" "Yellow"
} elseif (Test-Path -LiteralPath $VenvT5Legacy) {
# A staged run's venvs may never be activated, so only the live update migrates.
if (-not $StageRoot) {
Assert-StudioOwnedOrAbsent -Path $VenvT5Legacy -Label "legacy transformers sidecar venv"
Remove-Item -LiteralPath $VenvT5Legacy -Recurse -Force
}
$_NeedT5_530 = $true
$_NeedT5_550 = $true
$_NeedT5_510 = $true
}
if (-not (Test-SidecarCurrent -TargetDir $VenvT5_530Dir -Version "5.3.0")) { $_NeedT5_530 = $true }
if (-not (Test-SidecarCurrent -TargetDir $VenvT5_550Dir -Version "5.5.0")) { $_NeedT5_550 = $true }
if (-not (Test-SidecarCurrent -TargetDir $VenvT5_510Dir -Version "5.10.2")) { $_NeedT5_510 = $true }
# Offline keep: defer sidecar rebuilds; the runtime self-heal covers a missing tier. Mirrors setup.sh.
$_DeferT5_530 = $false
$_DeferT5_550 = $false
$_DeferT5_510 = $false
if (-not $script:OfflineFastPath -and (Test-UvOfflineRequested)) {
foreach ($tier in @(@("530", "5.3.0"), @("550", "5.5.0"), @("510", "5.10.2"))) {
$flag = "_NeedT5_$($tier[0])"
if ((Get-Variable -Name $flag -ValueOnly)) {
substep "transformers $($tier[1]) sidecar is stale or missing but UV_OFFLINE is set -- left for the next online update" "Yellow"
Set-Variable -Name $flag -Value $false
Set-Variable -Name "_DeferT5_$($tier[0])" -Value $true
}
}
}
if ($script:OfflineFastPath) {
foreach ($tier in @(@("530", "5.3.0"), @("550", "5.5.0"), @("510", "5.10.2"))) {
$flag = "_NeedT5_$($tier[0])"
if ((Get-Variable -Name $flag -ValueOnly)) {
substep "transformers $($tier[1]) sidecar is stale but UV_OFFLINE is set -- left for the next online update" "Yellow"
Set-Variable -Name $flag -Value $false
Set-Variable -Name "_DeferT5_$($tier[0])" -Value $true
}
}
}
if ($_NeedT5_530 -or $_NeedT5_550 -or $_NeedT5_510) {
Write-StudioLine ""
}
$script:PrevEAP_T5 = $ErrorActionPreference
$ErrorActionPreference = "Continue"
if ($_NeedT5_530) {
Install-T5Sidecar -TargetDir $VenvT5_530Dir -Version "5.3.0" -Label "5.3" -DirName ".venv_t5_530" -Reason "for newer model support"
} elseif ($_DeferT5_530) {
step "transformers" "5.3.0 sidecar stale -- left for the next online update"
} else {
step "transformers" "5.3.0 sidecar current"
Repair-SidecarTiktoken -TargetDir $VenvT5_530Dir -DirName ".venv_t5_530"
}
if ($_NeedT5_550) {
Install-T5Sidecar -TargetDir $VenvT5_550Dir -Version "5.5.0" -Label "5.5" -DirName ".venv_t5_550" -Reason "for Gemma 4 support"
} elseif ($_DeferT5_550) {
step "transformers" "5.5.0 sidecar stale -- left for the next online update"
} else {
step "transformers" "5.5.0 sidecar current"
Repair-SidecarTiktoken -TargetDir $VenvT5_550Dir -DirName ".venv_t5_550"
}
if ($_NeedT5_510) {
Install-T5Sidecar -TargetDir $VenvT5_510Dir -Version "5.10.2" -Label "5.10" -DirName ".venv_t5_510" -Reason "for Gemma 4 Unified support"
} elseif ($_DeferT5_510) {
step "transformers" "5.10.2 sidecar stale -- left for the next online update"
} else {
step "transformers" "5.10.2 sidecar current"
Repair-SidecarTiktoken -TargetDir $VenvT5_510Dir -DirName ".venv_t5_510"
}
$ErrorActionPreference = $script:PrevEAP_T5
# ==========================================================================
# PHASE 3.4: Prefer prebuilt llama.cpp bundles before source build
# ==========================================================================
# Reuse the managed path resolved and preflighted before phase 1.
if (-not (Test-Path -LiteralPath $UnslothHome)) { [System.IO.Directory]::CreateDirectory($UnslothHome) | Out-Null }
$NeedLlamaSourceBuild = $false
$script:LlamaSourceBuildIsFallback = $false
$SkipPrebuiltInstall = $false
$RequestedLlamaTag = if ($env:UNSLOTH_LLAMA_TAG) { $env:UNSLOTH_LLAMA_TAG } else { $DefaultLlamaTag }
$HelperReleaseRepo = "unslothai/llama.cpp"
$LlamaPr = if ($env:UNSLOTH_LLAMA_PR) { $env:UNSLOTH_LLAMA_PR.Trim() } else { "" }
$LlamaPrForce = if ($env:UNSLOTH_LLAMA_PR_FORCE) { $env:UNSLOTH_LLAMA_PR_FORCE.Trim() } else { $DefaultLlamaPrForce }
$LlamaSource = $DefaultLlamaSource
if ($LlamaSource.EndsWith('.git')) { $LlamaSource = $LlamaSource.Substring(0, $LlamaSource.Length - 4) }
$ResolvedSourceUrl = $LlamaSource
$ResolvedSourceRef = $RequestedLlamaTag
$ResolvedSourceRefKind = "tag"
$ResolvedLlamaTag = $RequestedLlamaTag
$sourceLlamaBackend = "$($env:UNSLOTH_LLAMA_CPP_BACKEND)".Trim().ToLowerInvariant()
$sourceLegacyForceVulkan = "$($env:UNSLOTH_FORCE_VULKAN)".Trim().ToLowerInvariant()
$explicitLlamaSourceBackend = $null
if (-not $IsMacOS) {
if ($sourceLlamaBackend -in @("cpu", "cuda", "vulkan", "hip", "rocm")) {
$explicitLlamaSourceBackend = if ($sourceLlamaBackend -eq "hip") { "rocm" } else { $sourceLlamaBackend }
} elseif ($sourceLlamaBackend -ne "auto" -and $sourceLegacyForceVulkan -in @("1", "true", "yes", "on")) {
$explicitLlamaSourceBackend = "vulkan"
}
}
if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
$NeedLlamaSourceBuild = $true
$SkipPrebuiltInstall = $true
}
function Invoke-LlamaHelper {
param(
[string[]]$Arguments,
[string]$StderrPath = $null
)
$previousErrorActionPreference = $ErrorActionPreference
$previousNativeErrorPreference = $null
$restoreNativeErrorPreference = $false
$ErrorActionPreference = "Continue"
if ($PSVersionTable.PSVersion.Major -ge 7) {
$previousNativeErrorPreference = $PSNativeCommandUseErrorActionPreference
$PSNativeCommandUseErrorActionPreference = $false
$restoreNativeErrorPreference = $true
}
try {
# Capture all output (2>&1) so PS does not make ErrorRecords.
$allOutput = & python "$PSScriptRoot\install_llama_prebuilt.py" @Arguments 2>&1
$exitCode = $LASTEXITCODE
$stdoutLines = @()
$stderrLines = @()
foreach ($line in $allOutput) {
if ($line -is [System.Management.Automation.ErrorRecord]) {
$stderrLines += $line.ToString()
} else {
$stdoutLines += $line
}
}
if ($StderrPath -and $stderrLines.Count -gt 0) {
$stderrLines | Out-File -FilePath $StderrPath -Encoding utf8
}
return [pscustomobject]@{
Output = $stdoutLines
ExitCode = $exitCode
}
} finally {
$ErrorActionPreference = $previousErrorActionPreference
if ($restoreNativeErrorPreference) {
$PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreference
}
}
}
function Test-LlamaTreeStillHealthy {
<#
Whether a tree the reuse shortcut keeps would pass preflight; llama-server.exe existing is
not enough. Same check as setup.sh via install_llama_prebuilt. Healthy on any failure to ask.
#>
param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$TreeRoot)
if ([string]::IsNullOrWhiteSpace($TreeRoot)) { return $true }
if (-not (Test-PathQuiet $TreeRoot "Container")) { return $true }
try {
$probe = Invoke-LlamaHelper -Arguments @("--check-existing-install", $TreeRoot)
} catch {
return $true
}
if ($null -eq $probe) { return $true }
if ($probe.ExitCode -eq 0) { return $true }
step "llama.cpp" "existing build is incomplete; rebuilding" "Yellow"
return $false
}
if ($LlamaSource -ne "https://github.com/ggml-org/llama.cpp") {
step "llama.cpp" "custom source: $LlamaSource -- forcing source build" "Yellow"
$NeedLlamaSourceBuild = $true
$SkipPrebuiltInstall = $true
}
if (-not $LlamaPr -and $LlamaPrForce -and $LlamaPrForce -match '^\d+$' -and [int]$LlamaPrForce -gt 0) {
$LlamaPr = $LlamaPrForce
step "llama.cpp" "baked-in PR_FORCE=$LlamaPrForce" "Yellow"
}
if ($LlamaPr) {
if ($LlamaPr -notmatch '^\d+$' -or [int]$LlamaPr -le 0) {
Write-StudioLine "[ERROR] UNSLOTH_LLAMA_PR=$LlamaPr is not a valid PR number" -ForegroundColor Red
Exit-SetupFailure "UNSLOTH_LLAMA_PR=$LlamaPr is not a valid PR number"
}
step "llama.cpp" "UNSLOTH_LLAMA_PR=$LlamaPr -- will build from PR head" "Yellow"
$ResolvedLlamaTag = "pr-$LlamaPr"
$ResolvedSourceUrl = $LlamaSource
$ResolvedSourceRef = "pr-$LlamaPr"
$ResolvedSourceRefKind = "pull"
$NeedLlamaSourceBuild = $true
$SkipPrebuiltInstall = $true
}
$LocalLlamaCppLinked = $false
$LocalLlamaCppSrc = $env:UNSLOTH_LOCAL_LLAMA_CPP_DIR
if ($LocalLlamaCppSrc) {
# Unreadable is not missing.
$localSrcState = Get-PathState -Path $LocalLlamaCppSrc -PathType Container
if ($localSrcState -eq "Denied") {
Exit-PathAccessDenied -Path $LocalLlamaCppSrc -Label "the UNSLOTH_LOCAL_LLAMA_CPP_DIR directory" -UserSupplied
}
if ($localSrcState -ne "Present") {
step "llama.cpp" "UNSLOTH_LOCAL_LLAMA_CPP_DIR does not exist: $LocalLlamaCppSrc" "Red"
Exit-SetupFailure "UNSLOTH_LOCAL_LLAMA_CPP_DIR does not exist: $LocalLlamaCppSrc"
}
$ResolvedLocal = (Resolve-Path -LiteralPath $LocalLlamaCppSrc).Path
# A local dir disables prebuilt + source build, so accept any layout the backend resolves.
$LocalLlamaServerFound = $false
$LocalIsCanonical = ($ResolvedLocal -eq $LlamaCppDir)
foreach ($_cand in @(
(Join-Path $ResolvedLocal "llama-server.exe"),
(Join-Path $ResolvedLocal "build\bin\llama-server.exe"),
(Join-Path $ResolvedLocal "build\bin\Release\llama-server.exe"))) {
# Denied must not read as "nothing built here", or the prebuilt installer replaces the user's build.
$candState = Get-PathState -Path $_cand
if ($candState -eq "Denied") {
# -UserSupplied: never advise deleting the user's build.
Exit-PathAccessDenied -Path $ResolvedLocal -Label "the UNSLOTH_LOCAL_LLAMA_CPP_DIR build" -UserSupplied
}
if ($candState -eq "Present") { $LocalLlamaServerFound = $true; break }
}
if ($LocalIsCanonical) {
# Pointing at the canonical location: reuse an existing build, never link onto itself.
if ($LocalLlamaServerFound) {
substep "UNSLOTH_LOCAL_LLAMA_CPP_DIR is the canonical install location and already holds a build; reusing it" "Yellow"
$LocalLlamaCppLinked = $true
$NeedLlamaSourceBuild = $false
} else {
substep "UNSLOTH_LOCAL_LLAMA_CPP_DIR points to the canonical install location with nothing built there yet; running the normal install" "Yellow"
}
} else {
if (-not $LocalLlamaServerFound) {
step "llama.cpp" "no llama-server.exe under $ResolvedLocal (looked for .\llama-server.exe, .\build\bin and .\build\bin\Release) -- build llama.cpp there first, or drop --with-llama-cpp-dir" "Red"
Exit-SetupFailure "No llama-server.exe was found under $ResolvedLocal"
}
# Delete only the link: -Recurse can traverse a reparse point and wipe the real dir.
$existing = Get-Item -LiteralPath $LlamaCppDir -Force -ErrorAction SilentlyContinue
if ($existing -and ($existing.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
try { $existing.Delete() }
catch {
if (Test-AccessDeniedError $_) { Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" }
throw
}
}
if ($RuntimeRootIsCustom) {
Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom
}
$destState = Get-PathState -Path $LlamaCppDir
if ($destState -eq "Denied") {
Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install"
}
if ($destState -eq "Present") {
Remove-Item -Recurse -Force -LiteralPath $LlamaCppDir -ErrorAction SilentlyContinue
# A locked or denied tree can survive removal; do not link/copy over it.
if ((Get-PathState -Path $LlamaCppDir) -ne "Absent") {
step "llama.cpp" "install blocked; existing install could not be replaced" "Yellow"
substep "Close Unsloth or other llama.cpp users, or repair the ACLs on $LlamaCppDir, then retry" "Yellow"
Exit-SetupFailure "llama.cpp install is blocked; the existing install could not be replaced" 3
}
}
cmd /c "mklink /J `"$LlamaCppDir`" `"$ResolvedLocal`"" 2>&1 | Out-Null
if ($LASTEXITCODE -ne 0) {
substep "Could not create directory junction; copying instead..." "Yellow"
Copy-Item -Recurse -LiteralPath $ResolvedLocal -Destination $LlamaCppDir
Remove-AgentInstructionFiles -Roots @($LlamaCppDir)
}
Write-StudioLine ""
step "llama.cpp" "linked local directory: $ResolvedLocal"
$LocalLlamaCppLinked = $true
$NeedLlamaSourceBuild = $false
}
}
if ($LocalLlamaCppLinked) {
# local directory linked above; skip prebuilt install
} elseif ($explicitLlamaSourceBackend -and $NeedLlamaSourceBuild) {
Write-StudioLine ""
step "llama.cpp" "$explicitLlamaSourceBackend was explicitly requested, but this installation requires a source build" "Red"
substep "Explicit backend selection requires a matching prebuilt bundle; allow prebuilts or unset UNSLOTH_LLAMA_CPP_BACKEND" "Yellow"
Exit-SetupFailure "$explicitLlamaSourceBackend was explicitly requested, but this installation requires a source build. Explicit backend selection requires a matching prebuilt bundle."
} elseif ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
Write-StudioLine ""
substep "UNSLOTH_LLAMA_FORCE_COMPILE=1 -- skipping prebuilt llama.cpp install" "Yellow"
$NeedLlamaSourceBuild = $true
} elseif ($SkipPrebuiltInstall) {
Write-StudioLine ""
substep "Skipping prebuilt install -- falling back to source build" "Yellow"
} else {
Write-StudioLine ""
$llamaDirState = Get-LlamaCppInstallReadState -Path $LlamaCppDir
if ($llamaDirState -eq "Denied") {
Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$RuntimeRootIsCustom
}
if ($llamaDirState -eq "Readable") {
substep "Existing llama.cpp install detected -- validating staged prebuilt update before replacement"
$existingMetaPath = Join-Path $LlamaCppDir "UNSLOTH_PREBUILT_INFO.json"
if (Test-PathQuiet -Path $existingMetaPath -PathType Leaf) {
try {
$existingMeta = Get-Content -LiteralPath $existingMetaPath -Raw | ConvertFrom-Json
$existingKind = $existingMeta.install_kind
# windows-vulkan is in every branch, or a working Vulkan install is deleted every run.
# The VENV's arch, not the machine's.
$_arm64CudaOptOut = ("$env:UNSLOTH_LLAMA_ARM64_CUDA").Trim().ToLowerInvariant() -in @("0", "false", "no", "off")
$_nvidiaKinds = if (Test-WinArm64Venv) {
if ($_arm64CudaOptOut) { @("windows-arm64", "windows-vulkan") } else { @("windows-arm64-cuda", "windows-arm64", "windows-vulkan") }
} else { @("windows-cuda", "windows-vulkan") }
# A probe that did not answer is not evidence the GPU is gone.
$_woaEvidenceIndex = if ($WinArm64EffectiveTorchIndexUrl) { $WinArm64EffectiveTorchIndexUrl }
else {
$_p = Get-PinnedTorchIndexUrl
if ($_p) { ([string]$_p).Trim().TrimEnd('/') }
else {
$_m = Get-PersistedWoaTorchIndex -VenvPath $VenvDir
if ($_m) { $_m } else { Get-WoaTorchIndexMarker }
}
}
$_nvidiaEvidence = $HasNvidiaDriverEvidence -or ((Test-WinArm64Venv) -and $_woaEvidenceIndex -and
(Test-WoaPersistableIndex $_woaEvidenceIndex))
# No Windows ARM64 ROCm bundle, so include the CPU kind or the gate refetches every update.
$_rocmKinds = if (Test-WinArm64Venv) {
@("windows-rocm", "windows-hip", "windows-arm64", "windows-vulkan")
} else { @("windows-rocm", "windows-hip", "windows-vulkan") }
$expectedKinds = if ($HasROCm -or $script:ROCmGfxArch) { $_rocmKinds } elseif ($_nvidiaEvidence) { $_nvidiaKinds } else { @("windows-cpu", "windows-arm64", "windows-vulkan") }
if ($script:NvidiaDriverLibraryOnly) { $expectedKinds += $_nvidiaKinds }
# ARM64 Vulkan (a Vulkan GPU found, or UNSLOTH_LLAMA_CPP_BACKEND=vulkan) can land on any ARM64 host.
if (Test-WinArm64Venv) { $expectedKinds += "windows-arm64-vulkan" }
if ($existingKind -and ($existingKind -notin $expectedKinds)) {
substep "Removing mismatched llama.cpp install (found '$existingKind', need one of: $($expectedKinds -join ', '))..."
Remove-Item -Recurse -Force -LiteralPath $LlamaCppDir -ErrorAction SilentlyContinue
}
} catch {
# unreadable metadata -- let the installer handle it
}
}
}
substep "installing prebuilt llama.cpp bundle (preferred path)..."
# install_llama_prebuilt.py's os.replace() would displace a custom-home llama.cpp.
if ($RuntimeRootIsCustom) {
Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom
}
$prebuiltArgs = @(
"$PSScriptRoot\install_llama_prebuilt.py",
"--install-dir", $LlamaCppDir,
"--llama-tag", $RequestedLlamaTag,
"--published-repo", $HelperReleaseRepo
)
if ($HasROCm) {
$prebuiltArgs += "--has-rocm"
}
# --rocm-gfx implies ROCm, so the GPU prebuilt is picked with $HasROCm false.
if ($script:ROCmGfxArch) {
$prebuiltArgs += @("--rocm-gfx", $script:ROCmGfxArch)
}
if ($env:UNSLOTH_LLAMA_RELEASE_TAG) {
$prebuiltArgs += @("--published-release-tag", $env:UNSLOTH_LLAMA_RELEASE_TAG)
}
# Reporting only: the installer reads UNSLOTH_LLAMA_CPP_BACKEND itself; do not forward a copy.
$llamaBackend = $sourceLlamaBackend
if ($llamaBackend -eq "vulkan" -or $explicitLlamaSourceBackend -eq "vulkan") {
if ($IsMacOS) {
Write-StudioLine "[WARN] Vulkan has no effect on macOS; the universal build uses Metal" -ForegroundColor Yellow
} else {
Write-StudioLine " llama.cpp Vulkan selected for GGUF inference; the PyTorch training backend is unchanged" -ForegroundColor Cyan
}
} elseif ($llamaBackend -and $llamaBackend -notin @("auto", "cpu", "cuda", "hip", "rocm")) {
Write-StudioLine "[WARN] Ignoring UNSLOTH_LLAMA_CPP_BACKEND='$llamaBackend' (expected 'auto', 'cpu', 'cuda', 'vulkan', 'hip', or 'rocm')" -ForegroundColor Yellow
}
$prevEAPPrebuilt = $ErrorActionPreference
$ErrorActionPreference = "Continue"
$previousNativeErrorPreference = $null
$restoreNativeErrorPreference = $false
if ($PSVersionTable.PSVersion.Major -ge 7) {
$previousNativeErrorPreference = $PSNativeCommandUseErrorActionPreference
$PSNativeCommandUseErrorActionPreference = $false
$restoreNativeErrorPreference = $true
}
try {
if ($script:UnslothVerbose) {
$prebuiltLog = Join-Path $env:TEMP "unsloth-prebuilt-$PID.log"
& python @prebuiltArgs 2>&1 | Tee-Object -FilePath $prebuiltLog | Out-Host
$prebuiltExit = $LASTEXITCODE
$prebuiltOutput = if (Test-Path $prebuiltLog) { Get-Content $prebuiltLog -Raw } else { "" }
Remove-Item $prebuiltLog -ErrorAction SilentlyContinue
} else {
$prebuiltOutput = & python @prebuiltArgs 2>&1 | Show-DownloadProgress | Out-String
$prebuiltExit = $LASTEXITCODE
}
} finally {
if ($restoreNativeErrorPreference) {
$PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreference
}
}
$ErrorActionPreference = $prevEAPPrebuilt
if ($prebuiltExit -eq 0) {
if ($prebuiltOutput -match "already matches") {
step "llama.cpp" "prebuilt up to date and validated"
} elseif ($prebuiltOutput -match "keeping the existing complete install") {
# Exit 0 can also mean the existing tree was kept after a transient failure.
step "llama.cpp" "update unavailable, existing prebuilt kept" "Yellow"
} else {
step "llama.cpp" "prebuilt installed and validated"
}
if ($RuntimeRootIsCustom -and (Test-Path -LiteralPath $LlamaCppDir -PathType Container)) {
Mark-StudioOwned -Path $LlamaCppDir
}
$installedRelease = Get-InstalledLlamaPrebuiltRelease -InstallDir $LlamaCppDir
if ($installedRelease) {
substep $installedRelease
}
} elseif ($prebuiltExit -eq 3) {
# WinError 5 is both an in-use file and an ACL denial.
step "llama.cpp" "install blocked; existing install could not be replaced" "Yellow"
Write-LlamaFailureLog -Output $prebuiltOutput
if (Test-Path -LiteralPath $LlamaCppDir) {
substep "Existing install was restored" "Yellow"
}
if ($prebuiltOutput -match 'takeown /F') {
substep "Close Unsloth or other llama.cpp users, or repair the ACLs named above, then retry" "Yellow"
} else {
substep "Close Unsloth or other llama.cpp users and retry" "Yellow"
}
Exit-SetupFailure "llama.cpp install is blocked; the existing install could not be replaced" 3
} elseif ($prebuiltExit -eq 4) {
step "llama.cpp" "not enough disk space to install llama.cpp" "Yellow"
Write-LlamaFailureLog -Output $prebuiltOutput
substep "Free up disk or move UNSLOTH_STUDIO_HOME/TEMP to a larger volume, then re-run" "Yellow"
$PreservedLlamaServerFound = $false
foreach ($_cand in @(
(Join-Path $LlamaCppDir "llama-server.exe"),
(Join-Path $LlamaCppDir "build\bin\llama-server.exe"),
(Join-Path $LlamaCppDir "build\bin\Release\llama-server.exe"))) {
if (Test-PathQuiet $_cand) { $PreservedLlamaServerFound = $true; break }
}
if (-not $PreservedLlamaServerFound) { $script:LlamaCppDegraded = $true }
# Never report success on an unverified backend for an explicit request.
if ($explicitLlamaSourceBackend) {
step "llama.cpp" "$explicitLlamaSourceBackend was explicitly requested, so the installer will not keep an unverified existing backend" "Red"
Exit-SetupFailure "$explicitLlamaSourceBackend was explicitly requested, so the installer will not keep an unverified existing llama.cpp backend."
}
} elseif ($prebuiltExit -eq 5) {
step "llama.cpp" "selected backend could not be installed" "Red"
Write-LlamaFailureLog -Output $prebuiltOutput
if (Test-Path -LiteralPath $LlamaCppDir) {
substep "Existing install was restored" "Yellow"
}
substep "Check the error above, choose another backend, or retry" "Yellow"
Exit-SetupFailure "The selected llama.cpp backend could not be installed, so the installer will not substitute a different source backend."
} elseif ($prebuiltExit -eq 2) {
$keptBackend = Get-GpuPrebuiltToKeepOverSourceBuild -InstallDir $LlamaCppDir
if ($keptBackend) {
# The source fallback builds for CPU without a compute capability; keep a working GPU prebuilt.
$script:LlamaKeptGpuPrebuilt = $keptBackend
step "llama.cpp" "update failed ($(Get-LlamaUpdateFailReason $prebuiltOutput)); keeping the installed $keptBackend prebuilt, the next update will retry" "Yellow"
Write-LlamaFailureLog -Output $prebuiltOutput
} else {
step "llama.cpp" "prebuilt install failed" "Yellow"
Write-LlamaFailureLog -Output $prebuiltOutput
if (Test-Path -LiteralPath $LlamaCppDir) {
substep "Prebuilt update failed; existing install was restored or cleaned before source build fallback" "Yellow"
}
substep "Prebuilt llama.cpp path unavailable or failed validation -- falling back to source build" "Yellow"
$NeedLlamaSourceBuild = $true
$script:LlamaSourceBuildIsFallback = $true
}
} else {
step "llama.cpp" "prebuilt helper failed unexpectedly" "Red"
Write-LlamaFailureLog -Output $prebuiltOutput
if (Test-Path -LiteralPath $LlamaCppDir) {
substep "Existing install was restored or left unchanged" "Yellow"
}
substep "Source build was not started because it cannot repair an unexpected helper or permissions error" "Yellow"
Exit-SetupFailure "llama.cpp prebuilt helper failed unexpectedly (exit code $prebuiltExit). Check the error above and retry setup."
}
}
# ==========================================================================
# PHASE 3.4: Install the whisper.cpp prebuilt (dictation runtime)
# ==========================================================================
# Mirrors the llama.cpp prebuilt install above; current whisper releases are
# slim bundles that reuse the llama install's ggml runtime, so this runs after
# llama. Failure is never fatal: local dictation falls back to Transformers STT.
$WhisperCppDir = Join-Path $UnslothHome "whisper.cpp"
$WhisperInstaller = Join-Path $PSScriptRoot "install_whisper_prebuilt.py"
# A user-configured whisper binary/dir or an explicit skip disables the managed install entirely.
if ($env:WHISPER_SERVER_PATH -or $env:UNSLOTH_WHISPER_CPP_PATH) {
substep "whisper.cpp: using a user-configured binary/dir; skipping managed install"
} elseif ($env:UNSLOTH_SKIP_WHISPER_INSTALL -eq "1") {
substep "whisper.cpp: install skipped (UNSLOTH_SKIP_WHISPER_INSTALL=1)"
} elseif ($RuntimeRootIsCustom -and (Test-Path -LiteralPath $WhisperInstaller) -and
(Assert-StudioOwnedOrAbsent -Path $WhisperCppDir -Label "whisper.cpp install" -NonFatal -IsCustom $RuntimeRootIsCustom) -eq "Denied") {
# Never fatal: only the denial is caught here; an unowned tree still stops.
step "whisper.cpp" "install directory cannot be read: access is denied; curated whisper.cpp dictation is unavailable; restore access to $WhisperCppDir or move it aside, then re-run setup; browser and Transformers dictation remain available" "Yellow"
} elseif (Test-Path -LiteralPath $WhisperInstaller) {
# The installer replaces the whole directory, so the ownership guard runs first.
if ($RuntimeRootIsCustom) {
Assert-StudioOwnedOrAbsent -Path $WhisperCppDir -Label "whisper.cpp install" -IsCustom $RuntimeRootIsCustom
}
$whisperArgs = @($WhisperInstaller, "--install-dir", $WhisperCppDir)
if ($env:UNSLOTH_WHISPER_RELEASE_TAG) {
$whisperArgs += @("--published-release-tag", $env:UNSLOTH_WHISPER_RELEASE_TAG)
}
if ($script:ROCmGfxArch) {
$whisperArgs += @("--rocm-gfx", $script:ROCmGfxArch)
} elseif ($HasROCm) {
$whisperArgs += "--has-rocm"
}
$prevEAPWhisper = $ErrorActionPreference
$ErrorActionPreference = "Continue"
$previousNativeErrorPreferenceW = $null
$restoreNativeErrorPreferenceW = $false
if ($PSVersionTable.PSVersion.Major -ge 7) {
$previousNativeErrorPreferenceW = $PSNativeCommandUseErrorActionPreference
$PSNativeCommandUseErrorActionPreference = $false
$restoreNativeErrorPreferenceW = $true
}
try {
$whisperOutput = & python @whisperArgs 2>&1 | Show-DownloadProgress | Out-String
$whisperExit = $LASTEXITCODE
} finally {
if ($restoreNativeErrorPreferenceW) {
$PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreferenceW
}
}
$ErrorActionPreference = $prevEAPWhisper
if ($whisperExit -eq 0) {
if ($whisperOutput -match "already matches") {
step "whisper.cpp" "prebuilt up to date"
} elseif ($whisperOutput -match "keeping the existing complete install") {
step "whisper.cpp" "update unavailable, existing prebuilt kept" "Yellow"
} else {
step "whisper.cpp" "prebuilt installed"
}
if ($RuntimeRootIsCustom -and (Test-PathQuiet $WhisperCppDir "Container")) {
Mark-StudioOwned -Path $WhisperCppDir
}
} elseif ($whisperExit -eq 3) {
step "whisper.cpp" "install busy; keeping existing runtime" "Yellow"
} elseif ($whisperExit -eq 2) {
$requiredWhisperLlamaTag = "unknown"
if ($whisperOutput -match "slim bundle requires llama\.cpp ([^;\s]+)") {
$requiredWhisperLlamaTag = $Matches[1]
}
$installedWhisperLlamaTag = "unknown"
$llamaMarker = Join-Path $LlamaCppDir "UNSLOTH_PREBUILT_INFO.json"
if (Test-PathQuiet $llamaMarker "Leaf") {
try {
$markerPayload = Get-Content -LiteralPath $llamaMarker -Raw | ConvertFrom-Json
if ($markerPayload.release_tag) { $installedWhisperLlamaTag = $markerPayload.release_tag }
} catch {}
}
step "whisper.cpp" "no compatible prebuilt (installed llama.cpp $installedWhisperLlamaTag; whisper requires $requiredWhisperLlamaTag); curated whisper.cpp dictation is unavailable; publish paired releases in llama.cpp then whisper.cpp order; browser and Transformers dictation remain available" "Yellow"
} else {
step "whisper.cpp" "prebuilt install failed; curated whisper.cpp dictation is unavailable; retry setup or inspect verbose output; browser and Transformers dictation remain available" "Yellow"
}
}
# ==========================================================================
# ==========================================================================
# PHASE 3.4b: audio.cpp prebuilt. Self-contained bundles; failure is never fatal.
$AudioCppDir = Join-Path $UnslothHome "audio.cpp"
$AudioCppInstaller = Join-Path $PSScriptRoot "install_audio_cpp_prebuilt.py"
if ($env:AUDIOCPP_SERVER_PATH -or $env:UNSLOTH_AUDIO_CPP_PATH) {
substep "audio.cpp: using a user-configured binary/dir; skipping managed install"
} elseif ($env:UNSLOTH_SKIP_AUDIO_CPP_INSTALL -eq "1") {
substep "audio.cpp: install skipped (UNSLOTH_SKIP_AUDIO_CPP_INSTALL=1)"
} elseif ($RuntimeRootIsCustom -and (Test-Path -LiteralPath $AudioCppInstaller) -and
(Assert-StudioOwnedOrAbsent -Path $AudioCppDir -Label "audio.cpp install" -NonFatal -IsCustom $RuntimeRootIsCustom) -eq "Denied") {
step "audio.cpp" "install directory cannot be read: access is denied; audio.cpp models are unavailable; restore access to $AudioCppDir or move it aside, then re-run setup" "Yellow"
} elseif (Test-Path -LiteralPath $AudioCppInstaller) {
if ($RuntimeRootIsCustom) {
Assert-StudioOwnedOrAbsent -Path $AudioCppDir -Label "audio.cpp install" -IsCustom $RuntimeRootIsCustom
}
$audioCppArgs = @($AudioCppInstaller, "--install-dir", $AudioCppDir)
if ($env:UNSLOTH_AUDIO_CPP_ACCELERATOR) {
$audioCppArgs += @("--accelerator", $env:UNSLOTH_AUDIO_CPP_ACCELERATOR)
}
$prevEAPAudioCpp = $ErrorActionPreference
$ErrorActionPreference = "Continue"
$previousNativeErrorPreferenceA = $null
$restoreNativeErrorPreferenceA = $false
if ($PSVersionTable.PSVersion.Major -ge 7) {
$previousNativeErrorPreferenceA = $PSNativeCommandUseErrorActionPreference
$PSNativeCommandUseErrorActionPreference = $false
$restoreNativeErrorPreferenceA = $true
}
try {
$audioCppOutput = & python @audioCppArgs 2>&1 | Show-DownloadProgress | Out-String
$audioCppExit = $LASTEXITCODE
} finally {
if ($restoreNativeErrorPreferenceA) {
$PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreferenceA
}
}
$ErrorActionPreference = $prevEAPAudioCpp
if ($audioCppExit -eq 0) {
if ($audioCppOutput -match "already matches") {
step "audio.cpp" "prebuilt up to date"
} elseif ($audioCppOutput -match "keeping the existing complete install") {
step "audio.cpp" "update unavailable, existing prebuilt kept" "Yellow"
} else {
step "audio.cpp" "prebuilt installed"
}
if ($RuntimeRootIsCustom -and (Test-PathQuiet $AudioCppDir "Container")) {
Mark-StudioOwned -Path $AudioCppDir
}
} elseif ($audioCppExit -eq 3) {
step "audio.cpp" "install busy; keeping existing runtime" "Yellow"
} elseif ($audioCppOutput -match "cannot be read by this account") {
# An elevated run left it owned by Administrators (#14052); only an elevated shell can remove it.
step "audio.cpp" "$AudioCppDir is unreadable (left by an elevated run); in an elevated PowerShell run Remove-Item -Recurse -Force `"$AudioCppDir`", then unsloth studio update" "Yellow"
} else {
step "audio.cpp" "prebuilt install failed; audio.cpp models are unavailable; retry setup or inspect verbose output; other audio engines remain available" "Yellow"
}
}
if ($StageRoot -and $NeedLlamaSourceBuild) {
Exit-SetupFailure "Background staging cannot install system build tools for llama.cpp; retry with the foreground updater."
}
# A CMake build next to `tsc -b && vite build` can exhaust a host the overlap gate admitted.
if ($NeedLlamaSourceBuild) { Complete-FrontendBuildBackground }
# Asked before Phase 3.5: OpenSSL is a system install too.
$script:LlamaBuildToolsDeclined = $NeedLlamaSourceBuild -and $script:LlamaSourceBuildIsFallback -and (Test-LlamaBuildToolsMissing) -and
-not (Test-LlamaBuildToolsInstallAllowed)
# ==========================================================================
# PHASE 3.5: Install OpenSSL dev (for HTTPS support in llama-server)
# ==========================================================================
$OpenSslAvailable = $false
if ($NeedLlamaSourceBuild -and -not $script:LlamaBuildToolsDeclined) {
$OpenSslRoots = @(
'C:\Program Files\OpenSSL-Win64',
'C:\Program Files\OpenSSL',
'C:\OpenSSL-Win64'
)
$OpenSslRoot = $null
foreach ($root in $OpenSslRoots) {
if (Test-Path (Join-Path $root 'include\openssl\ssl.h')) {
$OpenSslRoot = $root
break
}
}
if ($OpenSslRoot) {
$OpenSslAvailable = $true
substep "OpenSSL dev found at $OpenSslRoot"
} elseif ($script:LlamaSourceBuildIsFallback -and -not (Test-LlamaBuildToolsInstallAllowed)) {
# Optional for the build, so it is skipped rather than declining the whole build.
substep "OpenSSL dev not found; building without HTTPS (UNSLOTH_INSTALL_BUILD_TOOLS=1 installs it)" "Yellow"
} else {
Write-StudioLine ""
substep "installing OpenSSL dev (for HTTPS in llama-server)..."
$HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
if ($HasWinget) {
# Optional: a winget that cannot launch (#13662) must not abort setup under EAP Stop.
try {
Invoke-SetupCommand { winget install -e --id ShiningLight.OpenSSL.Dev --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
} catch { }
# Re-check after install
foreach ($root in $OpenSslRoots) {
if (Test-Path (Join-Path $root 'include\openssl\ssl.h')) {
$OpenSslRoot = $root
$OpenSslAvailable = $true
substep "OpenSSL dev installed at $OpenSslRoot"
break
}
}
}
if (-not $OpenSslAvailable) {
substep "OpenSSL dev not available -- llama-server will be built without HTTPS" "Yellow"
}
}
} else {
substep "OpenSSL dev install skipped -- prebuilt llama.cpp already validated" "Yellow"
}
# ==========================================================================
# PHASE 4: Build llama.cpp from source
# ==========================================================================
$OriginalLlamaCppDir = $LlamaCppDir
$BuildDir = Join-Path $LlamaCppDir "build"
$LlamaServerBin = Join-Path $BuildDir "bin\Release\llama-server.exe"
$HasCmakeForBuild = $null -ne (Get-Command cmake -ErrorAction SilentlyContinue)
$HasGitForBuild = $null -ne (Get-Command git -ErrorAction SilentlyContinue)
$NeedRebuild = $false
# Forced or custom source builds skip the phase 3.4 guard, so this may be the first read of the tree.
$llamaBinState = if ($LocalLlamaCppLinked) { "Absent" } else { Get-PathState -Path $LlamaServerBin -PathType Leaf }
if ($llamaBinState -eq "Denied") {
# Nothing proved this tree is ours here, so do not advise deleting it.
Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$RuntimeRootIsCustom
}
if ($llamaBinState -eq "Present") {
$CmakeCacheFile = Join-Path $BuildDir "CMakeCache.txt"
if (Test-PathQuiet $CmakeCacheFile "Leaf") {
# A listed file can still deny the read, which Test-PathQuiet cannot see.
try {
$cachedCuda = Select-String -LiteralPath $CmakeCacheFile -Pattern 'GGML_CUDA:BOOL=ON' -Quiet
} catch {
if (-not (Test-AccessDeniedError $_)) { throw }
Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$RuntimeRootIsCustom
}
if ($HasNvidiaDriverEvidence -and -not $cachedCuda) {
Write-StudioLine " Existing llama-server is CPU-only but GPU is available -- rebuilding" -ForegroundColor Yellow
$NeedRebuild = $true
} elseif (-not $HasNvidiaDriverEvidence -and $cachedCuda) {
Write-StudioLine " Existing llama-server was built with CUDA but no GPU detected -- rebuilding" -ForegroundColor Yellow
$NeedRebuild = $true
}
}
}
# One predicate for the plan and the shortcut, so a refused tree also plans the toolchain.
$CanReuseLlamaBuild = (Test-PathQuiet $LlamaServerBin "Leaf") -and -not $NeedRebuild -and `
$RequestedLlamaTag -ne "master"
if ($CanReuseLlamaBuild -and $NeedLlamaSourceBuild -and -not $LocalLlamaCppLinked) {
$CanReuseLlamaBuild = Test-LlamaTreeStillHealthy $LlamaCppDir
}
$WillBuildLlamaFromSource = $NeedLlamaSourceBuild -and -not $CanReuseLlamaBuild
if ($script:LlamaBuildToolsDeclined -and -not $CanReuseLlamaBuild) { $WillBuildLlamaFromSource = $false }
if ($WillBuildLlamaFromSource) {
if (-not $HasGitForBuild) {
# Invoke-SetupCommand returns 0 for command-not-found, so a git-less clone misreports as cmake failure.
if ($null -ne (Get-Command winget -ErrorAction SilentlyContinue)) {
try {
Invoke-SetupCommand { winget install Git.Git --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
Refresh-Environment
} catch { }
}
$HasGitForBuild = $null -ne (Get-Command git -ErrorAction SilentlyContinue)
}
# Git first: Ensure-BuildToolsForLlamaSourceBuild exits setup when Build Tools cannot be installed.
if ($HasGitForBuild) {
Ensure-BuildToolsForLlamaSourceBuild
$HasCmakeForBuild = $null -ne (Get-Command cmake -ErrorAction SilentlyContinue)
}
}
if ($LocalLlamaCppLinked) {
# Honour the local-dir contract: skip BOTH prebuilt and source build.
Write-StudioLine ""
step "llama.cpp" "linked (skipping build)"
} elseif (-not $NeedLlamaSourceBuild) {
Write-StudioLine ""
step "llama.cpp" "prebuilt (validated)"
} elseif ($CanReuseLlamaBuild) {
# Skip rebuild only for pinned tags; "master" moves, so always rebuild.
Write-StudioLine ""
step "llama.cpp" "already built"
} elseif ($script:LlamaBuildToolsDeclined) {
Write-StudioLine ""
step "llama.cpp" "build skipped (build tools not installed)" "Yellow"
substep "The prebuilt download failed, and a source build needs Git, CMake and Visual Studio Build Tools." "Yellow"
substep "GGUF inference and export will not be available." "Yellow"
substep "To install them and build from source, set UNSLOTH_INSTALL_BUILD_TOOLS=1 and re-run setup." "Yellow"
$script:LlamaCppDegraded = $true
} elseif (-not $HasGitForBuild) {
# cmake may be missing only because git was; degrade rather than abort.
Write-StudioLine ""
step "llama.cpp" "build skipped (git not available)" "Yellow"
substep "The prebuilt download failed and a source build clones llama.cpp." "Yellow"
substep "GGUF inference and export will not be available." "Yellow"
substep "Install Git from https://git-scm.com/download/win and re-run setup." "Yellow"
$script:LlamaCppDegraded = $true
} elseif (-not $HasCmakeForBuild) {
Write-StudioLine ""
if (-not $HasNvidiaDriverEvidence) {
substep "CMake is required to build llama-server for GGUF chat mode." "Yellow"
substep "Continuing setup without llama.cpp build." "Yellow"
substep "Install CMake from https://cmake.org/download/ and re-run setup." "Yellow"
}
step "llama.cpp" "build skipped (cmake not available)" "Yellow"
substep "GGUF inference and export will not be available." "Yellow"
substep "Install CMake from https://cmake.org/download/ and re-run setup." "Yellow"
$script:LlamaCppDegraded = $true
} else {
# Finalize the VS generator before Resolve-CudaToolkit, which copies the CUDA .targets into it.
if ($CmakeGenerator -match 'Visual Studio 18\b') {
if (-not (Test-CmakeCanDriveGenerator -Generator $CmakeGenerator)) {
$cmakeVerObj = Get-CmakeVersion
$cmakeVerStr = if ($cmakeVerObj) { $cmakeVerObj.ToString() } else { '0.0' }
substep "CMake $cmakeVerStr cannot drive the Visual Studio 2026 generator (need 4.2+ or a VS-bundled cmake) -- updating via winget..." "Yellow"
if ($null -ne (Get-Command winget -ErrorAction SilentlyContinue)) {
try {
Invoke-SetupCommand { winget upgrade Kitware.CMake --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
Refresh-Environment
} catch { substep "CMake winget upgrade failed: $($_.Exception.Message)" "Yellow" }
Add-DefaultCmakeToPath | Out-Null
# upgrade no-ops for a Scoop/Chocolatey/VS cmake.
if (-not (Test-CmakeCanDriveGenerator -Generator $CmakeGenerator)) {
try {
Invoke-SetupCommand { winget install Kitware.CMake --source winget --accept-package-agreements --accept-source-agreements } | Out-Null
Refresh-Environment
} catch { substep "CMake winget install failed: $($_.Exception.Message)" "Yellow" }
Add-DefaultCmakeToPath | Out-Null
}
}
if (-not (Test-CmakeCanDriveGenerator -Generator $CmakeGenerator)) {
$fallback = Get-FallbackVsGenerator
if ($fallback) {
substep "CMake cannot drive $CmakeGenerator; falling back to $($fallback.Generator)" "Yellow"
$CmakeGenerator = $fallback.Generator
$VsInstallPath = $fallback.InstallPath
} else {
Write-StudioLine "[ERROR] CMake 4.2+ is required to build llama.cpp with the Visual Studio 2026 generator, and no older Visual Studio toolchain was found to fall back to." -ForegroundColor Red
Write-StudioLine " Upgrade CMake from https://cmake.org/download/ and re-run, or use a prebuilt llama.cpp bundle." -ForegroundColor Red
Exit-SetupFailure "CMake cannot drive the Visual Studio 2026 generator"
}
}
}
substep "CMake can drive the $CmakeGenerator generator"
}
if ($HasNvidiaDriverEvidence) { Resolve-CudaToolkit -RequireOrExit }
Write-StudioLine ""
if ($HasNvidiaDriverEvidence) {
substep "building llama.cpp with CUDA support..."
} elseif ($HasROCm -or $script:ROCmGfxArch) {
# A HIP source build needs the full HIP SDK.
$_amdArch = if ($script:ROCmGfxArch) { $script:ROCmGfxArch } else { "ROCm" }
substep "[WARN] AMD GPU ($_amdArch) detected, but the GPU-accelerated ROCm" "Yellow"
substep " llama.cpp prebuilt could not be installed -- falling back to a CPU build." "Yellow"
substep " The prebuilt is the AMD GPU path (no HIP SDK required). To restore GPU" "Yellow"
substep " acceleration: re-run the installer (check your network / proxy), or set" "Yellow"
substep " UNSLOTH_LLAMA_RELEASE_TAG to a tag with a gfx prebuilt for your GPU." "Yellow"
substep "building llama.cpp (CPU-only fallback)..." "Yellow"
} else {
substep "building llama.cpp (CPU-only, no NVIDIA GPU detected)..."
}
substep "This typically takes 5-10 minutes on first build."
Write-StudioLine ""
$totalSw = [System.Diagnostics.Stopwatch]::StartNew()
$prevEAP = $ErrorActionPreference
$ErrorActionPreference = "Continue"
$BuildOk = $true
$FailedStep = ""
# Refresh-Environment may have repopulated conflicting CUDA_PATH_V* from the registry.
if ($HasNvidiaDriverEvidence -and $CudaToolkitRoot) {
$cudaPathVars2 = @([Environment]::GetEnvironmentVariables('Process').Keys | Where-Object { $_ -match '^CUDA_PATH_V' })
foreach ($v2 in $cudaPathVars2) {
[Environment]::SetEnvironmentVariable($v2, $null, 'Process')
}
$tkDirName2 = Split-Path $CudaToolkitRoot -Leaf
if ($tkDirName2 -match '^v(\d+)\.(\d+)') {
[Environment]::SetEnvironmentVariable("CUDA_PATH_V$($Matches[1])_$($Matches[2])", $CudaToolkitRoot, 'Process')
}
[Environment]::SetEnvironmentVariable('CUDA_PATH', $CudaToolkitRoot, 'Process')
[Environment]::SetEnvironmentVariable('CudaToolkitDir', "$CudaToolkitRoot\", 'Process')
}
if (-not $LlamaPr) {
$ResolvedSourceUrl = $LlamaSource
if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
if ($RequestedLlamaTag -eq "latest") {
$ResolvedSourceRef = if ($env:UNSLOTH_LLAMA_FORCE_COMPILE_REF) {
$env:UNSLOTH_LLAMA_FORCE_COMPILE_REF
} else {
$DefaultLlamaForceCompileRef
}
$ResolvedSourceRefKind = "branch"
} else {
$ResolvedSourceRef = $RequestedLlamaTag
$ResolvedSourceRefKind = "tag"
}
} elseif ($RequestedLlamaTag -eq "latest") {
$resolveTagArgs = @("--resolve-llama-tag", "latest", "--published-repo", "ggml-org/llama.cpp", "--output-format", "json")
$resolveTagResult = Invoke-LlamaHelper -Arguments $resolveTagArgs
$resolveTagOutput = $resolveTagResult.Output
$resolveTagExit = $resolveTagResult.ExitCode
if ($resolveTagExit -eq 0 -and $resolveTagOutput) {
try {
$ResolvedSourceRef = (($resolveTagOutput | Out-String) | ConvertFrom-Json).llama_tag
} catch {
$ResolvedSourceRef = ""
}
} else {
$ResolvedSourceRef = ""
}
if ([string]::IsNullOrWhiteSpace($ResolvedSourceRef)) {
$ResolvedSourceRef = "latest"
}
$ResolvedSourceRefKind = "tag"
} else {
$ResolvedSourceRef = $RequestedLlamaTag
$ResolvedSourceRefKind = "tag"
}
if ([string]::IsNullOrWhiteSpace($ResolvedSourceUrl)) { $ResolvedSourceUrl = $LlamaSource }
if ([string]::IsNullOrWhiteSpace($ResolvedSourceRef)) { $ResolvedSourceRef = $RequestedLlamaTag }
}
# -- Step A: Clone or pull llama.cpp --
$UseConcreteRef = ($ResolvedSourceRef -ne "latest" -and -not [string]::IsNullOrWhiteSpace($ResolvedSourceRef))
# --depth 1 makes llama.cpp stamp build 1 (#12798); set only once the tag is checked out.
$TagBuildNumber = if ($ResolvedSourceRef -match '^b(\d+)$') { $Matches[1] } else { $null }
$LlamaBuildNumber = $null
# Denied must not read as "no checkout": the swap would half-delete an unreadable tree.
$llamaGitState = Get-PathState -Path (Join-Path $LlamaCppDir ".git")
if ($llamaGitState -eq "Denied") {
Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install"
}
if ($llamaGitState -eq "Present") {
# In-place git mutation rewrites $LlamaCppDir, so require ownership on a custom root.
if ($RuntimeRootIsCustom) {
Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom
}
Write-StudioLine " Syncing llama.cpp to $ResolvedSourceRef..." -ForegroundColor Gray
Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir remote set-url origin "$ResolvedSourceUrl.git" } | Out-Null
if ($LlamaPr) {
$gitFetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir fetch --depth 1 origin "pull/$LlamaPr/head" }
if ($gitFetchExit -ne 0) {
$BuildOk = $false
$FailedStep = "git fetch PR #$LlamaPr"
} else {
$gitCheckoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir checkout -B "pr-$LlamaPr" FETCH_HEAD }
if ($gitCheckoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout PR #$LlamaPr"
} else {
Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir clean -fdx } | Out-Null
}
}
} elseif ($ResolvedSourceRefKind -eq "pull") {
$gitFetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir fetch --depth 1 origin $ResolvedSourceRef }
if ($gitFetchExit -ne 0) {
substep "git fetch failed -- using existing source" "Yellow"
} else {
$gitCheckoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir checkout -B unsloth-llama-build FETCH_HEAD }
if ($gitCheckoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout"
} else {
Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir clean -fdx } | Out-Null
}
}
} elseif ($ResolvedSourceRefKind -eq "commit") {
$gitFetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir fetch --depth 1 origin $ResolvedSourceRef }
if ($gitFetchExit -ne 0) {
substep "git fetch failed -- using existing source" "Yellow"
} else {
$gitCheckoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir checkout -B unsloth-llama-build FETCH_HEAD }
if ($gitCheckoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout"
} else {
Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir clean -fdx } | Out-Null
}
}
} elseif ($UseConcreteRef) {
$gitFetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir fetch --depth 1 origin $ResolvedSourceRef }
if ($gitFetchExit -ne 0) {
substep "git fetch failed -- using existing source" "Yellow"
} else {
$gitCheckoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir checkout -B unsloth-llama-build FETCH_HEAD }
if ($gitCheckoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout"
} else {
Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir clean -fdx } | Out-Null
$LlamaBuildNumber = $TagBuildNumber
}
}
} else {
$gitFetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir fetch --depth 1 origin }
if ($gitFetchExit -ne 0) {
substep "git fetch failed -- using existing source" "Yellow"
} else {
$gitCheckoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir checkout -B unsloth-llama-build FETCH_HEAD }
if ($gitCheckoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout"
} else {
Invoke-SetupCommand -AlwaysQuiet { git -C $LlamaCppDir clean -fdx } | Out-Null
}
}
}
# Mark the tree, else a later Assert-StudioOwnedOrAbsent exits.
if ($BuildOk -and $RuntimeRootIsCustom) {
Mark-StudioOwned -Path $LlamaCppDir
}
} else {
Write-StudioLine " Cloning llama.cpp @ $ResolvedSourceRef..." -ForegroundColor Gray
$buildTmp = "$LlamaCppDir.build.$PID"
$null = [System.IO.Directory]::CreateDirectory((Split-Path -LiteralPath $LlamaCppDir))
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
if ($LlamaPr) {
$cloneExit = Invoke-SetupCommand -AlwaysQuiet { git clone --depth 1 "$LlamaSource.git" $buildTmp }
if ($cloneExit -ne 0) {
$BuildOk = $false
$FailedStep = "git clone"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
if ($BuildOk) {
$fetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $buildTmp fetch --depth 1 origin "pull/$LlamaPr/head:pr-$LlamaPr" }
if ($fetchExit -ne 0) {
$BuildOk = $false
$FailedStep = "git fetch PR #$LlamaPr"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
}
if ($BuildOk) {
$checkoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $buildTmp checkout "pr-$LlamaPr" }
if ($checkoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout PR #$LlamaPr"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
}
} elseif ($ResolvedSourceRefKind -eq "pull") {
$cloneExit = Invoke-SetupCommand -AlwaysQuiet { git clone --depth 1 "$ResolvedSourceUrl.git" $buildTmp }
if ($cloneExit -ne 0) {
$BuildOk = $false
$FailedStep = "git clone"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
if ($BuildOk) {
$fetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $buildTmp fetch --depth 1 origin $ResolvedSourceRef }
if ($fetchExit -ne 0) {
$BuildOk = $false
$FailedStep = "git fetch source PR ref"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
}
if ($BuildOk) {
$checkoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $buildTmp checkout -B unsloth-llama-build FETCH_HEAD }
if ($checkoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout source PR ref"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
}
} elseif ($ResolvedSourceRefKind -eq "commit") {
$cloneExit = Invoke-SetupCommand -AlwaysQuiet { git clone --depth 1 "$ResolvedSourceUrl.git" $buildTmp }
if ($cloneExit -ne 0) {
$BuildOk = $false
$FailedStep = "git clone"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
if ($BuildOk) {
$fetchExit = Invoke-SetupCommand -AlwaysQuiet { git -C $buildTmp fetch --depth 1 origin $ResolvedSourceRef }
if ($fetchExit -ne 0) {
$BuildOk = $false
$FailedStep = "git fetch source commit"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
}
if ($BuildOk) {
$checkoutExit = Invoke-SetupCommand -AlwaysQuiet { git -C $buildTmp checkout -B unsloth-llama-build FETCH_HEAD }
if ($checkoutExit -ne 0) {
$BuildOk = $false
$FailedStep = "git checkout source commit"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
}
}
} else {
$cloneArgs = @("clone", "--depth", "1")
if ($UseConcreteRef) {
$cloneArgs += @("--branch", $ResolvedSourceRef)
}
$cloneArgs += @("$ResolvedSourceUrl.git", $buildTmp)
$cloneExit = Invoke-SetupCommand -AlwaysQuiet { git @cloneArgs }
if ($cloneExit -ne 0) {
$BuildOk = $false
$FailedStep = "git clone"
if (Test-Path -LiteralPath $buildTmp) { Remove-Item -LiteralPath $buildTmp -Recurse -Force }
} elseif ($UseConcreteRef) {
$LlamaBuildNumber = $TagBuildNumber
}
}
if ($BuildOk) {
$LlamaCppDir = $buildTmp
$BuildDir = Join-Path $LlamaCppDir "build"
}
}
# -- Step B: cmake configure --
if ($BuildOk) {
Write-StudioLine ""
Write-StudioLine "--- cmake configure ---" -ForegroundColor Cyan
$CmakeArgs = @(
'-S', $LlamaCppDir,
'-B', $BuildDir,
'-G', $CmakeGenerator,
'-Wno-dev'
)
if ($VsInstallPath) {
$CmakeArgs += "-DCMAKE_GENERATOR_INSTANCE=$VsInstallPath"
}
$CmakeArgs += '-DBUILD_SHARED_LIBS=OFF'
$CmakeArgs += '-DLLAMA_BUILD_TESTS=OFF'
$CmakeArgs += '-DLLAMA_BUILD_EXAMPLES=OFF'
$CmakeArgs += '-DLLAMA_BUILD_SERVER=ON'
$CmakeArgs += '-DGGML_NATIVE=ON'
if ($LlamaBuildNumber) {
$CmakeArgs += "-DLLAMA_BUILD_NUMBER=$LlamaBuildNumber"
}
# HTTPS support via OpenSSL
if ($OpenSslAvailable -and $OpenSslRoot) {
$CmakeArgs += "-DOPENSSL_ROOT_DIR=$OpenSslRoot"
$CmakeArgs += '-DLLAMA_OPENSSL=ON'
} else {
$CmakeArgs += '-DLLAMA_CURL=OFF'
}
$CmakeArgs += '-DCMAKE_EXE_LINKER_FLAGS=/NODEFAULTLIB:LIBCMT'
if ($HasNvidiaDriverEvidence -and $NvccPath) {
$CudaArchOverride = if ($env:UNSLOTH_LLAMA_CUDA_ARCHS) { ($env:UNSLOTH_LLAMA_CUDA_ARCHS -replace '\s', '') } else { '' }
if ((-not $CudaArch) -and (-not $CudaArchOverride)) {
# -DGGML_CUDA=ON with no arch builds PTX-only.
substep "could not detect a CUDA compute capability; building CPU llama.cpp instead of a PTX-only binary (set UNSLOTH_LLAMA_CUDA_ARCHS=120 to force a CUDA build)." "Yellow"
$CmakeArgs += '-DGGML_CUDA=OFF'
} else {
$CmakeArgs += '-DGGML_CUDA=ON'
if (Test-CudaDriverNeedsUncompressedFatbin -DriverMaxCuda $script:DriverMaxCuda) {
$CmakeArgs += '-DGGML_CUDA_COMPRESSION_MODE=none'
substep "driver CUDA $script:DriverMaxCuda predates 12.4; building uncompressed CUDA kernels it can load." "Yellow"
}
# Accept a host MSVC newer than nvcc's whitelist, which would otherwise abort.
$nvccAllowFlag = '-allow-unsupported-compiler'
if ([string]::IsNullOrEmpty($env:NVCC_PREPEND_FLAGS)) {
$env:NVCC_PREPEND_FLAGS = $nvccAllowFlag
} elseif ($env:NVCC_PREPEND_FLAGS -notlike "*$nvccAllowFlag*") {
$env:NVCC_PREPEND_FLAGS = "$($env:NVCC_PREPEND_FLAGS) $nvccAllowFlag"
}
substep "NVCC_PREPEND_FLAGS = $env:NVCC_PREPEND_FLAGS"
$CmakeArgs += "-DCUDAToolkit_ROOT=$CudaToolkitRoot"
$CmakeArgs += "-DCUDA_TOOLKIT_ROOT_DIR=$CudaToolkitRoot"
$CmakeArgs += "-DCMAKE_CUDA_COMPILER=$NvccPath"
if ($CudaArchOverride) {
$CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$CudaArchOverride"
} elseif ($CudaArch) {
if (Test-NvccArchSupport -NvccExe $NvccPath -Arch $CudaArch) {
$CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$CudaArch"
} else {
# Arch too new for this toolkit: use the highest supported (PTX JITs).
$maxArch = Get-NvccMaxArch -NvccExe $NvccPath
if ($maxArch) {
$CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$maxArch"
substep "GPU is sm_$CudaArch but nvcc only supports up to sm_$maxArch" "Yellow"
substep "Building with sm_$maxArch (PTX will JIT for your GPU at runtime)" "Yellow"
}
}
}
}
} else {
$CmakeArgs += '-DGGML_CUDA=OFF'
}
$cmakeOutput = cmake @CmakeArgs 2>&1 | Out-String
$cmakeConfigureExit = $LASTEXITCODE
if ($cmakeConfigureExit -ne 0) {
$BuildOk = $false
$FailedStep = "cmake configure"
Write-LlamaFailureLog -Output $cmakeOutput
if ($cmakeOutput -match 'No CUDA toolset found|CUDA_TOOLKIT_ROOT_DIR|nvcc') {
Write-StudioLine ""
Write-StudioLine " Hint: CUDA VS integration may be missing. Try running as admin:" -ForegroundColor Yellow
Write-StudioLine " Copy contents of:" -ForegroundColor Yellow
Write-StudioLine " <CUDA_PATH>\extras\visual_studio_integration\MSBuildExtensions" -ForegroundColor Yellow
Write-StudioLine " into:" -ForegroundColor Yellow
$hintCustomizations = if ($VsInstallPath) { Get-VcBuildCustomizationsDir -VsInstallPath $VsInstallPath -Generator $CmakeGenerator } else { "<VS_PATH>\MSBuild\Microsoft\VC\v170\BuildCustomizations" }
Write-StudioLine " $hintCustomizations" -ForegroundColor Yellow
}
}
}
# -- Step C: Build llama-server --
$NumCpu = Get-LlamaBuildJobs
if ($BuildOk) {
Write-StudioLine ""
Write-StudioLine "--- cmake build (llama-server) ---" -ForegroundColor Cyan
Write-StudioLine " Parallel jobs: $NumCpu of $([Environment]::ProcessorCount) cores (RAM-capped; UNSLOTH_LLAMA_BUILD_JOBS overrides)" -ForegroundColor Gray
Write-StudioLine ""
$output = cmake --build $BuildDir --config Release --target llama-server -j $NumCpu 2>&1 | Out-String
$cmakeBuildServerExit = $LASTEXITCODE
if ($cmakeBuildServerExit -ne 0) {
$BuildOk = $false
$FailedStep = "cmake build (llama-server)"
Write-LlamaFailureLog -Output $output
}
}
# -- Step D: Build llama-quantize (optional, best-effort) --
if ($BuildOk) {
Write-StudioLine ""
Write-StudioLine "--- cmake build (llama-quantize) ---" -ForegroundColor Cyan
$output = cmake --build $BuildDir --config Release --target llama-quantize -j $NumCpu 2>&1 | Out-String
$cmakeBuildQuantizeExit = $LASTEXITCODE
if ($cmakeBuildQuantizeExit -ne 0) {
substep "llama-quantize build failed (GGUF export may be unavailable)" "Yellow"
Write-LlamaFailureLog -Output $output
}
}
# -- Step E: Build the DiffusionGemma visual server (optional, best-effort) --
if ($BuildOk) {
$null = cmake --build $BuildDir --config Release --target llama-diffusion-gemma-visual-server -j $NumCpu 2>&1 | Out-String
}
# -- Step F: llama-bench (best-effort) --
if ($BuildOk) {
$null = cmake --build $BuildDir --config Release --target llama-bench -j $NumCpu 2>&1 | Out-String
}
# Swap temp build dir into final location (only if we built in a temp dir)
if ($BuildOk -and $LlamaCppDir -ne $OriginalLlamaCppDir) {
Assert-StudioOwnedOrAbsent -Path $OriginalLlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom
if ((Get-PathState -Path $OriginalLlamaCppDir) -ne "Absent") {
Remove-Item -LiteralPath $OriginalLlamaCppDir -Recurse -Force -ErrorAction SilentlyContinue
# Unreadable or locked leftovers would make Move-Item nest the build inside them.
$swapState = Get-PathState -Path $OriginalLlamaCppDir
if ($swapState -eq "Denied") {
Exit-PathAccessDenied -Path $OriginalLlamaCppDir -Label "llama.cpp install"
}
if ($swapState -ne "Absent") {
step "llama.cpp" "could not replace the existing install at $OriginalLlamaCppDir" "Red"
substep "Part of it survived removal; the new build is intact at $LlamaCppDir" "Yellow"
substep "Close Unsloth and other llama.cpp users, or move that folder aside, then re-run setup" "Yellow"
Exit-SetupFailure "llama.cpp install at $OriginalLlamaCppDir could not be replaced; the new build is at $LlamaCppDir" 3
}
}
Move-Item -LiteralPath $LlamaCppDir -Destination $OriginalLlamaCppDir
# A failed move is non-terminating too.
if ((Get-PathState -Path $LlamaCppDir) -ne "Absent") {
step "llama.cpp" "could not move the new build into $OriginalLlamaCppDir" "Red"
Exit-SetupFailure "llama.cpp build at $LlamaCppDir could not be moved into $OriginalLlamaCppDir" 3
}
$LlamaCppDir = $OriginalLlamaCppDir
$BuildDir = Join-Path $LlamaCppDir "build"
$LlamaServerBin = Join-Path $BuildDir "bin\Release\llama-server.exe"
Mark-StudioOwned -Path $LlamaCppDir
} elseif (-not $BuildOk -and $LlamaCppDir -ne $OriginalLlamaCppDir) {
if (Test-Path -LiteralPath $LlamaCppDir) { Remove-Item -LiteralPath $LlamaCppDir -Recurse -Force }
$LlamaCppDir = $OriginalLlamaCppDir
$BuildDir = Join-Path $LlamaCppDir "build"
$LlamaServerBin = Join-Path $BuildDir "bin\Release\llama-server.exe"
}
$ErrorActionPreference = $prevEAP
$totalSw.Stop()
$totalMin = [math]::Floor($totalSw.Elapsed.TotalMinutes)
$totalSec = [math]::Round($totalSw.Elapsed.TotalSeconds % 60, 1)
# -- Summary --
if ($BuildOk -and (Test-PathQuiet $LlamaServerBin "Leaf")) {
step "llama.cpp" "built"
$QuantizeBin = Join-Path $BuildDir "bin\Release\llama-quantize.exe"
if (Test-PathQuiet $QuantizeBin "Leaf") {
step "llama-quantize" "built"
}
step "build time" "${totalMin}m ${totalSec}s" "DarkGray"
} else {
$altBin = Join-Path $BuildDir "bin\llama-server.exe"
if ($BuildOk -and (Test-PathQuiet $altBin "Leaf")) {
step "llama.cpp" "built"
step "build time" "${totalMin}m ${totalSec}s" "DarkGray"
} else {
step "llama.cpp" "build failed at: $FailedStep (${totalMin}m ${totalSec}s); continuing" "Yellow"
substep "To retry: delete $LlamaCppDir and re-run setup." "Yellow"
$script:LlamaCppDegraded = $true
}
}
}
$llamaCppItem = Get-Item -LiteralPath $LlamaCppDir -Force -ErrorAction SilentlyContinue
$llamaCppIsLink = $llamaCppItem -and ($llamaCppItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)
if (-not $llamaCppIsLink -and (
-not $RuntimeRootIsCustom -or
(Test-PathQuiet (Join-Path $LlamaCppDir $StudioOwnedMarker) "Leaf") -or
(Test-StudioOwnedAdoptable $LlamaCppDir)
)) {
Remove-AgentInstructionFiles -Roots @($LlamaCppDir)
}
Complete-FrontendBuildBackground
# ── Precompile bytecode ── (opt-in: a whole-venv compile per update cost more than lazy compile on import; never fatal)
$_pycPython = Join-Path $VenvDir 'Scripts\python.exe'
$_pycHelper = Join-Path $PSScriptRoot 'precompile_bytecode.py'
$_pycSwitches = @(@($env:UV_COMPILE_BYTECODE, $env:UNSLOTH_STUDIO_COMPILE_BYTECODE) |
Where-Object { $_ } | ForEach-Object { $_.Trim().ToLowerInvariant() })
$_pycOptedOut = @($_pycSwitches | Where-Object { @('0', 'false', 'no', 'off') -contains $_ }).Count -gt 0
$_pycOptedIn = @($_pycSwitches | Where-Object { @('1', 'true', 'yes', 'on') -contains $_ }).Count -gt 0
if (($script:SetupVenvChanged -or $env:UNSLOTH_SETUP_RERUN -eq '1') -and $_pycOptedIn -and -not $_pycOptedOut -and
(Test-Path -LiteralPath $_pycPython -PathType Leaf) -and
(Test-Path -LiteralPath $_pycHelper -PathType Leaf)) {
step "python" "precompiling bytecode..."
$_pycPrevExit = $global:LASTEXITCODE
$_pycPrevEAP = $ErrorActionPreference
$ErrorActionPreference = 'Continue'
try { & $_pycPython -I $_pycHelper } catch { } finally { $ErrorActionPreference = $_pycPrevEAP }
$global:LASTEXITCODE = $_pycPrevExit
}
# ─────────────────────────────────────────────
# Footer
# ─────────────────────────────────────────────
$DoneLabel = if ($env:SKIP_STUDIO_BASE -eq "1") { "Unsloth Studio Setup Complete" } else { "Unsloth Studio Updated" }
if ($script:StudioVtOk -and -not $env:NO_COLOR) {
Write-StudioLine (" {0}{1}{2}" -f (Get-StudioAnsi Dim), $Rule, (Get-StudioAnsi Reset))
if ($script:LlamaCppDegraded) {
Write-StudioLine (" " + (Get-StudioAnsi Warn) + "$DoneLabel (limited: llama.cpp unavailable)" + (Get-StudioAnsi Reset))
} else {
Write-StudioLine (" " + (Get-StudioAnsi Title) + $DoneLabel + (Get-StudioAnsi Reset))
}
Write-StudioLine (" {0}{1}{2}" -f (Get-StudioAnsi Dim), $Rule, (Get-StudioAnsi Reset))
} else {
Write-StudioLine " $Rule" -ForegroundColor DarkGray
if ($script:LlamaCppDegraded) {
Write-StudioLine " $DoneLabel (limited: llama.cpp unavailable)" -ForegroundColor Yellow
} else {
Write-StudioLine " $DoneLabel" -ForegroundColor Green
}
Write-StudioLine " $Rule" -ForegroundColor DarkGray
}
if ($script:LlamaKeptGpuPrebuilt) {
step "llama.cpp" "update failed; the installed $($script:LlamaKeptGpuPrebuilt) prebuilt was kept and the next update will retry" "Yellow"
}
step "launch" "unsloth studio -p 8888"
substep "(add -H 0.0.0.0 for LAN / cloud access; exposes the raw port only, not a public URL)"
substep "(add -H 0.0.0.0 --cloudflare for a public Cloudflare HTTPS link, or --secure to keep the raw port private; anyone with the API key can run code)"
Write-StudioLine ""
# Non-zero for degraded llama.cpp only under install.ps1; 'studio update' stays successful.
if ($script:LlamaCppDegraded -and $env:SKIP_STUDIO_BASE -eq "1") {
# Tauri mode reports instead of aborting, as setup.sh does: a non-zero exit fails the whole install.
# [TAURI:PROGRESS], not [TAURI:STEP], which would push the step counter past INSTALL_STEPS.
if (@("1", "true") -contains $env:UNSLOTH_TAURI_MODE) {
[Console]::Out.WriteLine("[TAURI:PROGRESS] llama.cpp unavailable; GGUF inference is disabled until 'unsloth studio update' succeeds")
[Console]::Out.WriteLine("[TAURI:DIAG] llama_cpp=unavailable")
[Console]::Out.Flush()
} elseif ($script:LlamaBuildToolsDeclined) {
step "llama.cpp" "unavailable; GGUF inference is disabled until the build tools are installed" "Yellow"
} else {
Exit-SetupFailure "llama.cpp setup did not produce a usable server"
}
}
# A desktop repair runs update.rs, which sets UNSLOTH_TAURI_UPDATE alone, so the block above
# is skipped and a degraded repair recorded nothing. Marker only: the update stays successful.
if ($script:LlamaCppDegraded -and $env:SKIP_STUDIO_BASE -ne "1" -and
(@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE)) {
[Console]::Out.WriteLine("[TAURI:DIAG] llama_cpp=unavailable")
[Console]::Out.Flush()
}
Remove-WoaMergedOverrides