Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Windows on ARM: install the native ARM64 CUDA stack on NVIDIA hosts (#10282)

Daniel Hanb535eca250ae
diff --git a/.github/scripts/repack_sqlite_vec.py b/.github/scripts/repack_sqlite_vec.py
new file mode 100644
index 00000000000..142bd3b5e95
--- /dev/null
+++ b/.github/scripts/repack_sqlite_vec.py
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+"""Repack the PyPI sqlite-vec win_amd64 wheel with an ARM64 vec0.dll under the win_arm64 tag.
+
+The wheel is pure Python plus one DLL, generated upstream by sqlite-dist: replacing the DLL,
+the WHEEL tag and RECORD is the whole port. Usage: repack_sqlite_vec.py <amd64 wheel> <vec0.dll> <out dir>
+"""
+import base64, hashlib, struct, sys, zipfile
+from pathlib import Path
+
+src, dll, out = Path(sys.argv[1]), Path(sys.argv[2]), Path(sys.argv[3])
+assert src.name.endswith("-py3-none-win_amd64.whl"), src.name
+dst = out / src.name.replace("-win_amd64.whl", "-win_arm64.whl")
+
+data = dll.read_bytes()
+e_lfanew = struct.unpack_from("<I", data, 0x3C)[0]
+assert data[e_lfanew : e_lfanew + 4] == b"PE\0\0", "not a PE file"
+machine = struct.unpack_from("<H", data, e_lfanew + 4)[0]
+assert machine == 0xAA64, f"vec0.dll machine is {machine:#x}, not ARM64 (0xaa64)"
+
+def record_line(name: str, blob: bytes) -> str:
+ digest = base64.urlsafe_b64encode(hashlib.sha256(blob).digest()).rstrip(b"=").decode()
+ return f"{name},sha256={digest},{len(blob)}"
+
+out.mkdir(parents = True, exist_ok = True)
+with zipfile.ZipFile(src) as zin, zipfile.ZipFile(dst, "w", zipfile.ZIP_DEFLATED) as zout:
+ names = zin.namelist()
+ record_name = next(n for n in names if n.endswith(".dist-info/RECORD"))
+ lines = []
+ for name in names:
+ if name == record_name:
+ continue
+ blob = zin.read(name)
+ if name.endswith("/vec0.dll"):
+ blob = data
+ elif name.endswith(".dist-info/WHEEL"):
+ text = blob.decode()
+ assert "Tag: py3-none-win_amd64" in text, text
+ blob = text.replace("Tag: py3-none-win_amd64", "Tag: py3-none-win_arm64").encode()
+ zout.writestr(name, blob)
+ lines.append(record_line(name, blob))
+ lines.append(f"{record_name},,")
+ zout.writestr(record_name, "\n".join(lines) + "\n")
+print(dst.name, dst.stat().st_size, "bytes")
diff --git a/.github/scripts/sign_wheel_binaries.py b/.github/scripts/sign_wheel_binaries.py
new file mode 100644
index 00000000000..26378f18681
--- /dev/null
+++ b/.github/scripts/sign_wheel_binaries.py
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Authenticode-sign the native binaries inside a wheel and repack it.
+
+A .whl cannot itself be Authenticode signed: it is a zip, and Windows has no subject
+interface package for one. What CAN be signed are the PE images inside it -- the .pyd
+extension modules and the .dll files they link -- which is what Windows actually loads and
+what SmartScreen and an enterprise WDAC policy judge. So this unpacks the wheel, signs each
+PE we built, and packs it back under the same filename.
+
+RECORD is regenerated, because it has to be: signing appends a certificate table, so every
+signed member's sha256 and length change, and a wheel whose RECORD disagrees with its
+contents is one `pip check`, `uv pip install --strict` or reproducibility audit away from
+being called corrupt.
+
+Files that already carry a certificate are left alone. delvewheel vendors Microsoft's own
+redistributables (msvcp140.dll and friends) into pyarrow, already signed by Microsoft;
+re-signing those would replace their signature with ours and claim authorship of somebody
+else's binary.
+
+The signing itself is delegated, never reimplemented: --signer names the command, and CI
+passes studio/src-tauri/windows/sign-with-trusted-signing.ps1, the same helper the desktop
+release uses, so the endpoint, the identity and the Azure retry policy have one definition.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+#: IMAGE_FILE_MACHINE_ARM64. The wheels this signs are win_arm64.
+MACHINE_ARM64 = 0xAA64
+#: Data directory index 4 is the Certificate Table -- a non-zero size means "already signed".
+CERTIFICATE_TABLE_INDEX = 4
+
+
+def _pe_header_offset(blob: bytes) -> "int | None":
+ """Offset of the PE signature, or None when this is not a PE image at all."""
+ if len(blob) < 0x40 or blob[:2] != b"MZ":
+ return None
+ try:
+ offset = struct.unpack_from("<I", blob, 0x3C)[0]
+ except struct.error:
+ return None
+ if offset <= 0 or offset + 24 > len(blob) or blob[offset : offset + 4] != b"PE\0\0":
+ return None
+ return offset
+
+
+def pe_machine(blob: bytes) -> "int | None":
+ """The COFF machine type, or None when the bytes are not a PE image."""
+ offset = _pe_header_offset(blob)
+ if offset is None:
+ return None
+ return struct.unpack_from("<H", blob, offset + 4)[0]
+
+
+def is_signed(blob: bytes) -> bool:
+ """Does this PE image already carry a certificate table?
+
+ Read from the optional header's data directory rather than by running a tool, so the
+ answer does not depend on a Windows host or on the file being unpacked first.
+ """
+ offset = _pe_header_offset(blob)
+ if offset is None:
+ return False
+ magic_at = offset + 24
+ if magic_at + 2 > len(blob):
+ return False
+ magic = struct.unpack_from("<H", blob, magic_at)[0]
+ # PE32+ has 8 more bytes of fixed fields before the data directory than PE32 does.
+ directory_at = magic_at + (112 if magic == 0x20B else 96) + CERTIFICATE_TABLE_INDEX * 8
+ if directory_at + 8 > len(blob):
+ return False
+ _, size = struct.unpack_from("<II", blob, directory_at)
+ return size > 0
+
+
+def record_line(name: str, blob: bytes) -> str:
+ """One RECORD row: urlsafe base64 sha256 with the padding stripped, per PEP 376."""
+ digest = base64.urlsafe_b64encode(hashlib.sha256(blob).digest()).rstrip(b"=").decode()
+ return f"{name},sha256={digest},{len(blob)}"
+
+
+def sign_file(path: Path, signer: "list[str]") -> None:
+ """Run the signing command over one file, failing the build if it cannot sign."""
+ result = subprocess.run([*signer, str(path)], text = True)
+ if result.returncode != 0:
+ raise SystemExit(f"signing failed for {path.name} (exit {result.returncode})")
+
+
+def sign_wheel(
+ wheel: Path,
+ out_dir: Path,
+ signer: "list[str]",
+ *,
+ require_machine: "int | None" = MACHINE_ARM64,
+) -> "tuple[Path, list[str], list[str]]":
+ """Sign every unsigned PE inside `wheel` and write the result into `out_dir`.
+
+ Returns (written wheel, names signed, names skipped as already signed).
+ """
+ out_dir.mkdir(parents = True, exist_ok = True)
+ destination = out_dir / wheel.name
+ signed: list[str] = []
+ skipped: list[str] = []
+
+ with tempfile.TemporaryDirectory() as scratch:
+ work = Path(scratch)
+ with zipfile.ZipFile(wheel) as archive:
+ names = archive.namelist()
+ payload = {name: archive.read(name) for name in names}
+
+ for name in names:
+ blob = payload[name]
+ machine = pe_machine(blob)
+ if machine is None:
+ continue
+ if require_machine is not None and machine != require_machine:
+ raise SystemExit(
+ f"{wheel.name}: {name} is machine {machine:#x}, not {require_machine:#x}"
+ )
+ if is_signed(blob):
+ skipped.append(name)
+ continue
+ # Signed on disk under its own name: signtool and trusted-signing-cli both work
+ # in place, and the suffix decides which subject interface package is used.
+ staged = work / Path(name).name
+ staged.write_bytes(blob)
+ sign_file(staged, signer)
+ resigned = staged.read_bytes()
+ if not is_signed(resigned):
+ raise SystemExit(f"{wheel.name}: {name} has no certificate after signing")
+ payload[name] = resigned
+ signed.append(name)
+ staged.unlink()
+
+ if not signed and not skipped:
+ raise SystemExit(f"{wheel.name}: no PE images found -- nothing to sign")
+
+ record_name = next((n for n in names if n.endswith(".dist-info/RECORD")), None)
+ if record_name is None:
+ raise SystemExit(f"{wheel.name}: no .dist-info/RECORD")
+
+ # Member order preserved: the installer does not care, but a diff between the signed
+ # and unsigned wheel should show the signatures and nothing else.
+ with zipfile.ZipFile(destination, "w", zipfile.ZIP_DEFLATED) as out:
+ lines = []
+ for name in names:
+ if name == record_name:
+ continue
+ out.writestr(name, payload[name])
+ lines.append(record_line(name, payload[name]))
+ lines.append(f"{record_name},,")
+ out.writestr(record_name, "\n".join(lines) + "\n")
+
+ return destination, signed, skipped
+
+
+def main(argv: "list[str] | None" = None) -> int:
+ parser = argparse.ArgumentParser(description = __doc__)
+ parser.add_argument("wheels", nargs = "+", type = Path)
+ parser.add_argument("--out", required = True, type = Path)
+ parser.add_argument(
+ "--signer",
+ required = True,
+ help = "signing command; the file to sign is appended as the last argument",
+ )
+ parser.add_argument(
+ "--expect-machine",
+ default = "arm64",
+ choices = ("arm64", "any"),
+ help = "refuse a wheel carrying a PE for another architecture (default: arm64)",
+ )
+ args = parser.parse_args(argv)
+
+ import shlex
+
+ signer = shlex.split(args.signer, posix = False)
+ require = MACHINE_ARM64 if args.expect_machine == "arm64" else None
+ failures = 0
+ for wheel in args.wheels:
+ written, signed, skipped = sign_wheel(wheel, args.out, signer, require_machine = require)
+ print(f"{written.name}: signed {len(signed)}, already signed {len(skipped)}")
+ for name in signed:
+ print(f" signed {name}")
+ for name in skipped:
+ print(f" kept {name} (already carries a certificate)")
+ if not signed:
+ print(f"::warning::{wheel.name} had nothing to sign")
+ failures += 1
+ return 1 if failures and len(args.wheels) == failures else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/.github/workflows/windows-arm64-ci.yml b/.github/workflows/windows-arm64-ci.yml
new file mode 100644
index 00000000000..09dc630b6d5
--- /dev/null
+++ b/.github/workflows/windows-arm64-ci.yml
@@ -0,0 +1,167 @@
+# The native Windows on ARM install path, run on Windows on ARM: wheel-tag arithmetic, path handling and
+# PowerShell parsing, none of which fails the same way on x64. No GPU, CUDA or compiler, so a full install or a Tauri build is out of scope (ring and aws-lc-sys need clang for their aarch64 sources).
+name: Windows ARM64 CI
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'install.ps1'
+ - 'scripts/uninstall.ps1'
+ - 'scripts/uninstall.sh'
+ - 'studio/install_python_stack.py'
+ - 'studio/setup.ps1'
+ - 'pyproject.toml'
+ - 'studio/backend/requirements/**'
+ - 'tests/studio/install/test_woa_wheelhouse_prefers_pypi.py'
+ - 'tests/studio/install/test_woa_wheelhouse_guard_behaviour.py'
+ - 'tests/studio/install/test_woa_torch_index_persistence.py'
+ - 'tests/studio/install/test_diffusers_pin.py'
+ - 'tests/python/test_windows_arm64_wheelhouse_tags.py'
+ - 'tests/studio/test_uninstall_arg_guard.ps1'
+ - 'tests/studio/test_uninstall_dual_install_icon.ps1'
+ - 'tests/studio/test_uninstall_prebuilt_parity.ps1'
+ - 'tests/studio/test_uninstall_reparse_stop_roots.ps1'
+ - '.github/workflows/windows-arm64-ci.yml'
+ pull_request:
+ paths:
+ - 'install.ps1'
+ - 'scripts/uninstall.ps1'
+ - 'scripts/uninstall.sh'
+ - 'studio/install_python_stack.py'
+ - 'studio/setup.ps1'
+ - 'pyproject.toml'
+ - 'studio/backend/requirements/**'
+ - 'tests/studio/install/test_woa_wheelhouse_prefers_pypi.py'
+ - 'tests/studio/install/test_woa_wheelhouse_guard_behaviour.py'
+ - 'tests/studio/install/test_woa_torch_index_persistence.py'
+ - 'tests/studio/install/test_diffusers_pin.py'
+ - 'tests/python/test_windows_arm64_wheelhouse_tags.py'
+ - 'tests/studio/test_uninstall_arg_guard.ps1'
+ - 'tests/studio/test_uninstall_dual_install_icon.ps1'
+ - 'tests/studio/test_uninstall_prebuilt_parity.ps1'
+ - 'tests/studio/test_uninstall_reparse_stop_roots.ps1'
+ - '.github/workflows/windows-arm64-ci.yml'
+ workflow_dispatch:
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+ contents: read
+
+jobs:
+ woa:
+ # Free for public repositories since 2025-08-07; a fork on a private plan fails to start.
+ runs-on: windows-11-arm
+ timeout-minutes: 40
+ strategy:
+ fail-fast: false
+ matrix:
+ # Both shells: pwsh 7 is what CI has always run, and Windows PowerShell 5.1 is the only shell on a stock Windows box, which the CLI launches setup.ps1 with (see #8335).
+ powershell: [pwsh-7, windows-powershell-5.1]
+ name: woa (${{ matrix.powershell }})
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+
+ - name: The runner really is ARM64
+ shell: pwsh
+ run: |
+ $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
+ $proc = [System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture
+ # Machine scope: an x64-emulated process reports AMD64 in its own environment block.
+ $machine = [Environment]::GetEnvironmentVariable(
+ "PROCESSOR_ARCHITECTURE", [EnvironmentVariableTarget]::Machine)
+ Write-Host "OSArchitecture=$arch ProcessArchitecture=$proc machine=$machine"
+ if ("$arch" -ne "Arm64") {
+ Write-Host "::error::this job is not running on ARM64 (OSArchitecture=$arch)"
+ exit 1
+ }
+
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+ # Required: the image ships an emulated x64 Python whose sysconfig says win-amd64.
+ architecture: 'arm64'
+
+ - name: The interpreter really is ARM64
+ shell: pwsh
+ run: |
+ python -c "import platform, sysconfig, sys; print(sys.version); print('machine', platform.machine()); print('platform', sysconfig.get_platform())"
+ python -c "import sysconfig, sys; p = sysconfig.get_platform(); sys.exit(0 if p == 'win-arm64' else (print(f'::error::sysconfig reports {p}, expected win-arm64') or 1))"
+
+ - run: python -m pip install -U pip pytest packaging
+
+ # 5.1 has no `pwsh` on PATH and the suites locate their shell with shutil.which("pwsh"), so without this they SKIP and report green. A copy, because CreateProcess will not run a .cmd.
+ - name: Put Windows PowerShell 5.1 on PATH as pwsh
+ if: matrix.powershell == 'windows-powershell-5.1'
+ shell: pwsh
+ run: |
+ $dir = Join-Path $env:RUNNER_TEMP "wps51"
+ New-Item -ItemType Directory -Path $dir -Force | Out-Null
+ $src = Join-Path $env:SystemRoot "System32\WindowsPowerShell\v1.0\powershell.exe"
+ if (-not (Test-Path -LiteralPath $src)) {
+ Write-Host "::error::Windows PowerShell 5.1 was not found at $src"
+ exit 1
+ }
+ Copy-Item -LiteralPath $src -Destination (Join-Path $dir "pwsh.exe") -Force
+ "$dir" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+ - name: Which PowerShell the suites will use
+ shell: pwsh
+ run: |
+ $exe = (Get-Command pwsh).Source
+ $ver = & $exe -NoProfile -Command '$PSVersionTable.PSVersion.ToString()'
+ Write-Host "pwsh resolves to $exe (version $ver)"
+ $wanted = if ("${{ matrix.powershell }}" -eq "pwsh-7") { "7" } else { "5" }
+ if (-not $ver.StartsWith($wanted)) {
+ Write-Host "::error::expected PowerShell $wanted.x for this row, got $ver"
+ exit 1
+ }
+
+ # A skip is a failure here: these files exist for this row, and -rs only REPORTS skipped cases, so the summary line is read back and any skipped count fails the step.
+ - name: WoA installer and wheelhouse tests
+ shell: pwsh
+ env:
+ UNSLOTH_NO_TORCH: '1'
+ run: |
+ & python -m pytest `
+ tests/studio/install/test_woa_wheelhouse_prefers_pypi.py `
+ tests/studio/install/test_woa_wheelhouse_guard_behaviour.py `
+ tests/studio/install/test_woa_torch_index_persistence.py `
+ tests/studio/install/test_diffusers_pin.py `
+ tests/python/test_windows_arm64_wheelhouse_tags.py `
+ -q -rs 2>&1 | Tee-Object -Variable pytestOut
+ $rc = $LASTEXITCODE
+ $summary = ($pytestOut | Where-Object { $_ -match '\d+ (passed|failed|error)' } | Select-Object -Last 1)
+ if ($rc -ne 0) { exit $rc }
+ if ($summary -match '(\d+) skipped') {
+ Write-Host "::error::$($Matches[1]) test(s) skipped on the row they exist for: $summary"
+ exit 1
+ }
+
+ - name: Uninstaller tests
+ shell: pwsh
+ run: |
+ $failed = @()
+ foreach ($t in @(
+ "test_uninstall_arg_guard",
+ "test_uninstall_dual_install_icon",
+ "test_uninstall_prebuilt_parity",
+ "test_uninstall_reparse_stop_roots"
+ )) {
+ $path = "tests/studio/$t.ps1"
+ if (-not (Test-Path -LiteralPath $path)) { continue }
+ Write-Host "::group::$t"
+ & (Get-Command pwsh).Source -NoProfile -File $path
+ $code = $LASTEXITCODE
+ Write-Host "::endgroup::"
+ if ($code -ne 0) { $failed += "$t (exit $code)" }
+ }
+ if ($failed.Count -gt 0) {
+ Write-Host "::error::failing uninstaller tests: $($failed -join ', ')"
+ exit 1
+ }
diff --git a/.github/workflows/woa-wheelhouse.yml b/.github/workflows/woa-wheelhouse.yml
new file mode 100644
index 00000000000..49383c5b98a
--- /dev/null
+++ b/.github/workflows/woa-wheelhouse.yml
@@ -0,0 +1,634 @@
+# The Windows on ARM wheelhouse: build, SIGN and publish the two win_arm64 wheels the
+# native ARM64 installer cannot get anywhere else.
+#
+# pyarrow -- mandatory. `datasets` imports it, and PyPI has published no win_arm64 wheel
+# in any release (apache/arrow#48539 adds the CI support and is still open).
+# Its sdist needs Arrow C++, vcpkg and the MSVC ARM64 toolchain, which is
+# ~45 min on this runner and flatly out of reach on a user's machine.
+# sqlite-vec -- optional (RAG). PyPI ships one py3-none-win_amd64 wheel: pure Python plus a
+# single x64 vec0.dll. The port is that DLL rebuilt for ARM64.
+#
+# Signed, because these are the only binaries in the stack we produce ourselves. Everything
+# else on that install comes from PyPI or from NVIDIA. An unsigned .pyd we host and tell the
+# installer to fetch is the weakest link in the chain, and Authenticode is what Windows,
+# SmartScreen and a WDAC policy actually check. The procedure is release-desktop.yml's,
+# unchanged: the digest-pinned trusted-signing-cli, sign-with-trusted-signing.ps1, and the
+# release-signing environment gating the Azure secrets.
+#
+# A .whl cannot be Authenticode signed (a zip has no subject interface package), so what is
+# signed is every PE inside it; sign_wheel_binaries.py repacks and regenerates RECORD.
+#
+# Dispatch only. This holds signing credentials and writes a release, so it must never be
+# reachable from a pull request, and `publish: false` is the default: a run then builds,
+# signs and verifies, and leaves the wheels as artifacts to inspect.
+name: Windows on ARM wheelhouse
+
+on:
+ workflow_dispatch:
+ inputs:
+ arrow_tag:
+ description: "apache/arrow tag to build pyarrow from"
+ default: "apache-arrow-25.0.1"
+ sqlite_vec_tag:
+ description: "asg017/sqlite-vec tag"
+ default: "v0.1.9"
+ release_tag:
+ description: "release tag to publish under"
+ default: "Windows-ARM64"
+ publish:
+ description: "upload to the release (otherwise artifacts only)"
+ type: boolean
+ default: false
+
+permissions:
+ contents: read
+
+concurrency:
+ group: woa-wheelhouse-${{ github.ref }}
+ cancel-in-progress: false
+
+env:
+ # Windows ARM64 support in Arrow's wheel build is CI-only and still unmerged, so it is
+ # overlaid onto the release tag. Both halves move together or not at all.
+ ARROW_WOA_REPO: MugundanMCW/arrow
+ ARROW_WOA_REF: Pyarrow_WoA
+
+jobs:
+ build-pyarrow:
+ name: pyarrow win_arm64 / cp${{ matrix.python }}
+ runs-on: windows-11-arm
+ timeout-minutes: 300
+ strategy:
+ fail-fast: false
+ matrix:
+ python: ['3.11', '3.12', '3.13', '3.14']
+ env:
+ CMAKE_BUILD_TYPE: release
+ ARCH: ARM64
+ steps:
+ - name: Harden runner (audit)
+ uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@v4
+ with:
+ repository: apache/arrow
+ ref: ${{ inputs.arrow_tag }}
+ path: arrow
+
+ - uses: actions/checkout@v4
+ with:
+ repository: ${{ env.ARROW_WOA_REPO }}
+ ref: ${{ env.ARROW_WOA_REF }}
+ path: arrow-woa
+ sparse-checkout: |
+ ci/scripts
+ ci/vcpkg
+ sparse-checkout-cone-mode: false
+
+ # Every edit below asserts on the text it replaces, so an upstream rename fails this
+ # step rather than silently producing an x64 wheel with an arm64 filename.
+ - name: Overlay the ARM64 build support onto the release tag
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ Copy-Item arrow-woa/ci/scripts/python_wheel_windows_build.bat arrow/ci/scripts/ -Force
+ Copy-Item arrow-woa/ci/scripts/python_wheel_windows_test.bat arrow/ci/scripts/ -Force
+
+ $json = 'arrow/ci/vcpkg/vcpkg.json'
+ $t = Get-Content $json -Raw
+ $edits = @(
+ @('"supports": "x64 | (arm64 & !windows)"', '"supports": "x64 | arm64"'),
+ @(" `"xsimd`",", " {`n `"name`": `"xsimd`",`n `"platform`": `"!(arm64 & windows)`"`n },")
+ )
+ foreach ($e in $edits) {
+ if (-not $t.Contains($e[0])) { throw "vcpkg.json no longer contains: $($e[0])" }
+ $t = $t.Replace($e[0], $e[1])
+ }
+ Set-Content $json -Value $t -Encoding ascii -NoNewline
+ python -c "import json; json.load(open('$json'))"
+
+ # The upstream script hardcodes VS 2022 Enterprise and its generator. This image
+ # moves to VS 2026, so both come from the installed toolset instead.
+ $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+ $vs = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.ARM64 -property installationPath
+ if (-not $vs) { throw 'no Visual Studio with the ARM64 C++ tools' }
+ $major = [int]((& $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.ARM64 -property installationVersion) -split '\.')[0]
+ $generator = switch ($major) { 17 { 'Visual Studio 17 2022' } 18 { 'Visual Studio 18 2026' } default { throw "unknown Visual Studio major $major" } }
+ $bat = 'arrow/ci/scripts/python_wheel_windows_build.bat'
+ $b = Get-Content $bat -Raw
+ $edits = @(
+ @('set VCVARS_BAT=C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsarm64.bat', "set VCVARS_BAT=$vs\VC\Auxiliary\Build\vcvarsarm64.bat"),
+ @('set CMAKE_GENERATOR=Visual Studio 17 2022', "set CMAKE_GENERATOR=$generator")
+ )
+ foreach ($e in $edits) {
+ if (-not $b.Contains($e[0])) { throw "build.bat no longer contains: $($e[0])" }
+ $b = $b.Replace($e[0], $e[1])
+ }
+ Set-Content $bat -Value $b -Encoding ascii
+ if (-not (Test-Path "$vs\VC\Auxiliary\Build\vcvarsarm64.bat")) { throw "no vcvarsarm64.bat under $vs" }
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python }}
+ architecture: arm64
+
+ - name: Python build dependencies
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ python -c "import sys, sysconfig; print(sys.version, sysconfig.get_platform())"
+ python -m pip install --upgrade pip
+ python -m pip install -r arrow/python/requirements-wheel-build.txt
+ "PYTHON_CMD=$env:pythonLocation\python.exe" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
+ - name: Version from the C++ tree
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $cm = Get-Content arrow/cpp/CMakeLists.txt -Raw
+ if ($cm -notmatch 'set\(ARROW_VERSION "([0-9.]+)(-SNAPSHOT)?"\)') { throw 'no ARROW_VERSION' }
+ $v = $Matches[1]; if ($Matches[2]) { $v = "$v.dev${{ github.run_number }}" }
+ Write-Host "pyarrow version: $v"
+ "SETUPTOOLS_SCM_PRETEND_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
+ # Trimmed to what `datasets` reaches: this removes gRPC and the cloud SDKs from the
+ # vcpkg build entirely, which is most of the wall clock and most of the attack surface.
+ - name: Trim the build to what datasets needs
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $bat = 'arrow/ci/scripts/python_wheel_windows_build.bat'
+ $t = Get-Content $bat -Raw
+ foreach ($flag in 'ARROW_AZURE','ARROW_FLIGHT','ARROW_GCS','ARROW_HDFS','ARROW_ORC','ARROW_S3','ARROW_SUBSTRAIT','ARROW_TENSORFLOW','ARROW_WITH_OPENTELEMETRY') {
+ $before = $t
+ $t = $t -replace "set $flag=ON", "set $flag=OFF"
+ if ($t -eq $before) { throw "did not find 'set $flag=ON'" }
+ }
+ Set-Content $bat -Value $t -Encoding ascii
+ Select-String -Path $bat -Pattern '^set ARROW_' | ForEach-Object { $_.Line }
+
+ - name: Cache vcpkg packages
+ uses: actions/cache@v4
+ with:
+ path: C:\vcpkg\installed
+ key: vcpkg-arm64-static-md-trimmed-${{ inputs.arrow_tag }}-${{ hashFiles('arrow/ci/vcpkg/vcpkg.json') }}
+ restore-keys: |
+ vcpkg-arm64-static-md-trimmed-${{ inputs.arrow_tag }}-
+ vcpkg-arm64-static-md-trimmed-
+
+ # Retried: the ports fetch source tarballs from archive.apache.org and friends, and one
+ # timed-out download fails the whole step. Packages already built survive an attempt.
+ - name: vcpkg dependencies (base + json + parquet)
+ shell: cmd
+ run: |
+ cd arrow\ci\vcpkg
+ set attempt=0
+ :again
+ set /a attempt+=1
+ C:\vcpkg\vcpkg.exe install ^
+ --triplet arm64-windows-static-md ^
+ --x-install-root=C:\vcpkg\installed ^
+ --x-manifest-root=. ^
+ --x-feature=json ^
+ --x-feature=parquet && exit /B 0
+ if %attempt% GEQ 3 exit /B 1
+ echo vcpkg install failed, attempt %attempt% of 3; retrying in 60s
+ timeout /t 60 /nobreak >nul
+ goto again
+
+ - name: Build Arrow C++ and the pyarrow wheel
+ shell: cmd
+ run: |
+ call "arrow\ci\scripts\python_wheel_windows_build.bat"
+
+ # A win_arm64 filename says nothing about what was linked in, so every native image is
+ # opened and its COFF machine checked before anything downstream trusts the wheel.
+ - name: Verify the wheel is really ARM64
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $whl = Get-ChildItem arrow/python/repaired_wheels/*.whl | Select-Object -First 1
+ Write-Host "wheel: $($whl.Name) ($([math]::Round($whl.Length/1MB)) MB)"
+ if ($whl.Name -notmatch '-win_arm64\.whl$') { throw "not a win_arm64 wheel: $($whl.Name)" }
+ python -c @"
+ import struct, sys, zipfile
+ z = zipfile.ZipFile(sys.argv[1]); bad = []; n = 0
+ for name in z.namelist():
+ if not name.lower().endswith(('.pyd', '.dll')): continue
+ d = z.read(name); off = struct.unpack_from('<I', d, 0x3C)[0]
+ machine = struct.unpack_from('<H', d, off + 4)[0]; n += 1
+ if machine != 0xAA64: bad.append((name, hex(machine)))
+ print(n, 'native images, all ARM64' if not bad else bad)
+ sys.exit(1 if bad or n == 0 else 0)
+ "@ $whl.FullName
+ if ($LASTEXITCODE -ne 0) { exit 1 }
+
+ - name: Smoke test in a fresh venv
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $whl = Get-ChildItem arrow/python/repaired_wheels/*.whl | Select-Object -First 1
+ python -m venv smoke
+ smoke\Scripts\python.exe -m pip install --quiet $whl.FullName numpy
+ smoke\Scripts\python.exe -c @"
+ import pyarrow as pa, pyarrow.parquet as pq, pyarrow.dataset as ds, pyarrow.compute as pc, pyarrow.csv, pyarrow.json, sysconfig
+ print('pyarrow', pa.__version__, sysconfig.get_platform())
+ t = pa.table({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})
+ pq.write_table(t, 'smoke.parquet')
+ back = pq.read_table('smoke.parquet')
+ assert back.equals(t), back
+ print('sum a =', pc.sum(back['a']).as_py())
+ print('dataset rows =', ds.dataset('smoke.parquet').count_rows())
+ print('compression:', [c for c in ('snappy','zstd','lz4','brotli','gzip','bz2') if pa.Codec.is_available(c)])
+ "@
+ if ($LASTEXITCODE -ne 0) { exit 1 }
+
+ # The reason the wheel exists at all, so it is a gate and not a nice-to-have.
+ - name: Does datasets work on it
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ smoke\Scripts\python.exe -m pip install --quiet datasets
+ smoke\Scripts\python.exe -c @"
+ from datasets import Dataset
+ d = Dataset.from_dict({'text': ['hello', 'world'], 'n': [1, 2]})
+ d = d.map(lambda r: {'len': len(r['text'])})
+ d.to_parquet('ds.parquet')
+ print('datasets round-trip ok:', Dataset.from_parquet('ds.parquet').to_dict())
+ "@
+ if ($LASTEXITCODE -ne 0) { exit 1 }
+
+ - uses: actions/upload-artifact@v4
+ with:
+ name: unsigned-pyarrow-cp${{ matrix.python }}
+ path: arrow/python/repaired_wheels/*.whl
+ if-no-files-found: error
+
+ build-sqlite-vec:
+ name: sqlite-vec win_arm64
+ runs-on: windows-11-arm
+ timeout-minutes: 30
+ steps:
+ - name: Harden runner (audit)
+ uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@v4
+ with:
+ repository: asg017/sqlite-vec
+ ref: ${{ inputs.sqlite_vec_tag }}
+ path: sv
+ fetch-depth: 0
+
+ - uses: actions/checkout@v4
+ with:
+ path: tools
+ sparse-checkout: |
+ .github/scripts
+ sparse-checkout-cone-mode: false
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.13'
+ architecture: arm64
+
+ # scripts/vendor.sh without the unzip dependency. The amalgamation URL is read from
+ # that script rather than hardcoded here, so the tag decides which sqlite is vendored.
+ - name: Vendor the sqlite amalgamation
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $vendor = Get-Content sv/scripts/vendor.sh -Raw
+ if ($vendor -notmatch '(https://www\.sqlite\.org/\d{4}/sqlite-amalgamation-\d+\.zip)') {
+ throw "could not read the amalgamation URL out of scripts/vendor.sh"
+ }
+ $url = $Matches[1]
+ Write-Host "amalgamation: $url"
+ Invoke-WebRequest -Uri $url -OutFile amalgamation.zip -UseBasicParsing -MaximumRetryCount 3 -RetryIntervalSec 5
+ Expand-Archive amalgamation.zip -DestinationPath amalgamation
+ New-Item -ItemType Directory -Force -Path sv/vendor | Out-Null
+ Get-ChildItem amalgamation/*/* | Move-Item -Destination sv/vendor
+ Get-ChildItem sv/vendor
+
+ - name: Generate sqlite-vec.h from its template
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ Set-Location sv
+ $version = (Get-Content VERSION -Raw).Trim()
+ $parts = $version.Split('.')
+ $source = (git log -n 1 --pretty=format:%H -- VERSION)
+ $date = (git log -n 1 --pretty=format:%cI -- VERSION)
+ $h = Get-Content sqlite-vec.h.tmpl -Raw
+ $h = $h.Replace('${VERSION}', $version).Replace('${DATE}', $date).Replace('${SOURCE}', $source)
+ $h = $h.Replace('${VERSION_MAJOR}', $parts[0]).Replace('${VERSION_MINOR}', $parts[1]).Replace('${VERSION_PATCH}', ($parts[2] -split '-')[0])
+ if ($h -match '\$\{') { throw "unreplaced placeholder in sqlite-vec.h" }
+ Set-Content sqlite-vec.h -Value $h -Encoding ascii
+ "SQLITE_VEC_VERSION=$version" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
+ - name: Locate the ARM64 MSVC environment
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+ $vs = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.ARM64 -property installationPath
+ if (-not $vs) { $vs = & $vswhere -latest -products * -property installationPath }
+ $bat = Join-Path $vs 'VC\Auxiliary\Build\vcvarsarm64.bat'
+ if (-not (Test-Path $bat)) { throw "no vcvarsarm64.bat under $vs" }
+ Write-Host "vcvars: $bat"
+ "VCVARS_BAT=$bat" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
+ # The upstream release workflow's own cl line, run natively for arm64.
+ - name: Compile vec0.dll for ARM64
+ shell: cmd
+ run: |
+ call "%VCVARS_BAT%" || exit /B 1
+ cd sv
+ mkdir dist
+ cl.exe /nologo /W4 /O2 /LD /Ivendor sqlite-vec.c /Fe:dist\vec0.dll || exit /B 1
+ dir dist
+
+ # The PyPI wheel is pure Python plus that one DLL, generated by sqlite-dist, so the
+ # port is a DLL swap, a tag rewrite and a regenerated RECORD -- not a rebuild.
+ - name: Repack the PyPI wheel with the ARM64 DLL
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ python -m pip download --quiet --no-deps --only-binary=:all: --platform win_amd64 --python-version 3.13 -d amd64 "sqlite-vec==$env:SQLITE_VEC_VERSION"
+ $src = Get-ChildItem amd64/*.whl | Select-Object -First 1
+ python tools/.github/scripts/repack_sqlite_vec.py $src.FullName sv/dist/vec0.dll wheel
+ Get-ChildItem wheel
+
+ - name: Load it through sqlite3 and run a vec0 query
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $whl = Get-ChildItem wheel/*.whl | Select-Object -First 1
+ python -m venv smoke
+ smoke\Scripts\python.exe -m pip install --quiet $whl.FullName
+ smoke\Scripts\python.exe -c @"
+ import sqlite3, sqlite_vec, sysconfig
+ print('platform', sysconfig.get_platform(), 'sqlite', sqlite3.sqlite_version)
+ db = sqlite3.connect(':memory:')
+ db.enable_load_extension(True)
+ sqlite_vec.load(db)
+ db.enable_load_extension(False)
+ print('vec_version', db.execute('select vec_version()').fetchone()[0])
+ db.execute('create virtual table v using vec0(embedding float[4])')
+ for rid, vec in [(1, [1, 0, 0, 0]), (2, [0, 1, 0, 0]), (3, [0.9, 0.1, 0, 0])]:
+ db.execute('insert into v(rowid, embedding) values (?, ?)', (rid, sqlite_vec.serialize_float32(vec)))
+ got = db.execute('select rowid, distance from v where embedding match ? order by distance limit 2', (sqlite_vec.serialize_float32([1, 0, 0, 0]),)).fetchall()
+ print('knn', got)
+ assert [r[0] for r in got] == [1, 3], got
+ "@
+ if ($LASTEXITCODE -ne 0) { exit 1 }
+
+ - uses: actions/upload-artifact@v4
+ with:
+ name: unsigned-sqlite-vec
+ path: wheel/*.whl
+ if-no-files-found: error
+
+ sign:
+ name: Sign the native binaries
+ needs: [build-pyarrow, build-sqlite-vec]
+ # x64, deliberately. The wheels are ARM64 but Authenticode does not care what the host
+ # is, and trusted-signing-cli is an x64 binary whose digest is pinned for windows-latest
+ # in release-desktop.yml. Signing here runs the same verified bytes rather than the same
+ # bytes under emulation.
+ runs-on: windows-latest
+ timeout-minutes: 45
+ # The Azure Trusted Signing secrets are read by this job and no other. Naming the
+ # environment is what makes them gateable; add required reviewers in repo settings to
+ # close the gap, exactly as release-desktop.yml documents.
+ environment: release-signing
+ steps:
+ - name: Harden runner (audit)
+ uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@v4
+
+ - uses: actions/download-artifact@v4
+ with:
+ pattern: unsigned-*
+ merge-multiple: true
+ path: unsigned
+
+ - name: List what was built
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $wheels = Get-ChildItem unsigned/*.whl
+ $wheels | ForEach-Object { "{0,-52} {1,8:N0} KB" -f $_.Name, ($_.Length / 1KB) }
+ # Four pyarrow (cp311-cp314) and one sqlite-vec. A short matrix leg would otherwise
+ # publish a wheelhouse missing an interpreter, which reads as "no wheel" downstream.
+ if ($wheels.Count -ne 5) { throw "expected 5 wheels, got $($wheels.Count)" }
+
+ # Same pin as release-desktop.yml. The URL is reproducibility, the digest is the gate:
+ # a release asset can be replaced after upload, and a replaced one must fail the run
+ # rather than sign with an unknown binary. Bump both together.
+ - name: Install trusted-signing-cli
+ shell: pwsh
+ env:
+ TRUSTED_SIGNING_CLI_URL: "https://github.com/Levminer/artifact-signing-cli/releases/download/0.10.0/trusted-signing-cli.exe"
+ TRUSTED_SIGNING_CLI_SHA256: "8c9d750ca582891a7433925dcf302d5d3761fbed757b46c4bf5b417562dccb0e"
+ run: |
+ $ErrorActionPreference = "Stop"
+ $dir = Join-Path $env:RUNNER_TEMP "trusted-signing-cli"
+ New-Item -ItemType Directory -Force -Path $dir | Out-Null
+ $dest = Join-Path $dir "trusted-signing-cli.exe"
+ Invoke-WebRequest -Uri $env:TRUSTED_SIGNING_CLI_URL -OutFile $dest -MaximumRetryCount 3 -RetryIntervalSec 5
+ $actual = (Get-FileHash -Path $dest -Algorithm SHA256).Hash.ToLower()
+ $expected = $env:TRUSTED_SIGNING_CLI_SHA256.ToLower()
+ if ($actual -ne $expected) {
+ Remove-Item -Force $dest
+ Write-Output "::error::trusted-signing-cli digest mismatch, refusing to sign with an unverified binary. Expected $expected, got $actual."
+ exit 1
+ }
+ Write-Output "verified trusted-signing-cli sha256=$actual"
+ $dir | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+ - name: Verify trusted-signing-cli
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $cli = Get-Command trusted-signing-cli -ErrorAction SilentlyContinue
+ if (-not $cli) {
+ Write-Output "::error::trusted-signing-cli is not on PATH. Check the install step above."
+ exit 1
+ }
+ # The helper invokes it by bare name, so whatever PATH resolves is what signs. Only
+ # the digest-verified copy may do that.
+ $verified = [IO.Path]::GetFullPath((Join-Path (Join-Path $env:RUNNER_TEMP "trusted-signing-cli") "trusted-signing-cli.exe"))
+ if ([IO.Path]::GetFullPath($cli.Source) -ne $verified) {
+ Write-Output "::error::trusted-signing-cli resolved to $($cli.Source), not the verified $verified."
+ exit 1
+ }
+ try { & $cli.Source --version }
+ catch {
+ $detail = ($_.Exception.Message -replace '\s+', ' ').Trim()
+ Write-Output "::error::trusted-signing-cli could not be started. Underlying error: $detail"
+ exit 1
+ }
+ if ($LASTEXITCODE -ne 0) {
+ Write-Output "::error::trusted-signing-cli is on PATH but exited $LASTEXITCODE."
+ exit 1
+ }
+
+ - name: Sign every native binary inside the wheels
+ shell: pwsh
+ env:
+ AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+ AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+ AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+ AZURE_TRUSTED_SIGNING_ACCOUNT_NAME: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
+ AZURE_CERTIFICATE_PROFILE_NAME: ${{ secrets.AZURE_CERTIFICATE_PROFILE_NAME }}
+ run: |
+ $ErrorActionPreference = "Stop"
+ python .github/scripts/sign_wheel_binaries.py (Get-ChildItem unsigned/*.whl | ForEach-Object { $_.FullName }) `
+ --out signed `
+ --signer "pwsh -NoProfile -File studio/src-tauri/windows/sign-with-trusted-signing.ps1 -Path"
+ if ($LASTEXITCODE -ne 0) { Write-Output "::error::signing failed"; exit 1 }
+
+ # Independent of the signing tool's own report: unpack what will actually be published
+ # and ask Windows whether each signature validates on this machine.
+ - name: Verify the published wheels validate
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $bad = 0; $ok = 0; $ms = 0
+ foreach ($whl in Get-ChildItem signed/*.whl) {
+ $dir = Join-Path $env:RUNNER_TEMP ("verify-" + $whl.BaseName)
+ Remove-Item -Recurse -Force $dir -ErrorAction SilentlyContinue
+ Expand-Archive -Path $whl.FullName -DestinationPath $dir
+ foreach ($pe in Get-ChildItem $dir -Recurse -Include *.pyd, *.dll) {
+ $sig = Get-AuthenticodeSignature $pe.FullName
+ if ($sig.Status -ne 'Valid') {
+ Write-Output "::error::$($whl.Name) :: $($pe.Name) is $($sig.Status)"
+ $bad++
+ continue
+ }
+ if ($sig.SignerCertificate.Subject -match 'Unsloth') { $ok++ } else { $ms++ }
+ }
+ }
+ Write-Output "signed by us: $ok, upstream-signed (Microsoft redistributables): $ms, invalid: $bad"
+ if ($bad -gt 0) { exit 1 }
+ if ($ok -eq 0) { Write-Output "::error::nothing carries our signature"; exit 1 }
+
+ # RECORD is rewritten by the signing step, so this proves the wheel is still installable
+ # and that its own manifest agrees with its contents.
+ - name: Install each wheel and check its RECORD
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ python -c @"
+ import base64, hashlib, pathlib, sys, zipfile
+ bad = 0
+ for whl in sorted(pathlib.Path('signed').glob('*.whl')):
+ z = zipfile.ZipFile(whl)
+ record = next(n for n in z.namelist() if n.endswith('.dist-info/RECORD'))
+ rows = {}
+ for line in z.read(record).decode().splitlines():
+ if not line.strip():
+ continue
+ name, digest, _, = (line.split(',') + ['', ''])[:3]
+ rows[name] = digest
+ for name in z.namelist():
+ if name == record:
+ continue
+ want = rows.get(name)
+ if not want:
+ print('MISSING from RECORD:', whl.name, name); bad += 1; continue
+ got = 'sha256=' + base64.urlsafe_b64encode(hashlib.sha256(z.read(name)).digest()).rstrip(b'=').decode()
+ if got != want:
+ print('DIGEST MISMATCH:', whl.name, name); bad += 1
+ print(whl.name, 'RECORD ok,', len(rows), 'entries')
+ sys.exit(1 if bad else 0)
+ "@
+ if ($LASTEXITCODE -ne 0) { exit 1 }
+
+ - name: Build index.txt and SHA256SUMS
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ $wheels = Get-ChildItem signed/*.whl | Sort-Object Name
+ # Flat find-links listing: install.ps1 reads this, then fetches each name beside it.
+ ($wheels | ForEach-Object { $_.Name }) -join "`n" | Set-Content signed/index.txt -Encoding ascii
+ ($wheels | ForEach-Object { "{0} {1}" -f (Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLower(), $_.Name }) -join "`n" |
+ Set-Content signed/SHA256SUMS -Encoding ascii
+ Get-Content signed/index.txt
+ Get-Content signed/SHA256SUMS
+
+ - uses: actions/upload-artifact@v4
+ with:
+ name: woa-wheelhouse-signed
+ path: |
+ signed/*.whl
+ signed/index.txt
+ signed/SHA256SUMS
+ if-no-files-found: error
+
+ publish:
+ name: Publish the wheelhouse
+ needs: sign
+ if: inputs.publish
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ permissions:
+ contents: write
+ steps:
+ - name: Harden runner (audit)
+ uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+ with:
+ egress-policy: audit
+
+ - uses: actions/download-artifact@v4
+ with:
+ name: woa-wheelhouse-signed
+ path: wheelhouse
+
+ # A release, not a branch: GitHub reports a per-asset `digest` through the release API,
+ # which is the same verification the installer already applies to the llama.cpp bundles.
+ - name: Create or update the release
+ shell: bash
+ env:
+ GH_TOKEN: ${{ github.token }}
+ TAG: ${{ inputs.release_tag }}
+ run: |
+ set -euo pipefail
+ if ! gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+ gh release create "$TAG" \
+ --repo "$GITHUB_REPOSITORY" \
+ --title "Windows on ARM wheelhouse" \
+ --notes "Signed win_arm64 wheels for the native Windows on ARM installer: pyarrow (cp311-cp314) and sqlite-vec. Neither publishes a win_arm64 wheel on PyPI. The native binaries inside each wheel are Authenticode signed through Azure Trusted Signing; SHA256SUMS lists the digest of every wheel as published."
+ fi
+ # --clobber: this tag is a rolling wheelhouse, and a rebuilt wheel for the same
+ # interpreter is meant to replace its predecessor rather than fail the upload.
+ gh release upload "$TAG" --repo "$GITHUB_REPOSITORY" --clobber \
+ wheelhouse/*.whl wheelhouse/index.txt wheelhouse/SHA256SUMS
+
+ - name: Report the wheelhouse URL
+ shell: bash
+ env:
+ TAG: ${{ inputs.release_tag }}
+ run: |
+ set -euo pipefail
+ url="https://github.com/$GITHUB_REPOSITORY/releases/download/$TAG"
+ {
+ echo "### Windows on ARM wheelhouse published"
+ echo
+ echo 'Point the installer at it with:'
+ echo
+ echo '```powershell'
+ echo "\$env:UNSLOTH_WOA_WHEELHOUSE = \"$url\""
+ echo '```'
+ echo
+ echo '| wheel | sha256 |'
+ echo '| --- | --- |'
+ while read -r digest name; do echo "| $name | \`$digest\` |"; done < wheelhouse/SHA256SUMS
+ } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.gitignore b/.gitignore
index 0588eec4afd..8b281a8ca4b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -255,6 +255,10 @@ Speech_12dB_s16.flac
# so a test run or an Unsloth start rewrites it and dirties the checkout.
.studio-test-root/
+# _filter_requirements() in studio/install_python_stack.py writes its skip-filtered copy beside
+# the source file so relative -r/-c includes still resolve. A killed install leaves them behind.
+studio/backend/requirements/.*-filtered-*.txt
+
# launch.py --outdir scratch from a local run
/out/
diff --git a/install.ps1 b/install.ps1
index 1e90654a03c..f2a8272aa5e 100644
--- a/install.ps1
+++ b/install.ps1
@@ -269,7 +269,10 @@ function Install-UnslothStudio {
function Get-HostMachineArch {
$osArch = ""
try { $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() } catch { $osArch = "" }
- $signals = @([string]$env:PROCESSOR_ARCHITEW6432, [string]$env:PROCESSOR_ARCHITECTURE, $osArch)
+ # Machine scope first: emulated x64 says AMD64 per-process (ARCHITEW6432 is WOW64-only).
+ $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" }
}
@@ -284,6 +287,1067 @@ function Install-UnslothStudio {
return "unknown"
}
+ # WoA + NVIDIA: emulated triton cannot target the Blackwell SM. Probed for a win_arm64 CUDA wheel, never by arch.
+ $script:WoaNativeCudaTorch = $false
+ $script:WoaTorchIndexUrl = $null
+
+ $script:WoaNvidiaTorchIndexUrls = if ($env:UNSLOTH_WOA_TORCH_INDEX_URL) {
+ @($env:UNSLOTH_WOA_TORCH_INDEX_URL.Trim().TrimEnd('/'))
+ } else {
+ @(
+ "https://pypi.nvidia.com/nvtorch_oot",
+ "https://pypi.nvidia.com/nvtorch_oot_nightly"
+ )
+ }
+ $script:WoaTorchAudio = $false
+
+ # Wheels PyPI has no win_arm64 build of: pyarrow 25.0.1 (cp311-cp314) and sqlite-vec 0.1.9, built from their release tags on a windows-11-arm runner. Set UNSLOTH_WOA_WHEELHOUSE to override.
+ $script:WoaWheelhouse = if ($env:UNSLOTH_WOA_WHEELHOUSE) {
+ $env:UNSLOTH_WOA_WHEELHOUSE.Trim().TrimEnd('/')
+ } else {
+ "https://huggingface.co/danielhanchen/unsloth-blackwell-docker/resolve/main/windows-arm64-wheels"
+ }
+ # AVAILABLE, not missing: a name absent here is EXCLUDED on ARM64 by the drop list below.
+ $script:WoaPyPIProvided = @{}
+ $script:WoaPyPIMatchedVersion = $null
+ $script:WoaPyarrowWheel = $null
+ $script:WoaPyarrowSource = $null # "pypi" | "wheelhouse" | "local"
+ $script:WoaPyarrowWheelName = $null # the wheel the pin is written from
+
+ function Test-ZipArchiveReadable {
+ param([string]$Path)
+ try {
+ Add-Type -AssemblyName System.IO.Compression.FileSystem -ErrorAction SilentlyContinue
+ $zip = [System.IO.Compression.ZipFile]::OpenRead($Path)
+ } catch { return $false }
+ try { return ($zip.Entries.Count -gt 0) } catch { return $false } finally { $zip.Dispose() }
+ }
+
+ # NVIDIA ships bare .bin artifacts; uv/pip need the tags in the filename, so rebuild it.
+ function Get-WheelFileNameFromArchive {
+ param([string]$Path)
+ try {
+ Add-Type -AssemblyName System.IO.Compression.FileSystem -ErrorAction SilentlyContinue
+ $zip = [System.IO.Compression.ZipFile]::OpenRead($Path)
+ } catch { return $null }
+ try {
+ $wheelEntry = $zip.Entries | Where-Object { $_.FullName -match '^[^/]+\.dist-info/WHEEL$' } | Select-Object -First 1
+ if (-not $wheelEntry) { return $null }
+ $distInfo = ($wheelEntry.FullName -split '/')[0] -replace '\.dist-info$', ''
+ $reader = New-Object System.IO.StreamReader($wheelEntry.Open())
+ try { $content = $reader.ReadToEnd() } finally { $reader.Dispose() }
+ if ($content -notmatch '(?m)^Tag:\s*(\S+)\s*$') { return $null }
+ return "$distInfo-$($Matches[1]).whl"
+ } catch {
+ return $null
+ } finally {
+ $zip.Dispose()
+ }
+ }
+
+ # "$base/$leaf" would put the leaf inside a mirror's ?token=.
+ function Join-UrlPath {
+ param([string]$Base, [string]$Path)
+ if ([string]::IsNullOrWhiteSpace($Base)) { return $Path }
+ $cut = $Base.IndexOfAny([char[]]('?', '#'))
+ if ($cut -lt 0) { return "$($Base.TrimEnd('/'))/$Path" }
+ $head = $Base.Substring(0, $cut).TrimEnd('/')
+ $tail = $Base.Substring($cut)
+ return "$head/$Path$tail"
+ }
+
+ # Userinfo AND query/fragment, so an authenticated pin never leaks. Mirrors the Python side.
+ function Remove-IndexUrlCredentials {
+ param([string]$Url)
+ # Ordinal, not culture-aware: th-TH treats "://" as ignorable and crashes Substring (#7279).
+ $sep = $Url.IndexOf('://', [System.StringComparison]::Ordinal)
+ if ($sep -lt 0) { return $Url }
+ $scheme = $Url.Substring(0, $sep)
+ $rest = $Url.Substring($sep + 3)
+ $q = $rest.IndexOfAny([char[]]('?', '#'))
+ if ($q -ge 0) { $rest = $rest.Substring(0, $q) }
+ $slash = $rest.IndexOf('/', [System.StringComparison]::Ordinal)
+ $authority = if ($slash -ge 0) { $rest.Substring(0, $slash) } else { $rest }
+ $at = $authority.LastIndexOf('@', [System.StringComparison]::Ordinal)
+ $host_ = if ($at -ge 0) { $authority.Substring($at + 1) } else { $authority }
+ if ($slash -ge 0) { return "${scheme}://${host_}$($rest.Substring($slash))" }
+ return "${scheme}://${host_}"
+ }
+
+ function Test-WoaWheelhouseIsLocal {
+ param([string]$Value)
+ if (-not $Value) { return $false }
+ if ($Value -match '^[A-Za-z][A-Za-z0-9+.-]*://') { return $false }
+ try { return (Test-Path -LiteralPath $Value -PathType Container) } catch { return $false }
+ }
+
+ # uv splits UV_OVERRIDE on whitespace, so a spaced path breaks every later uv call (#6503).
+ 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
+ }
+ if ($short -and -not $short.Contains(" ")) { return $short }
+ } catch {}
+ return $Path
+ }
+
+ # uv accepts no quoting in UV_OVERRIDE (0.10.7), so 8.3 is the only mitigation, and a volume can disable it.
+ $script:WoaResolverPathsOk = $null
+ function Test-WoaResolverPathsUsable {
+ if ($null -ne $script:WoaResolverPathsOk) { return $script:WoaResolverPathsOk }
+ try { New-Item -ItemType Directory -Force -Path $StudioHome -ErrorAction Stop | Out-Null } catch {}
+ $script:WoaResolverPathsOk = -not ((Get-UvSafePath $StudioHome) -match '\s')
+ if (-not $script:WoaResolverPathsOk) {
+ substep "windows on arm: $StudioHome contains a space and this volume has no 8.3" "Yellow"
+ substep "short name for it, which uv cannot read -- using the x64 stack instead." "Yellow"
+ substep "Set UNSLOTH_STUDIO_HOME to a path without spaces for the native install." "Yellow"
+ }
+ return $script:WoaResolverPathsOk
+ }
+
+ # PEP 425 fields, not a substring: "*cp313-cp313*" also matches cp313-cp313t. Fields are "."-sets.
+ function Test-WoaWheelTags {
+ 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))
+ }
+
+ # PEP 440 to the depth these floors use; a pre-release sorts BELOW its release (21.0.0rc1 fails >=21.0.0).
+ function Test-WoaVersionAtLeast {
+ param([string]$Version, [string]$Floor)
+ $parse = {
+ param([string]$v)
+ if ($v -notmatch '^\s*v?(\d+(\.\d+)*)') { return $null }
+ $release = $Matches[1] -split '\.' | ForEach-Object { [int]$_ }
+ $post = 0
+ if ($v -match '\.post(\d+)') { $post = [int]$Matches[1] }
+ # a/b/rc only, and only off the release, so ".post1rc1" is not a pre-release of it.
+ $pre = [bool]($v -match '(?i)^\s*v?\d+(\.\d+)*(a|b|rc)\d')
+ # PEP 440 hangs .devN off what precedes it, so 0.0.22.post7.dev0 is below 0.0.22.post7.
+ $dev = [int]::MaxValue
+ if ($v -match '(?i)\.dev(\d+)') { $dev = [int]$Matches[1] }
+ return @{ Release = @($release); Post = $post; Pre = $pre; Dev = $dev }
+ }
+ $a = & $parse $Version
+ $b = & $parse $Floor
+ if ($null -eq $a -or $null -eq $b) { return $false }
+ $width = [Math]::Max($a.Release.Count, $b.Release.Count)
+ for ($i = 0; $i -lt $width; $i++) {
+ $x = if ($i -lt $a.Release.Count) { $a.Release[$i] } else { 0 }
+ $y = if ($i -lt $b.Release.Count) { $b.Release[$i] } else { 0 }
+ if ($x -ne $y) { return ($x -gt $y) }
+ }
+ if ($a.Pre -ne $b.Pre) { return $b.Pre }
+ if ($a.Post -ne $b.Post) { return ($a.Post -gt $b.Post) }
+ if ($a.Dev -ne $b.Dev) { return ($a.Dev -gt $b.Dev) }
+ return $true
+ }
+
+ # The wheelhouse may BE the managed directory (offline reuse), and Copy-Item refuses a self-copy.
+ function Test-WoaSamePath {
+ param([string]$A, [string]$B)
+ if (-not $A -or -not $B) { return $false }
+ try {
+ $a = [System.IO.Path]::GetFullPath($A).TrimEnd('\', '/')
+ $b = [System.IO.Path]::GetFullPath($B).TrimEnd('\', '/')
+ } catch { return $false }
+ return $a.Equals($b, [System.StringComparison]::OrdinalIgnoreCase)
+ }
+
+ # uv and pip resolve -r/-c/-f against the file CONTAINING the line, so a moved line must rebase.
+ 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 off, or the rebase reads it as part of 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, dropping the option token.
+ $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"
+ }
+ # -e / --editable names a path too. Extras split off first, or GetFullPath folds ".[dev]" into the parent and leaves a directory nobody has.
+ 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]
+ # PEP 508 separates a marker from a URL with whitespace before the ";": kept aside, or it would be 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" }
+ }
+ # A bare local directory is a requirement to pip and uv both; the leading dot segment is what tells it from a package name, which may not start with one.
+ 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"
+ }
+
+ # Which index a uv resolve uses, from uv.toml / pyproject.toml. Quote-aware, and a subset parser because PS 5.1 has no TOML reader.
+ 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's inline spelling of [[index]]: `index = [{ url = "...", default = true }]`. Returns @{ DefaultUrl; Extras }, or $null on ANY doubt; only a single-line, brace-balanced array of FLAT inline tables is read.
+ # The brace characters below are built from code points: the parity tests extract a function by counting braces, so a literal one inside a string would make this body un-tested.
+ 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 }
+ 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 }
+ # uv: an explicit index serves only packages pinned to it via [tool.uv.sources], so it is neither the default nor an 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 the default (uv docs): 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 { $_ }) }
+ }
+
+ function Get-WoaUvConfigIndexPolicy {
+ $result = @{ NoIndex = $false; DefaultIndex = $null; Unreadable = $false; UnreadablePath = $null; ExtraIndexes = @() }
+ $noCfg = [string](Get-Item Env:UV_NO_CONFIG -ErrorAction SilentlyContinue).Value
+ if ($noCfg -and ($noCfg.Trim().ToLowerInvariant() -notin @("", "0", "false"))) { return $result }
+ $files = @()
+ $cfgFile = [string](Get-Item Env:UV_CONFIG_FILE -ErrorAction SilentlyContinue).Value
+ 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
+ }
+
+ # The host, not a substring: "https://pypi.org.corp.example/simple" is not public PyPI.
+ function Test-WoaUrlIsPublicPyPI {
+ param([string]$Url)
+ if (-not $Url) { return $false }
+ try { $u = [System.Uri]$Url.Trim() } catch { return $false }
+ if (-not $u.IsAbsoluteUri) { return $false }
+ return ($u.Host.ToLowerInvariant() -eq "pypi.org")
+ }
+
+ # This script resolves with uv, so uv's policy is the one that counts: UV_* and its configuration files. pip's PIP_* variables are pip's alone; uv never reads them.
+ function Test-WoaResolveReachesPyPI {
+ foreach ($name in @("UV_OFFLINE", "UV_NO_INDEX")) {
+ $flag = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($flag -and ($flag.Trim().ToLowerInvariant() -notin @("", "0", "false"))) { return $false }
+ }
+ $extraIsPyPI = $false
+ foreach ($name in @("UV_INDEX", "UV_EXTRA_INDEX_URL")) {
+ $list = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ foreach ($u in ($list -split '\s+' | Where-Object { $_ })) {
+ if (Test-WoaUrlIsPublicPyPI $u) { $extraIsPyPI = $true }
+ }
+ }
+ foreach ($name in @("UV_DEFAULT_INDEX", "UV_INDEX_URL")) {
+ $url = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($url -and ($url.Trim())) { return ($extraIsPyPI -or (Test-WoaUrlIsPublicPyPI $url)) }
+ }
+ # Doubt resolves to "not PyPI": that answer keeps a wheel, the other loses the package.
+ $cfg = Get-WoaUvConfigIndexPolicy
+ if ($cfg.Unreadable -or $cfg.NoIndex) { return $false }
+ foreach ($u in @($cfg.ExtraIndexes)) { if (Test-WoaUrlIsPublicPyPI $u) { $extraIsPyPI = $true } }
+ if ($cfg.DefaultIndex -and -not (Test-WoaUrlIsPublicPyPI $cfg.DefaultIndex)) { return $extraIsPyPI }
+ return $true
+ }
+
+ # True when uv's own config decides the indexes and we could not read it: fatal where the caller scrubs UV_* and sets UV_NO_CONFIG, because the trio index would be the only source left.
+ function Test-WoaUvIndexPolicyUnreadable {
+ foreach ($name in @("UV_NO_INDEX", "UV_DEFAULT_INDEX", "UV_INDEX_URL")) {
+ $v = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($v -and $v.Trim()) { return $false }
+ }
+ return [bool](Get-WoaUvConfigIndexPolicy).Unreadable
+ }
+
+ # The index beside the CUDA one for torch's shared dependencies. Invoke-InstallCommand clears the inherited index settings whenever --default-index is passed, so the caller's policy is restated here.
+ function Get-WoaDependencyIndexArgs {
+ param([string]$Resolver = "uv")
+ $pip = ($Resolver -eq "pip")
+ $noIndexNames = if ($pip) { @("PIP_NO_INDEX") } else { @("UV_NO_INDEX") }
+ $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") }
+ foreach ($name in $noIndexNames) {
+ $flag = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($flag -and ($flag.Trim().ToLowerInvariant() -notin @("", "0", "false"))) { return @() }
+ }
+ $default = $null
+ foreach ($name in $defaultNames) {
+ $url = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($url -and $url.Trim()) { $default = $url.Trim(); break }
+ }
+ $extras = @()
+ foreach ($name in $extraNames) {
+ $list = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ 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
+ }
+
+ # Exact tags, or a wheel that does not care (cp38-abi3, py3-none). Free-threaded has no abi3.
+ function Test-WoaWheelTagsUsable {
+ param([string]$Name, [string]$PyTag, [string]$AbiTag = "")
+ if (-not $AbiTag) { $AbiTag = $PyTag }
+ if (Test-WoaWheelTags -Name $Name -PyTag $PyTag -AbiTag $AbiTag) { return $true }
+ $fields = ($Name -replace '(?i)\.whl$', '') -split '-'
+ if ($fields.Count -lt 5) { return $false }
+ # Free-threaded CPython has no stable ABI (CPython #111506), so abi3 is not an option there.
+ if ($AbiTag -like "*t") { return $false }
+ $abiTags = $fields[$fields.Count - 2] -split '\.'
+ $minor = 0
+ if ($PyTag -match '^cp3(\d+)$') { $minor = [int]$Matches[1] }
+ foreach ($pyTag in ($fields[$fields.Count - 3] -split '\.')) {
+ # abi3 is forward compatible only from what it was built against: cp314-abi3 fails on cp313.
+ if (($abiTags -contains "abi3") -and ($pyTag -match '^cp3(\d+)$')) {
+ if ([int]$Matches[1] -le $minor) { return $true }
+ }
+ if ($abiTags -contains "none") {
+ if ($pyTag -match '^py3(\d*)$') {
+ if ([string]::IsNullOrEmpty($Matches[1]) -or ([int]$Matches[1] -le $minor)) { return $true }
+ }
+ if ($pyTag -match '^cp3(\d+)$') {
+ if ([int]$Matches[1] -le $minor) { return $true }
+ }
+ }
+ }
+ return $false
+ }
+
+ function Test-WoaPyPIWheel {
+ param([string]$Project, [string]$PyTag, [string]$AbiTag = "", [string]$Floor = "", [switch]$AllowAgnostic, [switch]$Exact)
+ if (-not $Project -or -not $PyTag) { return $false }
+ if (-not $AbiTag) { $AbiTag = $PyTag }
+ # pypi.org/simple normalises the project name; a wheel filename carries the underscored form.
+ $slug = ($Project -replace '_', '-').ToLowerInvariant()
+ try {
+ $body = [string](Invoke-RestMethod -Uri "https://pypi.org/simple/$slug/" -UseBasicParsing -TimeoutSec 20)
+ } catch { return $false }
+ foreach ($match in [regex]::Matches($body, "[A-Za-z0-9_.+-]+win_arm64\.whl")) {
+ $name = $match.Value
+ $tagsOk = if ($AllowAgnostic) { Test-WoaWheelTagsUsable -Name $name -PyTag $PyTag -AbiTag $AbiTag }
+ else { Test-WoaWheelTags -Name $name -PyTag $PyTag -AbiTag $AbiTag }
+ if (-not $tagsOk) { continue }
+ $fields = ($name -replace '(?i)\.whl$', '') -split '-'
+ if ($fields.Count -lt 5) { continue }
+ if (($fields[0] -replace '_', '-').ToLowerInvariant() -ne $slug) { continue }
+ if (-not $Floor) { $script:WoaPyPIMatchedVersion = $fields[1]; return $true }
+ # -Exact: the same version, so an exact pin the wheelhouse copy satisfies is never lost to a newer upstream release it does not.
+ $ok = if ($Exact) {
+ (Test-WoaVersionAtLeast -Version $fields[1] -Floor $Floor) -and (Test-WoaVersionAtLeast -Version $Floor -Floor $fields[1])
+ } else { Test-WoaVersionAtLeast -Version $fields[1] -Floor $Floor }
+ if ($ok) {
+ $script:WoaPyPIMatchedVersion = $fields[1]
+ return $true
+ }
+ }
+ return $false
+ }
+
+ # Ours is first in UV_FIND_LINKS and wins the tie; an upstream BEHIND it leaves ours staged.
+ function Test-WoaWheelhouseWheelIsRedundant {
+ param([string]$Name, [string]$PyTag, [string]$AbiTag = "")
+ if ($Name -notlike "*win_arm64*") { return $false }
+ $fields = ($Name -replace '(?i)\.whl$', '') -split '-'
+ if ($fields.Count -lt 5) { return $false }
+ if (-not (Test-WoaResolveReachesPyPI)) { return $false }
+ if (-not (Test-WoaWheelTagsUsable -Name $Name -PyTag $PyTag -AbiTag $AbiTag)) { return $false }
+ return (Test-WoaPyPIWheel -Project $fields[0] -PyTag $PyTag -AbiTag $AbiTag -Floor $fields[1] -AllowAgnostic -Exact)
+ }
+
+ function Test-WoaWheelAvailable {
+ param([string]$Project, [string]$PythonMinor, [string]$AbiTag = "")
+ $tag = "cp" + ($PythonMinor -replace '\.', '')
+ if (-not $AbiTag) { $AbiTag = $tag }
+ $pattern = "$Project-[^`"'<>\s]*?win_arm64\.whl"
+ if ((Test-WoaResolveReachesPyPI) -and (Test-WoaPyPIWheel -Project $Project -PyTag $tag -AbiTag $AbiTag)) { return $true }
+ if (-not $script:WoaWheelhouse) { return $false }
+ if (Test-WoaWheelhouseIsLocal $script:WoaWheelhouse) {
+ $local = Get-ChildItem -LiteralPath $script:WoaWheelhouse -Filter "$Project-*win_arm64.whl" -ErrorAction SilentlyContinue |
+ Where-Object { Test-WoaWheelTags -Name $_.Name -PyTag $tag -AbiTag $AbiTag } | Select-Object -First 1
+ return [bool]$local
+ }
+ try {
+ $index = [string](Invoke-RestMethod -Uri (Join-UrlPath $script:WoaWheelhouse "index.txt") -UseBasicParsing -TimeoutSec 20)
+ foreach ($match in [regex]::Matches($index, $pattern)) {
+ if (Test-WoaWheelTags -Name $match.Value -PyTag $tag -AbiTag $AbiTag) { return $true }
+ }
+ } catch {}
+ return $false
+ }
+
+ # constraints.txt floors ARM64 pyarrow at 21.0.0 and staging pins exactly, so a 19.x cannot resolve.
+ $script:WoaPyarrowFloor = "21.0.0"
+ function Test-WoaPyarrowWheelUsable {
+ param([string]$Name, [string]$PyTag, [string]$AbiTag)
+ # Usable, not exact: pyarrow's coming win_arm64 wheel is cp311-abi3 (apache/arrow#48539).
+ if (-not (Test-WoaWheelTagsUsable -Name $Name -PyTag $PyTag -AbiTag $AbiTag)) { return $false }
+ $fields = ($Name -replace '(?i)\.whl$', '') -split '-'
+ if ($fields.Count -lt 5) { return $false }
+ return (Test-WoaVersionAtLeast -Version $fields[1] -Floor $script:WoaPyarrowFloor)
+ }
+
+ # uv's --overrides beat a spec named on the command line (0.10.7): drop the trio only, here only.
+ function New-WoaTorchStepOverrideValue {
+ 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-WoaRequirementEntries -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 }
+ # Flattened, because a line dropped from an include cannot come along by reference. Recorded for deletion: it can carry an authenticated URL.
+ $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
+ }
+
+ function Get-WoaRequirementEntries {
+ 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-WoaRequirementEntries -Path $nested -Seen $Seen -Depth ($Depth + 1))
+ continue
+ }
+ $entries += , @{ Line = $line; BaseDir = $dir }
+ }
+ return $entries
+ }
+
+ # UNSLOTH_PYARROW_WHEEL, then PyPI, then the wheelhouse. "" leaves native unselected.
+ function Get-WoaPyarrowSource {
+ param([string]$PythonMinor, [string]$AbiTag = "")
+ $tag = "cp" + ($PythonMinor -replace '\.', '')
+ if (-not $AbiTag) { $AbiTag = $tag }
+ $script:WoaPyarrowWheelName = $null
+ if ($env:UNSLOTH_PYARROW_WHEEL) {
+ $_paWheel = $env:UNSLOTH_PYARROW_WHEEL
+ if (Test-Path -LiteralPath $_paWheel -PathType Leaf) {
+ $_paName = Split-Path -Leaf $_paWheel
+ if ($_paName -notlike "*.whl") {
+ $_paFromArchive = Get-WheelFileNameFromArchive -Path $_paWheel
+ if ($_paFromArchive) { $_paName = $_paFromArchive }
+ }
+ if (($_paName -like "pyarrow-*") -and (Test-WoaPyarrowWheelUsable -Name $_paName -PyTag $tag -AbiTag $AbiTag) -and
+ ($_paName -like "*win_arm64.whl")) {
+ # The whole archive: a truncated download still starts with "PK".
+ if (Test-ZipArchiveReadable -Path $_paWheel) { return "local" }
+ substep "windows on arm: UNSLOTH_PYARROW_WHEEL is not a readable wheel archive -- ignoring it." "Yellow"
+ } else {
+ substep "windows on arm: UNSLOTH_PYARROW_WHEEL is not a $tag win_arm64 pyarrow >= $($script:WoaPyarrowFloor) wheel -- ignoring it." "Yellow"
+ }
+ } else {
+ substep "windows on arm: UNSLOTH_PYARROW_WHEEL does not exist -- ignoring it." "Yellow"
+ }
+ }
+ if (Test-WoaResolveReachesPyPI) { try {
+ $body = [string](Invoke-RestMethod -Uri "https://pypi.org/simple/pyarrow/" -UseBasicParsing -TimeoutSec 20)
+ foreach ($match in [regex]::Matches($body, 'pyarrow-[^"''<>\s]*?win_arm64\.whl')) {
+ if (Test-WoaPyarrowWheelUsable -Name $match.Value -PyTag $tag -AbiTag $AbiTag) {
+ # Recorded so the override pins THIS wheel: a newer sdist satisfies >=21.0.0.
+ $script:WoaPyarrowWheelName = $match.Value
+ return "pypi"
+ }
+ }
+ } catch {} }
+ if (Test-WoaWheelhouseIsLocal $script:WoaWheelhouse) {
+ $local = Get-ChildItem -LiteralPath $script:WoaWheelhouse -Filter "pyarrow-*win_arm64.whl" -ErrorAction SilentlyContinue |
+ Where-Object {
+ (Test-WoaPyarrowWheelUsable -Name $_.Name -PyTag $tag -AbiTag $AbiTag) -and
+ (Test-ZipArchiveReadable -Path $_.FullName)
+ } | Select-Object -First 1
+ if ($local) { return "wheelhouse" }
+ return ""
+ }
+ try {
+ $index = [string](Invoke-RestMethod -Uri (Join-UrlPath $script:WoaWheelhouse "index.txt") -UseBasicParsing -TimeoutSec 20)
+ foreach ($match in [regex]::Matches($index, 'pyarrow-[^"''<>\s]*?win_arm64\.whl')) {
+ if (Test-WoaPyarrowWheelUsable -Name $match.Value -PyTag $tag -AbiTag $AbiTag) { return "wheelhouse" }
+ }
+ } catch {}
+ return ""
+ }
+
+ # ── Bound nvidia-smi so a wedged driver cannot hang the installer. ──
+ 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; the human-readable probes keep the default merge.
+ [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 ""
+ }
+ }
+
+ # One list, because the presence probe and the driver-version probe must agree: a host only the first finds reports a GPU with no driver version, and the CUDA-major guard is then skipped.
+ function Get-WoaNvidiaSmiPath {
+ $exe = $null
+ try { $exe = (Get-Command nvidia-smi -ErrorAction SilentlyContinue).Source } catch { $exe = $null }
+ if ($exe) { return $exe }
+ foreach ($candidate in @(
+ "$env:SystemRoot\System32\nvidia-smi.exe",
+ "$env:ProgramFiles\NVIDIA Corporation\NVSMI\nvidia-smi.exe"
+ )) {
+ if (Test-Path -LiteralPath $candidate -PathType Leaf) { return $candidate }
+ }
+ return $null
+ }
+
+ function Test-WoaNvidiaPresent {
+ $exe = Get-WoaNvidiaSmiPath
+ if (-not $exe) { return $false }
+ $listing = Invoke-NvidiaSmiBounded $exe @('-L')
+ return ($LASTEXITCODE -eq 0 -and $listing -match '(?m)^\s*GPU\s+\d+')
+ }
+
+ # The driver's CUDA version as @(major, minor), or $null when nvidia-smi does not say.
+ function Get-WoaDriverCudaVersion {
+ $exe = Get-WoaNvidiaSmiPath
+ if (-not $exe) { return $null }
+ $out = Invoke-NvidiaSmiBounded $exe
+ # Newer drivers print "CUDA UMD Version"; accept both spellings.
+ if ($out -notmatch 'CUDA(?: UMD)? Version:\s+(\d+)\.(\d+)') { return $null }
+ return @([int]$Matches[1], [int]$Matches[2])
+ }
+
+ function Get-WoaDriverCudaLeaf {
+ $v = Get-WoaDriverCudaVersion
+ if (-not $v) { return $null }
+ $major = [int]$v[0]; $minor = [int]$v[1]
+ if ($major -ge 13) { return "cu130" }
+ if ($major -eq 12 -and $minor -ge 8) { return "cu128" }
+ if ($major -eq 12 -and $minor -ge 6) { return "cu126" }
+ if ($major -ge 12) { return "cu124" }
+ if ($major -ge 11) { return "cu118" }
+ return $null
+ }
+
+ # A free-threaded build installs cp313t, not cp313. Unknown answers $false, keeping the GIL path.
+ function Test-PythonFreeThreaded {
+ param([string]$PythonExe)
+ if (-not $PythonExe -or -not (Test-Path -LiteralPath $PythonExe -PathType Leaf)) { return $false }
+ $out = ""
+ try {
+ $out = (& $PythonExe -c "import sysconfig; print(1 if sysconfig.get_config_var('Py_GIL_DISABLED') else 0)" 2>$null | Out-String).Trim()
+ } catch { return $false }
+ return ($out -eq "1")
+ }
+
+ function Get-WoaAbiTag {
+ param([string]$PythonMinor, [bool]$FreeThreaded)
+ $tag = "cp" + ($PythonMinor -replace '\.', '')
+ if ($FreeThreaded) { return "${tag}t" }
+ return $tag
+ }
+
+ # CUDA is established POSITIVELY by requiring +cuNNN: PyPI's own win_arm64 torch carries no local version, and the stamp and +cuXXX tag identify the torch BUILD a companion belongs to.
+ function Test-WoaWheelPairsWithTorch {
+ 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 share an empty stamp, so they pair by offset: torchvision 0.(M+15) to 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 Get-WoaCudaWheelVersion {
+ param([string]$IndexUrl, [string]$PythonMinor, [string]$Project = "torch", [string]$AbiTag = "",
+ [string]$PairWith = "", [string]$Below = "")
+ if ([string]::IsNullOrWhiteSpace($IndexUrl) -or [string]::IsNullOrWhiteSpace($PythonMinor)) { return $null }
+ $tag = "cp" + ($PythonMinor -replace '\.', '')
+ if (-not $AbiTag) { $AbiTag = $tag }
+ $projectUrl = Join-UrlPath $IndexUrl "$Project/"
+ try {
+ $body = [string](Invoke-RestMethod -Uri $projectUrl -UseBasicParsing -TimeoutSec 20)
+ } catch {
+ return $null
+ }
+ if ([string]::IsNullOrWhiteSpace($body)) { return $null }
+ $best = $null
+ $bestKey = $null
+ # PEP 440 order within one numeric release: dev < a < b < rc < final, then by number.
+ $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)
+ }
+ # -Below: only versions ranked strictly under it, so a caller can walk back from an unpaired newest.
+ $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-WoaWheelTags -Name $name -PyTag $tag -AbiTag $AbiTag)) { continue }
+ if ($name -notmatch '\+cu[0-9]+') { continue }
+ $version = ($name -split '-')[1]
+ if ($PairWith -and -not (Test-WoaWheelPairsWithTorch -TorchVersion $PairWith -OtherVersion $version -Project $Project)) { continue }
+ # Numeric release only: a .dev suffix must not make a newer line look older.
+ $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 Test-WoaCudaWheel {
+ param([string]$IndexUrl, [string]$PythonMinor, [string]$Project = "torch", [string]$AbiTag = "")
+ return [bool](Get-WoaCudaWheelVersion -IndexUrl $IndexUrl -PythonMinor $PythonMinor -Project $Project -AbiTag $AbiTag)
+ }
+
+ function Test-WoaAudioMatchesTorch {
+ 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 Initialize-WoaNativeCudaTorch {
+ param([string]$PythonMinor, [bool]$FreeThreaded = $false)
+ # ABI, not just minor: cp313-cp313 for a 3.13t interpreter finds GIL wheels it cannot install.
+ $_woaAbiTag = Get-WoaAbiTag -PythonMinor $PythonMinor -FreeThreaded $FreeThreaded
+ $script:WoaFreeThreaded = $FreeThreaded
+ $script:WoaNativeCudaTorch = $false
+ $script:WoaTorchIndexUrl = $null
+ $script:WoaTorchAudio = $false
+ if ((Get-HostMachineArch) -ne "arm64") { return }
+ if ($SkipTorch) { return }
+ if ($env:UNSLOTH_WOA_NATIVE -and $env:UNSLOTH_WOA_NATIVE.Trim().ToLowerInvariant() -in @("0", "false", "no", "off")) {
+ substep "windows on arm: UNSLOTH_WOA_NATIVE is off -- using the x64 path." "Yellow"
+ return
+ }
+ if (-not (Test-WoaNvidiaPresent)) { return }
+ if (-not (Test-WoaResolverPathsUsable)) { return }
+ $pinned = @()
+ if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_URL)) {
+ $pinned += $env:UNSLOTH_TORCH_INDEX_URL.Trim().TrimEnd('/')
+ } elseif (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_FAMILY)) {
+ $mirror = if ($env:UNSLOTH_PYTORCH_MIRROR) { $env:UNSLOTH_PYTORCH_MIRROR.TrimEnd('/') } else { "https://download.pytorch.org/whl" }
+ $pinned += "$mirror/$($env:UNSLOTH_TORCH_INDEX_FAMILY.Trim().Trim('/'))"
+ }
+ $candidates = @()
+ if ($pinned.Count -gt 0) {
+ $candidates = $pinned
+ } else {
+ $mirror = if ($env:UNSLOTH_PYTORCH_MIRROR) { $env:UNSLOTH_PYTORCH_MIRROR.TrimEnd('/') } else { "https://download.pytorch.org/whl" }
+ $driverLeaf = Get-WoaDriverCudaLeaf
+ if ($driverLeaf) { $candidates += "$mirror/$driverLeaf" }
+ $candidates += $script:WoaNvidiaTorchIndexUrls
+ }
+ $torchIndex = $null
+ $_woaTorchVersion = $null
+ $_woaVisionVersion = $null
+ $_woaUnpairedIndex = $null
+ foreach ($candidate in $candidates) {
+ if (-not (Test-WoaCudaWheel -IndexUrl $candidate -PythonMinor $PythonMinor -AbiTag $_woaAbiTag -Project "torch")) { continue }
+ $_woaTorchVersion = Get-WoaCudaWheelVersion -IndexUrl $candidate -PythonMinor $PythonMinor -AbiTag $_woaAbiTag
+ # An index qualifies only with a torchvision build PAIRED to that torch, or a lagging nightly or partial mirror leaves torchvision resolving against a torch it was not built for.
+ # The newest torch is not the only candidate: a nightly torchvision lags by days, so the newest COMPLETE pair is searched for, a few versions deep.
+ $_woaVisionVersion = $null
+ $_woaBacktracks = 0
+ while ($_woaTorchVersion) {
+ $_woaVisionVersion = Get-WoaCudaWheelVersion -IndexUrl $candidate -PythonMinor $PythonMinor -Project "torchvision" -AbiTag $_woaAbiTag -PairWith $_woaTorchVersion
+ if ($_woaVisionVersion -or $_woaBacktracks -ge 5) { break }
+ $_woaOlderTorch = Get-WoaCudaWheelVersion -IndexUrl $candidate -PythonMinor $PythonMinor -AbiTag $_woaAbiTag -Below $_woaTorchVersion
+ if (-not $_woaOlderTorch) { break }
+ substep "windows on arm: $(Remove-IndexUrlCredentials $candidate) publishes torch $_woaTorchVersion but no torchvision paired with it; trying torch $_woaOlderTorch." "Yellow"
+ $_woaTorchVersion = $_woaOlderTorch
+ $_woaBacktracks++
+ }
+ if (-not $_woaVisionVersion) {
+ substep "windows on arm: $(Remove-IndexUrlCredentials $candidate) publishes torch $_woaTorchVersion but no torchvision paired with it; trying the next index." "Yellow"
+ if (-not $_woaUnpairedIndex) { $_woaUnpairedIndex = $candidate }
+ continue
+ }
+ $torchIndex = $candidate
+ break
+ }
+ if (-not $torchIndex) {
+ if ($_woaUnpairedIndex) {
+ substep "windows on arm: no index pairs a torchvision with its win_arm64 CUDA torch; using the x64 stack instead." "Yellow"
+ }
+ return
+ }
+ # A CUDA 13 runtime does not run on a CUDA 12 driver (no forward compatibility on Windows), so the wheel's major is checked against the driver's.
+ $_woaDriver = Get-WoaDriverCudaVersion
+ if ($_woaDriver -and $_woaTorchVersion -match '\+cu(\d+)') {
+ $_woaWheelMajor = [int]($Matches[1].Substring(0, $Matches[1].Length - 1))
+ if ($_woaWheelMajor -gt [int]$_woaDriver[0]) {
+ substep "windows on arm: $(Remove-IndexUrlCredentials $torchIndex) publishes torch $_woaTorchVersion (CUDA $_woaWheelMajor), but this driver supports CUDA $($_woaDriver[0]).$($_woaDriver[1])." "Yellow"
+ substep "using the x64 stack instead. Update the NVIDIA driver for the native install." "Yellow"
+ return
+ }
+ }
+ # torch alone is not enough: datasets needs pyarrow, unbuildable here. Both decided up front.
+ $pyarrowSource = Get-WoaPyarrowSource -PythonMinor $PythonMinor -AbiTag $_woaAbiTag
+ if (-not $pyarrowSource) {
+ substep "windows on arm: native CUDA torch is available, but no win_arm64 pyarrow wheel could be found." "Yellow"
+ substep "using the x64 stack instead. Set UNSLOTH_PYARROW_WHEEL to a win_arm64 pyarrow wheel for the native install." "Yellow"
+ return
+ }
+ # Free-threaded only: constraints.txt's win_arm64 av wheel is cp311-abi3 (CPython #111506).
+ if ($FreeThreaded -and -not (Test-WoaWheelAvailable -Project "av" -PythonMinor $PythonMinor -AbiTag $_woaAbiTag)) {
+ substep "windows on arm: no win_arm64 av (PyAV) wheel for this free-threaded interpreter ($_woaAbiTag)." "Yellow"
+ substep "using the x64 stack instead. A GIL build of the same Python takes the native path." "Yellow"
+ return
+ }
+ $script:WoaNativeCudaTorch = $true
+ $script:WoaTorchIndexUrl = $torchIndex
+ $script:WoaPyarrowSource = $pyarrowSource
+ # Only when the audio wheel PAIRS with the torch one: 2.11 dropped its exact torch pin.
+ $_woaAudioVersion = Get-WoaCudaWheelVersion -IndexUrl $torchIndex -PythonMinor $PythonMinor -Project "torchaudio" -AbiTag $_woaAbiTag -PairWith $_woaTorchVersion
+ $script:WoaTorchAudio = Test-WoaAudioMatchesTorch -TorchVersion $_woaTorchVersion -AudioVersion $_woaAudioVersion
+ # Kept so the install pins what the probe SELECTED: unsafe-best-match spans ALL indexes.
+ $script:WoaTorchWheelVersion = $_woaTorchVersion
+ $script:WoaAudioWheelVersion = $_woaAudioVersion
+ $script:WoaVisionWheelVersion = $_woaVisionVersion
+ # Read off the wheel, not the URL: a mirror of the prerelease channel need not say "nightly".
+ $script:WoaTorchIsPrerelease = [bool]($_woaTorchVersion -match '(?i)\d(a|b|rc)\d|\.dev\d')
+ if ($_woaAudioVersion -and -not $script:WoaTorchAudio) {
+ substep "windows on arm: this index has torchaudio $_woaAudioVersion but torch $_woaTorchVersion; skipping torchaudio."
+ }
+ }
+
function Get-TauriTorchIndexFamily {
param([string]$TorchIndexUrl)
if ($SkipTorch) { return "none" }
@@ -4165,7 +5229,10 @@ exit 0
# win_arm64 wheel, so a native ARM64 Python source-builds both and dies on CMake /
# Rust minutes in; x64 runs fine emulated. ARM64 is still returned when it is all
# there is, and the caller then bootstraps x64 or warns.
- $preferX64 = $X64Only -or ((Get-HostMachineArch) -eq "arm64")
+ # ARM64 first on a native host, so a leftover x64 interpreter does not capture the venv.
+ $preferArm64 = $script:WoaNativeCudaTorch -and -not $X64Only
+ $preferX64 = $X64Only -or ((Get-HostMachineArch) -eq "arm64" -and -not $preferArm64)
+ $rankByArch = $preferX64 -or $preferArm64
$candidates = @()
# Try the Python Launcher first (most reliable on Windows)
# py.exe resolves to the standard CPython install, not conda.
@@ -4188,7 +5255,7 @@ exit 0
# Resolve the actual executable path and verify it is not conda-based
$resolvedExe = (& $pyLauncher.Source "-$minor" -S -c "import sys; print(sys.executable)" 2>$null | Out-String).Trim()
if ($resolvedExe -and (Test-Path -LiteralPath $resolvedExe -PathType Leaf) -and -not (Test-IsCondaPython $resolvedExe)) {
- if (-not $preferX64) { return @{ Version = $ver; Path = $resolvedExe; Arch = "" } }
+ if (-not $rankByArch) { return @{ Version = $ver; Path = $resolvedExe; Arch = "" } }
$candidates += @{ Version = $ver; Path = $resolvedExe }
}
}
@@ -4211,7 +5278,7 @@ exit 0
# Resolve the real executable so uv bypasses wrapper re-resolution.
$resolvedExe = (& $cmd.Source -S -c "import sys; print(sys.executable)" 2>$null | Out-String).Trim()
if ($resolvedExe -and (Test-Path -LiteralPath $resolvedExe -PathType Leaf) -and -not (Test-IsCondaPython $resolvedExe)) {
- if (-not $preferX64) { return @{ Version = $ver; Path = $resolvedExe; Arch = "" } }
+ if (-not $rankByArch) { return @{ Version = $ver; Path = $resolvedExe; Arch = "" } }
$candidates += @{ Version = $ver; Path = $resolvedExe }
}
}
@@ -4222,7 +5289,7 @@ exit 0
# a same-minor x64 install that is neither preferred nor on PATH never becomes a
# candidate. `-3.12-64` cannot disambiguate (deprecated, it only means "not
# 32-bit"), so enumerate every registration with -0p and probe each path.
- if ($preferX64) {
+ if ($rankByArch) {
foreach ($pyLauncher in @(Get-Command py -All -CommandType Application -ErrorAction SilentlyContinue)) {
if ($pyLauncher.Source -match $script:CondaSkipPattern) { continue }
$listed = @()
@@ -4257,6 +5324,12 @@ exit 0
foreach ($minor in $minors) {
$sameMinor = @($candidates | Where-Object { $_.Version -eq $minor })
if ($sameMinor.Count -eq 0) { continue }
+ if ($preferArm64) {
+ # x64 is still returned when no ARM64 build exists; the torch step re-checks the tag.
+ $arm = $sameMinor | Where-Object { $_.Arch -eq "arm64" } | Select-Object -First 1
+ if ($arm) { return $arm }
+ return $sameMinor[0]
+ }
$x64 = $sameMinor | Where-Object { $_.Arch -eq "x86_64" } | Select-Object -First 1
if ($x64) { return $x64 }
if (-not $X64Only) { return $sameMinor[0] }
@@ -4393,6 +5466,11 @@ exit 0
# ── Install Python if no compatible version (3.11-3.13) found ──
Write-TauriLog "STEP" "Installing Python"
+ Initialize-WoaNativeCudaTorch -PythonMinor $PythonVersion
+ if ($script:WoaNativeCudaTorch) {
+ step "gpu" "Windows on ARM + NVIDIA: native CUDA wheels available -- installing the ARM64 stack" "Green"
+ substep "torch index: $(Remove-IndexUrlCredentials $script:WoaTorchIndexUrl)"
+ }
$DetectedPython = Remove-SkippedPython (Find-CompatiblePython)
if ($DetectedPython) {
@@ -4449,10 +5527,83 @@ exit 0
return (Exit-InstallFailure "Python installation failed")
}
}
+ # Re-probe for the interpreter actually selected: every native decision is keyed to a cp3XX tag.
+ $WoaProbedMinor = $PythonVersion
+ $WoaProbedFreeThreaded = $false
+ $WoaDetectedFreeThreaded = $false
+ if ($DetectedPython -and (Get-HostMachineArch) -eq "arm64") {
+ $WoaDetectedFreeThreaded = Test-PythonFreeThreaded -PythonExe $DetectedPython.Path
+ }
+ if ($DetectedPython -and (
+ ($DetectedPython.Version -ne $WoaProbedMinor) -or
+ ($WoaDetectedFreeThreaded -ne $WoaProbedFreeThreaded))) {
+ $WoaNativeBeforeReprobe = $script:WoaNativeCudaTorch
+ $WoaProbedMinor = $DetectedPython.Version
+ $WoaProbedFreeThreaded = $WoaDetectedFreeThreaded
+ Initialize-WoaNativeCudaTorch -PythonMinor $DetectedPython.Version `
+ -FreeThreaded $WoaDetectedFreeThreaded
+ if ($script:WoaNativeCudaTorch -ne $WoaNativeBeforeReprobe) {
+ $ReselectedPython = Remove-SkippedPython (Find-CompatiblePython)
+ if ($ReselectedPython) {
+ # The reselection can hand back an interpreter the probe has not answered for, so that one is probed too; when it has no stack the probe's interpreter is kept and its answer restored.
+ $_woaReselectedFreeThreaded = $false
+ if ((Get-HostMachineArch) -eq "arm64") {
+ $_woaReselectedFreeThreaded = Test-PythonFreeThreaded -PythonExe $ReselectedPython.Path
+ }
+ if (($ReselectedPython.Version -ne $WoaProbedMinor) -or
+ ($_woaReselectedFreeThreaded -ne $WoaProbedFreeThreaded)) {
+ Initialize-WoaNativeCudaTorch -PythonMinor $ReselectedPython.Version `
+ -FreeThreaded $_woaReselectedFreeThreaded
+ if ($script:WoaNativeCudaTorch) {
+ $WoaProbedMinor = $ReselectedPython.Version
+ $WoaProbedFreeThreaded = $_woaReselectedFreeThreaded
+ $DetectedPython = $ReselectedPython
+ } else {
+ substep "windows on arm: Python $($ReselectedPython.Version) has no win_arm64 CUDA stack; keeping Python $($DetectedPython.Version), which has one." "Yellow"
+ Initialize-WoaNativeCudaTorch -PythonMinor $WoaProbedMinor `
+ -FreeThreaded $WoaProbedFreeThreaded
+ }
+ } else {
+ $DetectedPython = $ReselectedPython
+ }
+ }
+ if ($script:WoaNativeCudaTorch) {
+ step "gpu" "Windows on ARM + NVIDIA: native CUDA wheels available -- installing the ARM64 stack" "Green"
+ substep "torch index: $(Remove-IndexUrlCredentials $script:WoaTorchIndexUrl)"
+ } else {
+ substep "windows on arm: no win_arm64 CUDA stack for Python $($DetectedPython.Version) -- using the x64 stack." "Yellow"
+ }
+ }
+ }
+ # An emulated x64 python cannot load the win_arm64 wheels the probe just found.
+ if ($script:WoaNativeCudaTorch -and $DetectedPython -and $DetectedPython.Arch -eq "x86_64") {
+ substep "windows on arm: found an x64 Python $($DetectedPython.Version); installing the native ARM64 build..." "Yellow"
+ $Arm64Python = Install-PythonFromPythonOrg -Arch "arm64"
+ if ($Arm64Python -and $Arm64Python.Arch -ne "x86_64") {
+ $DetectedPython = $Arm64Python
+ step "python" "using native ARM64 Python $($DetectedPython.Version)"
+ $_woaNewFreeThreaded = Test-PythonFreeThreaded -PythonExe $DetectedPython.Path
+ if (($DetectedPython.Version -ne $WoaProbedMinor) -or
+ ($_woaNewFreeThreaded -ne $WoaProbedFreeThreaded)) {
+ $WoaProbedMinor = $DetectedPython.Version
+ $WoaProbedFreeThreaded = $_woaNewFreeThreaded
+ Initialize-WoaNativeCudaTorch -PythonMinor $DetectedPython.Version `
+ -FreeThreaded $_woaNewFreeThreaded
+ if (-not $script:WoaNativeCudaTorch) {
+ substep "windows on arm: no win_arm64 CUDA stack for Python $($DetectedPython.Version) -- using the x64 stack." "Yellow"
+ }
+ }
+ } else {
+ substep "could not install a native ARM64 Python; falling back to the x64 stack." "Yellow"
+ $script:WoaNativeCudaTorch = $false
+ $script:WoaTorchIndexUrl = $null
+ }
+ }
# ── Windows on ARM: swap a native ARM64 interpreter for x64 ──
# pyarrow and hf-transfer publish no win_arm64 wheel, so an ARM64 Python source-builds
- # both and fails deep into the run. Warn up front if x64 is unobtainable.
- if ($DetectedPython -and (Get-HostMachineArch) -eq "arm64" -and $DetectedPython.Arch -ne "x86_64") {
+ # both and fails deep into the run. Warn up front if x64 is unobtainable. Not on native.
+ if (-not $script:WoaNativeCudaTorch -and
+ $DetectedPython -and (Get-HostMachineArch) -eq "arm64" -and $DetectedPython.Arch -ne "x86_64") {
substep "windows on arm: only a native ARM64 Python $($DetectedPython.Version) was found." "Yellow"
substep "pyarrow and hf-transfer publish no win_arm64 wheels, so installing x64 Python..." "Yellow"
$X64Python = Install-X64Python
@@ -5276,6 +6427,26 @@ exit 0
$_Migrated = $true
}
+ # A migrated environment has to be ARM64 too: an x64 one has a Triton that cannot do sm_121.
+ if ($script:WoaNativeCudaTorch -and $_Migrated -and (Test-Path -LiteralPath $VenvPython)) {
+ $_woaMigPlatform = ""
+ try {
+ $_woaMigPlatform = (& $VenvPython -c "import sysconfig; print(sysconfig.get_platform())" 2>$null | Out-String).Trim().ToLowerInvariant()
+ } catch { $_woaMigPlatform = "" }
+ if ($_woaMigPlatform -ne "win-arm64") {
+ $_woaMigLabel = if ($_woaMigPlatform) { $_woaMigPlatform } else { "unknown" }
+ substep "windows on arm: the migrated environment is $_woaMigLabel, not win-arm64 --" "Yellow"
+ substep "rebuilding it as ARM64; the previous one is kept for rollback." "Yellow"
+ try {
+ Start-StudioVenvRollback -ExistingDir $VenvDir
+ # Left set, the install step below would --no-deps into an empty venv.
+ $_Migrated = $false
+ } catch {
+ substep "could not preserve it for rollback -- using the x64 stack instead." "Yellow"
+ }
+ }
+ }
+
if (-not (Test-Path -LiteralPath $VenvPython)) {
step "venv" "creating Python $($DetectedPython.Version) virtual environment"
substep "$VenvDir"
@@ -5294,6 +6465,385 @@ exit 0
try { [System.IO.File]::WriteAllText((Join-Path $VenvDir ".unsloth-studio-owned"), "") } catch {}
}
+ # The venv itself has to be ARM64 and nothing downstream re-checks: an x64 one aborts here.
+ $WoaVenvMinor = if ($DetectedPython) { $DetectedPython.Version } else { $PythonVersion }
+ if ($script:WoaNativeCudaTorch) {
+ $_woaVenvPlatform = ""
+ try {
+ $_woaVenvPlatform = (& $VenvPython -c "import sysconfig; print(sysconfig.get_platform())" 2>$null | Out-String).Trim().ToLowerInvariant()
+ } catch { $_woaVenvPlatform = "" }
+ if ($_woaVenvPlatform -ne "win-arm64") {
+ $_woaVenvLabel = if ($_woaVenvPlatform) { $_woaVenvPlatform } else { "unknown" }
+ substep "windows on arm: the existing environment is $_woaVenvLabel, not win-arm64 -- using the x64 stack." "Yellow"
+ $script:WoaNativeCudaTorch = $false
+ $script:WoaTorchIndexUrl = $null
+ } else {
+ $_woaVenvVersion = ""
+ try {
+ $_woaVenvVersion = (& $VenvPython -c "import sys; print('%d.%d' % sys.version_info[:2])" 2>$null | Out-String).Trim()
+ } catch { $_woaVenvVersion = "" }
+ if ($_woaVenvVersion -match '^\d+\.\d+$') { $WoaVenvMinor = $_woaVenvVersion }
+ $script:WoaVenvFreeThreaded = Test-PythonFreeThreaded -PythonExe $VenvPython
+ }
+ }
+
+ # Drop what a PREVIOUS run left and nothing else, or an air-gapped user's mirror goes with it.
+ $_woaOwnedPrefix = Join-Path $StudioHome "woa"
+ $_woaOwnedPrefixes = @($_woaOwnedPrefix, (Get-UvSafePath $_woaOwnedPrefix)) |
+ Where-Object { $_ } | Select-Object -Unique
+ # Split with the separator it is joined with: a whitespace split tears "C:\a b" in two.
+ $_woaJoinWith = @{ "UV_OVERRIDE" = " "; "UV_FIND_LINKS" = ","; "PIP_FIND_LINKS" = " " }
+ $_woaSplitOn = @{ "UV_OVERRIDE" = '\s+'; "UV_FIND_LINKS" = ','; "PIP_FIND_LINKS" = '\s+' }
+ foreach ($_woaResolverVar in 'UV_OVERRIDE', 'UV_FIND_LINKS', 'PIP_FIND_LINKS') {
+ $_woaInherited = [Environment]::GetEnvironmentVariable($_woaResolverVar)
+ if (-not $_woaInherited) { continue }
+ $_woaSep = $_woaSplitOn[$_woaResolverVar]
+ $_woaKept = @()
+ foreach ($_woaEntry in ($_woaInherited -split $_woaSep | ForEach-Object { $_.Trim() })) {
+ if (-not $_woaEntry) { continue }
+ $_woaOwned = $false
+ foreach ($_woaPrefix in $_woaOwnedPrefixes) {
+ if ($_woaEntry.Equals($_woaPrefix, [System.StringComparison]::OrdinalIgnoreCase) -or
+ $_woaEntry.StartsWith("$_woaPrefix\", [System.StringComparison]::OrdinalIgnoreCase) -or
+ $_woaEntry.StartsWith("$_woaPrefix/", [System.StringComparison]::OrdinalIgnoreCase)) {
+ $_woaOwned = $true
+ break
+ }
+ }
+ if (-not $_woaOwned) { $_woaKept += $_woaEntry }
+ }
+ if ($_woaKept.Count -eq 0) {
+ Remove-Item "Env:$_woaResolverVar" -ErrorAction SilentlyContinue
+ } elseif ($_woaKept.Count -ne @($_woaInherited -split $_woaSep | ForEach-Object { $_.Trim() } | Where-Object { $_ }).Count) {
+ Set-Item "Env:$_woaResolverVar" -Value ($_woaKept -join $_woaJoinWith[$_woaResolverVar])
+ }
+ }
+ if ($script:WoaNativeCudaTorch) {
+ $WoaDir = Join-Path $StudioHome "woa"
+ $script:WoaDir = $WoaDir
+ $WoaWheelDir = Join-Path $WoaDir "wheels"
+ try {
+ New-Item -ItemType Directory -Force -Path $WoaWheelDir -ErrorAction Stop | Out-Null
+ # Checked, not assumed: with a file in the way New-Item can return without creating anything.
+ if (-not (Test-Path -LiteralPath $WoaWheelDir -PathType Container)) { throw "$WoaWheelDir was not created; a file may occupy part of the path" }
+ } catch {
+ # The venv is already native ARM64: standing down here would send the torch step to an index with no win_arm64 wheel, so stop with the reason.
+ Write-StudioLine "[ERROR] windows on arm: could not create $WoaWheelDir ($($_.Exception.Message)), and the native ARM64 environment cannot resolve without it." -ForegroundColor Red
+ Write-StudioLine " Move aside whatever occupies that path, or set UNSLOTH_WOA_NATIVE=0 for the x64 stack." -ForegroundColor Yellow
+ return (Exit-InstallFailure "windows on arm: could not create $WoaWheelDir")
+ }
+ }
+ if ($script:WoaNativeCudaTorch) {
+ if ($script:WoaPyarrowSource -eq "local") {
+ $srcWheel = $env:UNSLOTH_PYARROW_WHEEL
+ $wheelName = [System.IO.Path]::GetFileName($srcWheel)
+ if ($wheelName -notlike "*.whl") {
+ $wheelName = Get-WheelFileNameFromArchive -Path $srcWheel
+ }
+ if (-not $wheelName) {
+ substep "UNSLOTH_PYARROW_WHEEL is not a readable wheel: $srcWheel" "Yellow"
+ $script:WoaNativeCudaTorch = $false
+ } else {
+ try {
+ $_woaLocalDest = Join-Path $WoaWheelDir $wheelName
+ if (-not (Test-WoaSamePath $srcWheel $_woaLocalDest)) {
+ Copy-Item -LiteralPath $srcWheel -Destination $_woaLocalDest -Force -ErrorAction Stop
+ }
+ $script:WoaPyarrowWheelName = $wheelName
+ substep "windows on arm: using the supplied pyarrow wheel $wheelName"
+ } catch {
+ substep "could not stage $srcWheel ($($_.Exception.Message))." "Yellow"
+ $script:WoaNativeCudaTorch = $false
+ }
+ }
+ } elseif ($script:WoaPyarrowSource -eq "wheelhouse") {
+ $tag = "cp" + ($WoaVenvMinor -replace '\.', '')
+ $AbiTag = Get-WoaAbiTag -PythonMinor $WoaVenvMinor -FreeThreaded ([bool]$script:WoaVenvFreeThreaded)
+ if (Test-WoaWheelhouseIsLocal $script:WoaWheelhouse) {
+ $found = Get-ChildItem -LiteralPath $script:WoaWheelhouse -Filter "pyarrow-*win_arm64.whl" -ErrorAction SilentlyContinue |
+ Where-Object {
+ (Test-WoaPyarrowWheelUsable -Name $_.Name -PyTag $tag -AbiTag $AbiTag) -and
+ (Test-ZipArchiveReadable -Path $_.FullName)
+ } | Select-Object -First 1
+ if ($found) {
+ $_woaDest = Join-Path $WoaWheelDir $found.Name
+ if (-not (Test-WoaSamePath $found.FullName $_woaDest)) {
+ Copy-Item -LiteralPath $found.FullName -Destination $_woaDest -Force
+ }
+ $script:WoaPyarrowWheelName = $found.Name
+ substep "windows on arm: using pyarrow wheel $($found.Name) from the wheelhouse"
+ } else {
+ $script:WoaNativeCudaTorch = $false
+ }
+ } else {
+ $wheelName = $null
+ try {
+ $index = [string](Invoke-RestMethod -Uri (Join-UrlPath $script:WoaWheelhouse "index.txt") -UseBasicParsing -TimeoutSec 20)
+ foreach ($match in [regex]::Matches($index, 'pyarrow-[^"''<>\s]*?win_arm64\.whl')) {
+ if (Test-WoaPyarrowWheelUsable -Name $match.Value -PyTag $tag -AbiTag $AbiTag) { $wheelName = $match.Value; break }
+ }
+ } catch {}
+ if ($wheelName) {
+ try {
+ $_woaPaDest = Join-Path $WoaWheelDir $wheelName
+ Invoke-WebRequest -Uri (Join-UrlPath $script:WoaWheelhouse $wheelName) -OutFile $_woaPaDest -UseBasicParsing -TimeoutSec 300 -ErrorAction Stop
+ # A mirror can serve a truncated body with a 200.
+ if (-not (Test-ZipArchiveReadable -Path $_woaPaDest)) {
+ Remove-Item -LiteralPath $_woaPaDest -Force -ErrorAction SilentlyContinue
+ throw "the downloaded wheel is not a readable archive"
+ }
+ $script:WoaPyarrowWheelName = $wheelName
+ substep "windows on arm: downloaded pyarrow wheel $wheelName"
+ } catch {
+ substep "could not download $wheelName ($($_.Exception.Message))." "Yellow"
+ $script:WoaNativeCudaTorch = $false
+ }
+ } else {
+ $script:WoaNativeCudaTorch = $false
+ }
+ }
+ }
+ if (-not $script:WoaNativeCudaTorch) {
+ # The venv is already native ARM64, and without pyarrow neither the CUDA index nor the x64 one can resolve for it.
+ Write-StudioLine "[ERROR] windows on arm: pyarrow could not be staged, and the native ARM64 environment cannot resolve without it." -ForegroundColor Red
+ Write-StudioLine " Re-run the installer (a transient download is the usual cause), or set UNSLOTH_WOA_NATIVE=0 for the x64 stack." -ForegroundColor Yellow
+ return (Exit-InstallFailure "windows on arm: pyarrow could not be staged")
+ }
+ }
+ if ($script:WoaNativeCudaTorch) {
+ $WoaExtraStaged = 0
+ $_woaListing = $null
+ $_woaExtraTag = "cp" + ($WoaVenvMinor -replace '\.', '')
+ $_woaExtraAbi = Get-WoaAbiTag -PythonMinor $WoaVenvMinor -FreeThreaded ([bool]$script:WoaVenvFreeThreaded)
+ if (Test-WoaWheelhouseIsLocal $script:WoaWheelhouse) {
+ $_woaListing = @(Get-ChildItem -LiteralPath $script:WoaWheelhouse -Filter "*.whl" -ErrorAction SilentlyContinue | ForEach-Object { $_.Name })
+ foreach ($wheel in @(Get-ChildItem -LiteralPath $script:WoaWheelhouse -Filter "*.whl" -ErrorAction SilentlyContinue)) {
+ if ($wheel.Name -like "pyarrow-*") { continue }
+ if ($wheel.Name -notlike "*win_arm64*" -and $wheel.Name -notlike "*-any.whl") { continue }
+ if (Test-WoaWheelhouseWheelIsRedundant -Name $wheel.Name -PyTag $_woaExtraTag -AbiTag $_woaExtraAbi) {
+ $_woaRedundantKey = (($wheel.Name -split '-')[0] -replace '[-_.]+', '-').ToLowerInvariant()
+ if (-not $script:WoaPyPIProvided.ContainsKey($_woaRedundantKey)) { $script:WoaPyPIProvided[$_woaRedundantKey] = @() }
+ $script:WoaPyPIProvided[$_woaRedundantKey] += [string]$script:WoaPyPIMatchedVersion
+ substep "windows on arm: PyPI publishes $($wheel.Name) itself -- taking it from there, not the wheelhouse."
+ # The managed copy too, or UV_FIND_LINKS still offers it and wins the tie.
+ Remove-Item -LiteralPath (Join-Path $WoaWheelDir $wheel.Name) -Force -ErrorAction SilentlyContinue
+ continue
+ }
+ # Opened, not just named: _find_links_wheel_versions reads only the filename.
+ if (-not (Test-ZipArchiveReadable -Path $wheel.FullName)) {
+ substep "windows on arm: $($wheel.Name) in the wheelhouse is not a readable wheel -- skipping it." "Yellow"
+ continue
+ }
+ try {
+ $_woaExtraDest = Join-Path $WoaWheelDir $wheel.Name
+ if (-not (Test-WoaSamePath $wheel.FullName $_woaExtraDest)) {
+ Copy-Item -LiteralPath $wheel.FullName -Destination $_woaExtraDest -Force -ErrorAction Stop
+ }
+ $WoaExtraStaged++
+ } catch {}
+ }
+ } else {
+ try {
+ $index = [string](Invoke-RestMethod -Uri (Join-UrlPath $script:WoaWheelhouse "index.txt") -UseBasicParsing -TimeoutSec 20)
+ $_woaListing = @([regex]::Matches($index, '[A-Za-z0-9_.+-]+\.whl') | ForEach-Object { $_.Value })
+ foreach ($match in [regex]::Matches($index, '[A-Za-z0-9_.+-]+\.whl')) {
+ $name = $match.Value
+ if ($name -like "pyarrow-*") { continue }
+ if ($name -notlike "*win_arm64*" -and $name -notlike "*-any.whl") { continue }
+ if (Test-WoaWheelhouseWheelIsRedundant -Name $name -PyTag $_woaExtraTag -AbiTag $_woaExtraAbi) {
+ $_woaRedundantKey = (($name -split '-')[0] -replace '[-_.]+', '-').ToLowerInvariant()
+ if (-not $script:WoaPyPIProvided.ContainsKey($_woaRedundantKey)) { $script:WoaPyPIProvided[$_woaRedundantKey] = @() }
+ $script:WoaPyPIProvided[$_woaRedundantKey] += [string]$script:WoaPyPIMatchedVersion
+ substep "windows on arm: PyPI publishes $name itself -- taking it from there, not the wheelhouse."
+ Remove-Item -LiteralPath (Join-Path $WoaWheelDir $name) -Force -ErrorAction SilentlyContinue
+ continue
+ }
+ $dest = Join-Path $WoaWheelDir $name
+ if (Test-Path -LiteralPath $dest) {
+ if (Test-ZipArchiveReadable -Path $dest) { $WoaExtraStaged++; continue }
+ Remove-Item -LiteralPath $dest -Force -ErrorAction SilentlyContinue
+ }
+ try {
+ Invoke-WebRequest -Uri (Join-UrlPath $script:WoaWheelhouse $name) -OutFile $dest -UseBasicParsing -TimeoutSec 300 -ErrorAction Stop
+ if (-not (Test-ZipArchiveReadable -Path $dest)) {
+ Remove-Item -LiteralPath $dest -Force -ErrorAction SilentlyContinue
+ continue
+ }
+ $WoaExtraStaged++
+ } catch {
+ Remove-Item -LiteralPath $dest -Force -ErrorAction SilentlyContinue
+ }
+ }
+ } catch {}
+ }
+ # Wheels an EARLIER wheelhouse staged read as hosted below; kept only when the listing could not be read (offline reuse).
+ if ($null -ne $_woaListing) {
+ $_woaKeep = @(@($_woaListing) + @($script:WoaPyarrowWheelName) | Where-Object { $_ } | ForEach-Object { $_.ToLowerInvariant() })
+ $_woaPruned = 0
+ foreach ($_woaOld in @(Get-ChildItem -LiteralPath $WoaWheelDir -Filter "*.whl" -ErrorAction SilentlyContinue)) {
+ if ($_woaKeep -notcontains $_woaOld.Name.ToLowerInvariant()) {
+ Remove-Item -LiteralPath $_woaOld.FullName -Force -ErrorAction SilentlyContinue
+ $_woaPruned++
+ }
+ }
+ if ($_woaPruned -gt 0) { substep "windows on arm: removed $_woaPruned wheel(s) an earlier wheelhouse left." }
+ }
+ if ($WoaExtraStaged -gt 0) {
+ substep "windows on arm: staged $WoaExtraStaged more wheel(s) from the wheelhouse."
+ }
+ }
+ if ($script:WoaNativeCudaTorch) {
+ $WoaOverrides = Join-Path $WoaDir "overrides.txt"
+ $WoaWheelTag = "cp" + ($WoaVenvMinor -replace '\.', '')
+ $WoaWheelAbi = Get-WoaAbiTag -PythonMinor $WoaVenvMinor -FreeThreaded ([bool]$script:WoaVenvFreeThreaded)
+ $WoaWheelStable = -not $script:WoaVenvFreeThreaded
+ $WoaWheelMinor = 0
+ if ($WoaVenvMinor -match '^\d+\.(\d+)') { $WoaWheelMinor = [int]$Matches[1] }
+ $WoaWheelNames = @{}
+ foreach ($wheel in @(Get-ChildItem -LiteralPath $WoaWheelDir -Filter "*.whl" -ErrorAction SilentlyContinue)) {
+ $parts = [System.IO.Path]::GetFileNameWithoutExtension($wheel.Name) -split '-'
+ if ($parts.Count -lt 5) { continue }
+ $platTags = $parts[-1] -split '\.'
+ if (-not (($platTags -contains 'win_arm64') -or ($platTags -contains 'any'))) { continue }
+ $abiTags = $parts[-2] -split '\.'
+ $compatible = $false
+ foreach ($pyTag in ($parts[-3] -split '\.')) {
+ # ABI too: uv rejects a cp313t wheel on a GIL interpreter.
+ if ($pyTag -eq $WoaWheelTag -and (
+ ($abiTags -contains $WoaWheelAbi) -or
+ ($WoaWheelStable -and ($abiTags -contains 'abi3')) -or
+ ($abiTags -contains 'none'))) {
+ $compatible = $true; break
+ }
+ if (($abiTags -contains 'none') -and ($pyTag -match '^py3(\d*)$')) {
+ if ([string]::IsNullOrEmpty($Matches[1]) -or ([int]$Matches[1] -le $WoaWheelMinor)) {
+ $compatible = $true; break
+ }
+ }
+ if ($WoaWheelStable -and ($abiTags -contains 'abi3') -and ($pyTag -match '^cp3(\d+)$')) {
+ if ([int]$Matches[1] -le $WoaWheelMinor) { $compatible = $true; break }
+ }
+ }
+ if (-not $compatible) { continue }
+ $_woaWheelKey = ($parts[0] -replace '[-_.]+', '-').ToLowerInvariant()
+ if (-not $WoaWheelNames.ContainsKey($_woaWheelKey)) { $WoaWheelNames[$_woaWheelKey] = @() }
+ $WoaWheelNames[$_woaWheelKey] += $parts[1]
+ }
+ # Still available for win_arm64, or the drop list below excludes it on ARM64 entirely.
+ foreach ($_woaProvided in $script:WoaPyPIProvided.Keys) {
+ if (-not $WoaWheelNames.ContainsKey($_woaProvided)) { $WoaWheelNames[$_woaProvided] = @() }
+ $WoaWheelNames[$_woaProvided] += @($script:WoaPyPIProvided[$_woaProvided] | Where-Object { $_ })
+ }
+ # None of these has a win_arm64 wheel or a buildable sdist; httpx negotiates around brotli.
+ $WoaDropCandidates = @(
+ "hf-transfer", "hf_transfer", "xformers", "torchcodec",
+ "brotli", "brotlicffi"
+ )
+ if (-not $script:WoaTorchAudio) { $WoaDropCandidates += "torchaudio" }
+ # Floors the RELEASED metadata puts on a drop candidate: below one, keep the drop.
+ $WoaDropFloors = @{ "xformers" = "0.0.22.post7" }
+ $WoaOverrideLines = @(
+ '# Generated by install.ps1 for Windows on ARM (win_arm64). See the WoA block there.'
+ )
+ $WoaReported = @{}
+ foreach ($candidate in $WoaDropCandidates) {
+ $key = ($candidate -replace '[-_.]+', '-').ToLowerInvariant()
+ $_woaHosted = $false
+ if ($WoaWheelNames.ContainsKey($key)) {
+ $_woaFloor = $WoaDropFloors[$key]
+ if (-not $_woaFloor) { $_woaHosted = $true }
+ else {
+ foreach ($_woaHostedVer in $WoaWheelNames[$key]) {
+ if (Test-WoaVersionAtLeast -Version $_woaHostedVer -Floor $_woaFloor) { $_woaHosted = $true; break }
+ }
+ if (-not $_woaHosted -and -not $WoaReported.ContainsKey($key)) {
+ $WoaReported[$key] = $true
+ substep "windows on arm: the wheelhouse $key is below the required $_woaFloor -- keeping the drop." "Yellow"
+ }
+ }
+ }
+ if ($_woaHosted) {
+ if (-not $WoaReported.ContainsKey($key)) {
+ $WoaReported[$key] = $true
+ substep "windows on arm: keeping $key (the wheelhouse provides a win_arm64 wheel)."
+ }
+ continue
+ }
+ $WoaOverrideLines += "$candidate ; platform_machine == `"AMD64`""
+ }
+ # Released unsloth metadata caps torch below the only win_arm64 CUDA build (a 2.15 nightly).
+ $WoaOverrideLines += 'torch>=2.4'
+ $WoaOverrideLines += 'torchvision>=0.19'
+ # Without this uv takes the newest pyarrow on PyPI, an sdist here. For the PyPI route too.
+ if ($script:WoaPyarrowWheelName -and $script:WoaPyarrowWheelName -match '^pyarrow-([^-]+)-') {
+ $WoaOverrideLines += "pyarrow==$($Matches[1])"
+ }
+ # uv COMBINES override files and two naming one package is an error: no overwrite, no append.
+ $_woaOwnNames = @{}
+ foreach ($_woaLine in $WoaOverrideLines) {
+ if ($_woaLine -match '^\s*(#|$)') { continue }
+ $_woaName = (($_woaLine -split '[\s<>=!~;@\[]', 2)[0]).Trim()
+ if ($_woaName) { $_woaOwnNames[($_woaName -replace '[-_.]+', '-').ToLowerInvariant()] = $true }
+ }
+ # Folding is the LAST resort: copying a line moves the base its relative paths resolve on.
+ $_woaKeepFiles = @()
+ $_woaSessionLines = @()
+ if ($env:UV_OVERRIDE) {
+ foreach ($_woaOvFile in ($env:UV_OVERRIDE -split '\s+' | Where-Object { $_ })) {
+ if (-not (Test-Path -LiteralPath $_woaOvFile -PathType Leaf)) { continue }
+ try { $_woaOvFull = Convert-Path -LiteralPath $_woaOvFile } catch { continue }
+ $_woaOvEntries = @(Get-WoaRequirementEntries -Path $_woaOvFull)
+ $_woaOvConflicts = $false
+ foreach ($_woaOvEntry in $_woaOvEntries) {
+ $_woaOvName = ((($_woaOvEntry.Line -split '[\s<>=!~;@\[]', 2)[0]).Trim() -replace '[-_.]+', '-').ToLowerInvariant()
+ if ($_woaOvName -and $_woaOwnNames.ContainsKey($_woaOvName)) { $_woaOvConflicts = $true; break }
+ }
+ if (-not $_woaOvConflicts) {
+ $_woaKeepFiles += $_woaOvFull
+ continue
+ }
+ foreach ($_woaOvEntry in $_woaOvEntries) {
+ $_woaOvName = ((($_woaOvEntry.Line -split '[\s<>=!~;@\[]', 2)[0]).Trim() -replace '[-_.]+', '-').ToLowerInvariant()
+ if ($_woaOvName -and $_woaOwnNames.ContainsKey($_woaOvName)) { continue }
+ $_woaSessionLines += (Resolve-WoaOverrideLine -Line $_woaOvEntry.Line -BaseDir $_woaOvEntry.BaseDir)
+ }
+ }
+ }
+ # No BOM: uv reads these as plain requirements files.
+ [System.IO.File]::WriteAllLines($WoaOverrides, [string[]]$WoaOverrideLines, (New-Object System.Text.UTF8Encoding($false)))
+ $_woaOverrideValue = @(Get-UvSafePath $WoaOverrides)
+ foreach ($_woaKeepFile in $_woaKeepFiles) { $_woaOverrideValue += (Get-UvSafePath $_woaKeepFile) }
+ # Folded caller lines go to a per-run file, never the persistent one setup.ps1 restores: their credentials and policy must not outlive this run.
+ $_woaSessionFile = Join-Path (Split-Path -Parent $WoaOverrides) "overrides.session.txt"
+ Remove-Item -LiteralPath $_woaSessionFile -Force -ErrorAction SilentlyContinue
+ if ($_woaSessionLines.Count -gt 0) {
+ [System.IO.File]::WriteAllLines($_woaSessionFile, [string[]]$_woaSessionLines, (New-Object System.Text.UTF8Encoding($false)))
+ $script:WoaSessionOverrides = $_woaSessionFile
+ $_woaOverrideValue += (Get-UvSafePath $_woaSessionFile)
+ }
+ # Under `irm | iex` these are the caller's own session variables: snapshotted once here and put back when the installer returns.
+ if ($null -eq $script:WoaResolverEnvSaved) {
+ $script:WoaResolverEnvSaved = @{
+ UV_OVERRIDE = $env:UV_OVERRIDE; UV_FIND_LINKS = $env:UV_FIND_LINKS; PIP_FIND_LINKS = $env:PIP_FIND_LINKS
+ }
+ }
+ $env:UV_OVERRIDE = ($_woaOverrideValue -join " ")
+ # Additive, ours first to win a tie. UV_FIND_LINKS is comma-separated, PIP_FIND_LINKS not.
+ $_woaCallerUvLinks = $env:UV_FIND_LINKS
+ $_woaCallerPipLinks = $env:PIP_FIND_LINKS
+ $env:UV_FIND_LINKS = if ($_woaCallerUvLinks) { "$WoaWheelDir,$_woaCallerUvLinks" } else { $WoaWheelDir }
+ $_woaSafeWheelDir = Get-UvSafePath $WoaWheelDir
+ $env:PIP_FIND_LINKS = if ($_woaCallerPipLinks) { "$_woaSafeWheelDir $_woaCallerPipLinks" } else { $_woaSafeWheelDir }
+ # install_python_stack.py falls back to pip when `uv` is missing, and pip has no UV_OVERRIDE.
+ $uvDir = $null
+ try { $uvDir = [System.IO.Path]::GetDirectoryName($script:UvExe) } catch {}
+ if ($uvDir -and (Test-Path -LiteralPath $uvDir -PathType Container) -and ($env:PATH -notlike "*$uvDir*")) {
+ $env:PATH = "$uvDir;$env:PATH"
+ }
+ step "windows on arm" "native ARM64 CUDA stack selected"
+ substep "overrides: $WoaOverrides"
+ }
+
if (-not (Test-VenvPythonReady -PythonExe $VenvPython)) {
$recordedBaseHome = Get-VenvBaseHome -VenvRoot $VenvDir
Write-StudioLine "[ERROR] The managed Python interpreter is missing or cannot be launched." -ForegroundColor Red
@@ -5350,41 +6900,6 @@ exit 0
}
}
- # ── Bound nvidia-smi so a wedged driver cannot hang the installer. ──
- 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; the human-readable probes keep the default merge.
- [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 ""
- }
- }
-
# ── A driverless nvidia-smi exits 0 listing no GPU, so require a "GPU <n>:" row. ──
# 124 is what Invoke-NvidiaSmiBounded reports when it had to kill the probe. Recorded
# so the banner below can skip a second query: detection already waited out the full
@@ -6412,6 +7927,10 @@ exit 0
if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_FAMILY)) {
return "$baseUrl/$($env:UNSLOTH_TORCH_INDEX_FAMILY.Trim().Trim('/'))"
}
+ # The native win_arm64 CUDA index was probed and paired up front; nothing below it applies.
+ if ($script:WoaNativeCudaTorch -and $script:WoaTorchIndexUrl) {
+ return $script:WoaTorchIndexUrl
+ }
$major = $null; $minor = $null; $caps = @()
if ($NvidiaSmiExe) {
try {
@@ -6442,39 +7961,6 @@ exit 0
return "$baseUrl/$(Get-CudaFamilyCappedForPreTuring $family $NvidiaSmiExe $caps)"
}
- function Remove-IndexUrlCredentials {
- param([string]$Url)
- # Ordinal, not culture-aware: on non-English locales (e.g. th-TH) linguistic
- # IndexOf treats "://" as ignorable, mis-locates it, and crashes Substring (issue #7279).
- $sep = $Url.IndexOf('://', [System.StringComparison]::Ordinal)
- if ($sep -lt 0) { return $Url }
- $scheme = $Url.Substring(0, $sep)
- $rest = $Url.Substring($sep + 3)
- # Drop query / fragment (may hold auth tokens).
- $q = $rest.IndexOfAny([char[]]('?', '#'))
- if ($q -ge 0) { $rest = $rest.Substring(0, $q) }
- $slash = $rest.IndexOf('/', [System.StringComparison]::Ordinal)
- $authority = if ($slash -ge 0) { $rest.Substring(0, $slash) } else { $rest }
- $at = $authority.LastIndexOf('@', [System.StringComparison]::Ordinal)
- $host_ = if ($at -ge 0) { $authority.Substring($at + 1) } else { $authority }
- if ($slash -ge 0) { return "${scheme}://${host_}$($rest.Substring($slash))" }
- return "${scheme}://${host_}"
- }
-
- # Append a path to a URL that may carry ?query / #fragment auth. A private mirror is
- # allowed to be "https://mirror/whl?token=abc", and a naive "$base/$leaf" put the leaf
- # INSIDE the token value, leaving the path still /whl -- so the tokenized mirror this
- # exists to honour was the one case that could not resolve a wheel.
- function Join-UrlPath {
- param([string]$Base, [string]$Path)
- if ([string]::IsNullOrWhiteSpace($Base)) { return $Path }
- $cut = $Base.IndexOfAny([char[]]('?', '#'))
- if ($cut -lt 0) { return "$($Base.TrimEnd('/'))/$Path" }
- $head = $Base.Substring(0, $cut).TrimEnd('/')
- $tail = $Base.Substring($cut)
- return "$head/$Path$tail"
- }
-
# ── Torch flavor helpers (to repair a stale CPU / wrong-CUDA wheel) ──
# torch.__version__ -> flavor tag (cuXXX / rocm / cpu); untagged wheel = cpu,
# matching setup.ps1's stale-venv parse.
@@ -6971,32 +8457,17 @@ exit 0
$lines = @($pins | Where-Object { $_ -match '^torch' })
if ($lines.Count -eq 0 -or $lines[0] -notmatch '^torch==') { return $null }
# --overrides replaces any UV_OVERRIDE env file, so fold caller files in, minus their trio.
- $ovDirs = @()
+ # REBASED as they are folded: uv resolves relative references against the containing file.
if ($env:UV_OVERRIDE) {
foreach ($ovFile in ($env:UV_OVERRIDE -split '\s+' | Where-Object { $_ })) {
- if (Test-Path -LiteralPath $ovFile -PathType Leaf) {
- $ovFull = (Convert-Path -LiteralPath $ovFile)
- # ReadAllLines, not Get-Content: PS 5.1 decodes a BOM-less file with the ANSI
- # code page, turning a non-ASCII path into mojibake the UTF-8 write preserves.
- $lines += @([System.IO.File]::ReadAllLines($ovFull) | Where-Object {
- $_ -notmatch '^\s*torch(vision|audio)?([\s<>=!~;@[]|$)'
- })
- $ovDirs += (Split-Path -Parent $ovFull)
- }
- }
- }
- # uv resolves an override's relative references against THAT file's dir, so write the
- # merge beside the caller's override; %TEMP% when there is none, several dirs, or read-only.
- $f = $null
- $ovDirs = @($ovDirs | Sort-Object -Unique)
- if ($ovDirs.Count -eq 1) {
- try {
- $candidate = Join-Path $ovDirs[0] ("unsloth-torch-overrides-" + [guid]::NewGuid().ToString("N") + ".txt")
- New-Item -ItemType File -Path $candidate -ErrorAction Stop | Out-Null
- $f = $candidate
- } catch { $f = $null }
+ if (-not (Test-Path -LiteralPath $ovFile -PathType Leaf)) { continue }
+ foreach ($ovEntry in (Get-WoaRequirementEntries -Path $ovFile)) {
+ if ($ovEntry.Line -match '^\s*torch(vision|audio)?([\s<>=!~;@[]|$)') { continue }
+ $lines += (Resolve-WoaOverrideLine -Line $ovEntry.Line -BaseDir $ovEntry.BaseDir)
+ }
+ }
}
- if (-not $f) { $f = [System.IO.Path]::GetTempFileName() }
+ $f = [System.IO.Path]::GetTempFileName()
# Track it the moment it exists: WriteAllText can throw and the outer cleanup would have
# no path to remove, leaving a partial copy, authenticated URLs included, on disk.
$script:TorchOverridesFile = $f
@@ -7214,11 +8685,47 @@ exit 0
# resolve a mismatched 2.11.0 build. Mirrors install.sh.
# The hoisted trio, so the vetted route window and the installed specs cannot drift.
$_torchSpecs = @($_pinTorchSpec, $_pinVisionSpec, $_pinAudioSpec)
+ $_torchExtraArgs = @()
if ($VenvPlatform -eq "win-arm64") {
- substep "windows on arm: skipping torchaudio (upstream publishes no"
- substep "win_arm64 wheel); torch and torchvision install normally."
+ if (-not $script:WoaTorchAudio) {
+ substep "windows on arm: skipping torchaudio (upstream publishes no"
+ substep "win_arm64 wheel); torch and torchvision install normally."
+ }
$_torchSpecs = @($_pinTorchSpec, $_pinVisionSpec)
}
+ # NVIDIA's out-of-tree builds sit above the usual ceiling, so lift it. Floors stay.
+ if ($script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64") {
+ # Pinned exactly with its local +cu tag: that version is on no other index.
+ $_torchSpecs = @()
+ $_torchSpecs += if ($script:WoaTorchWheelVersion) { "torch==$($script:WoaTorchWheelVersion)" } else { "torch>=2.4" }
+ $_torchSpecs += if ($script:WoaVisionWheelVersion) { "torchvision==$($script:WoaVisionWheelVersion)" } else { "torchvision>=0.19" }
+ if ($script:WoaTorchAudio) {
+ $_torchSpecs += if ($script:WoaAudioWheelVersion) { "torchaudio==$($script:WoaAudioWheelVersion)" } else { "torchaudio>=2.4" }
+ substep "windows on arm: this index publishes torchaudio; installing the full trio."
+ }
+ # NVIDIA's index publishes only the trio; the shared dependencies come from the index the caller's resolver policy names, public PyPI by default, or the wheelhouse alone under no-index.
+ $_woaDependencyIndexArgs = @(Get-WoaDependencyIndexArgs)
+ $_torchExtraArgs = @("--index-strategy", "unsafe-best-match") + $_woaDependencyIndexArgs
+ # Invoke-InstallCommand clears UV_FIND_LINKS beside the other inherited index settings, so the staged wheelhouse is named on the command line.
+ if ($script:WoaDir) {
+ $_torchExtraArgs += @("--find-links", (Get-UvSafePath (Join-Path $script:WoaDir "wheels")))
+ }
+ if ($_woaDependencyIndexArgs.Count -eq 0) {
+ substep "windows on arm: no-index is set, so torch's dependencies must come from the find-links wheelhouse."
+ } elseif ($_woaDependencyIndexArgs -notcontains "https://pypi.org/simple") {
+ substep "windows on arm: torch's dependencies resolve from the configured index, not public PyPI."
+ }
+ # Only a prerelease channel needs this. The URL spelling is a second signal.
+ if ($script:WoaTorchIsPrerelease -or ($script:WoaTorchIndexUrl -match 'nightly')) {
+ $_torchExtraArgs = @("--prerelease=allow") + $_torchExtraArgs
+ substep "windows on arm: allowing prerelease torch (this index publishes win_arm64 CUDA wheels as nightlies)."
+ }
+ }
+ # Release preservation cannot run here: its kept specs have no win_arm64 build.
+ if ($script:PrevTorchPin -and $script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64") {
+ $script:PrevTorchPin = $null
+ Remove-Item Env:UNSLOTH_KEPT_TORCH -ErrorAction SilentlyContinue
+ }
if ($script:PrevTorchPin) {
$_keptTorch = $script:PrevTorchPin.TorchSpec; $_keptVision = $script:PrevTorchPin.VisionSpec; $_keptAudio = $script:PrevTorchPin.AudioSpec
$_keptSpecs = @($_keptTorch, $_keptVision)
@@ -7231,7 +8738,42 @@ exit 0
}
}
if (-not $script:PrevTorchPin) {
- $torchInstallExit = Invoke-InstallCommandRetry -Label "install PyTorch" { & $script:UvExe pip install --python $VenvPython @_torchSpecs --default-index $TorchIndexUrl }
+ $_woaOverrideSaved = $null
+ $_woaOverrideSwapped = $false
+ $_woaOverrideTemps = @()
+ $_woaCutoffSaved = @{}
+ if ($script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64" -and $env:UV_OVERRIDE) {
+ $_woaOverrideSaved = $env:UV_OVERRIDE
+ $_woaStep = New-WoaTorchStepOverrideValue -Value $_woaOverrideSaved -Dir $script:WoaDir
+ $env:UV_OVERRIDE = $_woaStep.Value
+ $_woaOverrideTemps = @($_woaStep.Temps)
+ $_woaOverrideSwapped = $true
+ }
+ if ($script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64") {
+ # The probe read the index page, which carries no upload dates, and the pin is exact: an upload cutoff would reject the selected wheel. Only this one command.
+ foreach ($_woaCutoffName in @("UV_EXCLUDE_NEWER", "UV_EXCLUDE_NEWER_PACKAGE")) {
+ $_woaCutoffValue = [string](Get-Item "Env:$_woaCutoffName" -ErrorAction SilentlyContinue).Value
+ if ($_woaCutoffValue) {
+ $_woaCutoffSaved[$_woaCutoffName] = $_woaCutoffValue
+ Remove-Item "Env:$_woaCutoffName" -ErrorAction SilentlyContinue
+ substep "windows on arm: $_woaCutoffName is not applied to the exact CUDA pin (the index carries no upload dates)."
+ }
+ }
+ # --no-index ignores every registry index, the selected CUDA one included, so it yields for this one command: torch from the index the probe chose, dependencies from the wheelhouse.
+ $_woaNoIndexValue = [string](Get-Item "Env:UV_NO_INDEX" -ErrorAction SilentlyContinue).Value
+ if ($_woaNoIndexValue -and ($_woaNoIndexValue.Trim().ToLowerInvariant() -notin @("", "0", "false"))) {
+ $_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 {
+ $torchInstallExit = Invoke-InstallCommandRetry -Label "install PyTorch" { & $script:UvExe pip install --python $VenvPython @_torchSpecs --default-index $TorchIndexUrl @_torchExtraArgs }
+ } finally {
+ if ($_woaOverrideSwapped) { $env:UV_OVERRIDE = $_woaOverrideSaved }
+ foreach ($_woaTmp in $_woaOverrideTemps) { Remove-Item -LiteralPath $_woaTmp -Force -ErrorAction SilentlyContinue }
+ foreach ($_woaCutoffName in @($_woaCutoffSaved.Keys)) { Set-Item "Env:$_woaCutoffName" $_woaCutoffSaved[$_woaCutoffName] }
+ }
}
if ($torchInstallExit -ne 0) {
Write-StudioLine "[ERROR] Failed to install PyTorch (exit code $torchInstallExit)" -ForegroundColor Red
@@ -7595,6 +9137,25 @@ sys.exit(2 if conflict else (0 if installed else 1))
}
}
+ # setup.ps1 is fetched live while `unsloth` comes from PyPI, so it can predate ARM64 support. Tested by capability, not version.
+ if ($script:WoaNativeCudaTorch) {
+ $WoaStudioSetup = $null
+ try {
+ $WoaStudioSetup = (& $VenvPython -c "import pathlib, studio; print(pathlib.Path(studio.__file__).parent / 'setup.ps1')" 2>$null | Select-Object -First 1)
+ } catch {}
+ $WoaStudioAware = $false
+ if ($WoaStudioSetup -and (Test-Path -LiteralPath $WoaStudioSetup -PathType Leaf)) {
+ $WoaStudioAware = [bool](Select-String -LiteralPath $WoaStudioSetup -Pattern 'WinArm64Venv' -Quiet)
+ }
+ if (-not $WoaStudioAware) {
+ Write-StudioLine "[ERROR] This unsloth release predates Windows-on-ARM support." -ForegroundColor Red
+ Write-StudioLine " The installed studio setup would replace the ARM64 CUDA PyTorch just installed" -ForegroundColor Yellow
+ Write-StudioLine " with a build that has no win_arm64 wheel, leaving the environment without torch." -ForegroundColor Yellow
+ Write-StudioLine " Upgrade to a newer unsloth, or re-run with UNSLOTH_WOA_NATIVE=0 for the x64 path." -ForegroundColor Yellow
+ return (Exit-InstallFailure "installed unsloth has no Windows-on-ARM support")
+ }
+ }
+
# ── Run studio setup ──
# setup.ps1 will handle installing Git, CMake, Visual Studio Build Tools,
# CUDA Toolkit, and other dependencies automatically via winget. Node.js is
@@ -7678,6 +9239,14 @@ sys.exit(2 if conflict else (0 if installed else 1))
$hadPreviousInstallRollbackManaged = ($null -ne $previousInstallRollbackManaged)
$previousSetupPython = $env:UNSLOTH_SETUP_PYTHON
$hadPreviousSetupPython = ($null -ne $previousSetupPython)
+ $previousWoaHasTorchaudio = $env:UNSLOTH_WOA_HAS_TORCHAUDIO
+ $hadPreviousWoaHasTorchaudio = ($null -ne $previousWoaHasTorchaudio)
+ $previousWoaTorchPrerelease = $env:UNSLOTH_WOA_TORCH_PRERELEASE
+ $hadPreviousWoaTorchPrerelease = ($null -ne $previousWoaTorchPrerelease)
+ $previousWoaSelectedTorchIndex = $env:UNSLOTH_WOA_SELECTED_TORCH_INDEX
+ $hadPreviousWoaSelectedTorchIndex = ($null -ne $previousWoaSelectedTorchIndex)
+ $previousWoaPyPIProvided = $env:UNSLOTH_WOA_PYPI_PROVIDED
+ $hadPreviousWoaPyPIProvided = ($null -ne $previousWoaPyPIProvided)
try {
$env:SKIP_STUDIO_BASE = "1"
$env:STUDIO_PACKAGE_NAME = $PackageName
@@ -7691,6 +9260,22 @@ sys.exit(2 if conflict else (0 if installed else 1))
$env:UNSLOTH_INSTALLER_TORCH_TAG = if ($SkipTorch) { "" } else {
[string](Get-ExpectedTorchFlavorTag -TorchIndexUrl $TorchIndexUrl -ROCmIndexUrl $ROCmIndexUrl)
}
+ # Windows on ARM: whether this run's index paired a torchaudio, whether that torch is a prerelease (the URL alone misses a quiet mirror), and WHICH index. Not UNSLOTH_WOA_TORCH_INDEX_URL, which a later run would read as a pin.
+ $env:UNSLOTH_WOA_HAS_TORCHAUDIO = if ($script:WoaNativeCudaTorch -and $script:WoaTorchAudio) { "1" } else { "0" }
+ $env:UNSLOTH_WOA_TORCH_PRERELEASE = if ($script:WoaNativeCudaTorch -and $script:WoaTorchIsPrerelease) { "1" } else { "0" }
+ if ($script:WoaNativeCudaTorch -and $script:WoaTorchIndexUrl) {
+ $env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $script:WoaTorchIndexUrl
+ } else {
+ Remove-Item Env:UNSLOTH_WOA_SELECTED_TORCH_INDEX -ErrorAction SilentlyContinue
+ }
+ # Wheelhouse wheels discarded because PyPI serves the same version: the managed copy is gone, so this is the only record install_python_stack.py has that they resolve.
+ $_woaProvidedPairs = @()
+ foreach ($_woaProvidedKey in @($script:WoaPyPIProvided.Keys | Sort-Object)) {
+ foreach ($_woaProvidedVer in @($script:WoaPyPIProvided[$_woaProvidedKey] | Where-Object { $_ } | Select-Object -Unique)) {
+ $_woaProvidedPairs += "$_woaProvidedKey==$_woaProvidedVer"
+ }
+ }
+ $env:UNSLOTH_WOA_PYPI_PROVIDED = ($_woaProvidedPairs -join " ")
# Tauri desktop app bundles its own frontend — skip Node/npm/frontend build
$env:SKIP_STUDIO_FRONTEND = if ($TauriMode) { "1" } else { "0" }
# Always set STUDIO_LOCAL_INSTALL explicitly to avoid stale values from
@@ -7834,6 +9419,14 @@ sys.exit(2 if conflict else (0 if installed else 1))
} else {
Remove-Item Env:UNSLOTH_SETUP_PYTHON -ErrorAction SilentlyContinue
}
+ foreach ($_woaPair in @(
+ @("UNSLOTH_WOA_HAS_TORCHAUDIO", $hadPreviousWoaHasTorchaudio, $previousWoaHasTorchaudio),
+ @("UNSLOTH_WOA_TORCH_PRERELEASE", $hadPreviousWoaTorchPrerelease, $previousWoaTorchPrerelease),
+ @("UNSLOTH_WOA_SELECTED_TORCH_INDEX", $hadPreviousWoaSelectedTorchIndex, $previousWoaSelectedTorchIndex),
+ @("UNSLOTH_WOA_PYPI_PROVIDED", $hadPreviousWoaPyPIProvided, $previousWoaPyPIProvided))) {
+ if ($_woaPair[1]) { Set-Item "Env:$($_woaPair[0])" $_woaPair[2] }
+ else { Remove-Item "Env:$($_woaPair[0])" -ErrorAction SilentlyContinue }
+ }
}
# $null, not a code: Application Control refused to create the process, so there is
# no exit code to report. Checked first because in PowerShell $null -ne 0 is true,
@@ -8104,10 +9697,21 @@ sys.exit(2 if conflict else (0 if installed else 1))
}
# Under `irm | iex` the script scope IS the caller's session; an earlier value must not leak.
+$script:WoaResolverEnvSaved = $null
+$script:WoaSessionOverrides = $null
$script:TorchOverridesFile = $null
try {
Install-UnslothStudio @args
} finally {
+ # The resolver variables exported for the native ARM64 stack are process-scoped, so restore the caller's: their own `uv pip` would otherwise keep resolving with Studio's overrides and wheelhouse.
+ if ($script:WoaResolverEnvSaved) {
+ foreach ($_woaEnvName in @($script:WoaResolverEnvSaved.Keys)) {
+ $_woaEnvValue = $script:WoaResolverEnvSaved[$_woaEnvName]
+ if ($null -eq $_woaEnvValue) { Remove-Item "Env:$_woaEnvName" -ErrorAction SilentlyContinue }
+ else { Set-Item "Env:$_woaEnvName" $_woaEnvValue }
+ }
+ $script:WoaResolverEnvSaved = $null
+ }
# UNSLOTH_KEPT_TORCH is a process-scoped handoff, and the session outlives the installer.
Remove-Item Env:UNSLOTH_KEPT_TORCH -ErrorAction SilentlyContinue
# The generated overrides file copies the caller's UV_OVERRIDE contents; never leave it.
@@ -8115,4 +9719,8 @@ try {
Remove-Item -LiteralPath $script:TorchOverridesFile -Force -ErrorAction SilentlyContinue
$script:TorchOverridesFile = $null
}
+ if ($script:WoaSessionOverrides) {
+ Remove-Item -LiteralPath $script:WoaSessionOverrides -Force -ErrorAction SilentlyContinue
+ $script:WoaSessionOverrides = $null
+ }
}
diff --git a/pyproject.toml b/pyproject.toml
index bf8d4404bde..0ef1175f15f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -149,7 +149,9 @@ studio = [
"pydantic==2.13.4",
"packaging==26.3",
"matplotlib==3.10.9",
- "pandas==2.3.3",
+ # win_arm64 pandas wheels start at 3.0; the 3.11 floor is pandas 3's own requires-python.
+ "pandas==2.3.3 ; sys_platform != 'win32' or platform_machine != 'ARM64' or python_version < '3.11'",
+ "pandas>=3.0,<4 ; sys_platform == 'win32' and platform_machine == 'ARM64' and python_version >= '3.11'",
"nest_asyncio==1.6.0",
"datasets==4.3.0",
"pyjwt==2.13.0",
@@ -161,15 +163,21 @@ studio = [
"diceware==1.0.1",
"ddgs==9.14.4 ; python_version >= '3.10'",
"ddgs==9.8.0 ; python_version < '3.10'",
- "cryptography>=42.0.0",
+ "cryptography>=42.0.0; sys_platform != 'win32' or platform_machine != 'ARM64'",
+ # Windows on ARM: 46.0.7 publishes no win_arm64 wheel and the sdist needs Rust.
+ "cryptography>=42.0.0,<=46.0.3; sys_platform == 'win32' and platform_machine == 'ARM64'",
"boto3>=1.34.0",
"httpx>=0.27.0",
"fastmcp>=3.0.2",
"gguf==0.19.0 ; python_version >= '3.10'",
"gguf==0.18.0 ; python_version < '3.10'",
"av>=12.3.0",
- "sqlite-vec==0.1.9",
- "pymupdf==1.27.2.3",
+ # No win_arm64 wheel and no sdist either, so it cannot be floored or built. Dropped rather
+ # than pinned: the RAG store already treats a missing sqlite_vec as "RAG unavailable".
+ "sqlite-vec==0.1.9 ; sys_platform != 'win32' or platform_machine != 'ARM64'",
+ # Mirrors studio.txt: pymupdf publishes a win_arm64 wheel from 1.28 only.
+ "pymupdf==1.27.2.3 ; sys_platform != 'win32' or platform_machine != 'ARM64'",
+ "pymupdf>=1.28.2 ; sys_platform == 'win32' and platform_machine == 'ARM64'",
"pymupdf4llm==0.3.4",
"python-docx==1.2.0",
"markdown-it-py>=3.0",
@@ -177,7 +185,9 @@ studio = [
triton = [
"triton>=3.0.0 ; ('linux' in sys_platform)",
+ # triton-windows has win_arm64 wheels from 3.8.0.post28, so a floor works here, not a marker.
"triton-windows ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
+ "triton-windows>=3.8.0.post28 ; (sys_platform == 'win32') and platform_machine == 'ARM64'",
]
huggingfacenotorch = [
@@ -194,7 +204,9 @@ huggingfacenotorch = [
"accelerate>=0.34.1",
"peft>=0.18.0,!=0.11.0",
"huggingface_hub>=0.34.0",
- "hf_transfer",
+ # A Rust extension with no win_arm64 wheel. huggingface_hub imports it only under
+ # HF_HUB_ENABLE_HF_TRANSFER=1, and hf_xet ships win_arm64 and covers fast downloads.
+ "hf_transfer ; sys_platform != 'win32' or platform_machine != 'ARM64'",
# 0.39 is the floor the diffusion stack already assumes: Krea2Pipeline (the Krea 2
# workflow raises without it), the cache_context child-registry behavior, and the
# Flux2 / Z-Image pipelines. An unversioned entry let an upgrade keep an older
@@ -287,8 +299,11 @@ huggingface = [
# handles instead.
windows = [
"unsloth[huggingface]",
+ # bitsandbytes ships a win_arm64 wheel from 0.50.0, so this row covers it.
"bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0 ; (sys_platform == 'win32')",
- "xformers>=0.0.22.post7 ; (sys_platform == 'win32')",
+ # No win_arm64 wheel and no sdist that builds without CUDA's Windows-ARM toolchain, so this
+ # row would fail the whole extra. Torch's SDPA is the fallback.
+ "xformers>=0.0.22.post7 ; (sys_platform == 'win32') and platform_machine != 'ARM64'",
]
base = [
"unsloth[huggingface]",
diff --git a/studio/backend/plugins/data-designer-unstructured-seed/pyproject.toml b/studio/backend/plugins/data-designer-unstructured-seed/pyproject.toml
index c9d988bd9d8..82755bcb429 100644
--- a/studio/backend/plugins/data-designer-unstructured-seed/pyproject.toml
+++ b/studio/backend/plugins/data-designer-unstructured-seed/pyproject.toml
@@ -12,7 +12,8 @@ description = "Local Data Designer unstructured seed reader plugin"
requires-python = ">=3.11"
dependencies = [
"data-designer-engine>=0.5.4,<0.6",
- "pandas>=2,<3",
+ # <4: Windows on ARM installs pandas 3 (constraints.txt), and this plugin only reads and writes parquet.
+ "pandas>=2,<4",
"pymupdf>=1.24.0",
"pymupdf4llm>=0.0.17",
"mammoth>=1.8.0",
diff --git a/studio/backend/requirements/extras.txt b/studio/backend/requirements/extras.txt
index 41f8d72a57c..2a8261051a1 100644
--- a/studio/backend/requirements/extras.txt
+++ b/studio/backend/requirements/extras.txt
@@ -2,7 +2,9 @@
flatbuffers==25.12.19
# Also needed by sentence_transformers (installed with --no-deps in extras-no-deps.txt);
# librosa pulls it in too, but is skipped in no-torch mode.
-scikit-learn==1.7.1
+# scikit-learn publishes win_arm64 wheels from 1.8 only; 1.7.1 would source-build there.
+scikit-learn==1.7.1; sys_platform != "win32" or platform_machine != "ARM64"
+scikit-learn>=1.8.0; sys_platform == "win32" and platform_machine == "ARM64"
# Additional extras
jiwer==4.0.0 # WER/CER metrics for vision OCR save-merge benchmarks
@@ -18,7 +20,9 @@ openai-whisper==20250625
# av<16 because 16+ builds its macOS arm64 wheels against macosx_14_0 and so has
# no installable wheel on macOS 13. Pinning past the cap makes that leg
# unsatisfiable. Lift both together.
-av==15.1.0
+# See constraints.txt: win_arm64 av wheels start at 17.0.0.
+av==15.1.0; sys_platform != "win32" or platform_machine != "ARM64"
+av>=17.0.0; sys_platform == "win32" and platform_machine == "ARM64"
uroman==1.3.1.1 # 4.0 MB - used for Outetts.
# 19.9 MB - used for Outetts. No release ships a macOS cp314 wheel (0.996.12 added
# cp314 for Linux and win_amd64 only), so a 3.14 macOS host has no binary candidate
diff --git a/studio/backend/requirements/no-torch-runtime.txt b/studio/backend/requirements/no-torch-runtime.txt
index 190a7c1c0f8..b303b5fb37a 100644
--- a/studio/backend/requirements/no-torch-runtime.txt
+++ b/studio/backend/requirements/no-torch-runtime.txt
@@ -48,7 +48,8 @@ accelerate>=0.34.1
peft>=0.18.0,!=0.11.0
huggingface_hub>=1.23.0,<2.0; python_version >= "3.10"
huggingface_hub==0.36.2; python_version < "3.10"
-hf_transfer==0.1.9
+# No win_arm64 wheel and this file installs --no-deps, so pip would need cargo plus MSVC.
+hf_transfer==0.1.9; sys_platform != "win32" or platform_machine != "ARM64"
# diffusers: see diffusers-pin.txt, installed by its own step (this file is
# installed --no-deps, and the pin has to apply on the torch path too).
@@ -96,8 +97,12 @@ pillow==11.3.0; python_version < "3.10"
# RAG store + document parsing, mirroring studio.txt. Pinned here because
# this file installs --no-deps; without them Unsloth runs with RAG disabled.
-sqlite-vec==0.1.9
-pymupdf==1.27.2.3
+# sqlite-vec publishes win_amd64 only and no sdist; the RAG store treats a missing sqlite_vec as
+# "RAG unavailable". Same marker as studio.txt: this file is installed directly on an update.
+sqlite-vec==0.1.9; sys_platform != "win32" or platform_machine != "ARM64"
+# pymupdf publishes a win_arm64 wheel from 1.28 only.
+pymupdf==1.27.2.3; sys_platform != "win32" or platform_machine != "ARM64"
+pymupdf>=1.28.2; sys_platform == "win32" and platform_machine == "ARM64"
# 0.3.x keeps pymupdf-layout (which pulls onnxruntime) an optional extra; the
# lockstep 1.27.x line makes it a hard dep we do not need for to_markdown().
pymupdf4llm==0.3.4
diff --git a/studio/backend/requirements/single-env/constraints.txt b/studio/backend/requirements/single-env/constraints.txt
index 68c9980643b..34dc56992d4 100644
--- a/studio/backend/requirements/single-env/constraints.txt
+++ b/studio/backend/requirements/single-env/constraints.txt
@@ -13,7 +13,10 @@ huggingface-hub==0.36.2; python_version < "3.10"
# Unsloth stack
datasets==4.3.0
-pyarrow==23.0.1
+# pyarrow has never published a win_arm64 wheel (apache/arrow#48539). The floor below is the
+# floor of the wheels install.ps1 stages, not of anything upstream ships.
+pyarrow==23.0.1; sys_platform != "win32" or platform_machine != "ARM64"
+pyarrow>=21.0.0; sys_platform == "win32" and platform_machine == "ARM64"
# FastMCP compat
fastmcp>=3.0.2
@@ -34,7 +37,9 @@ anyio<4.14.0
# guards the call. install_python_stack.py repairs an install that is already past the cap.
accelerate<1.15.0; sys_platform == "win32"
-pandas==2.3.3
+# pandas publishes win_arm64 wheels from 3.0 only; 2.3.x would source-build there.
+pandas==2.3.3; sys_platform != "win32" or platform_machine != "ARM64" or python_version < "3.11"
+pandas>=3.0,<4; sys_platform == "win32" and platform_machine == "ARM64" and python_version >= "3.11"
# av (PyAV) 16+ builds its macOS arm64 wheels against macosx_14_0, so on macOS 13 none
# are installable and the resolver falls back to a source build, which needs FFmpeg
@@ -45,10 +50,16 @@ pandas==2.3.3
# The remaining sdist-only macOS defaults are pure Python, hence allowlisted in
# .github/scripts/clean-machine-assert.sh instead; cryptography below is the one
# other package that would compile.
-av<16
+av<16; sys_platform != "win32" or platform_machine != "ARM64"
+# The opposite case: av publishes win_arm64 wheels from 17.0.0 only (cp311-abi3,
+# plus a cp314t; there is no 3.13t wheel on any release).
+av>=17.0.0; sys_platform == "win32" and platform_machine == "ARM64"
# cryptography 49.0.0 dropped the macosx_10_9_universal2 wheel for arm64-only, so
# x86_64 macOS has no wheel and builds the sdist, needing Rust plus a working
# linker. 48.0.1 is the newest release with a universal2 wheel. Lift when
# cryptography ships an x86_64-capable macOS wheel again.
cryptography<49; sys_platform == "darwin" and platform_machine == "x86_64"
+
+# 46.0.3 is the newest cryptography with a win_arm64 wheel; raise the cap when upstream resumes.
+cryptography<=46.0.3; sys_platform == "win32" and platform_machine == "ARM64"
diff --git a/studio/backend/requirements/studio.txt b/studio/backend/requirements/studio.txt
index 99b7335f34b..dd53d60e643 100644
--- a/studio/backend/requirements/studio.txt
+++ b/studio/backend/requirements/studio.txt
@@ -12,8 +12,10 @@ packaging==26.3
matplotlib==3.10.9
# Held at 2.3.3 rather than the 3.0.x line: single-env/constraints.txt pins
# pandas==2.3.3, and 2.3.3 is also the newest release that still installs on
-# 3.9. Bump both together.
-pandas==2.3.3
+# 3.9. Bump both together. Windows on ARM is the exception: win_arm64 pandas wheels
+# start at 3.0, and the 3.11 floor there is pandas 3's own requires-python.
+pandas==2.3.3; sys_platform != "win32" or platform_machine != "ARM64" or python_version < "3.11"
+pandas>=3.0,<4; sys_platform == "win32" and platform_machine == "ARM64" and python_version >= "3.11"
nest_asyncio==1.6.0
datasets==4.3.0
pyjwt==2.13.0
@@ -37,7 +39,10 @@ structlog>=24.1.0
diceware==1.0.1
ddgs==9.14.4; python_version >= "3.10"
ddgs==9.8.0; python_version < "3.10"
-cryptography>=42.0.0
+cryptography>=42.0.0; sys_platform != "win32" or platform_machine != "ARM64"
+# Windows on ARM: 46.0.7 has no win_arm64 wheel and its sdist needs Rust. Matches
+# constraints.txt, which a plain pip install of the extra never reaches.
+cryptography>=42.0.0,<=46.0.3; sys_platform == "win32" and platform_machine == "ARM64"
boto3>=1.34.0 # optional: S3 dataset loading
httpx>=0.27.0
fastmcp>=3.0.2
@@ -53,8 +58,12 @@ gguf==0.18.0; python_version < "3.10"
av>=12.3.0
# RAG (knowledge bases, hybrid retrieval). sentence-transformers lives in
# extras-no-deps.txt; these add the lexical+dense store and document parsing.
-sqlite-vec==0.1.9
-pymupdf==1.27.2.3
+# sqlite-vec publishes win_amd64 only and no sdist, so there is nothing to floor to. The RAG
+# store treats a missing sqlite_vec as "RAG unavailable".
+sqlite-vec==0.1.9; sys_platform != "win32" or platform_machine != "ARM64"
+# pymupdf publishes a win_arm64 wheel from 1.28 only.
+pymupdf==1.27.2.3; sys_platform != "win32" or platform_machine != "ARM64"
+pymupdf>=1.28.2; sys_platform == "win32" and platform_machine == "ARM64"
# 0.3.x keeps pymupdf-layout (which pulls onnxruntime) an optional extra; the
# lockstep 1.27.x line makes it a hard dep we do not need for to_markdown().
pymupdf4llm==0.3.4
diff --git a/studio/backend/utils/prebuilt/llama_backend.py b/studio/backend/utils/prebuilt/llama_backend.py
index f3afac89c65..4b7ac5aae36 100644
--- a/studio/backend/utils/prebuilt/llama_backend.py
+++ b/studio/backend/utils/prebuilt/llama_backend.py
@@ -13,6 +13,8 @@ INSTALL_KIND_BACKENDS: dict[str, str] = {
"linux-cuda": "cuda",
"linux-arm64-cuda": "cuda",
"windows-cuda": "cuda",
+ # Distinct from windows-cuda: the arm64 bundle ships its own ARM64 cudart/cublas.
+ "windows-arm64-cuda": "cuda",
"linux-rocm": "rocm",
"windows-hip": "rocm",
"windows-rocm": "rocm",
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 68d6cb2ed90..b548a9b71e1 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -776,10 +776,52 @@ def checkout_friendly_ref(ref_kind: str | None, ref: str | None) -> str | None:
return ref
-def windows_cuda_upstream_asset_names(llama_tag: str, runtime: str) -> list[str]:
+# Upstream names these llama-<tag>-bin-win-cuda-<runtime>-<arch>.zip, arch in {x64, arm64}.
+WINDOWS_CUDA_ARCHS = ("x64", "arm64")
+_WINDOWS_CUDA_INSTALL_KINDS = ("windows-cuda", "windows-arm64-cuda")
+
+
+def _upstream_arm64_cuda_allowed() -> bool:
+ """May a Windows ARM64 NVIDIA host install a CUDA llama.cpp bundle at all? Defaults
+ to yes, because the only other answer is a CPU-only build on a CUDA machine.
+ UNSLOTH_LLAMA_ARM64_CUDA=0/false/no/off opts out.
+
+ This governs every ARM64 CUDA bundle, published or upstream. It started narrower --
+ only the unverified upstream bundle, since that is the one with a provenance question
+ -- but what the flag promises the user is a CPU bundle, and scoping it to the
+ unverified case meant the escape hatch would switch itself off the day the fork
+ published an approved windows-arm64-cuda artifact. A setting that silently stops
+ working on someone else's release is worse than one that is merely blunt.
+ """
+ raw = (os.environ.get("UNSLOTH_LLAMA_ARM64_CUDA") or "").strip().lower()
+ return raw not in {"0", "false", "no", "off"}
+
+
+def windows_cuda_arch_for_host(host: HostInfo) -> str:
+ """CUDA prebuilt arch token for a Windows host: arm64 on Windows on ARM, else x64.
+
+ ``is_arm64`` is also true for macOS arm64 and Linux aarch64, so the Windows test
+ is part of the question rather than the caller's job. Every caller today is already
+ inside a Windows branch; this keeps the answer right if one ever is not.
+ """
+ return "arm64" if (host.is_windows and host.is_arm64) else "x64"
+
+
+def windows_cuda_install_kind_for_arch(arch: str) -> str:
+ """install_kind for a Windows CUDA prebuilt of `arch`. Kept separate from the x64
+ kind so the runtime-overlay, health-check and marker tables can tell the two apart
+ (their payloads differ: the arm64 bundle carries no cuBLASLt-for-x64 DLL set)."""
+ return "windows-arm64-cuda" if arch == "arm64" else "windows-cuda"
+
+
+def windows_cuda_upstream_asset_names(
+ llama_tag: str,
+ runtime: str,
+ arch: str = "x64",
+) -> list[str]:
return [
- f"llama-{llama_tag}-bin-win-cuda-{runtime}-x64.zip",
- f"cudart-llama-bin-win-cuda-{runtime}-x64.zip",
+ f"llama-{llama_tag}-bin-win-cuda-{runtime}-{arch}.zip",
+ f"cudart-llama-bin-win-cuda-{runtime}-{arch}.zip",
]
@@ -787,29 +829,35 @@ def windows_cuda_asset_aliases(
asset_name: str, *, compatibility_tag: str | None = None
) -> list[str]:
aliases: list[str] = []
+ _arch_re = "|".join(WINDOWS_CUDA_ARCHS)
legacy_match = re.fullmatch(
- r"llama-(?P<tag>[^/]+)-bin-win-cuda-(?P<runtime>\d+\.\d+)-x64\.zip",
+ rf"llama-(?P<tag>[^/]+)-bin-win-cuda-(?P<runtime>\d+\.\d+)-(?P<arch>{_arch_re})\.zip",
asset_name,
)
if legacy_match:
runtime = legacy_match.group("runtime")
- aliases.append(f"cudart-llama-bin-win-cuda-{runtime}-x64.zip")
+ arch = legacy_match.group("arch")
+ aliases.append(f"cudart-llama-bin-win-cuda-{runtime}-{arch}.zip")
if compatibility_tag:
- aliases.append(f"llama-{compatibility_tag}-bin-win-cuda-{runtime}-x64.zip")
+ aliases.append(f"llama-{compatibility_tag}-bin-win-cuda-{runtime}-{arch}.zip")
return aliases
current_match = re.fullmatch(
- r"cudart-llama-bin-win-cuda-(?P<runtime>\d+\.\d+)-x64\.zip",
+ rf"cudart-llama-bin-win-cuda-(?P<runtime>\d+\.\d+)-(?P<arch>{_arch_re})\.zip",
asset_name,
)
if current_match and compatibility_tag:
runtime = current_match.group("runtime")
- aliases.append(f"llama-{compatibility_tag}-bin-win-cuda-{runtime}-x64.zip")
+ arch = current_match.group("arch")
+ aliases.append(f"llama-{compatibility_tag}-bin-win-cuda-{runtime}-{arch}.zip")
return aliases
def _published_windows_cuda_runtime(
- upstream_assets: dict[str, str], major: int, driver: tuple[int, int] | None
+ upstream_assets: dict[str, str],
+ major: int,
+ driver: tuple[int, int] | None,
+ arch: str = "x64",
) -> str | None:
"""Highest cuda-<major>.<minor> published upstream that `driver` can run by
default CUDA compatibility, i.e. (major, minor) <= driver. None if nothing
@@ -820,7 +868,7 @@ def _published_windows_cuda_runtime(
return None
best: int | None = None
for name in upstream_assets:
- m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", name)
+ m = re.search(rf"-bin-win-cuda-(\d+)\.(\d+)-{re.escape(arch)}\.zip$", name)
if m and int(m.group(1)) == major:
minor = int(m.group(2))
if (major, minor) <= driver and (best is None or minor > best):
@@ -1151,6 +1199,20 @@ def direct_upstream_release_plan(
)
)
elif host.is_windows and host.is_arm64:
+ # Upstream ships -arm64 CUDA bundles for these parts; try them first, CPU bundle still last.
+ if host.has_usable_nvidia and _upstream_arm64_cuda_allowed():
+ torch_preference = detect_torch_cuda_runtime_preference(host)
+ attempts.extend(
+ windows_cuda_attempts(
+ host,
+ release_tag,
+ assets,
+ torch_preference.runtime_line,
+ torch_preference.selection_log,
+ arch = "arm64",
+ )
+ )
+ attempts[:] = _drop_blackwell_incapable_windows_cuda(host, attempts)
# Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-win-cpu-arm64.zip
# (visible in the b9334 release manifest). Without this branch the
# selector returned 0 attempts and the installer fell back to a
@@ -1376,6 +1438,22 @@ def detected_linux_runtime_lines() -> tuple[list[str], dict[str, list[str]]]:
release_asset_map = _core.release_asset_map
+release_asset_digests = _core.release_asset_digests
+
+
+def github_release_asset_digests(repo: str, tag: str) -> dict[str, str]:
+ """asset name -> sha256, from the release GitHub already serves us.
+
+ Separate call rather than a second return value from github_release_assets: that one is
+ mocked in a dozen suites and used on every platform, while this is read on one branch
+ only. Any failure is an empty mapping, which that branch reads as "refuse", so a rate
+ limit or an outage costs the CUDA bundle rather than installing it unchecked.
+ """
+ try:
+ return release_asset_digests(github_release(repo, tag))
+ except Exception as exc:
+ log(f"could not read release asset digests for {repo}@{tag}: {exc}")
+ return {}
def parse_published_artifact(raw: Any) -> PublishedLlamaArtifact | None:
@@ -3103,8 +3181,14 @@ def windows_cuda_attempts(
upstream_assets: dict[str, str],
preferred_runtime_line: str | None,
selection_preamble: Iterable[str] = (),
+ arch: str | None = None,
) -> list[AssetChoice]:
+ if arch is None:
+ arch = windows_cuda_arch_for_host(host)
+ install_kind = windows_cuda_install_kind_for_arch(arch)
selection_log = list(selection_preamble)
+ if arch != "x64":
+ selection_log.append(f"windows_cuda_selection: arch={arch}")
driver_runtime = pick_windows_cuda_runtime(host)
detected_runtime_lines, runtime_dirs = detected_windows_runtime_lines()
compatible_runtime_lines = compatible_windows_runtime_lines(host)
@@ -3189,7 +3273,9 @@ def windows_cuda_attempts(
# Track whatever minor llama.cpp actually ships for this major
# (cuda13 -> 13.1, 13.3, ...). Skip the line when the release has no
# matching asset instead of guessing a now-missing name.
- runtime = _published_windows_cuda_runtime(upstream_assets, major, host.driver_cuda_version)
+ runtime = _published_windows_cuda_runtime(
+ upstream_assets, major, host.driver_cuda_version, arch
+ )
if runtime is None:
selection_log.append(
f"windows_cuda_selection: no driver-supported asset for {runtime_line}"
@@ -3197,7 +3283,7 @@ def windows_cuda_attempts(
continue
selected_name = None
asset_url = None
- for candidate_name in windows_cuda_upstream_asset_names(llama_tag, runtime):
+ for candidate_name in windows_cuda_upstream_asset_names(llama_tag, runtime, arch):
asset_url = upstream_assets.get(candidate_name)
if asset_url:
selected_name = candidate_name
@@ -3205,7 +3291,7 @@ def windows_cuda_attempts(
if not asset_url or not selected_name:
selection_log.append(
"windows_cuda_selection: skip missing assets "
- + ",".join(windows_cuda_upstream_asset_names(llama_tag, runtime))
+ + ",".join(windows_cuda_upstream_asset_names(llama_tag, runtime, arch))
)
continue
# Pair the cudart bundle when upstream ships it. Without this
@@ -3215,7 +3301,7 @@ def windows_cuda_attempts(
runtime_archive_name: str | None = None
runtime_archive_url: str | None = None
if selected_name.startswith("llama-"):
- cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-x64.zip"
+ cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-{arch}.zip"
cudart_url = upstream_assets.get(cudart_name)
if cudart_url and cudart_url != asset_url:
runtime_archive_name = cudart_name
@@ -3239,7 +3325,7 @@ def windows_cuda_attempts(
name = selected_name,
url = asset_url,
source_label = "upstream",
- install_kind = "windows-cuda",
+ install_kind = install_kind,
runtime_line = runtime_line,
runtime_name = runtime_archive_name,
runtime_url = runtime_archive_url,
@@ -3252,13 +3338,15 @@ def windows_cuda_attempts(
def _windows_cuda_attempt_covers_blackwell(
attempt: AssetChoice, min_toolkit: tuple[int, int] = _BLACKWELL_MIN_TOOLKIT
) -> bool:
- """True if a windows-cuda attempt is Blackwell-capable (app bundles via
+ """True if a windows CUDA attempt is Blackwell-capable (app bundles via
declared SMs; legacy upstream bundles via toolkit minor >= min_toolkit:
12.8 for the family, 12.9 for sm_103/sm_121)."""
- if attempt.install_kind != "windows-cuda":
+ if attempt.install_kind not in _WINDOWS_CUDA_INSTALL_KINDS:
return False
# Legacy bundle: the toolkit minor binds (12.4 cannot offload Blackwell).
- m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", attempt.name)
+ m = re.search(
+ rf"-bin-win-cuda-(\d+)\.(\d+)-(?:{'|'.join(WINDOWS_CUDA_ARCHS)})\.zip$", attempt.name
+ )
if m is not None:
return (int(m.group(1)), int(m.group(2))) >= min_toolkit
# App-named bundles carry no minor and declare their SM coverage directly.
@@ -3272,17 +3360,19 @@ _blackwell_min_toolkit_for_host = _core.blackwell_min_toolkit_for_host
def _drop_blackwell_incapable_windows_cuda(
host: HostInfo, attempts: list[AssetChoice]
) -> list[AssetChoice]:
- """On a Blackwell host, drop windows-cuda attempts that can't offload
+ """On a Blackwell host, drop windows CUDA attempts that can't offload
Blackwell (e.g. cuda-12.4): they load and validate but run a slow non-native
path (RTX 5090: 7.1 vs 551.2 tok/s on cuda-13.3). Non-cuda attempts pass
- through so the host can still fall back to an honest CPU install."""
+ through so the host can still fall back to an honest CPU install. Windows on ARM
+ is covered too: every NVIDIA part in that class (GB10 / N1X) is Blackwell, and its
+ only CUDA bundles are cuda-13.x, so nothing legitimate is filtered there."""
if not _host_is_blackwell(host):
return attempts
min_toolkit = _blackwell_min_toolkit_for_host(host)
return [
attempt
for attempt in attempts
- if attempt.install_kind != "windows-cuda"
+ if attempt.install_kind not in _WINDOWS_CUDA_INSTALL_KINDS
or _windows_cuda_attempt_covers_blackwell(attempt, min_toolkit)
]
@@ -3292,10 +3382,14 @@ def published_windows_cuda_attempts(
release: PublishedReleaseBundle,
preferred_runtime_line: str | None,
selection_preamble: Iterable[str] = (),
+ arch: str | None = None,
) -> list[AssetChoice]:
+ if arch is None:
+ arch = windows_cuda_arch_for_host(host)
+ install_kind = windows_cuda_install_kind_for_arch(arch)
selection_log = list(release.selection_log) + list(selection_preamble)
published_artifacts = [
- artifact for artifact in release.artifacts if artifact.install_kind == "windows-cuda"
+ artifact for artifact in release.artifacts if artifact.install_kind == install_kind
]
artifacts_by_runtime: dict[str, list[PublishedLlamaArtifact]] = {}
for artifact in published_artifacts:
@@ -3310,8 +3404,10 @@ def published_windows_cuda_attempts(
# actually provides on the host, preferring the torch line. Routing them
# through the synthetic-minor path wrongly dropped cuda13 on a 13.0 driver.
legacy_minors: list[str] = []
+ # Scoped to the arch being resolved: hardcoded x64 would mis-order the arm64 runtime lines.
+ _legacy_pattern = rf"-bin-win-cuda-(\d+\.\d+)-{re.escape(arch)}\.zip$"
for artifact in published_artifacts:
- m = re.search(r"-bin-win-cuda-(\d+\.\d+)-x64\.zip$", artifact.asset_name)
+ m = re.search(_legacy_pattern, artifact.asset_name)
if m:
legacy_minors.append(m.group(1))
if legacy_minors:
@@ -3321,11 +3417,12 @@ def published_windows_cuda_attempts(
host,
release.upstream_tag,
{
- f"llama-{release.upstream_tag}-bin-win-cuda-{minor}-x64.zip": "published"
+ f"llama-{release.upstream_tag}-bin-win-cuda-{minor}-{arch}.zip": "published"
for minor in legacy_minors
},
preferred_runtime_line,
selection_log,
+ arch = arch,
)
if attempt.runtime_line
]
@@ -3363,7 +3460,10 @@ def published_windows_cuda_attempts(
asset_url = release.assets.get(artifact.asset_name)
if not asset_url:
continue
- am = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", artifact.asset_name)
+ # Two groups (major, minor), for THIS arch: the x64 spelling never matched an arm64 bundle.
+ am = re.search(
+ rf"-bin-win-cuda-(\d+)\.(\d+)-{re.escape(arch)}\.zip$", artifact.asset_name
+ )
# Legacy upstream-named bundles encode the minor; gate it against the
# driver. app-named bundles carry no minor and are driver-gated at the
# runtime-line level by windows_cuda_attempts above.
@@ -3410,7 +3510,7 @@ def published_windows_cuda_attempts(
runtime_archive_url: str | None = None
if am is not None and artifact.asset_name.startswith("llama-"):
runtime = f"{am.group(1)}.{am.group(2)}"
- cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-x64.zip"
+ cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-{arch}.zip"
cudart_url = release.assets.get(cudart_name)
if cudart_url and cudart_url != asset_url:
runtime_archive_name = cudart_name
@@ -3430,7 +3530,7 @@ def published_windows_cuda_attempts(
name = artifact.asset_name,
url = asset_url,
source_label = "published",
- install_kind = "windows-cuda",
+ install_kind = install_kind,
runtime_line = runtime_line,
runtime_name = runtime_archive_name,
runtime_url = runtime_archive_url,
@@ -3446,7 +3546,10 @@ def published_windows_cuda_attempts(
def resolve_windows_cuda_choices(
- host: HostInfo, llama_tag: str, upstream_assets: dict[str, str]
+ host: HostInfo,
+ llama_tag: str,
+ upstream_assets: dict[str, str],
+ arch: str | None = None,
) -> list[AssetChoice]:
torch_preference = detect_torch_cuda_runtime_preference(host)
attempts = windows_cuda_attempts(
@@ -3455,6 +3558,7 @@ def resolve_windows_cuda_choices(
upstream_assets,
torch_preference.runtime_line,
torch_preference.selection_log,
+ arch = arch,
)
return attempts
@@ -3811,6 +3915,28 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
install_kind = "windows-cpu",
)
+ if host.is_windows and host.is_arm64:
+ # CUDA first on an NVIDIA host, then the CPU bundle; without this branch every Windows ARM64 host fell through to a source build.
+ if host.has_usable_nvidia and _upstream_arm64_cuda_allowed():
+ attempts = _drop_blackwell_incapable_windows_cuda(
+ host,
+ resolve_windows_cuda_choices(host, llama_tag, upstream_assets, arch = "arm64"),
+ )
+ if attempts:
+ return attempts[0]
+ log("no compatible Windows ARM64 CUDA asset was found -- falling back to CPU")
+ upstream_name = f"llama-{llama_tag}-bin-win-cpu-arm64.zip"
+ if upstream_name not in upstream_assets:
+ raise PrebuiltFallback("upstream Windows ARM64 CPU asset was not found")
+ return AssetChoice(
+ repo = UPSTREAM_REPO,
+ tag = llama_tag,
+ name = upstream_name,
+ url = upstream_assets[upstream_name],
+ source_label = "upstream",
+ install_kind = "windows-arm64",
+ )
+
if host.is_macos and host.is_arm64:
upstream_name = f"llama-{llama_tag}-bin-macos-arm64.tar.gz"
if upstream_name not in upstream_assets:
@@ -3918,7 +4044,72 @@ def resolve_release_asset_choice(
else:
published_choice = published_asset_choice_for_kind(release, "windows-cpu")
elif host.is_windows and host.is_arm64:
- # Windows arm64 has no GPU prebuilt, so it always takes the CPU bundle.
+ # Prefer a CUDA bundle, as x64 does: the published windows-arm64-cuda artifact first, then
+ # upstream's -arm64 zip, both hash-gated. The opt-out gates the WHOLE branch.
+ if host.has_usable_nvidia and _upstream_arm64_cuda_allowed():
+ torch_preference = detect_torch_cuda_runtime_preference(host)
+ published_arm64_cuda = _drop_blackwell_incapable_windows_cuda(
+ host,
+ published_windows_cuda_attempts(
+ host,
+ release,
+ torch_preference.runtime_line,
+ torch_preference.selection_log,
+ arch = "arm64",
+ ),
+ )
+ if published_arm64_cuda:
+ try:
+ return apply_approved_hashes(published_arm64_cuda, checksums)
+ except PrebuiltFallback as exc:
+ log(
+ "published Windows ARM64 CUDA assets ignored for install planning: "
+ f"{release.repo}@{release.release_tag} ({exc})"
+ )
+ # Same rule as the digest fetch below: a rate limit, an outage or a malformed payload from the
+ # release API costs the CUDA bundle, never the install; the ARM64 CPU bundle is still there.
+ try:
+ upstream_arm64_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
+ except Exception as exc:
+ log(
+ f"could not list the upstream {UPSTREAM_REPO}@{llama_tag} release assets "
+ f"({exc}); falling through to the ARM64 CPU bundle."
+ )
+ upstream_arm64_assets = {}
+ upstream_arm64_cuda = _drop_blackwell_incapable_windows_cuda(
+ host,
+ resolve_windows_cuda_choices(
+ host,
+ llama_tag,
+ upstream_arm64_assets,
+ arch = "arm64",
+ ),
+ )
+ if upstream_arm64_cuda:
+ try:
+ return apply_approved_hashes(upstream_arm64_cuda, checksums)
+ except PrebuiltFallback as exc:
+ # The fork publishes no windows-arm64-cuda bundle yet, so take upstream ggml-org's, the same release this fork
+ # repackages. Verified against GitHub's per-asset digest; an asset it states no digest for is refused, not installed.
+ verified = _apply_release_digests(
+ upstream_arm64_cuda,
+ github_release_asset_digests(UPSTREAM_REPO, llama_tag),
+ )
+ if verified:
+ log(
+ "no approved checksum covers a Windows ARM64 CUDA bundle "
+ f"({exc}); installing the upstream {UPSTREAM_REPO} bundle "
+ f"{verified[0].name}, verified against the release asset digest "
+ "GitHub reports. Set UNSLOTH_LLAMA_ARM64_CUDA=0 to use the CPU "
+ "bundle instead."
+ )
+ return verified
+ log(
+ "no approved checksum covers a Windows ARM64 CUDA bundle "
+ f"({exc}), and GitHub reports no asset digest for the upstream "
+ f"{UPSTREAM_REPO} bundle either; refusing to install it unverified "
+ "and falling through to the ARM64 CPU bundle."
+ )
published_choice = published_asset_choice_for_kind(release, "windows-arm64")
elif host.is_macos and host.is_arm64:
published_choice = published_asset_choice_for_kind(release, "macos-arm64")
@@ -4283,8 +4474,10 @@ def paired_runtime_dll_patterns(choice: AssetChoice) -> list[str]:
into the install. Used for the second copy_globs pass in
install_from_archives, narrower than runtime_patterns_for_choice so
the runtime archive cannot overwrite main-archive payload like
- llama-server.exe. Only Windows CUDA has paired runtimes today."""
- if choice.install_kind == "windows-cuda":
+ llama-server.exe. Only Windows CUDA has paired runtimes today (x64 and arm64
+ alike: upstream ships a cudart-...-arm64.zip beside the arm64 binary bundle,
+ carrying the same DLL names built for ARM64)."""
+ if choice.install_kind in _WINDOWS_CUDA_INSTALL_KINDS:
return ["cudart64_*.dll", "cublas64_*.dll", "cublasLt64_*.dll"]
return []
@@ -4325,6 +4518,7 @@ def runtime_patterns_for_install_kind(
if install_kind in {
"windows-cpu",
"windows-cuda",
+ "windows-arm64-cuda",
"windows-hip",
"windows-vulkan",
"windows-rocm",
@@ -6073,6 +6267,7 @@ def validate_server(
"linux-rocm",
"linux-vulkan",
"windows-cuda",
+ "windows-arm64-cuda",
"windows-hip",
"windows-vulkan",
"windows-rocm",
@@ -6405,6 +6600,34 @@ def collect_system_report(host: HostInfo, choice: AssetChoice | None, install_di
return "\n".join(lines)
+def _apply_release_digests(
+ attempts: Iterable[AssetChoice], digests: dict[str, str]
+) -> list[AssetChoice]:
+ """apply_approved_hashes against GitHub's per-asset digests instead of our manifest.
+
+ Same two rules, because they are the ones that matter: an attempt with no digest is
+ dropped rather than installed unverified, and a paired runtime archive with no digest
+ unpairs rather than riding along unchecked. Returns [] when nothing survives, which the
+ one caller reads as "refuse and fall through", not as "install anyway".
+ """
+ kept: list[AssetChoice] = []
+ for attempt in attempts:
+ digest = digests.get(attempt.name)
+ if digest is None:
+ continue
+ attempt.expected_sha256 = digest
+ if attempt.runtime_name and attempt.runtime_url:
+ runtime_digest = digests.get(attempt.runtime_name)
+ if runtime_digest is None:
+ attempt.runtime_name = None
+ attempt.runtime_url = None
+ attempt.runtime_sha256 = None
+ else:
+ attempt.runtime_sha256 = runtime_digest
+ kept.append(attempt)
+ return kept
+
+
def apply_approved_hashes(
attempts: Iterable[AssetChoice], checksums: ApprovedReleaseChecksums
) -> list[AssetChoice]:
@@ -7367,7 +7590,7 @@ def runtime_payload_health_groups(
return groups
if install_kind in {"windows-cpu", "windows-arm64"}:
return _windows_shared_groups(source_label, tag)
- if install_kind == "windows-cuda":
+ if install_kind in {"windows-cuda", "windows-arm64-cuda"}:
groups = _windows_shared_groups(source_label, tag) + [["ggml-cuda.dll"]]
# Require the complete cudart trio only when it was paired with this install.
if runtime_name:
diff --git a/studio/install_manifest.py b/studio/install_manifest.py
index d20a7a08509..73181751923 100644
--- a/studio/install_manifest.py
+++ b/studio/install_manifest.py
@@ -27,6 +27,7 @@ import re
import sys
import time
from pathlib import Path
+from urllib.parse import urlsplit
from typing import Dict, List, Optional, Sequence, Tuple
MANIFEST_NAME = "unsloth_install_manifest.json"
@@ -635,6 +636,9 @@ PROTECTED_MANIFEST_KEYS: Tuple[str, ...] = (
"no_torch",
"expected_torch_tag",
"expected_torch_tag_pinned",
+ # Validated on write (NVIDIA's own https channel, no userinfo/query/fragment) and read back
+ # as an index to install from, so caller-composed evidence must not be able to name it.
+ "woa_torch_index",
)
@@ -646,6 +650,7 @@ def write_manifest(
no_torch: Optional[bool] = None,
expected_torch_tag: Optional[str] = None,
expected_torch_tag_pinned: Optional[bool] = None,
+ woa_torch_index: Optional[str] = None,
extra: Optional[Dict[str, object]] = None,
) -> Optional[Path]:
"""Record a completed install. Never raises: no manifest reads as incomplete,
@@ -679,6 +684,25 @@ def write_manifest(
# eGPU with no repair offered. Absent means unknown, as with every other additive key.
if expected_torch_tag_pinned is not None:
payload["expected_torch_tag_pinned"] = bool(expected_torch_tag_pinned)
+ # Windows on ARM has no CUDA wheels on download.pytorch.org, so a fresh shell cannot re-derive.
+ # Only NVIDIA's own channels, with no userinfo, query or fragment: a mirror is not persisted.
+ if woa_torch_index:
+ candidate = str(woa_torch_index).strip()
+ # urlsplit raises on a malformed authority, which would break the never-raises contract. Scheme and host compare case-insensitively (RFC 3986); the path keeps its case.
+ try:
+ parsed = urlsplit(candidate)
+ _woa_ok = (
+ parsed.scheme.lower() == "https"
+ and parsed.hostname == "pypi.nvidia.com"
+ and parsed.netloc.lower() == parsed.hostname
+ and not parsed.query
+ and not parsed.fragment
+ )
+ except ValueError:
+ _woa_ok = False
+ # netloc, not hostname: hostname strips ":443", so a value with a port is refused. Equality drops userinfo with it.
+ if _woa_ok:
+ payload["woa_torch_index"] = "https://pypi.nvidia.com" + parsed.path.rstrip("/")
# The dependency pass's own evidence (`pass_inputs`, `step_results`, `pip_check_ok`, ...):
# additive, never authoritative, every consumer re-verifies on disk. None is dropped so "absent
# means unknown" holds, and nothing may shadow a field verify_install reads.
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 09198075e20..4443447870d 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -83,15 +83,37 @@ _PLATFORM_HAS_TORCHCODEC_WHEEL = (
PLATFORM_LACKS_TORCHCODEC_WHEEL = not _PLATFORM_HAS_TORCHCODEC_WHEEL
+def _machine_arch_from_registry() -> str:
+ """The machine-scope PROCESSOR_ARCHITECTURE, which an emulated process cannot
+ misreport. Every per-process signal follows the process: under x64 emulation on
+ ARM64 Windows the process copy says AMD64, PROCESSOR_ARCHITEW6432 is unset (it is a
+ WOW64-only variable), and platform.machine() says AMD64 too. Empty when unreadable
+ or off Windows."""
+ if not IS_WINDOWS:
+ return ""
+ try:
+ import winreg
+ with winreg.OpenKey(
+ winreg.HKEY_LOCAL_MACHINE,
+ r"SYSTEM\CurrentControlSet\Control\Session Manager\Environment",
+ ) as key:
+ return str(winreg.QueryValueEx(key, "PROCESSOR_ARCHITECTURE")[0] or "")
+ except Exception:
+ return ""
+
+
def _is_windows_arm64() -> bool:
- """Windows on ARM, machine arch rather than process arch: platform.machine() reports
- AMD64 under an emulated x64 Python, and PROCESSOR_ARCHITEW6432 is ARM64 in exactly
- that case. Mirrors Get-HostMachineArch in install.ps1 / setup.ps1."""
+ """Windows on ARM, machine arch rather than process arch. The registry value leads
+ because the per-process signals all say AMD64 under an emulated x64 Python; they stay
+ as fallbacks for a native interpreter. Mirrors Get-HostMachineArch in install.ps1 /
+ setup.ps1. Wheel availability is an interpreter question, not a machine one: see
+ ``_is_win_arm64_interpreter``."""
if not IS_WINDOWS:
return False
return any(
(value or "").strip().lower() in {"arm64", "aarch64"}
for value in (
+ _machine_arch_from_registry(),
os.environ.get("PROCESSOR_ARCHITEW6432"),
os.environ.get("PROCESSOR_ARCHITECTURE"),
platform.machine(),
@@ -99,6 +121,44 @@ def _is_windows_arm64() -> bool:
)
[email protected]_cache(maxsize = None)
+def _is_win_arm64_interpreter() -> bool:
+ """Windows on ARM, the arch of THIS INTERPRETER rather than of the machine.
+
+ The distinction decides which wheels exist. ``_is_windows_arm64`` above answers
+ for the machine, and is true even under an emulated x64 Python -- which is what
+ every install predating native ARM64 support is running, because install.ps1
+ deliberately fetched an x64 interpreter there. Such a venv wants the x64 wheels
+ and gets them: ``platform_machine == "ARM64"`` in a requirement marker is the
+ INTERPRETER's arch, so the marker rows and this predicate have to agree or the
+ same machine is served two different answers.
+
+ ``sysconfig.get_platform()`` is what pip and uv tag wheels with, so it is the
+ same authority; ``platform.machine()`` is the fallback and reports AMD64 under
+ emulation, which is the answer we want there.
+ """
+ if not IS_WINDOWS:
+ return False
+ try:
+ tag = (sysconfig.get_platform() or "").strip().lower()
+ if tag:
+ return tag == "win-arm64"
+ except Exception:
+ pass
+ return (platform.machine() or "").strip().lower() in {"arm64", "aarch64"}
+
+
+def _windows_arm64_has_torchaudio() -> bool:
+ """Does the CUDA index this install used publish a win_arm64 torchaudio?
+
+ NVIDIA's GA out-of-tree channel does (2.11.0+cu134); its nightly channel and
+ download.pytorch.org do not. install.ps1 answers this in UNSLOTH_WOA_HAS_TORCHAUDIO.
+ Unset means "assume not": asking for a wheel that does not exist makes the whole trio
+ unresolvable, while skipping one that does costs only audio support.
+ """
+ return (os.environ.get("UNSLOTH_WOA_HAS_TORCHAUDIO") or "").strip() == "1"
+
+
# ── ROCm / AMD GPU support ─────────────────────────────────────────────────────
_ROCM_TORCH_INDEX: dict[tuple[int, int], str] = {
(7, 2): "rocm7.2", # torch 2.11.0
@@ -3119,8 +3179,7 @@ def _hsa_spoofed_physical_gfx(
re-probe."""
if physical == [inferred_gfx]:
_safe_print(
- f" {source} reports {inferred_gfx} -- {probed} is a spoof of the "
- f"physical arch.\n"
+ f" {source} reports {inferred_gfx} -- {probed} is a spoof of the physical arch.\n"
)
return inferred_gfx
# Say so rather than leaving "Checking whether..." hanging: on a real gfx1100
@@ -3937,8 +3996,7 @@ def _ensure_cuda_torch() -> None:
if _target_span is None or not _span_covers(_target_span, _sms):
return
_why = (
- f"torch is {_family} but this host has GPUs outside its "
- f"sm_{_span[0]}-{_span[1]} range"
+ f"torch is {_family} but this host has GPUs outside its sm_{_span[0]}-{_span[1]} range"
)
elif (
_marker == "cpu"
@@ -4971,6 +5029,10 @@ def _ensure_expected_torch_flavor(expected: "str | None" = None) -> bool:
"""
if NO_TORCH:
return True
+ if _is_win_arm64_interpreter() and _explicit_torch_index_url() is None:
+ _installed = _probe_installed_torch_version()
+ if _installed and _is_cuda_family_leaf(_torch_flavor_tag(_installed)):
+ return True
# rocm/xpu/cpu fall THROUGH: an explicit GPU pin sets _TORCH_BACKEND, and rejecting it
# here would skip the invariant on the hosts that asked for that family.
if _TORCH_BACKEND not in ("", "cuda", "rocm", "xpu", "cpu"):
@@ -5045,9 +5107,9 @@ def _ensure_expected_torch_flavor(expected: "str | None" = None) -> bool:
_torch_pkg, _vision_pkg, _audio_pkg = (
_XPU_TORCH_PKG_SPEC if expected == "xpu" else _TORCH_FLAVOR_REPAIR_PKG_SPEC
)
- # No win_arm64 torchaudio wheel exists on any index ($WinArm64NoAudio in setup.ps1).
+ # Keyed on the INTERPRETER, not the machine: an emulated x64 venv installs win_amd64 wheels.
_trio = [_torch_pkg, _vision_pkg, _audio_pkg]
- if _is_windows_arm64():
+ if _is_win_arm64_interpreter() and not _windows_arm64_has_torchaudio():
_trio = [_torch_pkg, _vision_pkg]
_label_before = str(installed_version)
# --force-reinstall, not install.ps1's uv-only --reinstall-package: pip_install falls
@@ -5392,10 +5454,8 @@ def _ensure_rocm_torch() -> None:
_torch_pkg, _vision_pkg, _audio_pkg = _WINDOWS_ROCM_TORCH_PKG_SPECS.get(
gfx_arch, ("torch", "torchvision", "torchaudio")
)
- # Same win_arm64 exception setup.ps1 applies: no torchaudio wheel exists
- # there, so asking for one makes the trio unresolvable.
_rocm_trio = [_torch_pkg, _vision_pkg, _audio_pkg]
- if _is_windows_arm64():
+ if _is_win_arm64_interpreter():
_rocm_trio = [_torch_pkg, _vision_pkg]
# Nonfatal: a transient AMD-index failure must not abort the install.
# --force-reinstall resolves before uninstalling, so a failed index keeps the
@@ -6392,6 +6452,35 @@ def run(
return result
+# First line of the overrides file install.ps1 generates; setup.ps1's merge copies it first.
+WOA_OVERRIDES_HEADER = "# Generated by install.ps1 for Windows on ARM"
+
+
+def _woa_overrides_are_load_bearing() -> bool:
+ """Is this a native win_arm64 resolve whose correctness depends on UV_OVERRIDE?
+
+ install.ps1 writes those overrides to lift the released torch cap -- no win_arm64 CUDA
+ wheel satisfies it -- and to drop the packages with no win_arm64 build. pip has no
+ override mechanism at all: constraints only narrow a requirement, they cannot replace
+ one, so there is nothing to translate them into. Falling back to pip on this stack does
+ not recover, it silently resolves the wrong thing.
+
+ Judged by the generated file, not by the variable: a caller's own override on a run that
+ never configured the stack (--no-torch, a direct run) keeps the fallback every host has.
+ """
+ if not _is_win_arm64_interpreter():
+ return False
+ for path in os.environ.get("UV_OVERRIDE", "").split():
+ try:
+ with open(path, encoding = "utf-8", errors = "replace") as handle:
+ first = handle.readline()
+ except OSError:
+ continue
+ if first.lstrip("\ufeff").startswith(WOA_OVERRIDES_HEADER):
+ return True
+ return False
+
+
def _report_failed_command(label: str, result: subprocess.CompletedProcess[bytes]) -> None:
"""Print a failed command's redacted output and exit with its code."""
_step("error", f"{label} failed (exit code {result.returncode})", _red)
@@ -6458,6 +6547,706 @@ def _purge_recordless_distributions(output: "bytes | str | None") -> list[str]:
# Packages to skip on Windows (require special build steps)
WINDOWS_SKIP_PACKAGES = {"triton_kernels"}
+# No win_arm64 wheel and no sdist buildable without MSVC / Rust / LLVM / FFmpeg. All optional:
+# tensorboard needs grpcio; librosa and openai-whisper need numba -> llvmlite (cp314 only).
+# Lowercase entries only: _filter_requirements lowercases the line and compares verbatim.
+WINDOWS_ARM64_SKIP_PACKAGES = {
+ "mecab",
+ "sqlite-vec",
+ "tiktoken",
+ "tensorboard",
+ "librosa",
+ "openai-whisper",
+ "torch-c-dlpack-ext",
+ "pytorch_tokenizers",
+ "hf_transfer",
+ "xformers",
+}
+
+
+def _wheel_matches_interpreter(filename: str) -> bool:
+ """Can THIS interpreter install the wheel named ``filename``?
+
+ A wheelhouse is not built for one interpreter: install.ps1 stages every win_arm64
+ wheel it finds, cp311 through cp314, as the wheelhouse published them. So a filename
+ is not proof on its own -- a cp311 tiktoken is invisible to a cp313 resolver, and
+ counting it as available drops the skip and sends the resolve to an sdist that cannot
+ build here. PEP 425: a wheel is installable when one of its (python, abi, platform)
+ triples is one the interpreter supports, and each filename field may be a
+ "."-separated set expanded as their cartesian product. Unparseable means not
+ installable, which only leaves the conservative skip in place.
+ """
+ stem = filename[:-4] if filename.lower().endswith(".whl") else filename
+ parts = stem.split("-")
+ if len(parts) < 5:
+ return False
+ py_tags, abi_tags, plat_tags = (set(field.split(".")) for field in parts[-3:])
+ this_platform = (sysconfig.get_platform() or "").replace("-", "_").replace(".", "_").lower()
+ if "any" not in plat_tags and this_platform not in plat_tags:
+ return False
+ major, minor = sys.version_info[:2]
+ free_threaded = bool(sysconfig.get_config_var("Py_GIL_DISABLED"))
+ this_cpython = f"cp{major}{minor}"
+ this_abi = f"{this_cpython}t" if free_threaded else this_cpython
+ for py_tag in py_tags:
+ for abi_tag in abi_tags:
+ # abi3 excluded HERE too: this branch shadows the one below (CPython #111506).
+ if py_tag == this_cpython and (
+ abi_tag in ("none", this_abi) or (abi_tag == "abi3" and not free_threaded)
+ ):
+ return True
+ if abi_tag == "none":
+ pure = re.fullmatch(r"py(\d)(\d*)", py_tag)
+ if pure and int(pure.group(1)) == major and int(pure.group(2) or 0) <= minor:
+ return True
+ elif abi_tag == "abi3" and not free_threaded:
+ stable = re.fullmatch(r"cp(\d)(\d+)", py_tag)
+ if stable and int(stable.group(1)) == major and 2 <= int(stable.group(2)) <= minor:
+ return True
+ return False
+
+
[email protected]_cache(maxsize = 1)
+def _find_links_wheel_versions() -> "dict[str, frozenset[str]]":
+ """Canonical name -> versions of the wheels in the configured find-links directories.
+
+ install.ps1 points UV_FIND_LINKS / PIP_FIND_LINKS at a local wheelhouse on Windows on
+ ARM, holding the wheels PyPI does not publish for win_arm64. Anything served there is
+ installable, so it must not also be filtered out as unavailable -- but only the wheels
+ tagged for this interpreter are, which is what the resolver will agree to.
+
+ The VERSIONS come back too, not just the names: every requirement these gate is
+ ``==``-pinned, and a wheelhouse holding tiktoken 0.12.0 against a ``tiktoken==0.13.0``
+ line satisfies nothing -- the resolver goes to PyPI, finds no win_arm64 wheel for the
+ pinned version, and falls to an sdist that cannot build here. That is the exact
+ failure the skip list exists to prevent, so the caller checks the pin.
+ """
+ versions: "dict[str, set[str]]" = {}
+ # UV_FIND_LINKS ONLY: uv does not consume PIP_FIND_LINKS. Comma-split, the way uv reads it.
+ for value, separator in ((os.environ.get("UV_FIND_LINKS"), ","),):
+ for entry in re.split(separator, value or ""):
+ entry = entry.strip().strip('"')
+ if not entry or "://" in entry:
+ continue # a URL index cannot be listed cheaply; treat it as unknown
+ try:
+ for wheel in Path(entry).glob("*.whl"):
+ if not _wheel_matches_interpreter(wheel.name):
+ continue
+ fields = wheel.name[:-4].split("-")
+ if len(fields) < 5:
+ continue # not a wheel filename; _wheel_matches_interpreter agrees
+ name = _canonical_dist_name(fields[0])
+ versions.setdefault(name, set()).add(fields[1])
+ except OSError:
+ continue
+ return {name: frozenset(vers) for name, vers in versions.items()}
+
+
+def _find_links_wheel_names() -> frozenset[str]:
+ """Just the names from :func:`_find_links_wheel_versions`."""
+ return frozenset(_find_links_wheel_versions())
+
+
+_find_links_wheel_names.cache_clear = _find_links_wheel_versions.cache_clear # type: ignore[attr-defined]
+
+
+def _parse_release(version: str) -> "tuple[int, ...] | None":
+ """The numeric release segment of a PEP 440 version, or None when it has none."""
+ match = re.match(r"^\s*v?(\d+(?:\.\d+)*)", version or "")
+ if not match:
+ return None
+ return tuple(int(part) for part in match.group(1).split("."))
+
+
+def _version_satisfies(version: str, specifier: str) -> "bool | None":
+ """Does ``version`` satisfy the PEP 440 specifier set ``specifier``?
+
+ None means "cannot tell" -- an epoch, an arbitrary-equality clause, anything this
+ deliberately small comparison does not model. The caller treats that as it treated
+ every version before this existed, so an exotic pin is no worse off than it was.
+ """
+ specifier = (specifier or "").strip()
+ if not specifier:
+ return True
+ for module_name in ("packaging.specifiers", "pip._vendor.packaging.specifiers"):
+ try:
+ module = importlib.import_module(module_name)
+ except Exception:
+ continue
+ try:
+ spec_set = module.SpecifierSet(specifier)
+ # Prereleases off unless the specifier names one; packaging's default admits 0.13.0rc1.
+ return bool(spec_set.contains(version, prereleases = bool(spec_set.prereleases)))
+ except Exception:
+ break
+ if not re.fullmatch(r"\s*v?\d+(?:\.\d+)*\s*", version or ""):
+ return False
+ got = _parse_release(version)
+ # "!" that is not part of "!=" is a PEP 440 epoch, which _parse_release does not model.
+ if got is None or "!" in (version or "") or "!" in specifier.replace("!=", ""):
+ return None
+ for clause in specifier.split(","):
+ clause = clause.strip()
+ if not clause:
+ continue
+ match = re.fullmatch(r"(==|!=|>=|<=|~=|>|<)\s*([^\s]+)", clause)
+ if not match:
+ return None
+ op, want_raw = match.group(1), match.group(2).rstrip(".*")
+ wildcard = match.group(2).endswith(".*")
+ want = _parse_release(want_raw)
+ if want is None:
+ return None
+ # Pad to a common length so 2.11 and 2.11.0 compare equal, as PEP 440 says.
+ width = max(len(got), len(want))
+ lhs = got + (0,) * (width - len(got))
+ rhs = want + (0,) * (width - len(want))
+ if wildcard:
+ # ==1.2.* / !=1.2.*: only the prefix is compared.
+ prefix = got[: len(want)] + (0,) * max(0, len(want) - len(got))
+ ok = prefix == want
+ if op == "==":
+ pass
+ elif op == "!=":
+ ok = not ok
+ else:
+ return None
+ elif op == "==":
+ ok = lhs == rhs
+ elif op == "!=":
+ ok = lhs != rhs
+ elif op == ">=":
+ ok = lhs >= rhs
+ elif op == "<=":
+ ok = lhs <= rhs
+ elif op == ">":
+ ok = lhs > rhs
+ elif op == "<":
+ ok = lhs < rhs
+ else: # ~=X.Y[.Z] is ">=X.Y[.Z], ==X.Y.*" one level up
+ if len(want) < 2:
+ return None
+ ok = lhs >= rhs and got[: len(want) - 1] == want[: len(want) - 1]
+ if not ok:
+ return False
+ return True
+
+
+def _marker_is_active(marker: str) -> "bool | None":
+ """Does ``marker`` hold for THIS interpreter? None when it cannot be decided.
+
+ packaging is what pip and uv evaluate markers with, so borrowing it keeps the answer
+ identical to the resolver's; pip vendors a copy, which is the fallback for a venv
+ where packaging is not installed in its own right. Neither available means the
+ caller keeps every clause instead of picking one.
+ """
+ if not marker:
+ return True
+ for module_name in ("packaging.markers", "pip._vendor.packaging.markers"):
+ try:
+ module = importlib.import_module(module_name)
+ except Exception:
+ continue
+ try:
+ return bool(module.Marker(marker).evaluate())
+ except Exception:
+ return None
+ return None
+
+
+def _requirement_pins(req: "Path | None") -> "dict[str, list[str]]":
+ """Canonical name -> the version specifiers a requirements file states for it.
+
+ A name can appear more than once, split by marker -- extras.txt carries
+ ``MeCab==0.996.13`` and ``MeCab==0.996.5`` on complementary markers -- so keeping one
+ specifier per name let the row for another platform overwrite the row that actually
+ applies. Markers are evaluated for this interpreter and inactive rows dropped;
+ when they cannot be evaluated every clause is kept, and the caller takes any of them
+ as satisfied, which is no stricter than the name-only check that came before.
+ """
+ pins: "dict[str, list[str]]" = {}
+ if req is None:
+ return pins
+ try:
+ text = req.read_text(encoding = "utf-8-sig")
+ except OSError:
+ return pins
+ for line in text.splitlines():
+ line = line.split("#", 1)[0].strip()
+ if not line or line.startswith("-") or "@" in line:
+ continue
+ line, _, marker = line.partition(";")
+ if _marker_is_active(marker.strip()) is False:
+ continue
+ line = line.strip()
+ match = re.match(r"^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*(.*)$", line)
+ if not match:
+ continue
+ pins.setdefault(_canonical_dist_name(match.group(1)), []).append(match.group(2).strip())
+ return pins
+
+
+# Skipped for their DEPENDENCIES: whisper's metadata needs tiktoken unconditionally, so filtering the direct line does not stop the sdist arriving transitively.
+WINDOWS_ARM64_SKIP_UNBLOCKED_BY = {
+ "tensorboard": ("grpcio",),
+ # soxr as well as the numba pair: librosa 0.11.0 requires soxr>=0.3.2 and soxr has never published a win_arm64 wheel, so un-skipping librosa would build it from an sdist.
+ "librosa": ("llvmlite", "numba", "soxr"),
+ "openai_whisper": ("llvmlite", "numba", "tiktoken"),
+}
+
+
+# The blocker versions the packages' OWN metadata demands: too old, and the extras pass fails.
+# {blocker: (specifier, package it was read from, that package's pinned version)}. llvmlite arrives through numba.
+WINDOWS_ARM64_BLOCKER_FLOORS: "dict[str, tuple[str, str, str]]" = {
+ "grpcio": (">=1.74.0", "tensorboard", "2.21.0"),
+ "numba": (">=0.51.0", "librosa", "0.11.0"),
+ "soxr": (">=0.3.2", "librosa", "0.11.0"),
+}
+
+
+# Excluded on win_arm64 by MARKER, so a hosted wheel has no requirement to satisfy. Floors given, because --no-deps otherwise takes whatever happens to be hosted.
+WINDOWS_ARM64_WHEELHOUSE_OPTIONALS = {
+ "hf-transfer": "",
+ "xformers": ">=0.0.22.post7",
+ "sqlite-vec": "",
+}
+
+
+def _wheelhouse_hosts(name: str) -> bool:
+ """Does the resolver's own find-links carry a wheel for this distribution?"""
+ return bool(_find_links_wheel_versions().get(_canonical_dist_name(name)))
+
+
+def _wheelhouse_best_version(name: str, floor: str) -> "str | None":
+ """The newest hosted version that clears ``floor``, or None if none does.
+
+ An unreadable comparison keeps the answer it would have had before this floor
+ existed, matching _windows_arm64_skip_packages: an exotic version is no worse off.
+ """
+ hosted = _find_links_wheel_versions().get(_canonical_dist_name(name)) or ()
+ usable = [
+ version
+ for version in hosted
+ if not floor or _version_satisfies(version, floor) is not False
+ ]
+ if not usable:
+ return None
+ try:
+ from packaging.version import Version
+ return max(usable, key = Version)
+ except Exception:
+ return sorted(usable)[-1]
+
+
+def _wheelhouse_torchcodec_version(torch_version: "str | None") -> "str | None":
+ """The hosted torchcodec inside the window this torch selects, or None.
+
+ win_arm64 only: elsewhere the platform's own wheel decides. An unknown torch has no
+ window, so it gets no answer either.
+ """
+ if not _is_win_arm64_interpreter() or not torch_version:
+ return None
+ spec = _select_torchcodec_spec(torch_version)
+ if spec is None:
+ return None
+ return _wheelhouse_best_version("torchcodec", spec.split("torchcodec", 1)[1])
+
+
+def _install_wheelhouse_optionals() -> None:
+ """Install the hosted optionals the metadata cannot ask for. Best effort.
+
+ --no-deps: the graph is already resolved and installed by the time this runs, and
+ xformers names torch, so resolving here could walk the win_arm64 CUDA build off to
+ whatever PyPI offers. A failure leaves the feature off, which is where it was.
+
+ Pinned to the selected version rather than installed by bare name, so the floor
+ checked here is the version that actually lands.
+ """
+ if not _is_win_arm64_interpreter():
+ return
+ for name, floor in WINDOWS_ARM64_WHEELHOUSE_OPTIONALS.items():
+ version = _wheelhouse_best_version(name, floor)
+ if version is None:
+ if _wheelhouse_hosts(name):
+ _note(f"windows on arm: the wheelhouse {name} is below {floor}; leaving it off")
+ # Nothing to refresh with, but the copy an earlier run installed is still resident.
+ if _canonical_dist_name(name) == "xformers":
+ _evict_xformers_built_for_another_torch()
+ continue
+ installed = pip_install_try(
+ f"Installing {name}=={version} from the Windows on ARM wheelhouse",
+ "--no-deps",
+ "--no-cache-dir",
+ f"{name}=={version}",
+ constrain = False,
+ )
+ if not installed:
+ _note(f"windows on arm: could not install the wheelhouse {name}; feature stays off")
+ # Checked even when the refresh failed: the copy an earlier torch left behind is still resident.
+ if _canonical_dist_name(name) == "xformers" and _evict_xformers_built_for_another_torch():
+ continue
+ if not installed:
+ continue
+ _note(f"windows on arm: installed {name}=={version} from the wheelhouse")
+
+
+def _evict_xformers_built_for_another_torch() -> bool:
+ """Remove a resident xFormers whose extension was built against another torch. True iff removed.
+
+ xFormers links its extension against ONE (torch, CUDA) pair; beside any other it is mute,
+ and a package install never uninstalls what an earlier run left behind.
+ """
+ built_for = _resident_xformers_build_torch()
+ resident = str(_probe_installed_torch_version() or "")
+ if not (built_for and resident and built_for != resident):
+ return False
+ _uninstall_distribution("xformers")
+ _note(
+ f"windows on arm: the wheelhouse xformers was built for torch "
+ f"{built_for}, not {resident} -- removed; attention uses torch SDPA"
+ )
+ return True
+
+
+WINDOWS_ARM64_PUBLIC_INDEX_WHEELS: "dict[str, dict[str, str]]" = {
+ "llvmlite": {"cp314": "0.49.0"},
+ "numba": {"cp314": "0.67.0"},
+}
+
+
+def _uv_config_files() -> "list[tuple[Path, str]]":
+ """The persistent configuration uv would discover, most specific first, as (path, table).
+
+ uv reads uv.toml or pyproject.toml [tool.uv] from the current directory or the nearest
+ parent (uv.toml wins over pyproject.toml in the same directory), then the user file
+ (%APPDATA%\\uv\\uv.toml on Windows, $XDG_CONFIG_HOME/uv/uv.toml elsewhere), then the
+ system file (%PROGRAMDATA%\\uv\\uv.toml, /etc/uv/uv.toml). UV_CONFIG_FILE names one file
+ instead of discovering; UV_NO_CONFIG discovers nothing. `table` is the prefix the index
+ keys sit under: "" for uv.toml, "tool.uv" for pyproject.toml.
+ """
+ if os.environ.get("UV_NO_CONFIG", "").strip().lower() not in ("", "0", "false"):
+ return []
+ explicit = os.environ.get("UV_CONFIG_FILE", "").strip()
+ if explicit:
+ return [(Path(explicit), "")]
+ found: "list[tuple[Path, str]]" = []
+ here = Path.cwd()
+ for d in (here, *here.parents):
+ uv_toml = d / "uv.toml"
+ if uv_toml.is_file():
+ found.append((uv_toml, ""))
+ break
+ pyproject = d / "pyproject.toml"
+ if pyproject.is_file():
+ try:
+ text = pyproject.read_text(encoding = "utf-8")
+ except OSError:
+ text = ""
+ if re.search(r"(?m)^\s*\[+tool\.uv(\.|\])", text):
+ found.append((pyproject, "tool.uv"))
+ break
+ if IS_WINDOWS:
+ user = os.environ.get("APPDATA", "")
+ system = os.environ.get("PROGRAMDATA", "")
+ if user:
+ found.append((Path(user) / "uv" / "uv.toml", ""))
+ if system:
+ found.append((Path(system) / "uv" / "uv.toml", ""))
+ else:
+ xdg = os.environ.get("XDG_CONFIG_HOME", "") or str(Path.home() / ".config")
+ found.append((Path(xdg) / "uv" / "uv.toml", ""))
+ found.append((Path("/etc/uv/uv.toml"), ""))
+ return [(p, table) for p, table in found if p.is_file()]
+
+
+def _uv_config_index_policy() -> "dict[str, object]":
+ """{no_index, default_index, unreadable} from uv's discovered configuration.
+
+ Project outranks user outranks system for a scalar, so the first file that sets a key
+ decides it. Only the keys that decide where a resolve looks are read: no-index and
+ default-index (index-url is the older spelling), at the top level and under [pip], and
+ an [[index]] entry carrying default = true. A file this cannot parse is reported rather
+ than guessed at.
+ """
+ policy: "dict[str, object]" = {
+ "no_index": None,
+ "default_index": None,
+ "unreadable": False,
+ "extra_indexes": [],
+ }
+ try:
+ import tomllib
+ except ImportError: # 3.10: the native path is 3.11+, so only the x64 fallback lands here
+ policy["unreadable"] = bool(_uv_config_files())
+ return policy
+ for path, table in _uv_config_files():
+ try:
+ with open(path, "rb") as fh:
+ data = tomllib.load(fh)
+ except (OSError, ValueError):
+ policy["unreadable"] = True
+ continue
+ section = data
+ for part in [p for p in table.split(".") if p]:
+ section = section.get(part, {}) if isinstance(section, dict) else {}
+ if not isinstance(section, dict):
+ continue
+ # uv pip (0.10.7): [pip] scalars beat top-level, and [[index]] default = true beats both.
+ pip_scope = section.get("pip", {}) if isinstance(section.get("pip"), dict) else {}
+ file_no_index = None
+ for scope in (pip_scope, section):
+ if file_no_index is None and isinstance(scope.get("no-index"), bool):
+ file_no_index = scope["no-index"]
+ file_default = None
+ extras: list[str] = []
+ indexes = section.get("index")
+ if isinstance(indexes, list):
+ for entry in indexes:
+ if not isinstance(entry, dict) or not isinstance(entry.get("url"), str):
+ continue
+ if entry.get("explicit") is True:
+ # uv: explicit serves only packages pinned via [tool.uv.sources]; with default = true it also removes PyPI as the default (not modelled: doubt).
+ if entry.get("default") is True:
+ policy["unreadable"] = True
+ continue
+ if entry.get("default") is True:
+ if file_default is None:
+ file_default = entry["url"]
+ else:
+ extras.append(entry["url"])
+ for scope in (pip_scope, section):
+ value = scope.get("extra-index-url")
+ if isinstance(value, str):
+ extras.append(value)
+ elif isinstance(value, list):
+ extras.extend(v for v in value if isinstance(v, str))
+ policy["extra_indexes"] = list(policy["extra_indexes"]) + extras
+ if file_default is None:
+ for scope in (pip_scope, section):
+ for key in ("default-index", "index-url"):
+ if file_default is None and isinstance(scope.get(key), str):
+ file_default = scope[key]
+ if policy["no_index"] is None and file_no_index is not None:
+ policy["no_index"] = file_no_index
+ if policy["default_index"] is None and file_default is not None:
+ policy["default_index"] = file_default
+ return policy
+
+
+def _url_is_public_pypi(url: str) -> bool:
+ """The host, not a substring: "https://pypi.org.corp.example/simple" and
+ ".../api/pypi/pypi.org/simple" both contain the name and neither is public PyPI."""
+ try:
+ from urllib.parse import urlsplit
+ host = urlsplit(url.strip()).hostname
+ except ValueError:
+ return False
+ return host is not None and host.lower() == "pypi.org"
+
+
+def _public_pypi_is_reachable() -> bool:
+ """Can this resolution actually reach public PyPI?
+
+ The table below records what PyPI publishes, which is only availability if PyPI is where
+ the resolve will look. Offline, or pointed at an exclusive corporate index, those wheels
+ are neither cached nor served: unblocking librosa there drops the skip and then fails the
+ whole extras pass on an unavailable numba, which is exactly what the skip prevents.
+
+ Judged for the resolver that runs the pass. uv reads UV_* and its configuration files and
+ ignores PIP_*; pip reads PIP_* and ignores UV_*. Mixing the two reported PyPI reachable
+ from a PIP_EXTRA_INDEX_URL that uv, the resolver in use, never consults. A default index
+ REPLACES PyPI; an extra index adds to it, so PyPI named there is still consulted.
+ Environment outranks uv's configuration files. Doubt resolves to False: that answer keeps
+ the skip, the other fails the extras pass.
+ """
+ if USE_UV:
+ return _uv_reaches_public_pypi()
+ return _pip_reaches_public_pypi()
+
+
+def _env_flag(name: str) -> bool:
+ return os.environ.get(name, "").strip().lower() not in ("", "0", "false")
+
+
+def _uv_reaches_public_pypi() -> bool:
+ if _uv_is_offline() or _env_flag("UV_NO_INDEX"):
+ return False
+ extra_is_pypi = any(
+ _url_is_public_pypi(u)
+ for var in ("UV_INDEX", "UV_EXTRA_INDEX_URL")
+ for u in os.environ.get(var, "").split()
+ )
+ for var in ("UV_DEFAULT_INDEX", "UV_INDEX_URL"):
+ value = os.environ.get(var, "").strip()
+ if value:
+ return extra_is_pypi or _url_is_public_pypi(value)
+ policy = _uv_config_index_policy()
+ if policy["unreadable"] or policy["no_index"] is True:
+ return False
+ extra_is_pypi = extra_is_pypi or any(
+ _url_is_public_pypi(u) for u in policy["extra_indexes"] if isinstance(u, str)
+ )
+ default = policy["default_index"]
+ if isinstance(default, str) and not _url_is_public_pypi(default):
+ return extra_is_pypi
+ return True
+
+
+def _pip_reaches_public_pypi() -> bool:
+ """pip's policy: its environment first, then the configuration files it would read.
+
+ PIP_* outranks every file. Below that, `pip config list` reports the effective values from
+ the site, user and global files, an `[install]` key outranking its `[global]` twin for an
+ install. A `no-index` or an exclusive `index-url` set there replaces PyPI just as the
+ environment does. Doubt (a `pip config` that cannot be read) keeps the skip.
+ """
+ if _env_flag("PIP_NO_INDEX"):
+ return False
+ extra_is_pypi = any(
+ _url_is_public_pypi(u) for u in os.environ.get("PIP_EXTRA_INDEX_URL", "").split()
+ )
+ value = os.environ.get("PIP_INDEX_URL", "").strip()
+ if value:
+ return extra_is_pypi or _url_is_public_pypi(value)
+ policy = _pip_config_index_policy()
+ if policy["unreadable"] or policy["no_index"] is True:
+ return False
+ extra_is_pypi = extra_is_pypi or any(_url_is_public_pypi(u) for u in policy["extra_index_urls"])
+ index_url = policy["index_url"]
+ if isinstance(index_url, str) and not _url_is_public_pypi(index_url):
+ return extra_is_pypi
+ return True
+
+
+def _pip_config_index_policy() -> "dict[str, object]":
+ """The index keys pip's configuration files set, read from `pip config list`.
+
+ Lines are `<section>.<key>='<value>'`; `:env:` entries mirror PIP_* variables the caller
+ already read, so they are skipped. `install.<key>` outranks `global.<key>`, as it does for
+ pip itself. A `pip config` that cannot run or be parsed is reported unreadable.
+ """
+ policy: "dict[str, object]" = {
+ "no_index": None,
+ "index_url": None,
+ "extra_index_urls": [],
+ "unreadable": False,
+ }
+ try:
+ done = subprocess.run(
+ [sys.executable, "-m", "pip", "config", "list"],
+ capture_output = True,
+ text = True,
+ timeout = 60,
+ **_windows_hidden_subprocess_kwargs(),
+ )
+ except (OSError, subprocess.SubprocessError):
+ policy["unreadable"] = True
+ return policy
+ if done.returncode != 0:
+ policy["unreadable"] = True
+ return policy
+ found: "dict[str, dict[str, str]]" = {"global": {}, "install": {}}
+ for line in done.stdout.splitlines():
+ m = re.match(r"^(global|install)\.([a-z-]+)=(.*)$", line.strip())
+ if not m:
+ continue
+ section, key, raw = m.groups()
+ raw = raw.strip()
+ if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in "'\"":
+ raw = raw[1:-1]
+ found[section][key] = raw
+ for section in ("global", "install"):
+ keys = found[section]
+ if "no-index" in keys:
+ policy["no_index"] = keys["no-index"].strip().lower() in ("1", "true", "yes", "on")
+ if keys.get("index-url", "").strip():
+ policy["index_url"] = keys["index-url"].strip()
+ if "extra-index-url" in keys:
+ # pip prints the repr, so a multi-line value arrives with a literal backslash-n.
+ policy["extra_index_urls"] = [
+ u for u in re.split(r"\s+|\\n", keys["extra-index-url"]) if u
+ ]
+ return policy
+
+
+def _woa_pypi_provided_versions() -> "dict[str, set[str]]":
+ """{canonical name: versions} install.ps1 found PyPI publishing for THIS interpreter.
+
+ UNSLOTH_WOA_PYPI_PROVIDED carries space-separated `name==version` entries: the wheelhouse
+ wheels install.ps1 discarded because PyPI serves the same version. The managed copy is
+ gone, so find-links no longer answers for them; this is the only record that they resolve.
+ """
+ provided: "dict[str, set[str]]" = {}
+ for entry in os.environ.get("UNSLOTH_WOA_PYPI_PROVIDED", "").split():
+ name, sep, version = entry.partition("==")
+ if sep and name and version:
+ provided.setdefault(_canonical_dist_name(name), set()).add(version)
+ return provided
+
+
+def _public_index_win_arm64_versions(canonical: str) -> "set[str]":
+ """Versions the public index publishes a usable win_arm64 wheel of, for THIS build.
+
+ Empty off win_arm64, empty when the resolve cannot reach PyPI, and empty for an
+ interpreter the recorded wheel is not tagged for. The tag is judged by
+ _wheel_matches_interpreter rather than by comparing strings, so a free-threaded build does
+ not claim a wheel built for the GIL one. install.ps1's own probe is added on top.
+ """
+ if not _is_win_arm64_interpreter() or not _public_pypi_is_reachable():
+ return set()
+ return {
+ version
+ for tag, version in WINDOWS_ARM64_PUBLIC_INDEX_WHEELS.get(canonical, {}).items()
+ if _wheel_matches_interpreter(f"{canonical}-{version}-{tag}-{tag}-win_arm64.whl")
+ } | _woa_pypi_provided_versions().get(_canonical_dist_name(canonical), set())
+
+
+def _windows_arm64_skip_packages(req: "Path | None" = None) -> set[str]:
+ """WINDOWS_ARM64_SKIP_PACKAGES minus whatever the wheelhouse already provides, so
+ hosting a wheel is all it takes to re-enable one of these features here.
+
+ ``req`` is the requirements file about to be installed, when there is one. Its pins
+ decide whether a hosted wheel is actually usable: a name match is not enough, because
+ the resolver has to honour ``tiktoken==0.13.0`` and a staged 0.12.0 wheel leaves it
+ with the unbuildable sdist rather than the skip this list is here to keep.
+ """
+ available = _find_links_wheel_versions()
+ if not available and not any(
+ _public_index_win_arm64_versions(name)
+ for name in set(WINDOWS_ARM64_PUBLIC_INDEX_WHEELS) | set(_woa_pypi_provided_versions())
+ ):
+ return set(WINDOWS_ARM64_SKIP_PACKAGES)
+ pins = _requirement_pins(req)
+
+ def hosted(name: str) -> bool:
+ canonical = _canonical_dist_name(name)
+ versions = set(available.get(canonical) or ()) | _public_index_win_arm64_versions(canonical)
+ if not versions:
+ return False
+ clauses = [clause for clause in pins.get(canonical, []) if clause]
+ if not clauses:
+ floor = WINDOWS_ARM64_BLOCKER_FLOORS.get(canonical)
+ if floor is None:
+ return True
+ clauses = [floor[0]]
+ verdicts = [_version_satisfies(v, c) for v in versions for c in clauses]
+ if any(verdict is True for verdict in verdicts):
+ return True
+ return any(verdict is None for verdict in verdicts)
+
+ keep_skipping: set[str] = set()
+ for package in WINDOWS_ARM64_SKIP_PACKAGES:
+ canonical = _canonical_dist_name(package)
+ blockers = WINDOWS_ARM64_SKIP_UNBLOCKED_BY.get(canonical)
+ if blockers:
+ if all(hosted(b) for b in blockers):
+ continue
+ elif hosted(package):
+ continue
+ keep_skipping.add(package)
+ return keep_skipping
+
+
# Skipped without torch (Intel Mac GGUF-only), plus librosa, whose numba chain fails (#5046).
NO_TORCH_SKIP_PACKAGES = {
"torch-stoi",
@@ -8285,10 +9074,39 @@ def pip_install(
if VERBOSE and result.stdout:
_safe_print(_redact_install_output(result.stdout))
return
+ if _woa_overrides_are_load_bearing():
+ _step("error", f"{label} failed and pip cannot stand in for it", _red)
+ _safe_print(
+ _red(
+ " The Windows on ARM stack resolves through UV_OVERRIDE, which pip has no "
+ "equivalent for: overrides REPLACE a requirement, and pip constraints can "
+ "only narrow one."
+ )
+ )
+ _safe_print(
+ _red(
+ " Falling back here would honour the released torch cap, which no "
+ "win_arm64 CUDA wheel satisfies, and pull back the packages that have no "
+ "win_arm64 build at all -- downgrading a working CUDA torch or failing "
+ "later, with nothing to say why."
+ )
+ )
+ _safe_print(_red(" Install uv and re-run, or re-run install.ps1."))
+ _report_failed_command(label, result)
_safe_print(_red(f" uv failed, falling back to pip..."))
if result.stdout:
_safe_print(_redact_install_output(result.stdout))
+ elif _woa_overrides_are_load_bearing():
+ _step("error", f"{label} needs uv on the Windows on ARM stack", _red)
+ _safe_print(
+ _red(
+ " The native ARM64 resolve depends on UV_OVERRIDE, which pip cannot express. "
+ "Install uv and re-run, or re-run install.ps1."
+ )
+ )
+ sys.exit(1)
+
pip_cmd, pip_env = _pinned_cmd_and_env(
_build_pip_cmd(args) + constraint_args_pip + req_args_pip
)
@@ -8880,11 +9698,19 @@ def _effective_requirements(req: Path) -> "tuple[Path, list[Path]]":
if IS_WINDOWS and WINDOWS_SKIP_PACKAGES:
actual = _filter_requirements(actual, WINDOWS_SKIP_PACKAGES)
temps.append(actual)
+ if _is_win_arm64_interpreter():
+ # Judged against the ORIGINAL file: the pins decide whether a hosted wheel is usable,
+ # and a copy already filtered above no longer carries the rows they sit on.
+ arm64_skip = _windows_arm64_skip_packages(req)
+ if arm64_skip:
+ actual = _filter_requirements(actual, arm64_skip)
+ temps.append(actual)
if NO_TORCH and NO_TORCH_SKIP_PACKAGES:
actual = _filter_requirements(actual, NO_TORCH_SKIP_PACKAGES)
temps.append(actual)
- if PLATFORM_LACKS_TORCHCODEC_WHEEL:
- # Linux aarch64 / Windows ARM64 / Intel Mac have no torchcodec wheel.
+ if PLATFORM_LACKS_TORCHCODEC_WHEEL and not _wheelhouse_hosts("torchcodec"):
+ # Linux aarch64 / Windows ARM64 / Intel Mac have no torchcodec wheel, unless the
+ # win_arm64 wheelhouse hosts one -- step 13b installs that copy itself.
actual = _filter_requirements(actual, {"torchcodec"})
temps.append(actual)
return actual, temps
@@ -10032,6 +10858,10 @@ def install_python_stack() -> int:
# beside a physical GPU.
torch_flavor_tag = _expected_torch_flavor_tag()
+ # 13x. Optional win_arm64 features whose released metadata excludes them outright. After the
+ # invariant above, so xformers is validated against the torch the install ends with.
+ _install_wheelhouse_optionals()
+
# 13b. torchcodec, pinned to the venv's torch minor (_select_torchcodec_spec), which
# extras-no-deps.txt cannot do because markers cannot see torch. Must run after the
# repair above: that can move torch onto another minor, staling an earlier choice.
@@ -10039,14 +10869,38 @@ def install_python_stack() -> int:
# tolerate), so read the installed metadata before giving up: guessing here means
# downgrading a matching codec onto the default and recreating the mismatch.
_codec_torch_ver = None
- if not NO_TORCH and not PLATFORM_LACKS_TORCHCODEC_WHEEL:
+ _codec_hosted = None
+ if not NO_TORCH and (not PLATFORM_LACKS_TORCHCODEC_WHEEL or _wheelhouse_hosts("torchcodec")):
_codec_torch_ver = _probe_installed_torch_version() or _installed_distribution_version(
"torch"
)
+ if not NO_TORCH and PLATFORM_LACKS_TORCHCODEC_WHEEL:
+ _codec_hosted = _wheelhouse_torchcodec_version(_codec_torch_ver)
if NO_TORCH:
_progress("torchcodec (skipped, no torch)")
+ elif _codec_hosted:
+ # The wheelhouse stands in for the wheel this platform lacks: --no-deps and pinned to
+ # the hosted version inside the resident torch's window, like the other hosted optionals.
+ _progress("torchcodec")
+ if pip_install_try(
+ f"Installing torchcodec=={_codec_hosted} from the Windows on ARM wheelhouse",
+ "--no-deps",
+ "--no-cache-dir",
+ f"torchcodec=={_codec_hosted}",
+ constrain = False,
+ ):
+ _note(f"windows on arm: installed torchcodec=={_codec_hosted} from the wheelhouse")
+ else:
+ _note(
+ "windows on arm: could not install the wheelhouse torchcodec -- audio decoding stays disabled"
+ )
elif PLATFORM_LACKS_TORCHCODEC_WHEEL:
_progress("torchcodec (skipped, no wheel for this platform)")
+ if _wheelhouse_hosts("torchcodec"):
+ _note(
+ f"windows on arm: the wheelhouse torchcodec is outside the window torch "
+ f"{_codec_torch_ver or 'unknown'} selects -- leaving audio decoding disabled"
+ )
elif not _codec_torch_ver:
_progress("torchcodec (skipped, torch version unknown)")
_note("could not read the installed torch version -- leaving torchcodec alone")
@@ -10240,6 +11094,7 @@ def install_python_stack() -> int:
expected_torch_tag = _recordable_torch_flavor_tag(torch_flavor_tag),
expected_torch_tag_pinned = bool(_recordable_torch_flavor_tag(torch_flavor_tag))
and _expected_torch_flavor_was_pinned(_recordable_torch_flavor_tag(torch_flavor_tag)),
+ woa_torch_index = os.environ.get("UNSLOTH_WOA_SELECTED_TORCH_INDEX"),
# What the NEXT run may skip. Digested from the CURRENT REQ_ROOT, which the core step
# may have replaced: a file that moved during this pass must not read as unchanged.
extra = {
diff --git a/studio/prebuilt_core.py b/studio/prebuilt_core.py
index afceebfb617..ed9d9bd5372 100644
--- a/studio/prebuilt_core.py
+++ b/studio/prebuilt_core.py
@@ -932,6 +932,31 @@ def release_asset_map(release: dict[str, Any]) -> dict[str, str]:
}
+def release_asset_digests(release: dict[str, Any]) -> dict[str, str]:
+ """asset name -> bare sha256 hex, for the assets whose digest GitHub reports.
+
+ Separate from release_asset_map because the name -> url mapping is what nearly every
+ caller wants and widening its return type would touch all of them. GitHub returns
+ `digest` as an algorithm-prefixed string ("sha256:<hex>"); anything else is skipped
+ rather than guessed at, so a future algorithm cannot be read as a sha256.
+ """
+ assets = release.get("assets")
+ if not isinstance(assets, list):
+ return {}
+ digests: dict[str, str] = {}
+ for asset in assets:
+ if not isinstance(asset, dict) or not isinstance(asset.get("name"), str):
+ continue
+ raw = asset.get("digest")
+ # The prefix is required, not stripped for convenience: normalize_sha256_digest accepts a bare 64-hex string, and an unprefixed digest is one whose algorithm GitHub did not state.
+ if not isinstance(raw, str) or not raw.lower().startswith("sha256:"):
+ continue
+ digest = normalize_sha256_digest(raw)
+ if digest:
+ digests[asset["name"]] = digest
+ return digests
+
+
def github_release(
ops: ModuleOps,
repo: str,
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index bf20c747486..04ffe02ae53 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -176,6 +176,7 @@ function Exit-SetupFailure {
[Parameter(Mandatory = $true)][string]$Message,
[int]$Code = 1
)
+ if (Get-Command Remove-WoaMergedOverrides -CommandType Function -ErrorAction SilentlyContinue) { Remove-WoaMergedOverrides }
if ($Code -eq 0) { $Code = 1 }
if ((@("1", "true") -contains $env:UNSLOTH_TAURI_MODE) -or
(@("1", "true") -contains $env:UNSLOTH_TAURI_UPDATE)) {
@@ -1721,7 +1722,10 @@ function Ensure-BuildToolsForLlamaSourceBuild {
function Get-HostMachineArch {
$osArch = ""
try { $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() } catch { }
- foreach ($s in @([string]$env:PROCESSOR_ARCHITEW6432, [string]$env:PROCESSOR_ARCHITECTURE, $osArch)) {
+ # 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"
@@ -4603,6 +4607,672 @@ function Get-PersistedNoTorch {
return (Test-Path -LiteralPath (Join-Path $VenvPath $NoTorchMarker) -PathType Leaf)
}
+# The CUDA index install.ps1 chose. Only NVIDIA's channels are written, so never credentialed.
+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, anchored, no `?` or `#`: a hand-edited manifest must not redirect torch.
+ if ($value -notmatch '^https://pypi\.nvidia\.com(/[A-Za-z0-9._~/-]*)?$') { return "" }
+ return $value
+}
+
+# The dependency pass drops the manifest before rebuilding it, so this marker lives outside it.
+# Parity copies of install.ps1's index probe, kept identical by a parity test: the forced repair below carries the same unsafe-best-match, so an open-ended spec lets a PyPI CPU release win.
+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 share an empty stamp, so they pair by offset: torchvision 0.(M+15) to 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: the index that serves torch's shared dependencies beside the CUDA one has to be the same answer from a fresh shell.
+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) {
+ # Basic strings escape; literal (single-quoted) ones do not.
+ 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's inline spelling of [[index]], returning @{ DefaultUrl; Extras } or $null on ANY doubt, and only for a single-line array of FLAT inline tables. The brace characters below are built from code points: the parity tests extract a function 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 = @() }
+ # `index = []` is a definite answer -- no indexes -- not a failure to read one.
+ 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, not an inline table. Tested before string mode starts, or the literal is consumed whole.
+ 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 }
+ # uv: an explicit index serves only packages pinned to it via [tool.uv.sources], so it is neither the default nor an 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 the default (uv docs): 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 { $_ }) }
+}
+
+function Get-WoaUvConfigIndexPolicy {
+ $result = @{ NoIndex = $false; DefaultIndex = $null; Unreadable = $false; UnreadablePath = $null; ExtraIndexes = @() }
+ $noCfg = [string](Get-Item Env:UV_NO_CONFIG -ErrorAction SilentlyContinue).Value
+ if ($noCfg -and ($noCfg.Trim().ToLowerInvariant() -notin @("", "0", "false"))) { return $result }
+ $files = @()
+ $cfgFile = [string](Get-Item Env:UV_CONFIG_FILE -ErrorAction SilentlyContinue).Value
+ 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
+}
+
+# True when uv's own config decides the indexes and we could not read it: fatal where the caller scrubs UV_* and sets UV_NO_CONFIG, because the trio index would be the only source left.
+function Test-WoaUvIndexPolicyUnreadable {
+ foreach ($name in @("UV_NO_INDEX", "UV_DEFAULT_INDEX", "UV_INDEX_URL")) {
+ $v = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($v -and $v.Trim()) { return $false }
+ }
+ return [bool](Get-WoaUvConfigIndexPolicy).Unreadable
+}
+
+function Get-WoaDependencyIndexArgs {
+ param([string]$Resolver = "uv")
+ $pip = ($Resolver -eq "pip")
+ $noIndexNames = if ($pip) { @("PIP_NO_INDEX") } else { @("UV_NO_INDEX") }
+ $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") }
+ foreach ($name in $noIndexNames) {
+ $flag = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($flag -and ($flag.Trim().ToLowerInvariant() -notin @("", "0", "false"))) { return @() }
+ }
+ $default = $null
+ foreach ($name in $defaultNames) {
+ $url = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ if ($url -and $url.Trim()) { $default = $url.Trim(); break }
+ }
+ $extras = @()
+ foreach ($name in $extraNames) {
+ $list = [string](Get-Item "Env:$name" -ErrorAction SilentlyContinue).Value
+ 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: torchaudio tracks torch's major.minor.
+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 numeric release: dev < a < b < rc < final, then by number.
+ $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)
+ }
+ # -Below: only versions ranked strictly under it, so a caller can walk back from an unpaired newest.
+ $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 corporate-mirror host back to NVIDIA's.
+ 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
+ }
+ if ($short -and -not $short.Contains(" ")) { 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 off, or the rebase reads it as part of 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, dropping the option token.
+ $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"
+ }
+ # -e / --editable names a path too. 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]
+ # PEP 508 separates a marker from a URL with whitespace before the ";": kept aside, or it would be 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" }
+ }
+ # A bare local directory is a requirement to pip and uv both; the leading dot segment is what tells it from a package name.
+ 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: a conflict can sit a level down, and two files naming one package is an error.
+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)
+}
+
+# Put back what install.ps1 exported: process-scoped, so a direct update starts without them. The merged override file copies caller lines, which can carry 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
+ # install.ps1's per-run copy of folded caller lines; an interrupted run must not leave it behind.
+ 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: standing down left the staged win_arm64 wheels out entirely.
+ $_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 that could be interrupted, and cleared when torch is
# wanted so migrating out of no-torch leaves nothing stale behind.
function Set-PersistedNoTorch {
@@ -4655,6 +5325,34 @@ $InstallerManagedSetup = $env:UNSLOTH_INSTALL_ROLLBACK_MANAGED -match '^(?i:true
# 7.0-7.4 remove the variable.
$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. Memoized.
+$script:_winArm64Venv = $null
+function Test-WinArm64Venv {
+ if ($null -ne $script:_winArm64Venv) { return $script:_winArm64Venv }
+ # Answered before any interpreter is launched: a corrupt python could hang the install.
+ if ((Get-HostMachineArch) -ne "arm64") {
+ $script:_winArm64Venv = $false
+ return $false
+ }
+ # By path first: `python` may not be the venv's own, and a wrong answer "repairs" a good torch.
+ $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) {
+ # Caching a failure would pin the wrong answer for the rest of the run.
+ $script:_winArm64Venv = ($platform -eq "win-arm64")
+ return $script:_winArm64Venv
+ }
+ }
+ return $false
+}
+
# Only the stale-venv block below assigns this, but the XPU install reads it to decide whether to
# force-reinstall and a fresh install never enters that block. Declaring it keeps a caller's
# Set-StrictMode from making the read fatal.
@@ -4805,6 +5503,16 @@ if ((Test-Path -LiteralPath $VenvDir -PathType Container) -and -not $NoTorchMode
}
}
+ # Keep a CUDA torch already here: its family tag is not one download.pytorch.org publishes, so the comparison can only disagree. ANY explicit pin is exempt; this distrusts the INFERRED one.
+ 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
+ }
+
# A stale venv whose torch still imports is repaired in place; only a broken venv wipes.
if ($shouldRebuild -and $_pinnedIdx -and $installedTorchTag) {
substep "Torch-index pin changed ($installedTorchTag) -- reinstalling torch from the pin in place." "Cyan"
@@ -5082,7 +5790,9 @@ $UvPinnedAssets = @{
function Get-UvHostArch {
$osArch = ""
try { $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() } catch { $osArch = "" }
- $signals = @([string]$env:PROCESSOR_ARCHITEW6432, [string]$env:PROCESSOR_ARCHITECTURE, $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" }
}
@@ -5343,6 +6053,29 @@ if (Get-Command uv -ErrorAction SilentlyContinue) {
# the catch: this is the last statement before Fast-Install starts resolving `python`.
Assert-VenvActivated -VenvDir $VenvDir
+# pip does not understand uv's resolver flags, so they are dropped with any value that follows. Of --prerelease's five values only allow maps to pip (--pre); the rest drop rather than invert.
+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
+}
+
# Helper: install a package, preferring uv with pip fallback
function Fast-Install {
param([Parameter(ValueFromRemainingArguments=$true)]$Args_)
@@ -5367,7 +6100,8 @@ function Fast-Install {
$result = & uv pip install --python $VenvPy @Args_ 2>&1
if ($LASTEXITCODE -eq 0) { return }
}
- & python -m pip install @Args_ 2>&1
+ $pipArgs = Remove-UvOnlyResolverFlags -Arguments $Args_
+ & python -m pip install @pipArgs 2>&1
}
finally {
if ($pinned) {
@@ -5691,6 +6425,39 @@ if ($script:PinChangedForceReinstall -or $script:TorchImportDefinitivelyFailed)
if (-not $SkipPythonDeps) {
+# Recover what a fresh shell lost, BEFORE the manifest is dropped below: recovery reads that file.
+$WinArm64Venv = Test-WinArm64Venv
+# Read BEFORE the re-export overwrites it: the flags install.ps1 left describe THAT index.
+$_woaHandoffIndex = if ($env:UNSLOTH_WOA_SELECTED_TORCH_INDEX) { $env:UNSLOTH_WOA_SELECTED_TORCH_INDEX.Trim().TrimEnd('/') } else { "" }
+# The index install.ps1 probed, or the CUDA branch takes a driver-derived family with no wheel.
+$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, not just held locally: the manifest rewrite reads it, so a fresh-shell update would erase the index for good. Either record opens the block: the WoA chain alone lost a mirror pin.
+$_woaPinnedIndex = if ($WinArm64Venv) { Get-PinnedTorchIndexUrl } else { $null }
+if ($WinArm64TorchIndexUrl -or $_woaPinnedIndex) {
+ # RECORD the index the torch steps will USE, the generic pin when there is one, in BOTH records since the read chain prefers the manifest. An unpersistable pin is refused rather than left stale.
+ $_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
+ # Written BEFORE the manifest is dropped below, so an interrupted run still leaves this index.
+ Save-WoaTorchIndexMarker -IndexUrl $_woaMarkerIndex
+}
+# A terminating error after this point reaches neither Exit-SetupFailure nor the last statement, so the merged override file, which can carry the caller's credentials, would stay on disk. The trap removes it.
+trap { Remove-WoaMergedOverrides; break }
+Restore-WoaResolverEnvironment
+
# install_python_stack.py drops the manifest before its own dependency pass, but
# pip, torch and triton are replaced first here. Drop it now so a run killed in
# those leaves the venv marked half-built, not behind a marker that verifies.
@@ -5844,17 +6611,111 @@ $TorchInstallIndexUrl = if ($ROCmIndexUrl) { "$PyTorchWhlBase/cpu" } elseif ($Pi
# no-torch mode never reaches the assignment below.
$XpuIndexUrl = $null
+$_effectiveTorchIndexUrl = $TorchInstallIndexUrl
+
if (-not $NoTorchMode) {
# Windows on ARM has win_arm64 torch and torchvision wheels but no torchaudio on any index,
-# so every branch below drops it. Ask the interpreter uv resolves for, not
-# PROCESSOR_ARCHITECTURE, which describes the host process. Inside the no-torch guard
-# because all three uses are, and no-torch installs nothing to skip.
-$_setupPlatform = ""
-try {
- $_setupPlatform = (& python -c "import sysconfig; print(sysconfig.get_platform())" 2>$null | Out-String).Trim().ToLowerInvariant()
-} catch { $_setupPlatform = "" }
-$WinArm64NoAudio = ($_setupPlatform -eq "win-arm64")
-if ($WinArm64NoAudio) { substep "windows on arm: skipping torchaudio (no win_arm64 wheel upstream)" }
+# Absent install.ps1's answer assume no torchaudio: an absent wheel makes the trio unresolvable. $WinArm64EffectiveTorchIndexUrl is which index the torch steps ACTUALLY use.
+$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; every win_arm64 build sits 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
+ # As install.ps1 selects: the newest COMPLETE pair, searched a few torch versions deep, before falling back to what is installed.
+ $_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 {
+ # The venv already exists, so a lagging index keeps the installed pair rather than pinning a torch whose torchvision would resolve against a build it was not made for.
+ $_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" }
+ # This probe is the same one install.ps1 ran, so it decides: a fresh shell has no handoff, and the handoff alone would drop an audio wheel the index does pair with this torch.
+ $_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)."
+ }
+ }
+}
+# <3.7 everywhere except Windows on ARM, whose first win_arm64 wheel is 3.8.0.post28.
+$_tritonSpec = if ($WinArm64Venv) { "triton-windows>=3.8.0.post28" } else { "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" }
+ # Stop rather than guess: Fast-Install sets UV_NO_CONFIG and scrubs UV_* whenever --index-url is passed, so an unreadable uv policy would leave the trio index as the only source here.
+ 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 UV_FIND_LINKS and PIP_FIND_LINKS whenever --index-url is given, so the staged wheelhouse is named on the command line. Only when it exists: 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) {
@@ -6078,9 +6939,10 @@ if (-not $ROCmIndexUrl -and -not $XpuIndexUrl -and ($CuTag -eq "cpu" -or $ROCmCp
$cudaAudioSpec = "torchaudio>=2.4,<2.12.0"
}
# Release preservation: keep the same release across re-runs (+cuXXX follows this index).
+ # Not on win_arm64: the kept release is one NVIDIA's channel does not publish.
$_cudaKeptActive = $false
$_cudaOrigTorch = $cudaTorchSpec; $_cudaOrigVision = $cudaVisionSpec; $_cudaOrigAudio = $cudaAudioSpec
- if ($env:UNSLOTH_KEPT_TORCH -match '^\d+\.\d+(\.\d+)?$') {
+ if (-not $WinArm64Venv -and $env:UNSLOTH_KEPT_TORCH -match '^\d+\.\d+(\.\d+)?$') {
$_keptMinor = [int](($env:UNSLOTH_KEPT_TORCH -split '\.')[1])
$cudaTorchSpec = "torch==$($env:UNSLOTH_KEPT_TORCH)"
$cudaVisionSpec = "torchvision==0.$($_keptMinor + 15).*"
@@ -6088,16 +6950,58 @@ if (-not $ROCmIndexUrl -and -not $XpuIndexUrl -and ($CuTag -eq "cpu" -or $ROCmCp
$_cudaKeptActive = $true
}
while ($true) {
- # A custom pin whose leaf is not cpu lands an ARM64 host here, so drop torchaudio.
+ # An unknown-leaf pin lands an ARM64 host here on builds above the ceilings, so drop them.
$_cudaTrio = @($cudaTorchSpec, $cudaVisionSpec, $cudaAudioSpec)
- if ($WinArm64NoAudio) { $_cudaTrio = @($cudaTorchSpec, $cudaVisionSpec) }
- if ($script:UnslothVerbose) {
- Fast-Install @_cudaTrio @cudaForce --index-url $TorchInstallIndexUrl | ForEach-Object { Redact-InstallOutput "$_" } | Out-Host
- $torchInstallExit = $LASTEXITCODE
- $output = ""
- } else {
- $output = Fast-Install @_cudaTrio @cudaForce --index-url $TorchInstallIndexUrl | Out-String
- $torchInstallExit = $LASTEXITCODE
+ if ($WinArm64Venv) {
+ $_cudaTrio = @($WinArm64TorchSpec, $WinArm64VisionSpec)
+ if (-not $WinArm64NoAudio) { $_cudaTrio += $WinArm64AudioSpec }
+ } elseif ($WinArm64NoAudio) {
+ $_cudaTrio = @($cudaTorchSpec, $cudaVisionSpec)
+ }
+ # An explicit pin outranks the persisted index, which is only a memory of an earlier run.
+ $_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](Get-Item "Env:$_woaCutoffName" -ErrorAction SilentlyContinue).Value
+ 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)."
+ }
+ }
+ # --no-index ignores every registry index, the CUDA one included, and Fast-Install leaves UV_NO_INDEX alone. It yields for this one command: the trio from the CUDA index, dependencies from the wheelhouse.
+ $_woaNoIndexValue = [string](Get-Item "Env:UV_NO_INDEX" -ErrorAction SilentlyContinue).Value
+ if ($_woaNoIndexValue -and ($_woaNoIndexValue.Trim().ToLowerInvariant() -notin @("", "0", "false"))) {
+ $_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 }
substep "[WARN] torch==$($env:UNSLOTH_KEPT_TORCH) not installable from this CUDA index -- using the supported release" "Yellow"
@@ -6111,14 +7015,35 @@ if (-not $ROCmIndexUrl -and -not $XpuIndexUrl -and ($CuTag -eq "cpu" -or $ROCmCp
Exit-SetupFailure "PyTorch CUDA installation failed (exit code $torchInstallExit)"
}
+ # torchaudio left out of the trio: uv would leave it 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 whole pairing, as at selection: major.minor, and the build (dev stamp, CUDA tag) too, since the extension is linked against one libtorch.
+ 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).
substep "installing Triton for Windows..."
if ($script:UnslothVerbose) {
- Fast-Install "triton-windows<3.7"
+ Fast-Install $_tritonSpec
$tritonInstallExit = $LASTEXITCODE
$output = ""
} else {
- $output = Fast-Install "triton-windows<3.7" | Out-String
+ $output = Fast-Install $_tritonSpec | Out-String
$tritonInstallExit = $LASTEXITCODE
}
if ($tritonInstallExit -ne 0) {
@@ -6146,7 +7071,7 @@ if (-not $ROCmIndexUrl -and -not $XpuIndexUrl -and ($CuTag -eq "cpu" -or $ROCmCp
# Windows wheel is 2.11.0+cpu, and only install.ps1 -- never on the updater's path -- repaired
# that. Vocabulary is Get-InstalledTorchTag's; an unknown leaf publishes nothing.
if (-not $NoTorchMode) {
- $_expectedLeaf = Get-TorchIndexLeaf $TorchInstallIndexUrl
+ $_expectedLeaf = Get-TorchIndexLeaf $_effectiveTorchIndexUrl
# $ROCmIndexUrl first: on the AMD path $TorchInstallIndexUrl still points at /cpu.
$_expectedTag = if ($ROCmIndexUrl) { "rocm" }
elseif (Test-CudaFamilyLeaf $_expectedLeaf) { $_expectedLeaf }
@@ -6161,8 +7086,8 @@ if (-not $NoTorchMode) {
} else {
Remove-Item Env:\UNSLOTH_EXPECTED_TORCH_TAG -ErrorAction SilentlyContinue
}
- if ($TorchInstallIndexUrl) {
- $env:UNSLOTH_TORCH_INSTALL_INDEX_URL = $TorchInstallIndexUrl
+ if ($_effectiveTorchIndexUrl) {
+ $env:UNSLOTH_TORCH_INSTALL_INDEX_URL = $_effectiveTorchIndexUrl
} else {
Remove-Item Env:\UNSLOTH_TORCH_INSTALL_INDEX_URL -ErrorAction SilentlyContinue
}
@@ -6307,7 +7232,7 @@ if ($stackExit -eq 0 -and $XpuIndexUrl) {
# Off the network by now, so this is disk/permissions. triton-windows is
# already gone and took the shared paths with it, so put SOME working
# triton back rather than leave the venv unable to import one.
- Fast-Install --force-reinstall --no-deps "triton-windows<3.7" | Out-Null
+ Fast-Install --force-reinstall --no-deps $_tritonSpec | Out-Null
$tritonBackExit = $LASTEXITCODE
$_tritonPresent = ($tritonBackExit -eq 0)
Write-StudioLine (Redact-InstallOutput $tritonOutput) -ForegroundColor Yellow
@@ -6874,12 +7799,29 @@ if ($LocalLlamaCppLinked) {
try {
$existingMeta = Get-Content -LiteralPath $existingMetaPath -Raw | ConvertFrom-Json
$existingKind = $existingMeta.install_kind
- # ROCm hosts carry windows-rocm or -hip; CPU covers -cpu and -arm64.
- # Inert: the marker records "backend", never "install_kind", so
- # $existingKind is always null. windows-vulkan is in every branch because
- # any x64 Windows host can end up there, and repairing this guard without
- # it would delete a working Vulkan install on every setup run.
- $expectedKinds = if ($HasROCm -or $script:ROCmGfxArch) { @("windows-rocm", "windows-hip", "windows-vulkan") } elseif ($HasNvidiaSmi) { @("windows-cuda", "windows-vulkan") } else { @("windows-cpu", "windows-arm64", "windows-vulkan") }
+ # windows-vulkan is in every branch: any x64 Windows host can land there, and a guard without it deletes a working Vulkan install on every run. The VENV's arch, not the machine's.
+ $_arm64CudaOptOut = ("$env:UNSLOTH_LLAMA_ARM64_CUDA").Trim().ToLowerInvariant() -in @("0", "false", "no", "off")
+ # Still valid unopted: the selector falls back to it when no ARM64 CUDA asset exists.
+ $_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. Read here, not from the dependency pass, which $SkipPythonDeps skips whole.
+ $_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 = $HasNvidiaSmi -or ((Test-WinArm64Venv) -and $_woaEvidenceIndex -and
+ (Test-WoaPersistableIndex $_woaEvidenceIndex))
+ # No ROCm bundle exists for Windows ARM64 (upstream's is hip-radeon-x64), so the selector falls through to the ARM64 CPU bundle; without that kind here the gate refetches it 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 ($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
@@ -7858,3 +8800,5 @@ if ($script:LlamaCppDegraded -and $env:SKIP_STUDIO_BASE -ne "1" -and
[Console]::Out.WriteLine("[TAURI:DIAG] llama_cpp=unavailable")
[Console]::Out.Flush()
}
+
+Remove-WoaMergedOverrides
diff --git a/studio/src-tauri/build.rs b/studio/src-tauri/build.rs
index d860e1e6a7c..03d4902b6be 100644
--- a/studio/src-tauri/build.rs
+++ b/studio/src-tauri/build.rs
@@ -1,3 +1,6 @@
+// Building for aarch64-pc-windows-msvc needs clang on PATH: ring and aws-lc-sys assemble their
+// aarch64 sources through cc-rs, which reaches for clang rather than cl.exe, and the failure
+// names ring rather than the missing toolchain. No other leg builds for aarch64 Windows.
fn main() {
tauri_build::build()
}
diff --git a/studio/src-tauri/src/update.rs b/studio/src-tauri/src/update.rs
index 0d52425dee9..eb7743c06fa 100644
--- a/studio/src-tauri/src/update.rs
+++ b/studio/src-tauri/src/update.rs
@@ -704,17 +704,19 @@ mod tests {
let state = new_update_state();
state.lock().unwrap().child = Some(child);
- for _ in 0..50 {
- if child_pid_file.is_file() {
- break;
+ // Wait for a pid that PARSES, not merely for the path to appear: the redirection above
+ // creates the file before anything is written, so is_file() can win that race and read "".
+ let mut descendant = None;
+ for _ in 0..100 {
+ if let Ok(text) = std::fs::read_to_string(&child_pid_file) {
+ if let Ok(pid) = text.trim().parse::<i32>() {
+ descendant = Some(pid);
+ break;
+ }
}
std::thread::sleep(std::time::Duration::from_millis(20));
}
- let descendant = std::fs::read_to_string(&child_pid_file)
- .unwrap()
- .trim()
- .parse::<i32>()
- .unwrap();
+ let descendant = descendant.expect("the test child never wrote a usable descendant pid");
stop_update(&state).unwrap();
diff --git a/tests/python/test_sign_wheel_binaries.py b/tests/python/test_sign_wheel_binaries.py
new file mode 100644
index 00000000000..0252ae4d7bb
--- /dev/null
+++ b/tests/python/test_sign_wheel_binaries.py
@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The wheelhouse signer: what it signs, what it refuses, and what it must not break.
+
+A .whl cannot be Authenticode signed, so the native binaries inside it are, and the wheel is
+repacked. That makes RECORD the thing most likely to go quietly wrong -- signing changes every
+signed member's bytes, and a stale RECORD ships a wheel that reads as corrupt to anything that
+checks it. The signing call itself is stubbed here: this is about the packing, the refusals and
+the RECORD, none of which need Azure.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import importlib.util
+import struct
+import sys
+import zipfile
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIGNER_PY = REPO_ROOT / ".github" / "scripts" / "sign_wheel_binaries.py"
+WORKFLOW = REPO_ROOT / ".github" / "workflows" / "woa-wheelhouse.yml"
+
+
[email protected](scope = "module")
+def mod():
+ spec = importlib.util.spec_from_file_location("_sign_wheel_binaries", SIGNER_PY)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _pe(
+ machine: int = 0xAA64,
+ *,
+ signed: bool = False,
+ plus: bool = True,
+) -> bytes:
+ """The smallest byte string the reader will accept as a PE image.
+
+ Built rather than vendored: a real .pyd in the tree would be a binary nobody can review,
+ and every field this tool reads is one of the four below.
+ """
+ header_at = 0x80
+ blob = bytearray(b"\0" * 0x400)
+ blob[0:2] = b"MZ"
+ struct.pack_into("<I", blob, 0x3C, header_at)
+ blob[header_at : header_at + 4] = b"PE\0\0"
+ struct.pack_into("<H", blob, header_at + 4, machine)
+ magic_at = header_at + 24
+ struct.pack_into("<H", blob, magic_at, 0x20B if plus else 0x10B)
+ directory_at = magic_at + (112 if plus else 96) + 4 * 8
+ if signed:
+ struct.pack_into("<II", blob, directory_at, 0x300, 0x40)
+ return bytes(blob)
+
+
+def _record(names_and_blobs) -> str:
+ lines = []
+ for name, blob in names_and_blobs:
+ digest = base64.urlsafe_b64encode(hashlib.sha256(blob).digest()).rstrip(b"=").decode()
+ lines.append(f"{name},sha256={digest},{len(blob)}")
+ return "\n".join(lines) + "\n"
+
+
+def _wheel(path: Path, members: dict) -> Path:
+ """A wheel whose RECORD matches its contents, the way a real one arrives."""
+ dist = "demo-1.0.dist-info"
+ record_name = f"{dist}/RECORD"
+ body = dict(members)
+ body.setdefault(f"{dist}/WHEEL", b"Wheel-Version: 1.0\nTag: cp313-cp313-win_arm64\n")
+ body.setdefault(f"{dist}/METADATA", b"Name: demo\nVersion: 1.0\n")
+ with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
+ for name, blob in body.items():
+ z.writestr(name, blob)
+ z.writestr(record_name, _record(list(body.items())) + f"{record_name},,\n")
+ return path
+
+
+def fake_signer(tmp_path):
+ """Stands in for trusted-signing-cli: appends a certificate table to the file it is given.
+
+ The real one talks to Azure. What this file's tests are about is everything around that
+ call, so the stub does the one thing the caller checks for -- the file comes back signed.
+ """
+ script = tmp_path / "fake_signer.py"
+ script.write_text(
+ "import struct, sys\n"
+ "from pathlib import Path\n"
+ "p = Path(sys.argv[1]); d = bytearray(p.read_bytes())\n"
+ "h = struct.unpack_from('<I', d, 0x3C)[0]\n"
+ "magic_at = h + 24\n"
+ "magic = struct.unpack_from('<H', d, magic_at)[0]\n"
+ "at = magic_at + (112 if magic == 0x20b else 96) + 4 * 8\n"
+ "struct.pack_into('<II', d, at, len(d), 0x40)\n"
+ "d += b'CERTIFICATE'\n"
+ "p.write_bytes(bytes(d))\n",
+ encoding = "utf-8",
+ )
+ return [sys.executable, str(script)]
+
+
+class TestWhatCountsAsAPeImage:
+ def test_a_pe_is_recognised(self, mod):
+ assert mod.pe_machine(_pe()) == 0xAA64
+
+ @pytest.mark.parametrize(
+ "blob, why",
+ [
+ (b"", "empty"),
+ (b"not a pe at all, just text in a wheel", "plain data"),
+ (b"MZ" + b"\0" * 8, "an MZ header too short to hold an offset"),
+ (b"MZ" + b"\0" * 0x200, "an MZ header whose PE offset points at zeros"),
+ ],
+ )
+ def test_everything_else_is_not(self, mod, blob, why):
+ assert mod.pe_machine(blob) is None, why
+
+ def test_an_unsigned_image_reads_as_unsigned(self, mod):
+ assert mod.is_signed(_pe()) is False
+
+ @pytest.mark.parametrize("plus", [True, False], ids = ["PE32+", "PE32"])
+ def test_a_signed_image_reads_as_signed(self, mod, plus):
+ """PE32 and PE32+ put the data directory at different offsets; a reader that assumed
+ one would call every 32-bit signed DLL unsigned and re-sign somebody else's binary."""
+ assert mod.is_signed(_pe(signed = True, plus = plus)) is True
+
+
+class TestSigningAWheel:
+ def test_every_unsigned_binary_is_signed(self, mod, tmp_path, fake_signer):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/__init__.py": b"x = 1\n",
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ "demo/helper.dll": _pe(),
+ },
+ )
+ out, signed, skipped = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ assert sorted(signed) == ["demo/_core.cp313-win_arm64.pyd", "demo/helper.dll"]
+ assert skipped == []
+ with zipfile.ZipFile(out) as z:
+ for name in signed:
+ assert mod.is_signed(z.read(name)), name
+
+ def test_an_already_signed_binary_is_left_alone(self, mod, tmp_path, fake_signer):
+ """delvewheel vendors Microsoft's redistributables into pyarrow already signed by
+ Microsoft. Re-signing one replaces their signature with ours."""
+ original = _pe(signed = True)
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ "demo.libs/msvcp140-abcdef.dll": original,
+ },
+ )
+ out, signed, skipped = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ assert signed == ["demo/_core.cp313-win_arm64.pyd"]
+ assert skipped == ["demo.libs/msvcp140-abcdef.dll"]
+ with zipfile.ZipFile(out) as z:
+ assert z.read("demo.libs/msvcp140-abcdef.dll") == original, "byte-for-byte untouched"
+
+ def test_the_wheel_keeps_its_name(self, mod, tmp_path, fake_signer):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ out, _, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ assert out.name == wheel.name, "the index and every pin name the wheel by filename"
+
+ def test_non_binary_members_are_carried_through_unchanged(self, mod, tmp_path, fake_signer):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/__init__.py": b"x = 1\n",
+ "demo/data.json": b'{"a": 1}',
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ out, _, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ with zipfile.ZipFile(out) as z:
+ assert z.read("demo/__init__.py") == b"x = 1\n"
+ assert z.read("demo/data.json") == b'{"a": 1}'
+
+ def test_member_order_is_preserved(self, mod, tmp_path, fake_signer):
+ members = {
+ "demo/__init__.py": b"x = 1\n",
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ "demo/zzz.py": b"pass\n",
+ }
+ wheel = _wheel(tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl", members)
+ with zipfile.ZipFile(wheel) as z:
+ before = z.namelist()
+ out, _, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ with zipfile.ZipFile(out) as z:
+ assert z.namelist() == before, "a diff should show signatures and nothing else"
+
+
+class TestTheRecordIsRegenerated:
+ """Signing appends a certificate table, so every signed member's digest and length move.
+ A wheel shipped with its original RECORD is one `pip check` away from reading as corrupt."""
+
+ @staticmethod
+ def _rows(wheel: Path) -> dict:
+ with zipfile.ZipFile(wheel) as z:
+ record = next(n for n in z.namelist() if n.endswith(".dist-info/RECORD"))
+ rows = {}
+ for line in z.read(record).decode().splitlines():
+ if line.strip():
+ parts = line.split(",")
+ rows[parts[0]] = (parts[1], parts[2])
+ return rows
+
+ def test_every_member_digest_matches_the_bytes_shipped(self, mod, tmp_path, fake_signer):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/__init__.py": b"x = 1\n",
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ out, _, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ rows = self._rows(out)
+ with zipfile.ZipFile(out) as z:
+ for name in z.namelist():
+ if name.endswith(".dist-info/RECORD"):
+ continue
+ blob = z.read(name)
+ expected = base64.urlsafe_b64encode(hashlib.sha256(blob).digest()).rstrip(b"=")
+ assert rows[name] == (f"sha256={expected.decode()}", str(len(blob))), name
+
+ def test_the_signed_binary_digest_actually_changed(self, mod, tmp_path, fake_signer):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ before = self._rows(wheel)["demo/_core.cp313-win_arm64.pyd"]
+ out, _, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ after = self._rows(out)["demo/_core.cp313-win_arm64.pyd"]
+ assert (
+ before != after
+ ), "the fixture did not really change the bytes, so this proves nothing"
+
+ def test_record_names_itself_without_a_digest(self, mod, tmp_path, fake_signer):
+ """PEP 376: RECORD cannot hash itself, and a tool that writes one anyway makes the
+ file self-contradictory."""
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ out, _, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+ assert self._rows(out)["demo-1.0.dist-info/RECORD"] == ("", "")
+
+
+class TestItRefusesRatherThanShipSomethingWrong:
+ def test_a_foreign_architecture_is_refused(self, mod, tmp_path, fake_signer):
+ """0x8664 is x64. A win_arm64 filename says nothing about what was linked in, and
+ signing one would publish a correctly signed wheel that cannot load."""
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(machine = 0x8664),
+ },
+ )
+ with pytest.raises(SystemExit, match = "0x8664"):
+ mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+
+ def test_a_foreign_architecture_is_allowed_when_asked(self, mod, tmp_path, fake_signer):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_amd64.whl",
+ {
+ "demo/_core.cp313-win_amd64.pyd": _pe(machine = 0x8664),
+ },
+ )
+ _, signed, _ = mod.sign_wheel(wheel, tmp_path / "out", fake_signer, require_machine = None)
+ assert signed == ["demo/_core.cp313-win_amd64.pyd"]
+
+ def test_a_wheel_with_no_binaries_is_refused(self, mod, tmp_path, fake_signer):
+ """Nothing to sign means the build produced a pure-Python wheel where a native one was
+ expected. Publishing it silently is how an unsigned wheelhouse comes back."""
+ wheel = _wheel(tmp_path / "demo-1.0-py3-none-win_arm64.whl", {"demo/__init__.py": b"x\n"})
+ with pytest.raises(SystemExit, match = "no PE images"):
+ mod.sign_wheel(wheel, tmp_path / "out", fake_signer)
+
+ def test_a_signer_that_fails_fails_the_run(self, mod, tmp_path):
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ failing = [sys.executable, "-c", "import sys; sys.exit(3)"]
+ with pytest.raises(SystemExit, match = "signing failed"):
+ mod.sign_wheel(wheel, tmp_path / "out", failing)
+
+ def test_a_signer_that_silently_does_nothing_fails_the_run(self, mod, tmp_path):
+ """Exit 0 with the file untouched is the dangerous case: it would publish an unsigned
+ wheel while every log line says it was signed."""
+ wheel = _wheel(
+ tmp_path / "demo-1.0-cp313-cp313-win_arm64.whl",
+ {
+ "demo/_core.cp313-win_arm64.pyd": _pe(),
+ },
+ )
+ noop = [sys.executable, "-c", "import sys"]
+ with pytest.raises(SystemExit, match = "no certificate after signing"):
+ mod.sign_wheel(wheel, tmp_path / "out", noop)
+
+
+class TestTheWorkflowUsesTheProcedureTheDesktopReleaseUses:
+ """One signing procedure, one definition. A second copy of the endpoint or the identity
+ drifts, and the drift is invisible until a release is signed by the wrong certificate."""
+
+ @pytest.fixture(scope = "class")
+ def text(self):
+ return WORKFLOW.read_text(encoding = "utf-8")
+
+ def test_it_delegates_to_the_shared_signing_helper(self, text):
+ assert "studio/src-tauri/windows/sign-with-trusted-signing.ps1" in text
+ assert "codesigning.azure.net" not in text, "the endpoint belongs to the helper only"
+
+ def test_the_signing_cli_is_digest_pinned(self, text):
+ assert "TRUSTED_SIGNING_CLI_SHA256" in text
+ desktop = (REPO_ROOT / ".github" / "workflows" / "release-desktop.yml").read_text(
+ encoding = "utf-8"
+ )
+ import re
+
+ pinned = re.findall(r'TRUSTED_SIGNING_CLI_SHA256:\s*"([0-9a-f]{64})"', text)
+ assert pinned, "no digest pin"
+ assert pinned[0] in desktop, "the two workflows pin different signing binaries"
+
+ def test_the_secrets_are_gated_by_an_environment(self, text):
+ assert "environment: release-signing" in text, (
+ "without an environment there is nowhere to hang a required reviewer, so anyone "
+ "who can dispatch this can sign under our identity"
+ )
+
+ def test_only_the_signing_job_reads_the_azure_secrets(self, text):
+ import yaml
+ data = yaml.safe_load(text)
+ for name, job in data["jobs"].items():
+ uses_azure = "AZURE_" in yaml.safe_dump(job)
+ if uses_azure:
+ assert name == "sign", f"{name} reads the signing secrets"
+ assert job.get("environment") == "release-signing"
+
+ def test_it_cannot_be_reached_from_a_pull_request(self, text):
+ import yaml
+
+ data = yaml.safe_load(text)
+ triggers = data[True] if True in data else data["on"]
+ assert set(triggers) == {
+ "workflow_dispatch"
+ }, "this job holds signing credentials and writes a release"
+
+ def test_publishing_is_opt_in(self, text):
+ import yaml
+
+ data = yaml.safe_load(text)
+ publish = data[True]["workflow_dispatch"]["inputs"]["publish"]
+ assert publish["default"] is False, "a dispatch must not publish unless asked"
+ assert "inputs.publish" in str(data["jobs"]["publish"]["if"])
+
+ def test_write_permission_is_scoped_to_the_publish_job(self, text):
+ import yaml
+
+ data = yaml.safe_load(text)
+ assert data["permissions"] == {"contents": "read"}, "the default must be read"
+ assert data["jobs"]["publish"]["permissions"] == {"contents": "write"}
+ for name, job in data["jobs"].items():
+ if name != "publish":
+ assert "permissions" not in job or job["permissions"].get("contents") != "write"
+
+ def test_the_published_set_is_checked_before_signing(self, text):
+ """A short matrix leg would otherwise publish a wheelhouse missing an interpreter,
+ which reads downstream as 'no wheel for this Python' rather than as a failed build."""
+ assert "expected 5 wheels" in text
diff --git a/tests/python/test_windows_arm64_requirement_markers.py b/tests/python/test_windows_arm64_requirement_markers.py
new file mode 100644
index 00000000000..53e31904233
--- /dev/null
+++ b/tests/python/test_windows_arm64_requirement_markers.py
@@ -0,0 +1,344 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Windows on ARM is pinned by splitting rows, so the split must be a true partition.
+
+Every package that needs a different version on win_arm64 is written as two rows:
+
+ X==old ; sys_platform != "win32" or platform_machine != "ARM64"
+ X>=new ; sys_platform == "win32" and platform_machine == "ARM64"
+
+The second marker is the exact complement of the first, so in every environment exactly one
+row is live. Getting that wrong is silent either way: an OVERLAP makes pip intersect two
+specifiers and can render the row unsatisfiable, a GAP drops the package on some platform
+nobody tested. The compare is case-sensitive, which is what isolates Windows on ARM (macOS
+reports ``arm64`` and Linux ``aarch64``), so that is asserted here too.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import itertools
+from pathlib import Path
+
+import pytest
+
+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+REQ_FILES = [
+ REPO_ROOT / "studio/backend/requirements/extras.txt",
+ REPO_ROOT / "studio/backend/requirements/no-torch-runtime.txt",
+ REPO_ROOT / "studio/backend/requirements/single-env/constraints.txt",
+ REPO_ROOT / "studio/backend/requirements/studio.txt",
+]
+
+# (sys_platform, platform_system, platform_machine, os_name)
+PLATFORMS = [
+ ("linux", "Linux", "x86_64", "posix"),
+ ("linux", "Linux", "aarch64", "posix"),
+ ("linux", "Linux", "armv7l", "posix"),
+ ("linux", "Linux", "ppc64le", "posix"),
+ ("linux", "Linux", "s390x", "posix"),
+ ("darwin", "Darwin", "arm64", "posix"),
+ ("darwin", "Darwin", "x86_64", "posix"),
+ ("win32", "Windows", "AMD64", "nt"),
+ ("win32", "Windows", "x86", "nt"),
+ ("win32", "Windows", "ARM64", "nt"),
+]
+PYTHONS = ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+WOA = ("win32", "Windows", "ARM64", "nt")
+
+
+def _env(plat, py):
+ sys_platform, platform_system, platform_machine, os_name = plat
+ return {
+ "implementation_name": "cpython",
+ "implementation_version": f"{py}.0",
+ "os_name": os_name,
+ "platform_machine": platform_machine,
+ "platform_python_implementation": "CPython",
+ "platform_release": "",
+ "platform_system": platform_system,
+ "platform_version": "",
+ "python_full_version": f"{py}.0",
+ "python_version": py,
+ "sys_platform": sys_platform,
+ "extra": "",
+ }
+
+
+#: Every environment the rows below are evaluated in, built once.
+ENVS = [(plat, py, _env(plat, py)) for plat, py in itertools.product(PLATFORMS, PYTHONS)]
+
+
+def _live(rows, env):
+ """The rows pip would install in `env`."""
+ return [r for r in rows if r.marker is None or r.marker.evaluate(env)]
+
+
+def _rows(path: Path) -> list[Requirement]:
+ out = []
+ for raw in path.read_text(encoding = "utf-8").splitlines():
+ line = raw.strip()
+ if not line or line.startswith(("#", "-")):
+ continue
+ line = line.split("#", 1)[0].strip()
+ if line:
+ out.append(Requirement(line))
+ return out
+
+
+def _by_name(reqs: list[Requirement]) -> dict[str, list[Requirement]]:
+ grouped: dict[str, list[Requirement]] = {}
+ for req in reqs:
+ grouped.setdefault(req.name.lower().replace("_", "-"), []).append(req)
+ return grouped
+
+
+def _multi_row_groups(reqs):
+ """Packages stated more than once, minus the ones that are different targets.
+
+ unsloth[a] and unsloth[b] may legitimately co-exist, so a group whose rows differ in
+ their extras is not a platform split at all.
+ """
+ for name, group in _by_name(reqs).items():
+ if len(group) < 2 or len({tuple(sorted(r.extras)) for r in group}) > 1:
+ continue
+ yield name, group
+
+
+def _markers(group) -> list[str]:
+ return [str(r.marker).replace("'", '"') for r in group if r.marker is not None]
+
+
+def _pyproject_extras() -> dict[str, list[Requirement]]:
+ try:
+ import tomllib
+ except ModuleNotFoundError: # pragma: no cover - 3.10 runs use tomli
+ import tomli as tomllib
+ data = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text(encoding = "utf-8"))
+ out = {}
+ for extra, lines in data["project"]["optional-dependencies"].items():
+ out[extra] = [Requirement(l) for l in lines]
+ return out
+
+
+ALL_SOURCES: list[tuple[str, list[Requirement]]] = [(p.name, _rows(p)) for p in REQ_FILES] + [
+ (f"pyproject[{k}]", v) for k, v in _pyproject_extras().items()
+]
+per_source = pytest.mark.parametrize("label,reqs", ALL_SOURCES, ids = [s[0] for s in ALL_SOURCES])
+
+
+@per_source
+def test_split_rows_never_overlap(label, reqs):
+ """Two rows for one package must never both be live: pip would intersect them."""
+ for name, group in _multi_row_groups(reqs):
+ for plat, py, env in ENVS:
+ live = _live(group, env)
+ assert len(live) <= 1, (
+ f"{label}: {name} has {len(live)} live rows on "
+ f"{plat[0]}/{plat[2]}/py{py}: {[str(r) for r in live]}"
+ )
+
+
+@per_source
+def test_no_package_is_dropped_on_a_non_woa_platform(label, reqs):
+ """A split may remove a package on Windows ARM64 only."""
+ if "constraints" in label:
+ return # a constraints file may legitimately have no cap in force
+ for name, group in _multi_row_groups(reqs):
+ # Only the complement-pair shape; triton-windows is two disjoint Windows-only rows.
+ markers = _markers(group)
+ if not (
+ any('platform_machine == "ARM64"' in m for m in markers)
+ and any('platform_machine != "ARM64"' in m for m in markers)
+ ):
+ continue
+ for plat, py, env in ENVS:
+ if plat == WOA:
+ continue
+ assert _live(
+ group, env
+ ), f"{label}: {name} has no live row on {plat[0]}/{plat[2]}/py{py}"
+
+
+def test_arm64_marker_is_case_sensitive_and_windows_only():
+ """``ARM64`` must not match macOS ``arm64`` or Linux ``aarch64``."""
+ woa = Requirement('x==1; sys_platform == "win32" and platform_machine == "ARM64"')
+ # The complement really is the complement.
+ other = Requirement('x==1; sys_platform != "win32" or platform_machine != "ARM64"')
+ for plat, py, env in ENVS:
+ live = woa.marker.evaluate(env)
+ assert live == (plat == WOA), f"win-ARM64 marker fired on {plat[0]}/{plat[2]}"
+ assert live != other.marker.evaluate(
+ env
+ ), f"the two halves are not complementary on {plat[0]}/{plat[2]}"
+
+
+@per_source
+def test_no_row_is_dead_on_arrival(label, reqs):
+ """Every row must be live in at least one real environment."""
+ for req in reqs:
+ if req.marker is None:
+ continue
+ assert any(req.marker.evaluate(env) for _, _, env in ENVS), (
+ f"{label}: `{req}` is live in none of the {len(ENVS)} environments tested, so it "
+ f'can never install. A lowercase "arm64" next to sys_platform == "win32" is the '
+ f'usual cause: Windows reports "ARM64".'
+ )
+
+
+# Which packages carry a Windows-on-ARM row, PER SOURCE, and in which shape.
+# "split" -- a positive `platform_machine == "ARM64"` row giving a different version
+# "dropped" -- only the negative row, so the package is absent on Windows on ARM
+# Checked per source and by shape: studio.txt and pyproject[studio] mirror each other, so a global
+# check stays green when one loses a row.
+WOA_ROWS_BY_SOURCE = {
+ "extras.txt": {"av": "split", "scikit-learn": "split"},
+ "no-torch-runtime.txt": {"pymupdf": "split", "hf-transfer": "dropped", "sqlite-vec": "dropped"},
+ "constraints.txt": {
+ "av": "split",
+ "cryptography": "split",
+ "pandas": "split",
+ "pyarrow": "split",
+ },
+ "studio.txt": {"cryptography": "split", "pandas": "split", "pymupdf": "split"},
+ "pyproject[studio]": {"cryptography": "split", "pandas": "split", "pymupdf": "split"},
+ "pyproject[triton]": {"triton-windows": "split"},
+ "pyproject[huggingfacenotorch]": {"hf-transfer": "dropped"},
+ "pyproject[windows]": {"xformers": "dropped"},
+}
+
+
[email protected]("label,expected", sorted(WOA_ROWS_BY_SOURCE.items()))
+def test_the_woa_split_is_used_where_we_claim_it_is(label, expected):
+ """Guard against a Windows-on-ARM row silently disappearing in a future edit."""
+ groups = _by_name(dict(ALL_SOURCES)[label])
+ for name, shape in sorted(expected.items()):
+ markers = _markers(groups.get(name, []))
+ positive = [m for m in markers if 'platform_machine == "ARM64"' in m]
+ negative = [m for m in markers if 'platform_machine != "ARM64"' in m]
+ if shape == "split":
+ assert positive, f"{label}: {name} lost its Windows-on-ARM row"
+ else:
+ assert negative and not positive, (
+ f"{label}: {name} should be excluded on Windows on ARM by a negative "
+ f"marker only; found positive={positive}"
+ )
+
+
+# A package's OWN requires-python floor, for rows pinning into a range that does not exist for
+# every interpreter. Only floors above our own 3.9 can make a row unsatisfiable.
+PACKAGE_PYTHON_FLOORS = {
+ "pandas": [(SpecifierSet(">=3.0"), (3, 11))],
+}
+
+
+def _minor(py: str) -> tuple:
+ major, minor = py.split(".")
+ return (int(major), int(minor))
+
+
+def _lowest_allowed(req) -> str:
+ """The smallest concrete version the row's specifier admits, for floor comparison."""
+ lowers = [s.version for s in req.specifier if s.operator in (">=", "==", "~=", ">")]
+ return lowers[0] if lowers else "0"
+
+
+@per_source
+def test_a_selected_row_is_installable_on_the_python_it_was_selected_for(label, reqs):
+ """Splitting on platform is not enough on its own: a row can be live for an interpreter
+ that no release in its range supports, which is not a resolution failure anyone reads
+ as a marker bug -- pip just reports that no version matches.
+ """
+ for plat, py, env in ENVS:
+ for req in _live(reqs, env):
+ for spec, floor in PACKAGE_PYTHON_FLOORS.get(req.name.lower(), ()):
+ # Does this row admit ONLY versions that need a newer interpreter?
+ if not spec.contains(_lowest_allowed(req), prereleases = True):
+ continue
+ assert _minor(py) >= floor, (
+ f"{label}: `{req}` is live on Python {py} {plat[2]}, but every "
+ f"version it admits needs Python >= {floor[0]}.{floor[1]}. "
+ "The row is unsatisfiable there; the marker needs a "
+ "python_version bound as well as a platform one."
+ )
+
+
+def test_the_woa_pandas_split_covers_every_supported_python():
+ """The complement of the test above: having added a python_version bound, no ARM64
+ interpreter may be left with no pandas row at all.
+ """
+ for label, reqs in ALL_SOURCES:
+ rows = [r for r in reqs if r.name.lower() == "pandas"]
+ if not rows:
+ continue
+ for py in PYTHONS:
+ live = _live(rows, _env(WOA, py))
+ assert len(live) == 1, (
+ f"{label}: Windows ARM64 on Python {py} has {len(live)} live pandas "
+ f"rows, expected exactly 1: {[str(r) for r in live]}"
+ )
+ if _minor(py) < (3, 11):
+ assert "3.0" not in str(
+ live[0].specifier
+ ), f"{label}: Python {py} must not be handed the pandas 3 row"
+
+
+# install_python_stack.py, loaded so the skip list is read rather than copied here.
+_SPEC = importlib.util.spec_from_file_location(
+ "_ips_marker_skiplist", REPO_ROOT / "studio" / "install_python_stack.py"
+)
+IPS = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(IPS)
+# Every name install_python_stack.py filters out of the requirements files on win_arm64.
+WOA_SKIPPED = {IPS._canonical_dist_name(n) for n in IPS.WINDOWS_ARM64_SKIP_PACKAGES}
+
+
+# Scoped to `studio` deliberately: it is the extra a Windows-on-ARM user installs. The other
+# 190-odd are x64 recipes, so an ARM64 marker there would assert what they never promised.
+WOA_INSTALLABLE_EXTRAS = ["studio"]
+per_extra = pytest.mark.parametrize("extra", WOA_INSTALLABLE_EXTRAS, ids = WOA_INSTALLABLE_EXTRAS)
+
+
+@per_extra
+def test_a_skipped_package_is_not_left_live_in_an_extra(extra):
+ """The runtime skip list cannot reach package METADATA, so the extra has to agree.
+
+ `pip install "unsloth[studio]"` never runs the installer's filtering: it resolves
+ pyproject's rows directly, so a row left live on win_arm64 for a package with no wheel
+ and no buildable sdist there fails the install outright. sqlite-vec was exactly this.
+ """
+ live = [
+ str(req)
+ for req in _live(_pyproject_extras()[extra], _env(WOA, "3.13"))
+ if IPS._canonical_dist_name(req.name) in WOA_SKIPPED
+ ]
+ assert not live, (
+ f"pyproject[{extra}] leaves these live on Windows ARM64 even though the installer "
+ f"treats them as unavailable there, so `pip install unsloth[{extra}]` cannot "
+ f"resolve: {live}"
+ )
+
+
+@per_extra
+def test_dropping_a_package_on_woa_drops_it_nowhere_else(extra):
+ """A negative ARM64 marker is a scalpel: every other platform keeps the row.
+
+ Checked as an outcome rather than a spelling, over the same platform table the rest of
+ this file uses, so a marker that reads correctly but excludes (say) Windows x86 as well
+ is still caught.
+ """
+ for req in _pyproject_extras()[extra]:
+ if IPS._canonical_dist_name(req.name) not in WOA_SKIPPED or req.marker is None:
+ continue
+ for plat, py, env in ENVS:
+ if plat == WOA:
+ continue
+ assert req.marker.evaluate(env), (
+ f"pyproject[{extra}] {req.name} is dropped on {plat[0]}/{plat[2]}/"
+ f"py{py} too, which is not what the ARM64 marker is for"
+ )
diff --git a/tests/python/test_windows_arm64_wheelhouse_tags.py b/tests/python/test_windows_arm64_wheelhouse_tags.py
new file mode 100644
index 00000000000..9df44ecb44d
--- /dev/null
+++ b/tests/python/test_windows_arm64_wheelhouse_tags.py
@@ -0,0 +1,1476 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Windows on ARM: a wheelhouse wheel only counts for the interpreter it was built for.
+
+install.ps1 stages every win_arm64 wheel the wheelhouse publishes, cp311 through cp314,
+so a filename alone proves nothing: a cp311 tiktoken is invisible to a cp313 resolver.
+Counting one as available drops its skip and its requirement override, and the resolve
+then falls to an sdist that needs the toolchain this whole path exists to avoid.
+
+Also pins the blocker map's keys to their canonical form. WINDOWS_ARM64_SKIP_UNBLOCKED_BY
+is read with _canonical_dist_name, which maps "-" to "_", so an "openai-whisper" key is
+never found and the entry silently does nothing.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+import sysconfig
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+INSTALL_PS1 = REPO_ROOT / "install.ps1"
+STACK_PY = REPO_ROOT / "studio" / "install_python_stack.py"
+
+# Read once: the source-level tests below want these whole files and none of them mutate
+# what they read.
+INSTALL_SRC = INSTALL_PS1.read_text(encoding = "utf-8")
+STACK_SRC = STACK_PY.read_text(encoding = "utf-8")
+EXTRAS_SRC = (REPO_ROOT / "studio" / "backend" / "requirements" / "extras.txt").read_text(
+ encoding = "utf-8"
+)
+
+# Constants of the running interpreter, restated in nearly every test below.
+MAJOR, MINOR = sys.version_info[:2]
+TAG = f"cp{MAJOR}{MINOR}"
+
+#: The two index URLs the tables below distinguish: PyPI itself, and an exclusive mirror.
+PYPI = "https://pypi.org/simple"
+CORP = "https://pypi.corp.test/simple"
+
+#: Every variable either resolver reads for its index configuration, cleared so the box
+#: running the suite cannot decide a row.
+RESOLVER_INDEX_VARS = tuple(
+ "UV_OFFLINE UV_NO_INDEX UV_DEFAULT_INDEX UV_INDEX_URL UV_INDEX UV_EXTRA_INDEX_URL "
+ "PIP_INDEX_URL PIP_NO_INDEX PIP_EXTRA_INDEX_URL".split()
+)
+
+
[email protected](scope = "module")
+def ips():
+ spec = importlib.util.spec_from_file_location("_ips_wheelhouse_tags", STACK_PY)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
[email protected](autouse = True)
+def _fresh_find_links(ips):
+ """Empty the memoized find-links listing around every test in this file.
+
+ `ips` is module scoped, so one test's UV_FIND_LINKS would otherwise be the answer the
+ next test got. Both names share one cache, and a test that changes the wheelhouse
+ mid-test still has to clear it itself.
+ """
+ ips._find_links_wheel_versions.cache_clear()
+ yield
+ ips._find_links_wheel_versions.cache_clear()
+
+
+#: What `_pip_config_index_policy` reports when pip's files set no index key.
+PIP_FILES_SILENT = {
+ "no_index": None,
+ "index_url": None,
+ "extra_index_urls": [],
+ "unreadable": False,
+}
+
+
[email protected](autouse = True)
+def _pip_files_silent(ips, monkeypatch):
+ """Keep the host's own pip.conf from deciding rows about the environment.
+
+ The pip path consults `pip config list`. Yields the real reader for the class that
+ tests it.
+ """
+ real = ips._pip_config_index_policy
+ monkeypatch.setattr(ips, "_pip_config_index_policy", lambda: dict(PIP_FILES_SILENT))
+ yield real
+
+
+def _this_platform() -> str:
+ return (sysconfig.get_platform() or "").replace("-", "_").replace(".", "_").lower()
+
+
+def _wheel(
+ dist: str,
+ py: str,
+ abi: str,
+ plat: str | None = None,
+ version: str = "1.0.0",
+) -> str:
+ return f"{dist}-{version}-{py}-{abi}-{plat or _this_platform()}.whl"
+
+
+def _stage(
+ directory: Path,
+ dist: str,
+ version: str = "1.0.0",
+ py: str | None = None,
+ **kw,
+) -> None:
+ """Put one wheel in `directory`, tagged for this interpreter unless told otherwise."""
+ py = py or TAG
+ (directory / _wheel(dist, py, kw.pop("abi", py), version = version, **kw)).write_bytes(b"")
+
+
+def _req(directory: Path, text: str) -> Path:
+ """A requirements file the skip list can read its pins from."""
+ path = directory / "extras.txt"
+ path.write_text(text, encoding = "utf-8")
+ return path
+
+
+def wheelhouse(tmp_path, monkeypatch):
+ """An empty wheelhouse that is the only find-links location the uv resolver reads."""
+ d = tmp_path / "wheels"
+ d.mkdir()
+ monkeypatch.setenv("UV_FIND_LINKS", str(d))
+ monkeypatch.delenv("PIP_FIND_LINKS", raising = False)
+ return d
+
+
+def native_cp314(ips, monkeypatch):
+ """A native win_arm64 interpreter that installs exactly the cp314 wheels: the only tag
+ llvmlite and numba publish a win_arm64 wheel for, so the index can unblock librosa."""
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: True)
+ monkeypatch.setattr(ips, "_wheel_matches_interpreter", lambda name: "cp314" in name)
+
+
+def soxr_published(ips, monkeypatch):
+ """Answer the index for soxr, which publishes no win_arm64 wheel in any release, so it
+ alone would decide tests that are about something else. test_librosa_still_needs_soxr
+ covers soxr itself."""
+ real = ips._public_index_win_arm64_versions
+ monkeypatch.setattr(
+ ips,
+ "_public_index_win_arm64_versions",
+ lambda name: {"1.0.0"} if name == "soxr" else real(name),
+ )
+
+
+def _woa_wheel_names_block() -> str:
+ """install.ps1's own availability scan, from $WoaWheelNames to $WoaDropCandidates."""
+ block = INSTALL_SRC[INSTALL_SRC.index("$WoaWheelNames = @{}") :]
+ return block[: block.index("$WoaDropCandidates")]
+
+
+class TestWheelMatchesInterpreter:
+ def test_own_tag_matches(self, ips):
+ assert ips._wheel_matches_interpreter(_wheel("tiktoken", TAG, TAG))
+
+ @pytest.mark.parametrize("offset", [-2, -1, 1, 2])
+ def test_other_minors_do_not_match(self, ips, offset):
+ TAG = f"cp{MAJOR}{MINOR + offset}"
+ assert not ips._wheel_matches_interpreter(_wheel("tiktoken", TAG, TAG))
+
+ def test_pure_python_any_matches(self, ips):
+ assert ips._wheel_matches_interpreter("six-1.17.0-py2.py3-none-any.whl")
+
+ def test_abi3_is_forward_compatible(self, ips):
+ free_threaded = bool(sysconfig.get_config_var("Py_GIL_DISABLED"))
+ matched = ips._wheel_matches_interpreter(_wheel("cffi", f"cp{MAJOR}2", "abi3"))
+ # The stable ABI is not implemented on free-threaded builds.
+ assert matched is not free_threaded
+ assert not ips._wheel_matches_interpreter(_wheel("cffi", f"cp{MAJOR}{MINOR + 1}", "abi3"))
+
+ @pytest.mark.parametrize("gil_disabled", [0, 1])
+ def test_an_exact_minor_abi3_wheel_follows_the_build(self, ips, monkeypatch, gil_disabled):
+ """The exact-MINOR branch accepted "abi3" outright, so cp313-abi3 was installable on
+ 3.13t, which implements no stable ABI (CPython #111506, PEP 703): the skip was dropped
+ and the resolver sent at a wheel it cannot use. Simulated in both directions rather
+ than read off whichever build is running the suite.
+ """
+ real = ips.sysconfig.get_config_var
+ monkeypatch.setattr(
+ ips.sysconfig,
+ "get_config_var",
+ lambda name: gil_disabled if name == "Py_GIL_DISABLED" else real(name),
+ )
+ exact = f"cp{MAJOR}{MINOR}"
+ assert ips._wheel_matches_interpreter(_wheel("cffi", exact, "abi3")) is (not gil_disabled)
+ # The TAG a free-threaded build CAN install, and the one a GIL build cannot.
+ ft_wheel = _wheel("cffi", exact, f"{exact}t")
+ assert ips._wheel_matches_interpreter(ft_wheel) is bool(gil_disabled)
+ # And the forward-compatible spelling stays gated the same way.
+ assert ips._wheel_matches_interpreter(_wheel("cffi", f"cp{MAJOR}2", "abi3")) is (
+ not gil_disabled
+ )
+
+ def test_foreign_platform_does_not_match(self, ips):
+ assert not ips._wheel_matches_interpreter(
+ _wheel("brotli", TAG, TAG, plat = "some_other_platform")
+ )
+
+ def test_unparseable_name_is_not_installable(self, ips):
+ assert not ips._wheel_matches_interpreter("garbage.whl")
+
+
+class TestWheelhouseSkipList:
+ def test_a_foreign_tagged_wheel_does_not_clear_the_skip(self, ips, wheelhouse):
+ _stage(wheelhouse, "tiktoken", py = f"cp{MAJOR}{MINOR + 1}")
+ assert "tiktoken" not in ips._find_links_wheel_names()
+ assert "tiktoken" in ips._windows_arm64_skip_packages()
+
+ def test_a_matching_wheel_clears_the_skip(self, ips, wheelhouse):
+ _stage(wheelhouse, "tiktoken")
+ assert "tiktoken" not in ips._windows_arm64_skip_packages()
+
+
+class TestBlockerMap:
+ def test_every_key_is_canonical(self, ips):
+ for key in ips.WINDOWS_ARM64_SKIP_UNBLOCKED_BY:
+ assert key == ips._canonical_dist_name(key), f"{key} is looked up canonically"
+
+ def test_every_key_is_a_package_that_is_actually_skipped(self, ips):
+ skipped = {ips._canonical_dist_name(p) for p in ips.WINDOWS_ARM64_SKIP_PACKAGES}
+ assert set(ips.WINDOWS_ARM64_SKIP_UNBLOCKED_BY) <= skipped
+
+ def test_whisper_needs_tiktoken_as_well_as_the_numba_chain(self, ips):
+ # Whisper's metadata requires tiktoken, so hosting llvmlite alone re-enables the sdist.
+ blockers = ips.WINDOWS_ARM64_SKIP_UNBLOCKED_BY[ips._canonical_dist_name("openai-whisper")]
+ assert "tiktoken" in blockers
+ assert "numba" in blockers
+
+ def test_one_hosted_blocker_is_not_enough(self, ips, wheelhouse):
+ _stage(wheelhouse, "llvmlite")
+ skipped = ips._windows_arm64_skip_packages()
+ assert "librosa" in skipped, "librosa still needs numba"
+ assert "openai-whisper" in skipped, "whisper still needs numba and tiktoken"
+
+
+class TestInstallPs1Mirror:
+ """install.ps1 builds the same availability set for its requirement overrides."""
+
+ def test_wheel_names_are_filtered_by_interpreter_tag(self):
+ block = _woa_wheel_names_block()
+ assert "$WoaWheelTag" in block, "the distribution name alone is not proof of availability"
+ assert re.search(r"if \(\$parts\.Count -lt 5\) \{ continue \}", block)
+ assert "abi3" in block and "^py3" in block
+
+ def test_uv_override_is_space_safe(self):
+ # uv reads UV_OVERRIDE as a space-separated list, so EVERY entry needs the 8.3 helper.
+ assert re.search(
+ r"\$_woaOverrideValue\s*=\s*@\(Get-UvSafePath\s+\$WoaOverrides\)", INSTALL_SRC
+ )
+ assert "$_woaOverrideValue += (Get-UvSafePath $_woaKeepFile)" in INSTALL_SRC
+ assert re.search(r'\$env:UV_OVERRIDE\s*=\s*\(\$_woaOverrideValue -join " "\)', INSTALL_SRC)
+ assert not re.search(r"\$env:UV_OVERRIDE\s*=\s*\$WoaOverrides\s*$", INSTALL_SRC, flags = re.M)
+
+ def test_the_selected_torch_index_is_redacted(self):
+ for line in INSTALL_SRC.splitlines():
+ if "torch index:" in line:
+ assert "Remove-IndexUrlCredentials" in line, line.strip()
+
+
+#: Tag triples for the wheels staged below: a pure-python wheel, and one built right here.
+PURE = ("py3", "none", "any")
+HERE = (TAG, TAG, _this_platform())
+
+
+class TestBlockersDecideEvenWhenThePackageItselfIsHosted:
+ """A package skipped for its DEPENDENCIES is not re-enabled by its own wheel."""
+
+ @pytest.fixture
+ def skips(self, ips, wheelhouse):
+ """The skip list, given a wheelhouse holding exactly the wheels named."""
+
+ def build(*specs):
+ for name, version, py, abi, plat in specs:
+ (wheelhouse / f"{name}-{version}-{py}-{abi}-{plat}.whl").write_bytes(b"")
+ return ips._windows_arm64_skip_packages()
+
+ return build
+
+ TENSORBOARD = ("tensorboard", "1.0.0") + PURE
+ LIBROSA = ("librosa", "1.0.0") + PURE
+
+ @pytest.mark.parametrize(
+ "specs, package, still_skipped, why",
+ [
+ ((TENSORBOARD,), "tensorboard", True, "its own wheel does not answer for grpcio"),
+ (
+ (TENSORBOARD, ("grpcio", "1.74.0") + HERE),
+ "tensorboard",
+ False,
+ "grpcio at tensorboard's own floor of >=1.74.0 lifts it",
+ ),
+ (
+ (TENSORBOARD, ("grpcio", "1.60.0") + HERE),
+ "tensorboard",
+ True,
+ "a blocker below that floor used to lift the skip on the name alone, and the "
+ "extras pass then failed on tensorboard's own metadata",
+ ),
+ (
+ (LIBROSA, ("llvmlite", "1.0.0") + HERE),
+ "librosa",
+ True,
+ "librosa needs numba as well as llvmlite",
+ ),
+ (
+ (("tiktoken", "1.0.0") + HERE,),
+ "tiktoken",
+ False,
+ "a package with no blockers still lifts on its own wheel",
+ ),
+ ],
+ ids = [
+ "tensorboard-alone",
+ "tensorboard-and-grpcio",
+ "grpcio-below-the-floor",
+ "librosa-llvmlite-only",
+ "tiktoken-no-blockers",
+ ],
+ )
+ def test_the_blockers_decide(self, skips, specs, package, still_skipped, why):
+ assert (package in skips(*specs)) is still_skipped, why
+
+
+class TestFreeThreadedWheelsAreNotOfferedToTheRegularInterpreter:
+ """cp313-cp313t is built for the free-threaded build; uv rejects it on cp313."""
+
+ def test_python_side_rejects_a_free_threaded_abi(self, ips):
+ free_threaded = bool(sysconfig.get_config_var("Py_GIL_DISABLED"))
+ assert ips._wheel_matches_interpreter(_wheel("tiktoken", TAG, f"{TAG}t")) is free_threaded
+
+ def test_install_ps1_checks_the_abi_not_just_the_python_tag(self):
+ block = _woa_wheel_names_block()
+ first = block[block.index("foreach ($pyTag in") :]
+ first = first[: first.index("$compatible = $true; break") + 30]
+ # $WoaWheelAbi, not $WoaWheelTag: a free-threaded venv installs cp313t but is tagged cp313.
+ assert (
+ "$abiTags -contains $WoaWheelAbi" in first
+ ), "the exact-python-TAG branch must also require a usable ABI"
+ assert (
+ "$WoaWheelStable -and ($abiTags -contains 'abi3')" in first
+ ), "and abi3 is not installable on a free-threaded build"
+
+
+class TestAHostedOptionalIsActuallyInstalled:
+ """Omitting the removal override only helps a package something still requires.
+
+ install.ps1 reported "keeping X (the wheelhouse provides a win_arm64 wheel)" and then
+ just declined to emit X's AMD64-only override line. hf_transfer and xformers are
+ marker-excluded on win_arm64 by their released metadata and torchcodec's only line was
+ filtered out here, so in all three cases hosting a wheel changed nothing.
+ """
+
+ #: The torch an xformers was built against, and the one now resident beside it.
+ OTHER_TORCH = "2.9.0+cu128"
+ THIS_TORCH = "2.15.0.dev20260101+cu134"
+
+ def test_the_optionals_are_the_ones_metadata_excludes(self, ips):
+ """Named here only because pyproject.toml puts them out of reach on ARM64."""
+ pyproject = (REPO_ROOT / "pyproject.toml").read_text(encoding = "utf-8")
+ for name in ips.WINDOWS_ARM64_WHEELHOUSE_OPTIONALS:
+ stem = name.replace("-", "[-_]")
+ rows = [
+ line
+ for line in pyproject.splitlines()
+ if re.search(rf'"\s*{stem}\b', line) and "ARM64" in line
+ ]
+ assert rows, f"{name} is no longer excluded on ARM64; the explicit install is stale"
+
+ @staticmethod
+ def _calls(
+ ips,
+ monkeypatch,
+ hosted,
+ install_ok = True,
+ **stubs,
+ ):
+ """Run the step with `hosted` standing in for the wheelhouse listing."""
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: True)
+ monkeypatch.setattr(ips, "_wheelhouse_best_version", lambda name, floor: hosted.get(name))
+ monkeypatch.setattr(ips, "_wheelhouse_hosts", lambda name: name in hosted)
+ monkeypatch.setattr(ips, "_note", lambda *a, **kw: None)
+ calls = []
+ monkeypatch.setattr(
+ ips, "pip_install_try", lambda label, *a, **kw: calls.append(a) or install_ok
+ )
+ for name, value in stubs.items():
+ monkeypatch.setattr(ips, name, value)
+ ips._install_wheelhouse_optionals()
+ return calls
+
+ def test_a_hosted_optional_is_installed(self, ips, monkeypatch):
+ calls = self._calls(ips, monkeypatch, {"hf-transfer": "0.1.9"})
+ assert len(calls) == 1, calls
+ assert "hf-transfer==0.1.9" in calls[0], "a bare name installs whatever is hosted"
+ assert "--no-deps" in calls[0], "resolving here could walk torch off the CUDA build"
+
+ def test_nothing_is_installed_without_a_hosted_wheel(self, ips, monkeypatch):
+ assert self._calls(ips, monkeypatch, {}) == []
+
+ def test_no_other_platform_is_touched(self, ips, monkeypatch):
+ """Every non-win_arm64 host must install exactly what it installed before."""
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: False)
+ monkeypatch.setattr(ips, "_wheelhouse_best_version", lambda name, floor: "9.9.9")
+ monkeypatch.setattr(
+ ips, "pip_install_try", lambda *a, **kw: pytest.fail("installed off win_arm64")
+ )
+ ips._install_wheelhouse_optionals()
+
+ def test_a_failed_optional_does_not_fail_the_install(self, ips, monkeypatch):
+ """It is an optional feature: off is where it already was."""
+ self._calls(ips, monkeypatch, {"hf-transfer": "0.1.9"}, install_ok = False)
+
+ def test_a_wheel_below_the_declared_floor_is_not_installed(self, ips, wheelhouse):
+ """xformers>=0.0.22.post7 is what pyproject.toml asks for; 0.0.20 satisfies nobody."""
+ _stage(wheelhouse, "xformers", "0.0.20")
+ assert ips._wheelhouse_best_version("xformers", ">=0.0.22.post7") is None
+ _stage(wheelhouse, "xformers", "0.0.31")
+ ips._find_links_wheel_versions.cache_clear()
+ assert ips._wheelhouse_best_version("xformers", ">=0.0.22.post7") == "0.0.31"
+
+ def test_the_newest_clearing_wheel_wins(self, ips, wheelhouse):
+ # Both clear the floor: 0.0.100 is the newer release and the SMALLER of the two as text.
+ for version in ("0.0.23", "0.0.100"):
+ _stage(wheelhouse, "xformers", version)
+ assert (
+ ips._wheelhouse_best_version("xformers", ">=0.0.22.post7") == "0.0.100"
+ ), "sorted as text 0.0.23 would win"
+
+ @pytest.mark.parametrize(
+ "hosted, install_ok, built_for, evicted, why",
+ [
+ (True, True, OTHER_TORCH, True, "an xformers built for another torch is removed"),
+ (True, False, OTHER_TORCH, True, "torch moved and the refresh failed: still evict"),
+ (True, False, THIS_TORCH, False, "a failed refresh keeps a matching resident copy"),
+ (True, True, THIS_TORCH, False, "a matching xformers is kept"),
+ (True, True, None, False, "no recorded pair is not evidence of a wrong one"),
+ # The check ran only after a hosted attempt, so a wheelhouse that stopped offering
+ # xformers left the copy an earlier run installed losing its ops at import time.
+ (False, True, OTHER_TORCH, True, "nothing hosted, and the resident copy is wrong"),
+ (False, True, THIS_TORCH, False, "nothing hosted, and the resident copy matches"),
+ ],
+ ids = [
+ "hosted-other-torch",
+ "failed-refresh-other-torch",
+ "failed-refresh-same-torch",
+ "hosted-same-torch",
+ "hosted-no-build-metadata",
+ "unhosted-other-torch",
+ "unhosted-same-torch",
+ ],
+ )
+ def test_an_xformers_built_for_another_torch_is_removed(
+ self, ips, monkeypatch, hosted, install_ok, built_for, evicted, why
+ ):
+ """Its extension links against one exact torch pair; beside any other the ops vanish
+ behind a log line, which would otherwise be reported here as installed."""
+ removed = []
+ calls = self._calls(
+ ips,
+ monkeypatch,
+ {"xformers": "0.0.31"} if hosted else {},
+ install_ok = install_ok,
+ _resident_xformers_build_torch = lambda: built_for,
+ _probe_installed_torch_version = lambda: self.THIS_TORCH,
+ _uninstall_distribution = lambda name: removed.append(name) or True,
+ )
+ assert removed == (["xformers"] if evicted else []), why
+ assert len(calls) == (1 if hosted else 0), "nothing hosted, nothing installed"
+
+ def test_an_evicted_xformers_is_not_reported_installed(self, ips, monkeypatch):
+ notes = []
+ self._calls(
+ ips,
+ monkeypatch,
+ {"xformers": "0.0.31"},
+ _resident_xformers_build_torch = lambda: self.OTHER_TORCH,
+ _probe_installed_torch_version = lambda: self.THIS_TORCH,
+ _uninstall_distribution = lambda name: True,
+ _note = lambda *a, **kw: notes.append(a[0]),
+ )
+ assert any("removed" in n for n in notes), notes
+ assert not any("installed xformers" in n for n in notes), notes
+
+ def test_the_step_runs_after_the_final_torch_repair(self, ips):
+ """A helper nothing calls re-enables nothing, and one that runs before the flavor
+ invariant validates xformers against a torch the invariant may then replace."""
+ call = STACK_SRC.index(" _install_wheelhouse_optionals()")
+ invariant = STACK_SRC.index("_ensure_expected_torch_flavor(torch_flavor_tag)")
+ assert invariant < call < STACK_SRC.index("# 13b. torchcodec")
+
+ def test_a_hosted_torchcodec_keeps_its_requirement(self, ips):
+ """The one line that asks for torchcodec was filtered out before the resolver."""
+ guard = STACK_SRC.index("if PLATFORM_LACKS_TORCHCODEC_WHEEL")
+ block = STACK_SRC[guard : STACK_SRC.index("_filter_requirements", guard)]
+ assert 'not _wheelhouse_hosts("torchcodec")' in block
+
+ def test_the_hosted_check_reads_the_resolvers_own_wheels(self, ips, wheelhouse):
+ """And only wheels THIS interpreter could install: the staging copies cp311
+ through cp314, and a wheel tagged for another MINOR is invisible to the resolver."""
+ assert not ips._wheelhouse_hosts("torchcodec")
+ _stage(wheelhouse, "torchcodec", py = f"cp{MAJOR}{MINOR + 1}")
+ # The listing is memoized for the process, so each state needs its own read.
+ ips._find_links_wheel_versions.cache_clear()
+ assert not ips._wheelhouse_hosts("torchcodec"), "a foreign-tagged wheel is not hosted"
+ _stage(wheelhouse, "torchcodec")
+ ips._find_links_wheel_versions.cache_clear()
+ assert ips._wheelhouse_hosts("torchcodec")
+
+
+class TestAHostedWheelMustAlsoSatisfyThePin:
+ """Name-only was not enough."""
+
+ @pytest.mark.parametrize(
+ "have, pin, still_skipped, why",
+ [
+ ("0.12.0", "tiktoken==0.13.0", True, "the pinned version is not the one hosted"),
+ ("0.13.0", "tiktoken==0.13.0", False, "an exact match re-enables it"),
+ ("0.13", "tiktoken==0.13.0", False, "0.13 and 0.13.0 are the same release"),
+ ("0.12.0", "tiktoken>=0.10", False, "a range the hosted wheel satisfies"),
+ ("0.9.0", "tiktoken>=0.10", True, "a range it does not"),
+ ("0.12.0", "tiktoken", False, "no specifier: nothing to fail"),
+ (
+ "0.12.0",
+ "tiktoken===0.12.0",
+ False,
+ "arbitrary equality is beyond the comparison, so the name-only answer stands",
+ ),
+ ],
+ )
+ def test_the_pin_decides(self, ips, wheelhouse, have, pin, still_skipped, why):
+ _stage(wheelhouse, "tiktoken", have)
+ req = _req(wheelhouse.parent, f"{pin}\n")
+ assert ("tiktoken" in ips._windows_arm64_skip_packages(req)) is still_skipped, why
+
+ def test_any_hosted_version_that_satisfies_is_enough(self, ips, wheelhouse):
+ for version in ("0.12.0", "0.13.0"):
+ _stage(wheelhouse, "tiktoken", version)
+ req = _req(wheelhouse.parent, "tiktoken==0.13.0\n")
+ assert "tiktoken" not in ips._windows_arm64_skip_packages(req)
+
+ @pytest.mark.parametrize(
+ "grpcio, still_skipped",
+ [("1.60.0", True), ("1.74.0", False)],
+ ids = ["below-the-floor", "at-the-floor"],
+ )
+ def test_a_blocker_with_no_line_of_its_own_is_checked_against_its_floor(
+ self, ips, wheelhouse, grpcio, still_skipped
+ ):
+ """grpcio arrives transitively, so extras.txt has no grpcio line to satisfy.
+
+ That absence used to mean any hosted version counted. It does not: the floor comes
+ from tensorboard's own metadata, which is what rejects a too-old blocker after the
+ skip has been dropped.
+ """
+ _stage(wheelhouse, "grpcio", grpcio)
+ req = _req(wheelhouse.parent, "tensorboard==2.21.0\n")
+ assert (
+ "tensorboard" in ips._windows_arm64_skip_packages(req)
+ ) is still_skipped, f"grpcio {grpcio} against tensorboard's grpcio>=1.74.0"
+
+ def test_a_blocker_with_no_floor_keeps_the_name_only_answer(self, ips, wheelhouse):
+ """llvmlite has no entry: nothing states a floor for it, so a guess is not made."""
+ for dist, version in (("llvmlite", "0.1.0"), ("numba", "0.62.0"), ("soxr", "1.0.0")):
+ _stage(wheelhouse, dist, version)
+ req = _req(wheelhouse.parent, "librosa==0.11.0\n")
+ assert "librosa" not in ips._windows_arm64_skip_packages(req)
+
+ def test_the_floors_name_the_pins_they_were_read_from(self, ips):
+ """A bump to extras.txt has to be a prompt to re-read the metadata: the floors come
+ from a version only that release states, so recorded provenance turns silent drift
+ into a failure here.
+ """
+ for blocker, (specifier, package, version) in ips.WINDOWS_ARM64_BLOCKER_FLOORS.items():
+ assert re.search(rf"(?m)^{re.escape(package)}=={re.escape(version)}\b", EXTRAS_SRC), (
+ f"{blocker}'s floor {specifier} was read from {package}=={version}, which "
+ f"extras.txt no longer pins -- re-read that release's metadata"
+ )
+ assert ips._canonical_dist_name(blocker) == blocker, "keys are canonical"
+
+ def test_no_requirements_file_keeps_the_old_answer(self, ips, wheelhouse):
+ _stage(wheelhouse, "tiktoken", "0.12.0")
+ assert "tiktoken" not in ips._windows_arm64_skip_packages()
+
+ @pytest.mark.parametrize(
+ "version, specifier, expected",
+ [
+ ("2.11.0", "==2.11.0", True),
+ ("2.11.0", "==2.11", True),
+ ("2.11.1", "==2.11.*", True),
+ ("2.12.0", "==2.11.*", False),
+ ("1.4.1", "<=1.4.1", True),
+ ("1.4.2", "<=1.4.1", False),
+ ("2.3.3", ">=2.0,<3", True),
+ ("3.0.0", ">=2.0,<3", False),
+ ("1.2.5", "~=1.2", True),
+ ("2.0.0", "~=1.2", False),
+ ("1.0.0", "!=1.0.0", False),
+ ("1.0.1", "!=1.0.0", True),
+ ("1.0", "", True),
+ # packaging answers these now; None is still the contract without packaging.
+ ("1!2.0", "==2.0", False),
+ ("1.0", "===1.0", True),
+ ("not-a-version", "==1.0", False),
+ ],
+ )
+ def test_the_comparison_itself(self, ips, version, specifier, expected):
+ assert ips._version_satisfies(version, specifier) is expected
+
+ def test_pins_are_read_canonically_and_markers_evaluated(self, ips, tmp_path):
+ req = tmp_path / "r.txt"
+ # One marker true on every host and one true on none, so the answer cannot depend on the box.
+ req.write_text(
+ "# comment\n"
+ "-r other.txt\n"
+ "Hf_Transfer == 0.1.9 ; python_version >= '3'\n"
+ "elsewhere == 1.0 ; sys_platform == 'nonesuch'\n"
+ "httpx[brotli]>=0.27\n"
+ "local @ file:///x\n",
+ encoding = "utf-8",
+ )
+ pins = ips._requirement_pins(req)
+ assert pins["hf_transfer"] == ["== 0.1.9"], "its marker holds on every host"
+ assert "elsewhere" not in pins, "an inactive marker drops the row"
+ assert pins["httpx"] == [">=0.27"]
+ assert "local" not in pins, "a direct URL has no version to compare"
+ assert "-r" not in pins
+
+
+class TestDuplicateRequirementRowsAreSplitByMarker:
+ """extras.txt states MeCab twice, once per marker."""
+
+ # One marker true on every host and one true on none; the real pair is host-dependent.
+ ACTIVE = 'python_version >= "3"'
+ INACTIVE = 'sys_platform == "nonesuch"'
+
+ @classmethod
+ def _rows(cls) -> str:
+ return f"MeCab==0.996.13; {cls.ACTIVE}\nMeCab==0.996.5; {cls.INACTIVE}\n"
+
+ def test_the_shipped_file_really_has_the_duplicate(self):
+ rows = [line for line in EXTRAS_SRC.splitlines() if line.lower().startswith("mecab")]
+ assert len(rows) == 2, "the case this fix exists for"
+
+ def test_only_the_active_row_is_kept(self, ips, tmp_path):
+ req = _req(tmp_path, self._rows())
+ pins = ips._requirement_pins(req)
+ assert pins["mecab"] == ["==0.996.13"], "the inactive row must not overwrite it"
+
+ @pytest.mark.parametrize(
+ "hosted, still_skipped, why",
+ [
+ ("0.996.5", True, "the hosted 0.996.5 satisfies only the row that does not apply here"),
+ ("0.996.13", False, "the version the active row asks for still unskips"),
+ ],
+ ids = ["inactive-row", "active-row"],
+ )
+ def test_only_the_active_row_can_unskip(self, ips, wheelhouse, hosted, still_skipped, why):
+ _stage(wheelhouse, "mecab", hosted)
+ req = _req(wheelhouse.parent, self._rows())
+ assert ("mecab" in ips._windows_arm64_skip_packages(req)) is still_skipped, why
+
+ def test_markers_are_evaluated_with_packaging(self, ips):
+ assert ips._marker_is_active("") is True
+ assert ips._marker_is_active('sys_platform == "%s"' % sys.platform) is True
+ assert ips._marker_is_active('sys_platform == "nonesuch"') is False
+ assert ips._marker_is_active("this is not a marker") is None
+
+ def test_without_packaging_every_clause_is_kept(self, ips, tmp_path, monkeypatch):
+ """The fallback is no stricter than the name-only check that came before."""
+ monkeypatch.setattr(ips, "_marker_is_active", lambda marker: None)
+ req = _req(tmp_path, self._rows())
+ assert ips._requirement_pins(req)["mecab"] == [
+ "==0.996.13",
+ "==0.996.5",
+ ], "including the one whose marker would otherwise have excluded it"
+
+
+class TestAPrereleaseWheelDoesNotSatisfyAFinalPin:
+ """A wheelhouse holding 0.13.0rc1 must not unskip a package pinned to ==0.13.0: the
+ numeric comparison reduced both to (0, 13, 0), so the skip was dropped and uv -- which
+ applies PEP 440 properly -- fell to the ARM64 sdist the skip list exists to avoid."""
+
+ @pytest.mark.parametrize(
+ "version, specifier, expected, why",
+ [
+ ("0.13.0rc1", "==0.13.0", False, "a release candidate is not the release"),
+ ("0.13.0", "==0.13.0", True, "the final version still satisfies it"),
+ ("0.13.0.dev1", "==0.13.0", False, "nor is a dev build"),
+ ("0.13.0rc1", ">=0.12", False, "a prerelease is excluded unless asked for"),
+ ("0.13.0", ">=0.12", True, "an ordinary version is unaffected"),
+ ("2.11", "==2.11.0", True, "trailing zeros still compare equal"),
+ ],
+ )
+ def test_the_comparison_is_pep_440(self, ips, version, specifier, expected, why):
+ assert ips._version_satisfies(version, specifier) is expected, why
+
+ def test_the_fallback_refuses_what_it_cannot_model(self, ips, monkeypatch):
+ """With packaging unavailable the numeric path runs, and answering "satisfied" for a
+ version it cannot parse is the failure this fixes, so it answers False instead."""
+ import importlib
+
+ real = importlib.import_module
+
+ def no_packaging(name, *args, **kwargs):
+ if "packaging" in name:
+ raise ImportError(name)
+ return real(name, *args, **kwargs)
+
+ monkeypatch.setattr(ips.importlib, "import_module", no_packaging)
+ assert ips._version_satisfies("0.13.0rc1", "==0.13.0") is False
+ assert ips._version_satisfies("0.13.0", "==0.13.0") is True
+
+ def test_a_prerelease_wheel_leaves_the_package_skipped(self, ips, wheelhouse, monkeypatch):
+ """End to end: the wheel is in the wheelhouse, and the skip survives anyway."""
+ if "win_arm64" not in _this_platform():
+ monkeypatch.setattr(ips, "_wheel_matches_interpreter", lambda name: "tiktoken" in name)
+ _stage(wheelhouse, "tiktoken", "0.13.0rc1", plat = "win_arm64")
+ req = _req(wheelhouse.parent, "tiktoken==0.13.0\n")
+ assert "tiktoken" in ips._windows_arm64_skip_packages(req = req), (
+ "an rc wheel satisfied an exact pin, so tiktoken was unskipped and the "
+ "resolve fell to the sdist"
+ )
+
+
+class TestOnlyTheResolversOwnLocationsCount:
+ """uv does not read PIP_FIND_LINKS, so a wheel hosted only there is not available, and
+ counting it sent the resolve at the sdist the skip exists to avoid. pip cannot be the
+ resolver here either: pip_install refuses the fallback under the win_arm64 overrides."""
+
+ @pytest.mark.parametrize(
+ "uv, pip, still_skipped, why",
+ [
+ (
+ False,
+ True,
+ True,
+ "the wheel is only where pip would look, and uv is what resolves here, so "
+ "counting it sends the resolve to an sdist that cannot build",
+ ),
+ (True, False, False, "a uv location still unskips"),
+ ],
+ ids = ["pip-only", "uv"],
+ )
+ def test_only_a_uv_location_unskips(
+ self, ips, tmp_path, monkeypatch, uv, pip, still_skipped, why
+ ):
+ _stage(tmp_path, "tiktoken", "0.13.0")
+ for name, wanted in (("UV_FIND_LINKS", uv), ("PIP_FIND_LINKS", pip)):
+ if wanted:
+ monkeypatch.setenv(name, str(tmp_path))
+ else:
+ monkeypatch.delenv(name, raising = False)
+ req = _req(tmp_path, "tiktoken==0.13.0\n")
+ assert ("tiktoken" in ips._windows_arm64_skip_packages(req = req)) is still_skipped, why
+
+ def test_install_ps1_sets_both_so_the_managed_wheelhouse_is_unaffected(self):
+ """The narrowing must not cost the path it was written for."""
+ assert "UV_FIND_LINKS" in INSTALL_SRC and "PIP_FIND_LINKS" in INSTALL_SRC
+ assert '"UV_FIND_LINKS" = ","' in INSTALL_SRC, "and each keeps its own separator"
+
+
+class TestAnExplicitPinIsNotOverriddenByThePreservationShortcut:
+ """The ARM64 CUDA-preservation shortcut distrusts the INFERRED expectation, not a pin.
+
+ A native cu134 venv has a family tag download.pytorch.org does not publish, so
+ "repairing" it would resolve a cu130 with no wheel. But a user who names cu129 by URL or
+ family has stated where they want to be, and exempting only a /cpu pin left them on the
+ old build. setup.ps1 exempts every explicit pin; this is the same rule.
+ """
+
+ class _Reached(Exception):
+ """Raised where the shortcut used to return, so "got past it" is observable."""
+
+ @pytest.fixture
+ def native_arm64_cuda_venv(self, ips, monkeypatch):
+ monkeypatch.setattr(ips, "NO_TORCH", False, raising = False)
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: True)
+ monkeypatch.setattr(ips, "_probe_installed_torch_version", lambda: "2.14.0+cu134")
+
+ def reached():
+ raise TestAnExplicitPinIsNotOverriddenByThePreservationShortcut._Reached()
+
+ monkeypatch.setattr(ips, "_expected_torch_flavor_tag", reached)
+ for name in ("UNSLOTH_TORCH_INDEX_URL", "UNSLOTH_TORCH_INDEX_FAMILY"):
+ monkeypatch.delenv(name, raising = False)
+ return ips
+
+ def test_an_unpinned_run_still_keeps_the_cuda_build(self, native_arm64_cuda_venv):
+ assert native_arm64_cuda_venv._ensure_expected_torch_flavor() is True, (
+ "without a pin the shortcut has to hold, or a working native CUDA venv is "
+ "repaired into a cu130 with no win_arm64 wheel"
+ )
+
+ @pytest.mark.parametrize(
+ "name, value",
+ [
+ ("UNSLOTH_TORCH_INDEX_URL", "https://download.pytorch.org/whl/cu129"),
+ ("UNSLOTH_TORCH_INDEX_FAMILY", "cu129"),
+ ("UNSLOTH_TORCH_INDEX_URL", "https://download.pytorch.org/whl/cpu"),
+ ("UNSLOTH_TORCH_INDEX_URL", "https://mirror.test/simple"),
+ ],
+ )
+ def test_a_pinned_run_is_evaluated(self, native_arm64_cuda_venv, monkeypatch, name, value):
+ monkeypatch.setenv(name, value)
+ with pytest.raises(TestAnExplicitPinIsNotOverriddenByThePreservationShortcut._Reached):
+ native_arm64_cuda_venv._ensure_expected_torch_flavor()
+
+ def test_the_two_installers_agree(self):
+ """setup.ps1 exempts every pin; the Python half must not narrow that to /cpu."""
+ assert (
+ "if _is_win_arm64_interpreter() and _explicit_torch_index_url() is None:" in STACK_SRC
+ )
+ setup = (REPO_ROOT / "studio" / "setup.ps1").read_text(encoding = "utf-8")
+ assert "-not $_pinnedIdx) {" in setup, "setup.ps1's own preservation guard moved"
+
+
+class TestThePublicIndexUnblocksWhatItAlreadyPublishes:
+ """The skip list was decided from the local wheelhouse alone, so a native CPython 3.14
+ ARM64 host -- where llvmlite and numba both publish a win_arm64 wheel, cp314 being the
+ only tag either publishes one for -- had librosa dropped with its chain resolvable."""
+
+ def test_the_recorded_versions_clear_the_blocker_floors(self, ips):
+ """A recorded version below the floor would unblock nothing but this table."""
+ for name, tags in ips.WINDOWS_ARM64_PUBLIC_INDEX_WHEELS.items():
+ floor = ips.WINDOWS_ARM64_BLOCKER_FLOORS.get(name)
+ if floor is None:
+ continue
+ for version in tags.values():
+ assert (
+ ips._version_satisfies(version, floor[0]) is not False
+ ), f"{name} {version} does not satisfy {floor[0]}"
+
+ def test_nothing_is_claimed_off_win_arm64(self, ips, monkeypatch):
+ """Every other platform must see exactly the availability it saw before."""
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: False)
+ for name in ips.WINDOWS_ARM64_PUBLIC_INDEX_WHEELS:
+ assert ips._public_index_win_arm64_versions(name) == set()
+
+ def test_the_tag_has_to_match_this_interpreter(self, ips, monkeypatch, native_cp314):
+ assert ips._public_index_win_arm64_versions("numba") == {"0.67.0"}
+ monkeypatch.setattr(ips, "_wheel_matches_interpreter", lambda name: False)
+ assert ips._public_index_win_arm64_versions("numba") == set()
+
+ def test_a_matching_interpreter_unblocks_librosa(
+ self, ips, monkeypatch, wheelhouse, native_cp314, soxr_published
+ ):
+ assert "librosa" not in ips._windows_arm64_skip_packages()
+ # And still dropped where the wheels are not published for this build.
+ monkeypatch.setattr(ips, "_wheel_matches_interpreter", lambda name: False)
+ ips._find_links_wheel_versions.cache_clear()
+ assert "librosa" in ips._windows_arm64_skip_packages()
+
+ def test_librosa_still_needs_soxr(self, ips, wheelhouse, native_cp314):
+ """librosa 0.11.0 requires soxr>=0.3.2 and soxr has published no win_arm64 wheel in
+ any release, so unblocking on llvmlite and numba alone put librosa back in the extras
+ pass, where soxr is then built from the sdist the skip list exists to avoid.
+ """
+ assert "librosa" in ips._windows_arm64_skip_packages()
+
+ def test_openai_whisper_still_needs_tiktoken(self, ips, wheelhouse, native_cp314):
+ """Its third blocker publishes no win_arm64 wheel, so unblocking two is not enough."""
+ assert "openai-whisper" in ips._windows_arm64_skip_packages()
+
+ def test_an_empty_wheelhouse_no_longer_short_circuits(
+ self, ips, monkeypatch, native_cp314, soxr_published
+ ):
+ """The early return read "nothing hosted" as "skip everything", which threw the
+ public-index answer away before it was asked for."""
+ monkeypatch.delenv("UV_FIND_LINKS", raising = False)
+ assert "librosa" not in ips._windows_arm64_skip_packages()
+ assert "mecab" in ips._windows_arm64_skip_packages(), "the rest still drop"
+
+
+class TestThePublicIndexClaimNeedsTheIndex:
+ """What PyPI publishes is only availability if the resolve will look at PyPI: offline, or
+ pointed at an exclusive corporate index, unblocking librosa drops the skip and then fails
+ the whole extras pass on a numba chain nothing serves."""
+
+ @pytest.fixture(autouse = True)
+ def _native(self, ips, monkeypatch, native_cp314):
+ # uv runs the pass; the pip rows below switch it off explicitly.
+ monkeypatch.setattr(ips, "USE_UV", True)
+ for var in RESOLVER_INDEX_VARS:
+ monkeypatch.delenv(var, raising = False)
+
+ @pytest.mark.parametrize(
+ "env, why",
+ [
+ ({}, "nothing configured is PyPI"),
+ ({"UV_DEFAULT_INDEX": PYPI}, "a default index that is PyPI itself is still PyPI"),
+ ({"UV_EXTRA_INDEX_URL": CORP}, "--extra-index-url ADDS to the default"),
+ ],
+ ids = ["unset", "pypi-as-default", "extra-index"],
+ )
+ def test_the_default_case_still_claims_them(self, ips, monkeypatch, env, why):
+ for key, value in env.items():
+ monkeypatch.setenv(key, value)
+ assert ips._public_index_win_arm64_versions("numba") == {"0.67.0"}, why
+
+ @pytest.mark.parametrize(
+ "use_uv, var, value",
+ [
+ (True, "UV_OFFLINE", "1"),
+ (True, "UV_NO_INDEX", "1"),
+ (True, "UV_DEFAULT_INDEX", CORP),
+ (True, "UV_INDEX_URL", CORP),
+ (False, "PIP_INDEX_URL", CORP),
+ (False, "PIP_NO_INDEX", "1"),
+ ],
+ )
+ def test_an_unreachable_pypi_claims_nothing(self, ips, monkeypatch, use_uv, var, value):
+ monkeypatch.setattr(ips, "USE_UV", use_uv)
+ monkeypatch.setenv(var, value)
+ assert ips._public_index_win_arm64_versions("numba") == set()
+
+ @pytest.mark.parametrize(
+ "use_uv, var, value",
+ [
+ (True, "PIP_INDEX_URL", CORP),
+ (True, "PIP_NO_INDEX", "1"),
+ (False, "UV_INDEX_URL", CORP),
+ (False, "UV_NO_INDEX", "1"),
+ (False, "UV_OFFLINE", "1"),
+ ],
+ )
+ def test_the_other_resolvers_variables_do_not_move_it(
+ self, ips, monkeypatch, use_uv, var, value
+ ):
+ """uv never reads PIP_*, pip never reads UV_*: the pass is judged for the one that runs."""
+ monkeypatch.setattr(ips, "USE_UV", use_uv)
+ monkeypatch.setenv(var, value)
+ assert ips._public_index_win_arm64_versions("numba") == {"0.67.0"}
+
+ def test_a_pip_extra_does_not_put_pypi_back_for_uv(self, ips, monkeypatch):
+ """The cross-resolver case: an exclusive uv index with PyPI named only for pip."""
+ monkeypatch.setenv("UV_INDEX_URL", CORP)
+ monkeypatch.setenv("PIP_EXTRA_INDEX_URL", PYPI)
+ assert ips._public_index_win_arm64_versions("numba") == set()
+ monkeypatch.setattr(ips, "USE_UV", False)
+ assert ips._public_index_win_arm64_versions("numba") == {
+ "0.67.0"
+ }, "pip: its own default is PyPI"
+
+ def test_librosa_goes_back_to_the_skip_list_offline(
+ self, ips, monkeypatch, wheelhouse, soxr_published
+ ):
+ assert "librosa" not in ips._windows_arm64_skip_packages()
+ monkeypatch.setenv("UV_OFFLINE", "1")
+ ips._find_links_wheel_versions.cache_clear()
+ assert "librosa" in ips._windows_arm64_skip_packages()
+
+
+class TestUvConfigurationFilesDecideWherePyPIIs:
+ """Only environment variables were read, and uv also discovers uv.toml, pyproject [tool.uv],
+ and the user and system files. A no-index or exclusive default-index set there still
+ unblocked librosa and then failed the extras resolve on a numba the configured source
+ does not carry."""
+
+ @pytest.fixture(autouse = True)
+ def _clean(self, ips, monkeypatch, tmp_path):
+ # uv's configuration files only matter to uv, the resolver that runs the pass here.
+ monkeypatch.setattr(ips, "USE_UV", True)
+ extra = ("UV_NO_CONFIG", "UV_CONFIG_FILE", "APPDATA", "PROGRAMDATA")
+ for var in RESOLVER_INDEX_VARS + extra:
+ monkeypatch.delenv(var, raising = False)
+ (tmp_path / "proj").mkdir()
+ # uv reads the user file from %APPDATA% on Windows and $XDG_CONFIG_HOME elsewhere, so both
+ # names point at one directory and the case is real on every platform.
+ (tmp_path / "user").mkdir()
+ monkeypatch.setenv("APPDATA", str(tmp_path / "user"))
+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "user"))
+ monkeypatch.chdir(tmp_path / "proj")
+ self.tmp = tmp_path
+
+ #: Where _write puts the "user file" row, spelled the same on every platform.
+ user_config = "user/uv/uv.toml"
+
+ def _write(self, rel, body):
+ p = self.tmp / rel
+ p.parent.mkdir(parents = True, exist_ok = True)
+ p.write_text(body, encoding = "utf-8")
+
+ def test_nothing_configured_is_pypi(self, ips):
+ assert ips._public_pypi_is_reachable() is True
+
+ #: The two files uv discovers in the project directory, and the fragments the rows
+ #: below compose out of, so a case that is one statement is one line.
+ UV = "proj/uv.toml"
+ PJ = "proj/pyproject.toml"
+ NO_IDX = "no-index = true\n"
+ NO_IDX_OFF = "no-index = false\n"
+ CORP_IDX = f'index-url = "{CORP}"\n'
+ PYPI_IDX = f'index-url = "{PYPI}"\n'
+ PIP_NO_IDX = "[pip]\nno-index = true\n"
+ PIP_NO_IDX_OFF = "[pip]\nno-index = false\n"
+ PIP_CORP = f'[pip]\nindex-url = "{CORP}"\n'
+ PIP_PYPI = f'[pip]\nindex-url = "{PYPI}"\n'
+ CORP_DEFAULT = f'[[index]]\nurl = "{CORP}"\ndefault = true\n'
+ PYPI_DEFAULT = f'[[index]]\nurl = "{PYPI}"\ndefault = true\n'
+ CORP_ADDED = f'[[index]]\nurl = "{CORP}"\n'
+ PYPI_ADDED = f'[[index]]\nurl = "{PYPI}"\n'
+ PYPI_EXTRA = f'extra-index-url = ["{PYPI}"]\n'
+ MIRROR_EXTRA = 'extra-index-url = ["https://mirror.test/simple"]\n'
+ CORP_EXPLICIT = f'[[index]]\nurl = "{CORP}"\nexplicit = true\n'
+ PYPI_EXPLICIT = f'[[index]]\nurl = "{PYPI}"\nexplicit = true\n'
+ CORP_EXPLICIT_DEFAULT = f'[[index]]\nurl = "{CORP}"\nexplicit = true\ndefault = true\n'
+
+ @pytest.mark.parametrize(
+ "rel, body, reachable, why",
+ [
+ # An exclusive source, however and wherever it is spelled.
+ (UV, NO_IDX, False, "no-index"),
+ (UV, f'default-index = "{CORP}"\n', False, "an exclusive default-index"),
+ (UV, CORP_IDX, False, "the older spelling of the same key"),
+ (UV, PIP_NO_IDX, False, "no-index under [pip]"),
+ (UV, CORP_DEFAULT, False, "[[index]] default = true"),
+ (UV, f'index = [{{ url = "{CORP}", default = true }}]\n', False, "an inline table"),
+ (PJ, "[tool.uv]\n" + NO_IDX, False, "pyproject [tool.uv]"),
+ (PJ, f'[tool.uv.pip]\nindex-url = "{CORP}"\n', False, "pyproject [tool.uv.pip]"),
+ ("uv.toml", NO_IDX, False, "a parent directory"),
+ ("user/uv/uv.toml", NO_IDX, False, "the user file"),
+ (UV, "this is = not [ toml\n", False, "an unreadable file is not guessed at"),
+ # Sources that leave PyPI in play, so the reader is not a blanket "not reachable".
+ (UV, CORP_ADDED, True, "an [[index]] without default = true is additive"),
+ (PJ, '[project]\nname = "x"\n', True, "a pyproject with no [tool.uv] at all"),
+ # uv pip's own precedence, verified on uv 0.10.7 with a dry-run resolve.
+ (UV, NO_IDX_OFF + PIP_NO_IDX, False, "[pip].no-index beats the top-level false"),
+ (UV, NO_IDX + PIP_NO_IDX_OFF, True, "[pip].no-index = false beats the top-level true"),
+ (UV, PYPI_IDX + PIP_CORP, False, "[pip].index-url beats the top-level index-url"),
+ (UV, CORP_IDX + PIP_PYPI, True, "the other way round"),
+ (UV, CORP_DEFAULT + PIP_PYPI, False, "[[index]] default beats [pip].index-url"),
+ (UV, PIP_CORP + PYPI_DEFAULT, True, "and still does when it comes later in the file"),
+ (UV, NO_IDX + PIP_PYPI, False, "no-index disables every registry"),
+ (
+ PJ,
+ "[tool.uv]\n" + NO_IDX_OFF + "[tool.uv.pip]\n" + NO_IDX,
+ False,
+ "[tool.uv.pip] outranks [tool.uv], as [pip] does the top level",
+ ),
+ # An extra index that is PyPI keeps PyPI in play, wherever it is written.
+ (UV, CORP_IDX + PYPI_EXTRA, True, "extra-index-url in the file"),
+ (UV, CORP_IDX + "[pip]\n" + PYPI_EXTRA, True, "extra-index-url under [pip]"),
+ (UV, CORP_DEFAULT + "\n" + PYPI_ADDED, True, "a second [[index]], not the default"),
+ (UV, NO_IDX + PYPI_EXTRA, False, "no-index disables extras too"),
+ (UV, CORP_IDX + MIRROR_EXTRA, False, "an extra that is not PyPI"),
+ # uv: explicit = true serves only packages pinned via [tool.uv.sources].
+ (UV, CORP_EXPLICIT, True, "an explicit corporate index leaves PyPI the default"),
+ (UV, CORP_IDX + PYPI_EXPLICIT, False, "an explicit PyPI does not put PyPI back"),
+ (UV, CORP_EXPLICIT_DEFAULT, False, "explicit and default: PyPI removed, not modelled"),
+ ],
+ )
+ def test_what_the_uv_files_set(self, ips, rel, body, reachable, why):
+ self._write(rel, body)
+ assert ips._public_pypi_is_reachable() is reachable, why
+
+ def test_an_explicit_index_is_not_an_extra(self, ips):
+ self._write(self.UV, self.CORP_EXPLICIT + self.PYPI_ADDED)
+ policy = ips._uv_config_index_policy()
+ assert policy["extra_indexes"] == [PYPI], policy
+ assert policy["unreadable"] is False
+
+ def test_project_outranks_user_for_a_scalar(self, ips):
+ self._write("proj/uv.toml", "no-index = false\n")
+ self._write(self.user_config, "no-index = true\n")
+ # Vacuous unless the user file is somewhere uv would look.
+ assert (self.tmp / self.user_config) in [p for p, _ in ips._uv_config_files()]
+ assert ips._public_pypi_is_reachable() is True
+
+ def test_uv_toml_beats_pyproject_in_the_same_directory(self, ips):
+ self._write("proj/uv.toml", "no-index = false\n")
+ self._write("proj/pyproject.toml", "[tool.uv]\nno-index = true\n")
+ assert ips._public_pypi_is_reachable() is True
+
+ def test_uv_no_config_discovers_nothing(self, ips, monkeypatch):
+ self._write("proj/uv.toml", "no-index = true\n")
+ monkeypatch.setenv("UV_NO_CONFIG", "1")
+ assert ips._public_pypi_is_reachable() is True
+
+ def test_uv_config_file_names_the_one_file_read(self, ips, monkeypatch):
+ self._write("proj/uv.toml", "no-index = false\n")
+ self._write("other.toml", "no-index = true\n")
+ monkeypatch.setenv("UV_CONFIG_FILE", str(self.tmp / "other.toml"))
+ assert ips._public_pypi_is_reachable() is False
+
+ def test_the_environment_outranks_every_file(self, ips, monkeypatch):
+ self._write("proj/uv.toml", "no-index = true\n")
+ monkeypatch.setenv("UV_DEFAULT_INDEX", "https://pypi.org/simple")
+ assert ips._public_pypi_is_reachable() is True
+
+ @pytest.mark.parametrize(
+ "env, reachable, why",
+ [
+ (
+ {"UV_INDEX_URL": CORP, "UV_EXTRA_INDEX_URL": PYPI},
+ True,
+ "an extra that is PyPI beside a corporate default",
+ ),
+ (
+ {"UV_DEFAULT_INDEX": CORP, "UV_INDEX": f"https://mirror.test/simple {PYPI}"},
+ True,
+ "UV_INDEX, space-separated",
+ ),
+ (
+ {"PIP_INDEX_URL": CORP, "PIP_EXTRA_INDEX_URL": PYPI},
+ True,
+ "pip's variables: uv never reads them, so its default PyPI stands",
+ ),
+ (
+ {"UV_INDEX_URL": CORP, "PIP_EXTRA_INDEX_URL": PYPI},
+ False,
+ "a pip extra does not put PyPI back for uv",
+ ),
+ (
+ {
+ "UV_INDEX_URL": CORP,
+ "UV_EXTRA_INDEX_URL": "https://pypi.org.corp.example/simple",
+ },
+ False,
+ "an extra that is not PyPI changes nothing",
+ ),
+ ],
+ )
+ def test_an_extra_index_that_is_pypi_keeps_pypi_in_play(
+ self, ips, monkeypatch, env, reachable, why
+ ):
+ for k, v in env.items():
+ monkeypatch.setenv(k, v)
+ assert ips._public_pypi_is_reachable() is reachable, why
+
+ @pytest.mark.parametrize(
+ "url, is_pypi, why",
+ [
+ ("https://pypi.org/simple", True, "the default index"),
+ ("HTTPS://PYPI.ORG/simple/", True, "case does not matter for a host"),
+ ("https://user:[email protected]/simple", True, "credentials do not hide the host"),
+ ("https://pypi.org.corp.example/simple", False, "a subdomain lookalike"),
+ ("https://packages.example/api/pypi/pypi.org/simple", False, "the name in the path"),
+ ("https://test.pypi.org/simple", False, "TestPyPI does not carry these packages"),
+ ("pypi.org/simple", False, "no scheme, no host"),
+ ("", False, "empty"),
+ ],
+ )
+ def test_the_host_decides_not_a_substring(self, ips, monkeypatch, url, is_pypi, why):
+ assert ips._url_is_public_pypi(url) is is_pypi, why
+ if url:
+ monkeypatch.setenv("UV_DEFAULT_INDEX", url)
+ assert ips._public_pypi_is_reachable() is is_pypi, "the environment path: " + why
+ monkeypatch.delenv("UV_DEFAULT_INDEX")
+ self._write("proj/uv.toml", f'default-index = "{url}"\n')
+ assert ips._public_pypi_is_reachable() is is_pypi, "the config path: " + why
+
+
+class TestPipConfigurationFilesDecideWherePyPIIs:
+ """The pip path read PIP_* only. pip also reads its site, user and global files, where
+ `[global] index-url` or `no-index` replaces PyPI exactly as the variables do; a host with
+ such a file had librosa unblocked and the extras pass then failed on numba."""
+
+ @pytest.fixture(autouse = True)
+ def _pip_runs(self, ips, monkeypatch, _pip_files_silent):
+ monkeypatch.setattr(ips, "USE_UV", False)
+ for var in ("PIP_NO_INDEX", "PIP_INDEX_URL", "PIP_EXTRA_INDEX_URL", "PIP_CONFIG_FILE"):
+ monkeypatch.delenv(var, raising = False)
+ monkeypatch.setattr(ips, "_pip_config_index_policy", _pip_files_silent)
+ self.ips = ips
+ self.monkeypatch = monkeypatch
+
+ def _listing(
+ self,
+ text,
+ returncode = 0,
+ ):
+ """Stand in for `pip config list` with this output."""
+
+ class Done:
+ stdout = text
+ stderr = ""
+
+ Done.returncode = returncode
+ self.monkeypatch.setattr(self.ips.subprocess, "run", lambda *a, **kw: Done())
+
+ def test_no_index_keys_means_pypi(self):
+ self._listing(":env:.cache-dir='/tmp/pip'\nglobal.timeout='60'\n")
+ assert self.ips._public_pypi_is_reachable() is True
+
+ #: Rows as `pip config list` prints them, composed so a case stays one line.
+ G_CORP = f"global.index-url='{CORP}'\n"
+ G_PYPI = f"global.index-url='{PYPI}'\n"
+ G_NO_IDX = "global.no-index='true'\n"
+ I_CORP = f"install.index-url='{CORP}'\n"
+ I_PYPI = f"install.index-url='{PYPI}'\n"
+ G_EXTRA_PYPI = f"global.extra-index-url='{PYPI}'\n"
+ MIRROR = "https://mirror.test/simple"
+
+ @pytest.mark.parametrize(
+ "text, reachable, why",
+ [
+ (G_CORP, False, "an exclusive index-url"),
+ (G_NO_IDX, False, "no-index"),
+ ("global.no-index='false'\n", True, "no-index switched off"),
+ (I_CORP, False, "under [install]"),
+ (G_PYPI, True, "PyPI named explicitly"),
+ (G_CORP + G_EXTRA_PYPI, True, "an extra that is PyPI beside a corporate default"),
+ (
+ G_CORP + f"global.extra-index-url='{MIRROR}\\n{PYPI}'\n",
+ True,
+ "one of several extras, newline-separated as pip prints them",
+ ),
+ (G_CORP + f"global.extra-index-url='{MIRROR}'\n", False, "an extra that is not PyPI"),
+ (G_NO_IDX + G_EXTRA_PYPI, False, "no-index disables extras too"),
+ (G_CORP + I_PYPI, True, "[install] outranks [global]"),
+ (I_CORP + G_PYPI, False, "and still does when printed first"),
+ (
+ G_NO_IDX + "install.no-index='false'\n",
+ True,
+ "[install].no-index = false beats the global true",
+ ),
+ (
+ f":env:.index-url='{CORP}'\n",
+ True,
+ ":env: rows mirror PIP_* the caller already read, and the variable is not set",
+ ),
+ (f'global.index-url="{CORP}"\n', False, "double quotes, should pip ever print them"),
+ ],
+ )
+ def test_what_the_files_set(self, text, reachable, why):
+ self._listing(text)
+ assert self.ips._public_pypi_is_reachable() is reachable, why
+
+ def test_the_environment_outranks_the_files(self):
+ self._listing("global.no-index='true'\n")
+ self.monkeypatch.setenv("PIP_INDEX_URL", PYPI)
+ assert self.ips._public_pypi_is_reachable() is True
+
+ def test_a_pip_extra_from_the_environment_counts_beside_a_file_index(self):
+ self._listing(f"global.index-url='{CORP}'\n")
+ self.monkeypatch.setenv("PIP_EXTRA_INDEX_URL", PYPI)
+ assert self.ips._public_pypi_is_reachable() is True
+
+ @pytest.mark.parametrize("cannot_run", [False, True], ids = ["exit-1", "no-pip"])
+ def test_a_pip_config_that_fails_is_not_guessed_at(self, cannot_run):
+ if cannot_run:
+
+ def boom(*a, **kw):
+ raise OSError("no pip")
+
+ self.monkeypatch.setattr(self.ips.subprocess, "run", boom)
+ else:
+ self._listing("", returncode = 1)
+ assert self.ips._public_pypi_is_reachable() is False
+
+ def test_uv_never_reads_pip_files(self):
+ self._listing("global.no-index='true'\n")
+ self.monkeypatch.setattr(self.ips, "USE_UV", True)
+ for var in ("UV_OFFLINE", "UV_NO_INDEX", "UV_DEFAULT_INDEX", "UV_INDEX_URL", "UV_INDEX"):
+ self.monkeypatch.delenv(var, raising = False)
+ self.monkeypatch.setenv("UV_NO_CONFIG", "1")
+ assert self.ips._public_pypi_is_reachable() is True
+
+ @pytest.mark.parametrize(
+ "body, reachable",
+ [
+ (f"[global]\nindex-url = {CORP}\n", False),
+ ("[global]\nno-index = true\n", False),
+ (f"[global]\nindex-url = {CORP}\n[install]\nindex-url = {PYPI}\n", True),
+ ("[global]\ntimeout = 60\n", True),
+ ],
+ )
+ def test_the_real_pip_reads_a_real_file(self, tmp_path, body, reachable):
+ """End to end through this interpreter's pip: PIP_CONFIG_FILE names the one file read."""
+ pytest.importorskip("pip")
+ conf = tmp_path / "pip.conf"
+ conf.write_text(body, encoding = "utf-8")
+ self.monkeypatch.setenv("PIP_CONFIG_FILE", str(conf))
+ assert self.ips._public_pypi_is_reachable() is reachable, body
+
+ def test_the_reader_is_the_one_the_pip_path_calls(self):
+ body = STACK_SRC[STACK_SRC.index("def _pip_reaches_public_pypi") :]
+ body = body[: body.index("\ndef ")]
+ assert "_pip_config_index_policy()" in body
+
+
+class TestSqliteVecIsAnExplicitOptionalToo:
+ """Marker-excluded on ARM64 in pyproject.toml and studio.txt alike, and the one
+ unconditional line lives in no-torch-runtime.txt, which the torch install never applies:
+ a staged wheel was ignored and RAG stayed unavailable."""
+
+ def test_it_is_in_the_explicit_install_map(self, ips):
+ assert "sqlite-vec" in ips.WINDOWS_ARM64_WHEELHOUSE_OPTIONALS
+
+ def test_no_torch_requirement_reaches_it_on_the_torch_path(self):
+ """The premise: without an explicit install nothing asks for it."""
+ for name in ("pyproject.toml", "studio/backend/requirements/studio.txt"):
+ text = (REPO_ROOT / name).read_text(encoding = "utf-8")
+ rows = [
+ l for l in text.splitlines() if "sqlite-vec" in l and not l.strip().startswith("#")
+ ]
+ assert rows and all("ARM64" in r for r in rows), name
+
+
+class TestInstallPs1HandsOverWhatPyPIProvides:
+ """install.ps1 discards a wheelhouse wheel once PyPI serves the same version for this
+ interpreter, and records that only in its own session. The managed copy is gone, so the
+ find-links scan here no longer answers for it and tiktoken went back onto the skip list,
+ taking openai-whisper with it, with both resolvable from PyPI."""
+
+ @pytest.fixture
+ def native_on_pypi(self, ips, monkeypatch, wheelhouse):
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: True)
+ monkeypatch.setattr(ips, "_public_pypi_is_reachable", lambda: True)
+ monkeypatch.delenv("UNSLOTH_WOA_PYPI_PROVIDED", raising = False)
+
+ def test_the_handed_over_versions_count_as_published(self, ips, monkeypatch, native_on_pypi):
+ monkeypatch.setenv("UNSLOTH_WOA_PYPI_PROVIDED", "tiktoken==0.12.0 sqlite-vec==0.1.9")
+ assert ips._public_index_win_arm64_versions("tiktoken") == {"0.12.0"}
+ assert ips._public_index_win_arm64_versions("sqlite_vec") == {
+ "0.1.9"
+ }, "read by canonical name, the way every table here is"
+ assert ips._public_index_win_arm64_versions("numba") == set()
+
+ def test_a_handed_over_wheel_leaves_the_skip_list(self, ips, monkeypatch, native_on_pypi):
+ """The managed copy is gone, so nothing but the handover says tiktoken resolves."""
+ assert "tiktoken" in ips._windows_arm64_skip_packages()
+ monkeypatch.setenv("UNSLOTH_WOA_PYPI_PROVIDED", "tiktoken==0.12.0")
+ assert "tiktoken" not in ips._windows_arm64_skip_packages()
+
+ def test_together_with_the_index_table_it_unblocks_whisper(
+ self, ips, monkeypatch, native_on_pypi
+ ):
+ monkeypatch.setattr(ips, "_wheel_matches_interpreter", lambda name: "cp314" in name)
+ assert "openai-whisper" in ips._windows_arm64_skip_packages()
+ monkeypatch.setenv("UNSLOTH_WOA_PYPI_PROVIDED", "tiktoken==0.12.0")
+ assert "openai-whisper" not in ips._windows_arm64_skip_packages()
+
+ def test_the_handover_still_needs_pypi(self, ips, monkeypatch, native_on_pypi):
+ """install.ps1 probed PyPI for the resolver it configured; a run whose resolve cannot
+ reach it gets the skip back, as the index table does."""
+ monkeypatch.setenv("UNSLOTH_WOA_PYPI_PROVIDED", "tiktoken==0.12.0")
+ monkeypatch.setattr(ips, "_public_pypi_is_reachable", lambda: False)
+ assert ips._public_index_win_arm64_versions("tiktoken") == set()
+ assert "tiktoken" in ips._windows_arm64_skip_packages()
+
+ def test_nothing_is_claimed_off_win_arm64(self, ips, monkeypatch, native_on_pypi):
+ monkeypatch.setenv("UNSLOTH_WOA_PYPI_PROVIDED", "tiktoken==0.12.0")
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: False)
+ assert ips._public_index_win_arm64_versions("tiktoken") == set()
+
+ @pytest.mark.parametrize("value", ["tiktoken", "==0.12.0", "tiktoken==", " ", "a=b"])
+ def test_an_entry_without_both_halves_is_ignored(self, ips, monkeypatch, value):
+ monkeypatch.setenv("UNSLOTH_WOA_PYPI_PROVIDED", value)
+ assert ips._woa_pypi_provided_versions() == {}
+
+ def test_install_ps1_exports_it_beside_the_other_handovers(self):
+ """Always assigned, like UNSLOTH_WOA_HAS_TORCHAUDIO, so a previous run in the same
+ session cannot leak its answer; and put back with the rest when the installer returns."""
+ assert '$env:UNSLOTH_WOA_PYPI_PROVIDED = ($_woaProvidedPairs -join " ")' in INSTALL_SRC
+ assert '@("UNSLOTH_WOA_PYPI_PROVIDED", $hadPreviousWoaPyPIProvided,' in INSTALL_SRC
+
+
+class TestAHostedTorchcodecIsInstalledByItsStep:
+ """The requirement filter kept a hosted torchcodec's row, but no requirements file has one,
+ and the dedicated step skipped every platform without a published wheel. Hosting the wheel
+ therefore re-enabled nothing, against what the drop list in install.ps1 promises."""
+
+ @pytest.fixture
+ def native(self, ips, monkeypatch, wheelhouse):
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: True)
+ return wheelhouse
+
+ def test_the_hosted_version_inside_the_torch_window(self, ips, native):
+ _stage(native, "torchcodec", "0.10.1")
+ assert ips._wheelhouse_torchcodec_version("2.10.0+cu134") == "0.10.1"
+
+ def test_a_wheel_outside_the_window_is_not_offered(self, ips, native):
+ """torch 2.11 selects 0.11.x; a 0.10 build is another torch's codec."""
+ _stage(native, "torchcodec", "0.10.1")
+ assert ips._wheelhouse_torchcodec_version("2.11.0+cu134") is None
+
+ def test_no_torch_version_means_no_window(self, ips, native):
+ _stage(native, "torchcodec", "0.10.1")
+ assert ips._wheelhouse_torchcodec_version(None) is None
+ assert ips._wheelhouse_torchcodec_version("") is None
+
+ def test_no_other_platform_is_offered_one(self, ips, monkeypatch, wheelhouse):
+ _stage(wheelhouse, "torchcodec", "0.10.1")
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: False)
+ assert ips._wheelhouse_torchcodec_version("2.10.0") is None
+
+ @staticmethod
+ def _run_step(ips, hosted, **stubs):
+ """Run step 13b on a platform without a published torchcodec wheel."""
+ from textwrap import dedent
+ from unittest.mock import Mock
+
+ calls = []
+ namespace = vars(ips).copy()
+ namespace.update(
+ NO_TORCH = False,
+ PLATFORM_LACKS_TORCHCODEC_WHEEL = True,
+ _wheelhouse_hosts = lambda name: hosted is not None,
+ _wheelhouse_torchcodec_version = lambda torch_version: hosted,
+ _probe_installed_torch_version = lambda: "2.10.0+cu134",
+ _progress = Mock(),
+ _note = Mock(),
+ pip_install_try = lambda label, *a, **kw: calls.append((a, kw)) or True,
+ )
+ namespace.update(stubs)
+ step = STACK_SRC.split("# 13b. torchcodec", 1)[1].split("# 14.", 1)[0]
+ exec(dedent(step[step.index(" _codec_torch_ver = None") :]), namespace)
+ return calls, namespace
+
+ def test_a_hosted_wheel_is_installed_pinned_and_without_deps(self, ips):
+ calls, ns = self._run_step(ips, "0.10.1")
+ assert len(calls) == 1, calls
+ args, kw = calls[0]
+ assert "torchcodec==0.10.1" in args and "--no-deps" in args
+ assert kw.get("constrain") is False, "constraints.txt knows nothing of this wheel"
+ ns["_progress"].assert_called_once_with("torchcodec")
+
+ def test_without_one_the_platform_skip_is_unchanged(self, ips):
+ calls, ns = self._run_step(ips, None)
+ assert calls == []
+ ns["_progress"].assert_called_once_with("torchcodec (skipped, no wheel for this platform)")
+
+ def test_a_hosted_wheel_outside_the_window_is_skipped_with_a_reason(self, ips):
+ calls, ns = self._run_step(ips, None, _wheelhouse_hosts = lambda name: True)
+ assert calls == []
+ ns["_progress"].assert_called_once_with("torchcodec (skipped, no wheel for this platform)")
+ assert any("outside the window" in c.args[0] for c in ns["_note"].call_args_list)
+
+ def test_a_failed_install_leaves_audio_off_without_failing(self, ips):
+ calls, ns = self._run_step(ips, "0.10.1", pip_install_try = lambda *a, **kw: False)
+ assert any("stays disabled" in c.args[0] for c in ns["_note"].call_args_list)
+
+
+class TestTheSkipGateAuditsTheArm64FilteredFile:
+ """The ARM64 skip list has to be applied by _effective_requirements, the helper pip_install
+ and the two skip-gate audits share. Filtering only inside pip_install would leave the audits
+ reading the raw file: tiktoken, xformers and sqlite-vec would read as missing on every
+ win_arm64 host, so no step could ever be skipped and `known_unmet` would record packages
+ this platform deliberately never installs."""
+
+ def test_the_filter_lives_in_the_shared_helper(self, ips):
+ helper = STACK_SRC[STACK_SRC.index("def _effective_requirements(") :]
+ helper = helper[: helper.index("\ndef ", 1)]
+ assert (
+ "_windows_arm64_skip_packages(req)" in helper
+ ), "the ARM64 skip is applied somewhere the audits do not see"
+ assert '_wheelhouse_hosts("torchcodec")' in helper
+
+ def test_the_skip_list_is_judged_against_the_unfiltered_file(self, ips):
+ """`req`, not the partly filtered copy: the pins decide whether a hosted wheel is
+ usable, and the Windows filter above has already dropped rows they sit on."""
+ helper = STACK_SRC[STACK_SRC.index("def _effective_requirements(") :]
+ helper = helper[: helper.index("\ndef ", 1)]
+ assert "_windows_arm64_skip_packages(actual)" not in helper
+
+ def test_pip_install_and_the_audits_share_it(self, ips):
+ """Three call sites: the install, the closure record, and the on-disk skip check."""
+ assert (
+ STACK_SRC.count("_effective_requirements(req)") == 3
+ ), "a caller that filters its own way can disagree with the file that installs"
diff --git a/tests/python/test_windows_installer_native_type_fallback.py b/tests/python/test_windows_installer_native_type_fallback.py
index 41765f947d3..1d9bfd49a73 100644
--- a/tests/python/test_windows_installer_native_type_fallback.py
+++ b/tests/python/test_windows_installer_native_type_fallback.py
@@ -1679,6 +1679,35 @@ def test_the_private_temp_removal_only_takes_what_it_created(tmp_path: Path):
assert (data / "studio.port").exists()
+# Split-Path's -LiteralPath lives in its own parameter set in Windows PowerShell 5.1, so naming
+# -Parent with it throws AmbiguousParameterSet at runtime, not at parse time, which is why eight of
+# them reached a release. -LiteralPath alone already splits off the parent, and -Path globs.
+# Static, because CI has no Windows PowerShell 5.1 to run the scripts under.
+_SPLIT_PATH_LITERAL_PARENT = re.compile(
+ r"Split-Path\b[^\r\n|;]*?-LiteralPath\b[^\r\n|;]*?-Parent\b"
+ r"|Split-Path\b[^\r\n|;]*?-Parent\b[^\r\n|;]*?-LiteralPath\b"
+)
+
+
+# The two installers this change touches. scripts/uninstall.ps1 has its own eight of these and its
+# own PR (#10471); listed here it failed on this tree unconditionally.
[email protected]("name", ("install.ps1", "studio/setup.ps1"))
+def test_split_path_never_pairs_literalpath_with_parent(name: str) -> None:
+ text = (REPO_ROOT / name).read_text(encoding = "utf-8")
+ offenders = [
+ f"{name}:{number}: {line.strip()}"
+ for number, line in enumerate(text.splitlines(), start = 1)
+ # Comments are prose about the rule, not a call the shell binds.
+ if not line.strip().startswith("#") and _SPLIT_PATH_LITERAL_PARENT.search(line)
+ ]
+ assert not offenders, (
+ "Split-Path -LiteralPath cannot be combined with -Parent: Windows PowerShell 5.1 "
+ "resolves no parameter set for the pair and the call throws at runtime. Drop "
+ "-Parent -- -LiteralPath alone already returns the parent, and unlike -Path it does "
+ "not treat [ ] in an install root as a wildcard.\n " + "\n ".join(offenders)
+ )
+
+
SETUP_PS1 = REPO_ROOT / "studio" / "setup.ps1"
diff --git a/tests/python/test_windows_xformers_installer.py b/tests/python/test_windows_xformers_installer.py
index 44607ced50a..313102c19ff 100644
--- a/tests/python/test_windows_xformers_installer.py
+++ b/tests/python/test_windows_xformers_installer.py
@@ -233,12 +233,23 @@ def test_installer_never_installs_an_unpinned_xformers():
necessarily built for the CUDA family the resident torch came from. The installer
picks the exact version for (torch, cuda) instead, so every spec must be pinned."""
source = _source()
+ # The Windows on ARM drop list names packages the installer REMOVES, so a bare name there is
+ # the opposite of an install spec and has to match the requirement line exactly.
+ drop_list = re.search(r"\$WoaDropCandidates = @\(.*?\n\s*\)\n", source, re.DOTALL)
+ drop_span = drop_list.span() if drop_list else (-1, -1)
+ # Same for the drop floors: the key is a package NAME being looked up, not an install spec.
+ floors = re.search(r"\$WoaDropFloors = @\{[^}]*\}", source, re.DOTALL)
+ floor_span = floors.span() if floors else (-1, -1)
for match in re.finditer(r'"xformers[^"]*"', source):
spec = match.group(0)
# A wheel FILENAME is not a spec: it names one exact file and cannot resolve to anything else, which is the
# whole point of preferring it.
if spec.endswith('.whl"'):
continue
+ if drop_span[0] <= match.start() < drop_span[1]:
+ continue
+ if floor_span[0] <= match.start() < floor_span[1]:
+ continue
assert spec == '"xformers==$_xfVersion"', f"unpinned xFormers spec in install.ps1: {spec}"
diff --git a/tests/studio/install/test_arm64_cuda_digest_verification.py b/tests/studio/install/test_arm64_cuda_digest_verification.py
new file mode 100644
index 00000000000..0a77013d76d
--- /dev/null
+++ b/tests/studio/install/test_arm64_cuda_digest_verification.py
@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The Windows ARM64 CUDA bundle was the one archive this installer would install unchecked.
+
+Every other prebuilt goes through apply_approved_hashes, which drops an attempt our checksum
+manifest does not cover. The ARM64 CUDA branch could not: we publish no windows-arm64-cuda
+artifact, so nothing covers upstream's zip, and refusing outright would mean no CUDA
+llama.cpp on this hardware at all. It logged that it had no hash and installed anyway.
+
+GitHub's release API now reports a `digest` for every asset (ggml-org/llama.cpp b10853: 27 of
+27, including llama-*-bin-win-cuda-13.4-arm64.zip and its paired cudart archive). That is
+weaker than a manifest we compute ourselves rather than read from the host serving the bytes,
+but it pins the download to what the API listed. An asset GitHub states no digest for is now
+refused, so no path installs an unverified archive.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(REPO_ROOT / "studio"))
+
+import install_llama_prebuilt as ip # noqa: E402
+import prebuilt_core # noqa: E402
+
+SHA_A = "a" * 64
+SHA_B = "b" * 64
+
+
+def _release(*assets: dict) -> dict:
+ return {"tag_name": "b10853", "assets": list(assets)}
+
+
+def _asset(name: str, digest: str | None) -> dict:
+ out = {"name": name, "browser_download_url": f"https://example.invalid/{name}"}
+ if digest is not None:
+ out["digest"] = digest
+ return out
+
+
+class TestTheDigestMapReadsOnlyWhatGitHubStated:
+ def test_a_sha256_digest_is_read_without_its_prefix(self):
+ release = _release(_asset("bundle.zip", f"sha256:{SHA_A}"))
+ assert prebuilt_core.release_asset_digests(release) == {"bundle.zip": SHA_A}
+
+ @pytest.mark.parametrize(
+ ("digest", "why"),
+ [
+ (None, "no digest field at all"),
+ ("", "empty"),
+ (SHA_A, "bare hex: GitHub did not say which algorithm produced it"),
+ (f"sha512:{'c' * 128}", "a different algorithm"),
+ ("sha256:nothex" + "0" * 58, "not hex"),
+ ("sha256:" + "a" * 63, "too short"),
+ ("sha256:" + "a" * 65, "too long"),
+ ],
+ ids = ["absent", "empty", "unprefixed", "sha512", "not-hex", "short", "long"],
+ )
+ def test_anything_else_is_left_out_rather_than_guessed_at(self, digest, why):
+ release = _release(_asset("bundle.zip", digest))
+ assert prebuilt_core.release_asset_digests(release) == {}, why
+
+ def test_an_upper_case_digest_still_matches_a_lower_case_file_hash(self):
+ """The verifier compares hex strings, so the case has to be normalised here."""
+ release = _release(_asset("bundle.zip", "SHA256:" + SHA_A.upper()))
+ assert prebuilt_core.release_asset_digests(release) == {"bundle.zip": SHA_A}
+
+ def test_a_release_with_no_assets_is_empty_not_an_error(self):
+ assert prebuilt_core.release_asset_digests({"tag_name": "b1"}) == {}
+ assert prebuilt_core.release_asset_digests({"assets": "not a list"}) == {}
+
+
+class TestAnAttemptWithNoDigestIsDropped:
+ """The rule that makes this safe. [] is what the caller reads as "refuse"."""
+
+ def _choice(
+ self,
+ name = "bundle.zip",
+ runtime = None,
+ ):
+ return ip.AssetChoice(
+ repo = "ggml-org/llama.cpp",
+ tag = "b10853",
+ name = name,
+ url = f"https://example.invalid/{name}",
+ source_label = "upstream",
+ install_kind = "windows-arm64-cuda",
+ runtime_name = runtime,
+ runtime_url = f"https://example.invalid/{runtime}" if runtime else None,
+ )
+
+ def test_a_covered_attempt_carries_the_digest_forward(self):
+ kept = ip._apply_release_digests([self._choice()], {"bundle.zip": SHA_A})
+ assert [c.expected_sha256 for c in kept] == [SHA_A]
+
+ def test_an_uncovered_attempt_is_dropped_not_installed(self):
+ assert ip._apply_release_digests([self._choice()], {"other.zip": SHA_A}) == []
+
+ def test_an_empty_digest_map_refuses_everything(self):
+ assert ip._apply_release_digests([self._choice()], {}) == []
+
+ def test_a_paired_runtime_gets_its_own_digest(self):
+ kept = ip._apply_release_digests(
+ [self._choice(runtime = "cudart.zip")],
+ {"bundle.zip": SHA_A, "cudart.zip": SHA_B},
+ )
+ assert kept[0].runtime_sha256 == SHA_B
+
+ def test_an_uncovered_runtime_unpairs_rather_than_riding_along(self):
+ """Dropping the whole attempt would lose CUDA over a missing side archive, and
+ keeping the pair would install one unverified. Unpairing is neither."""
+ kept = ip._apply_release_digests(
+ [self._choice(runtime = "cudart.zip")], {"bundle.zip": SHA_A}
+ )
+ assert len(kept) == 1
+ assert kept[0].expected_sha256 == SHA_A
+ assert kept[0].runtime_name is None
+ assert kept[0].runtime_url is None
+ assert kept[0].runtime_sha256 is None
+
+
+class TestTheFetcherFailsClosed:
+ def test_an_api_failure_is_an_empty_map_not_an_exception(self, monkeypatch):
+ """A rate limit or an outage has to cost the CUDA bundle, not the whole install,
+ and it must not be mistaken for "no digest needed"."""
+
+ def _boom(repo, tag):
+ raise RuntimeError("429 rate limited")
+
+ monkeypatch.setattr(ip, "github_release", _boom)
+ assert ip.github_release_asset_digests("ggml-org/llama.cpp", "b10853") == {}
+
+ def test_it_reads_the_digests_off_the_release_it_fetched(self, monkeypatch):
+ monkeypatch.setattr(
+ ip, "github_release", lambda repo, tag: _release(_asset("b.zip", f"sha256:{SHA_A}"))
+ )
+ assert ip.github_release_asset_digests("r", "t") == {"b.zip": SHA_A}
+
+
+def test_no_branch_returns_attempts_that_were_never_hash_gated():
+ """The property this file exists for, asserted against the source.
+
+ Every `return` of asset choices in the release-plan resolver goes through
+ apply_approved_hashes or _apply_release_digests. A future branch that returns a bare
+ list would reintroduce exactly the hole this closes.
+ """
+ source = (REPO_ROOT / "studio" / "install_llama_prebuilt.py").read_text(encoding = "utf-8")
+ start = source.index("def resolve_release_asset_choice(")
+ end = source.index("\ndef ", start + 1)
+ body = source[start:end]
+ returns = [
+ line.strip()
+ for line in body.splitlines()
+ if line.strip().startswith("return ") and "attempts" not in line
+ ]
+ for line in returns:
+ assert (
+ "apply_approved_hashes" in line
+ or "_apply_release_digests" in line
+ or "verified" in line
+ or "published_choice" in line
+ ), f"a return that is not hash gated: {line}"
diff --git a/tests/studio/install/test_cuda_repair.py b/tests/studio/install/test_cuda_repair.py
index c20a3ee6675..26ac1b5099b 100644
--- a/tests/studio/install/test_cuda_repair.py
+++ b/tests/studio/install/test_cuda_repair.py
@@ -836,6 +836,7 @@ def _run_flavor_invariant(
index_family = None,
index_url = None,
win_arm64 = False,
+ win_arm64_interpreter = None,
probe_cuda = None,
probe_hip = None,
):
@@ -913,6 +914,13 @@ def _run_flavor_invariant(
patch.object(stack_mod, "_RECORDED_TORCH_TAG", recorded),
patch.object(stack_mod.platform, "machine", return_value = "AMD64"),
patch.object(stack_mod, "_is_windows_arm64", return_value = win_arm64),
+ # The interpreter's arch, which the CUDA-preservation shortcut reads.
+ # They separate on an ARM64 machine running an emulated x64 python.
+ patch.object(
+ stack_mod,
+ "_is_win_arm64_interpreter",
+ return_value = win_arm64 if win_arm64_interpreter is None else win_arm64_interpreter,
+ ),
patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = nvidia),
patch.object(stack_mod.shutil, "which", side_effect = _which),
patch.object(stack_mod.os.path, "isfile", return_value = True),
@@ -1397,6 +1405,84 @@ class TestAPinnedCpuIndexIsEnforcedToo:
mock_pip.assert_not_called()
+class TestWindowsOnArmPreservesCudaOnlyForAnInferredExpectation:
+ """The win_arm64 CUDA shortcut must not swallow an explicit CPU pin.
+
+ Preserving an installed cu* build is right for an expectation DERIVED from the driver:
+ download.pytorch.org publishes no win_arm64 CUDA wheel, so that "repair" resolves
+ nothing. A pin is not a derivation, and /cpu does publish win_arm64 torch and
+ torchvision, so that repair has somewhere to go.
+ """
+
+ _PIN = "https://download.pytorch.org/whl/cpu"
+
+ def test_an_explicit_cpu_pin_still_repairs_a_cuda_venv(self):
+ ok, mock_pip = _run_flavor_invariant(
+ installed = "2.11.0+cu134",
+ repaired = "2.10.0+cpu",
+ expected_env = "cpu",
+ index_url = self._PIN,
+ backend = "cpu",
+ win_arm64 = True,
+ )
+ assert ok is True
+ assert mock_pip.call_count == 1
+ assert _index_url(mock_pip) == self._PIN
+ args = [str(a) for a in mock_pip.call_args.args]
+ # No win_arm64 torchaudio on /cpu either, so the existing drop still applies.
+ assert not any(a.startswith("torchaudio") for a in args)
+
+ def test_the_family_spelling_of_the_pin_is_honoured_too(self):
+ ok, mock_pip = _run_flavor_invariant(
+ installed = "2.11.0+cu134",
+ repaired = "2.10.0+cpu",
+ expected_env = "cpu",
+ index_family = "cpu",
+ backend = "cpu",
+ win_arm64 = True,
+ )
+ assert ok is True
+ assert mock_pip.call_count == 1
+
+ def test_a_driver_inferred_cuda_expectation_is_still_preserved(self):
+ ok, mock_pip = _run_flavor_invariant(
+ installed = "2.11.0+cu134",
+ expected_env = "cu130",
+ win_arm64 = True,
+ )
+ assert ok is True
+ mock_pip.assert_not_called()
+
+ def test_a_probed_cpu_tag_with_no_pin_does_not_downgrade_it(self):
+ # setup.ps1 also publishes "cpu" when its nvidia-smi probe comes back empty, and a probe
+ # result is not evidence, so the shortcut keeps the CUDA build.
+ ok, mock_pip = _run_flavor_invariant(
+ installed = "2.11.0+cu134",
+ expected_env = "cpu",
+ nvidia = False,
+ win_arm64 = True,
+ )
+ assert ok is True
+ mock_pip.assert_not_called()
+
+ def test_an_emulated_x64_interpreter_on_an_arm64_machine_still_repairs(self):
+ """The machine and the interpreter are separate axes, and the shortcut reads the
+ interpreter. Every Windows on ARM install predating native support runs an
+ emulated x64 python against ordinary win_amd64 wheels from
+ download.pytorch.org, so the repair must reach them exactly as it always did.
+ """
+ ok, mock_pip = _run_flavor_invariant(
+ installed = "2.9.1+cu118",
+ repaired = "2.10.0+cu128",
+ expected_env = "cu128",
+ win_arm64 = True,
+ win_arm64_interpreter = False,
+ )
+ assert ok is True
+ assert mock_pip.call_count == 1
+ assert _index_url(mock_pip).endswith("/cu128")
+
+
class TestWindowsOnArmKeepsTheNoTorchaudioException:
"""No win_arm64 torchaudio wheel is published on any index.
@@ -2192,9 +2278,13 @@ class TestTheDelegatedRocmRepairKeepsTheArm64Exception:
def test_the_windows_rocm_install_drops_torchaudio_on_arm64(self):
source = inspect.getsource(stack_mod._ensure_rocm_torch)
block = source[source.index("_WINDOWS_ROCM_TORCH_PKG_SPECS.get") :][:1200]
+ # The interpreter's arch, not the machine's: an emulated x64 venv installs win_amd64.
assert (
- "_is_windows_arm64()" in block
+ "_is_win_arm64_interpreter()" in block
), "the delegated ROCm repair needs the same exception as the flavor repair"
+ assert (
+ "_is_windows_arm64()" not in block
+ ), "the machine predicate would drop torchaudio from x64 venvs"
assert "*_rocm_trio" in block, "the trio has to be built, not passed positionally"
def test_x64_windows_still_asks_for_all_three(self):
diff --git a/tests/studio/install/test_diffusers_pin.py b/tests/studio/install/test_diffusers_pin.py
index fe8bb56893e..aaeb1957f2d 100644
--- a/tests/studio/install/test_diffusers_pin.py
+++ b/tests/studio/install/test_diffusers_pin.py
@@ -19,8 +19,11 @@ import ast
import io
import pathlib
import re
+import subprocess
import tokenize
+import pytest
+
REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
REQ_ROOT = REPO_ROOT / "studio" / "backend" / "requirements"
PIN_FILE = REQ_ROOT / "diffusers-pin.txt"
@@ -181,3 +184,70 @@ def test_install_sh_still_delegates_the_core_package_skip():
"""The handoff flag skips core packages while allowing other base entries through."""
assert 'SKIP_STUDIO_BASE="$_SKIP_BASE"' in INSTALL_SH.read_text(encoding = "utf-8")
assert "_SKIP_BASE=1" in INSTALL_SH.read_text(encoding = "utf-8")
+
+
+def test_no_generated_filter_snapshot_is_tracked():
+ """They are a copy of a file already in the tree, and one got committed.
+
+ _filter_requirements writes beside the source so relative -r/-c includes resolve.
+ pip_install unlinks them in a finally, but a test calling the helper directly, or an
+ install killed mid-run, leaves them in the checkout, where `git add -A` picks them up.
+ A stale snapshot then reads as a second, silently divergent copy of the pins.
+ """
+ done = subprocess.run(
+ ["git", "ls-files", "-z", "--", "studio/backend/requirements/"],
+ cwd = REPO_ROOT,
+ capture_output = True,
+ text = True,
+ )
+ if done.returncode != 0:
+ pytest.skip("not a git checkout")
+ tracked = [p for p in done.stdout.split("\0") if p]
+ offenders = [p for p in tracked if _GENERATED_FILTER.fullmatch(pathlib.Path(p).name)]
+ assert not offenders, f"generated filter snapshots are tracked: {offenders}"
+
+
+def test_gitignore_covers_the_generated_snapshots():
+ """So the next `git add -A` cannot put one back."""
+ probe = REQ_ROOT / ".studio-filtered-abcd1234.txt"
+ assert _GENERATED_FILTER.fullmatch(probe.name), "the probe must match the generated shape"
+ done = subprocess.run(
+ ["git", "check-ignore", "-q", "--no-index", str(probe)],
+ cwd = REPO_ROOT,
+ capture_output = True,
+ text = True,
+ )
+ if done.returncode == 128:
+ pytest.skip("not a git checkout")
+ assert done.returncode == 0, f"{probe.name} is not ignored; .gitignore needs the pattern"
+
+
+# A win_arm64 floor set above the first release that actually publishes one costs the
+# resolver every wheel in between, and for scikit-learn it cost the only one that exists on
+# a free-threaded 3.13. Each floor below is the earliest release carrying a win_arm64 wheel,
+# read off PyPI's own file list, so the pin can be checked against the index by hand.
+WIN_ARM64_FLOORS = [
+ # scikit-learn 1.9.0 dropped cp313-cp313t; 1.8.0 is the only release with one, so a
+ # >=1.9.0 floor leaves a free-threaded 3.13 with no wheel and an sdist to compile.
+ ("extras.txt", "scikit-learn", "1.8.0"),
+ # av publishes cp311-abi3 plus a cp314t from 17.0.0. No release has a 3.13t wheel.
+ ("extras.txt", "av", "17.0.0"),
+ ("single-env/constraints.txt", "av", "17.0.0"),
+]
+
+
+ "relpath, dist, floor",
+ WIN_ARM64_FLOORS,
+ ids = [f"{r.split('/')[-1]}:{d}" for r, d, _ in WIN_ARM64_FLOORS],
+)
+def test_the_win_arm64_floor_is_the_first_release_that_has_a_wheel(relpath, dist, floor):
+ text = (REQ_ROOT / relpath).read_text(encoding = "utf-8")
+ wanted = f'{dist}>={floor}; sys_platform == "win32" and platform_machine == "ARM64"'
+ assert wanted in text, f"{relpath} no longer floors {dist} at {floor}"
+ # And nothing else floors the same dist higher on that marker.
+ for line in text.splitlines():
+ line = line.strip()
+ if not line.startswith(f"{dist}>=") or 'platform_machine == "ARM64"' not in line:
+ continue
+ assert line == wanted, f"{relpath}: a second ARM64 floor for {dist}: {line}"
diff --git a/tests/studio/install/test_install_manifest_pass_evidence.py b/tests/studio/install/test_install_manifest_pass_evidence.py
index 827d5630e8d..da1d1f2eef4 100644
--- a/tests/studio/install/test_install_manifest_pass_evidence.py
+++ b/tests/studio/install/test_install_manifest_pass_evidence.py
@@ -132,6 +132,28 @@ def test_extras_cannot_shadow_a_field_verify_install_reads(tmp_path: pathlib.Pat
assert payload["package_version"] != "9.9.9"
+def test_extras_cannot_name_the_windows_on_arm_torch_index(tmp_path: pathlib.Path) -> None:
+ """setup.ps1 reads woa_torch_index back as an index to install torch FROM, and the
+ parameter that writes it accepts NVIDIA's own https channel only. Evidence reaching the
+ same key would hand a fresh-shell update any URL the caller liked."""
+ im.write_manifest(
+ root = tmp_path,
+ req_root = tmp_path,
+ package_name = "pytest",
+ extra = {"woa_torch_index": "https://evil.test/simple"},
+ )
+ assert "woa_torch_index" not in _payload(tmp_path)
+
+ im.write_manifest(
+ root = tmp_path,
+ req_root = tmp_path,
+ package_name = "pytest",
+ woa_torch_index = "https://pypi.nvidia.com/nvtorch_oot",
+ extra = {"woa_torch_index": "https://evil.test/simple"},
+ )
+ assert _payload(tmp_path)["woa_torch_index"] == "https://pypi.nvidia.com/nvtorch_oot"
+
+
def test_update_manifest_merges_without_touching_the_rest(tmp_path: pathlib.Path) -> None:
im.write_manifest(root = tmp_path, req_root = tmp_path, package_name = "pytest")
before = _payload(tmp_path)
diff --git a/tests/studio/install/test_llama_kind_gate_matches_selector.py b/tests/studio/install/test_llama_kind_gate_matches_selector.py
new file mode 100644
index 00000000000..e074aab3b56
--- /dev/null
+++ b/tests/studio/install/test_llama_kind_gate_matches_selector.py
@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The llama.cpp mismatch gate and the llama.cpp selector have to agree, or updates churn.
+
+Before reinstalling, setup.ps1 deletes the existing llama.cpp tree when its recorded
+`install_kind` is not in the set the gate considers correct for this host; then
+install_llama_prebuilt.py picks a bundle. Nothing makes those two agree, and a disagreement
+is permanent: every update deletes the tree and refetches the identical bundle, forever, on
+a working host. The only relationship that matters is "the kind the selector installs is one
+the gate accepts", so that is asserted directly, over the product of what either side
+branches on, rather than the text of either.
+
+Both churning combinations this found are on Windows ARM64 and invisible from an x64 box:
+
+ * NVIDIA. The gate expected windows-cuda; on an ARM64 venv the selector installs
+ windows-arm64. That is every Windows ARM64 machine with an NVIDIA GPU.
+ * ROCm. No ROCm bundle exists for Windows ARM64 at all, so the selector falls through to
+ the ARM64 CPU bundle while the gate still expected windows-rocm or windows-hip.
+
+Offline. direct_upstream_release_plan takes a release dict, and the gate's own block is lifted
+out of setup.ps1 and run with only its inputs replaced.
+"""
+
+from __future__ import annotations
+
+import itertools
+import pathlib
+import re
+import shutil
+import subprocess
+import sys
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+SETUP_PS1 = REPO_ROOT / "studio" / "setup.ps1"
+SETUP_SRC = SETUP_PS1.read_text(encoding = "utf-8")
+
+sys.path.insert(0, str(REPO_ROOT / "studio"))
+
+import install_llama_prebuilt as ip # noqa: E402
+
+PWSH = shutil.which("pwsh") or shutil.which("powershell")
+requires_pwsh = pytest.mark.skipif(PWSH is None, reason = "PowerShell is unavailable")
+
+TAG = "b9334"
+
+# Everything upstream publishes for Windows, so no row is starved of a candidate and a
+# disagreement is a disagreement rather than a missing asset. Note what is NOT here and
+# cannot be: there is no ROCm or CUDA bundle for Windows ARM64 upstream.
+ASSET_NAMES = (
+ f"llama-{TAG}-bin-win-cpu-arm64.zip",
+ f"llama-{TAG}-bin-win-cpu-x64.zip",
+ f"llama-{TAG}-bin-win-cuda-12.4-x64.zip",
+ f"llama-{TAG}-bin-win-cuda-13.0-x64.zip",
+ f"llama-{TAG}-bin-win-vulkan-x64.zip",
+ f"llama-{TAG}-bin-win-hip-radeon-x64.zip",
+)
+RELEASE = {
+ "tag_name": TAG,
+ "assets": [
+ {"name": name, "browser_download_url": f"https://example.invalid/{name}"}
+ for name in ASSET_NAMES
+ ],
+}
+
+
+def _host(*, arm64: bool, nvidia: bool, rocm: bool) -> ip.HostInfo:
+ """The interpreter's own view of the machine, which is what the selector reads: an
+ emulated x64 Python on an ARM64 box reports AMD64, and is an x64 host here."""
+ return ip.HostInfo(
+ system = "Windows",
+ machine = "ARM64" if arm64 else "AMD64",
+ is_windows = True,
+ is_linux = False,
+ is_macos = False,
+ is_x86_64 = not arm64,
+ is_arm64 = arm64,
+ nvidia_smi = "nvidia-smi" if nvidia else None,
+ driver_cuda_version = (13, 0) if nvidia else None,
+ compute_caps = ["12.1"] if nvidia else [],
+ visible_cuda_devices = None,
+ has_physical_nvidia = nvidia,
+ has_usable_nvidia = nvidia,
+ has_rocm = rocm,
+ rocm_gfx_target = "gfx1201" if rocm else None,
+ )
+
+
+def _gate_block() -> str:
+ """setup.ps1's own expected-kinds computation, from the opt-out read to the delete."""
+ start = SETUP_SRC.index("$_arm64CudaOptOut = ")
+ end = SETUP_SRC.index("if ($existingKind -and", start)
+ return SETUP_SRC[start:end]
+
+
+def _expected_kinds(*, arm64_venv: bool, nvidia: bool, rocm: bool, opt_out: bool) -> list[str]:
+ block = _gate_block()
+ # The parentheses stay: the source writes `if (Test-WinArm64Venv)`, and replacing the
+ # whole parenthesised form would leave `if $true {`, which does not parse.
+ block = block.replace("Test-WinArm64Venv", "$true" if arm64_venv else "$false")
+ # The evidence index is read through a chain of markers and a venv on disk. Its only use
+ # is Test-WoaPersistableIndex, so supply the answer and stub the predicate.
+ block = re.sub(
+ r"(?s)\$_woaEvidenceIndex = if.*?\n(\s*)\$_nvidiaEvidence",
+ "$_woaEvidenceIndex = '{}'\n\\1$_nvidiaEvidence".format(
+ "https://pypi.nvidia.com/nvtorch_oot" if nvidia else ""
+ ),
+ block,
+ )
+ script = "\n".join(
+ [
+ "$ErrorActionPreference = 'Stop'",
+ "function Test-WoaPersistableIndex { param($i) return ($i -like '*nvidia*') }",
+ f"$env:UNSLOTH_LLAMA_ARM64_CUDA = '{'0' if opt_out else '1'}'",
+ f"$HasNvidiaSmi = ${str(nvidia).lower()}",
+ f"$HasROCm = ${str(rocm).lower()}",
+ "$script:ROCmGfxArch = " + ("'gfx1201'" if rocm else "$null"),
+ block,
+ "Write-Output ('<<<' + ($expectedKinds -join ',') + '>>>')",
+ ]
+ )
+ done = subprocess.run(
+ [PWSH, "-NoProfile", "-NonInteractive", "-Command", script],
+ capture_output = True,
+ timeout = 120,
+ )
+ out = done.stdout.decode("utf-8", "replace")
+ assert "<<<" in out, done.stderr.decode("utf-8", "replace")
+ return out[out.index("<<<") + 3 : out.rindex(">>>")].split(",")
+
+
+def _installed_kinds(host: ip.HostInfo) -> list[str]:
+ plan = ip.direct_upstream_release_plan(RELEASE, host, "ggml-org/llama.cpp", "latest")
+ return [attempt.install_kind for attempt in plan.attempts] if plan else []
+
+
+# nvidia and rocm together is not a host we ship to: the ROCm arm wins outright on both sides.
+COMBINATIONS = [
+ (arm64_venv, nvidia, rocm, opt_out)
+ for arm64_venv, nvidia, rocm, opt_out in itertools.product([True, False], repeat = 4)
+ if not (nvidia and rocm)
+]
+
+
+@requires_pwsh
+ ("arm64_venv", "nvidia", "rocm", "opt_out"),
+ COMBINATIONS,
+ ids = [
+ "{}-{}{}".format(
+ "arm64" if a else "x64",
+ "nvidia" if n else ("rocm" if r else "cpu"),
+ "-optout" if o else "",
+ )
+ for a, n, r, o in COMBINATIONS
+ ],
+)
+def test_the_gate_accepts_what_the_selector_installs(arm64_venv, nvidia, rocm, opt_out):
+ expected = _expected_kinds(arm64_venv = arm64_venv, nvidia = nvidia, rocm = rocm, opt_out = opt_out)
+ installed = _installed_kinds(_host(arm64 = arm64_venv, nvidia = nvidia, rocm = rocm))
+ assert installed, "no candidate at all, so this row proves nothing"
+ assert installed[0] in expected, (
+ f"the gate would delete what the selector just installed, on every update: "
+ f"selector picks {installed[0]}, gate accepts {expected}"
+ )
+
+
+@requires_pwsh
+def test_no_arm64_row_expects_a_kind_only_published_for_x64():
+ """The shape behind both bugs: on an ARM64 venv a gate that expects an x64-only kind and
+ nothing else is a delete on every update whatever the selector does. windows-vulkan counts
+ as x64-only, since upstream's bundle is vulkan-x64."""
+ x64_only = {"windows-cuda", "windows-rocm", "windows-hip", "windows-cpu", "windows-vulkan"}
+ for nvidia, rocm, opt_out in itertools.product([True, False], repeat = 3):
+ if nvidia and rocm:
+ continue
+ expected = set(_expected_kinds(arm64_venv = True, nvidia = nvidia, rocm = rocm, opt_out = opt_out))
+ assert expected - x64_only, (
+ f"nvidia={nvidia} rocm={rocm} optout={opt_out}: the gate expects only x64 kinds "
+ f"on an ARM64 venv: {sorted(expected)}"
+ )
diff --git a/tests/studio/install/test_rdna1_unsupported_message_8529.py b/tests/studio/install/test_rdna1_unsupported_message_8529.py
index 99f22439401..ad822f75bdb 100644
--- a/tests/studio/install/test_rdna1_unsupported_message_8529.py
+++ b/tests/studio/install/test_rdna1_unsupported_message_8529.py
@@ -161,9 +161,13 @@ class TestUnsupportedNameLookup:
# ── The Windows WMI path end to end ──────────────────────────────────────────
-def _wmi_detect(names):
+def _wmi_detect(names, arm64 = False):
"""Drive _detect_windows_gfx_arch over `names` with no hipinfo and no amd-smi,
- which is the reporter's host: Adrenalin driver only. Returns (arch, stdout)."""
+ which is the reporter's host: Adrenalin driver only. Returns (arch, stdout).
+
+ `arm64` is the host the advice is being written for. Pinned here rather than read
+ from the box running the tests, because the machine predicate is right to answer
+ True on an ARM64 dev box and the reporter's box is x64."""
ps_result = MagicMock()
ps_result.returncode = 0
amd = [n for n in names if re.search(r"AMD|Radeon", n, re.IGNORECASE)]
@@ -190,7 +194,8 @@ def _wmi_detect(names):
with patch("shutil.which", return_value = None):
with patch("os.path.isfile", return_value = False):
with patch("subprocess.run", side_effect = _run):
- result = stack_mod._detect_windows_gfx_arch()
+ with patch.object(stack_mod, "_is_windows_arm64", return_value = arm64):
+ result = stack_mod._detect_windows_gfx_arch()
return result, buf.getvalue()
@@ -308,8 +313,7 @@ class TestPythonStackWindowsArm64:
ARM64 throw applies to it: setup.ps1 rejects the variable there."""
def test_arm64_gets_a_source_build_note_instead_of_the_setter(self):
- with patch.object(stack_mod, "_is_windows_arm64", return_value = True):
- _arch, out = _wmi_detect(["AMD Radeon RX 5700 XT"])
+ _arch, out = _wmi_detect(["AMD Radeon RX 5700 XT"], arm64 = True)
assert "gfx1010" in out, "the card is still named"
assert (
"UNSLOTH_LLAMA_CPP_BACKEND" not in out
@@ -318,29 +322,43 @@ class TestPythonStackWindowsArm64:
def test_x64_still_gets_the_setter(self):
"""Positive control: the guard must not silence the advice everywhere."""
- with patch.object(stack_mod, "_is_windows_arm64", return_value = False):
- _arch, out = _wmi_detect(["AMD Radeon RX 5700 XT"])
+ _arch, out = _wmi_detect(["AMD Radeon RX 5700 XT"])
assert "UNSLOTH_LLAMA_CPP_BACKEND" in out
@pytest.mark.parametrize(
- "env,expected",
+ "registry,env,expected",
[
- ({"PROCESSOR_ARCHITECTURE": "ARM64"}, True),
- ({"PROCESSOR_ARCHITECTURE": "AMD64", "PROCESSOR_ARCHITEW6432": "ARM64"}, True),
- ({"PROCESSOR_ARCHITECTURE": "AMD64", "PROCESSOR_ARCHITEW6432": ""}, False),
+ ("ARM64", {"PROCESSOR_ARCHITECTURE": "ARM64"}, True),
+ # x64 emulation on an ARM64 box: the process copy says AMD64 and ARCHITEW6432 is
+ # unset, so only the machine-scope registry value tells the truth.
+ ("ARM64", {"PROCESSOR_ARCHITECTURE": "AMD64"}, True),
+ # ARCHITEW6432 still counts on the builds that do set it.
+ ("", {"PROCESSOR_ARCHITECTURE": "AMD64", "PROCESSOR_ARCHITEW6432": "ARM64"}, True),
+ ("AMD64", {"PROCESSOR_ARCHITECTURE": "AMD64", "PROCESSOR_ARCHITEW6432": ""}, False),
+ # Unreadable registry falls back to the per-process signals, not to True.
+ ("", {"PROCESSOR_ARCHITECTURE": "AMD64"}, False),
+ ],
+ ids = [
+ "native-arm64",
+ "emulated-x64-on-arm64",
+ "architew6432-set",
+ "real-x64",
+ "no-registry-x64",
],
- ids = ["native-arm64", "emulated-x64-on-arm64", "real-x64"],
)
- def test_the_arch_probe_reads_the_machine_not_the_process(self, env, expected):
+ def test_the_arch_probe_reads_the_machine_not_the_process(self, registry, env, expected):
"""PROCESSOR_ARCHITECTURE describes the PROCESS, so an emulated x64 Python on an
- ARM64 box reports AMD64; ARCHITEW6432 is ARM64 in exactly that case."""
+ ARM64 box reports AMD64 and so does platform.machine(). The machine-scope value in
+ the registry is the one signal emulation cannot misreport. Patched per case so the
+ answer is the same on an ARM64 host as on x64 CI."""
with patch.object(stack_mod, "IS_WINDOWS", True):
- with patch.object(stack_mod.platform, "machine", return_value = "AMD64"):
- with patch.dict(os.environ, env, clear = False):
- for _k in ("PROCESSOR_ARCHITEW6432", "PROCESSOR_ARCHITECTURE"):
- if _k not in env:
- os.environ.pop(_k, None)
- assert stack_mod._is_windows_arm64() is expected
+ with patch.object(stack_mod, "_machine_arch_from_registry", return_value = registry):
+ with patch.object(stack_mod.platform, "machine", return_value = "AMD64"):
+ with patch.dict(os.environ, env, clear = False):
+ for _k in ("PROCESSOR_ARCHITEW6432", "PROCESSOR_ARCHITECTURE"):
+ if _k not in env:
+ os.environ.pop(_k, None)
+ assert stack_mod._is_windows_arm64() is expected
def test_it_is_false_off_windows(self):
with patch.object(stack_mod, "IS_WINDOWS", False):
diff --git a/tests/studio/install/test_seed_plugin_pandas_range.py b/tests/studio/install/test_seed_plugin_pandas_range.py
new file mode 100644
index 00000000000..b22c2fe2c8e
--- /dev/null
+++ b/tests/studio/install/test_seed_plugin_pandas_range.py
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The bundled seed plugin is installed with --no-deps, so its own pandas range was never
+resolved. On Windows on ARM (Python 3.11+) constraints.txt installs pandas 3, which the
+plugin declared out of range: a dependency-aware reinstall of the plugin would then look for
+a pandas 2 that has no win_arm64 wheel. The plugin's range must admit every pandas the
+constraints can install."""
+
+import pathlib
+import re
+
+from packaging.specifiers import SpecifierSet
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+PLUGIN = (
+ ROOT / "studio" / "backend" / "plugins" / "data-designer-unstructured-seed" / "pyproject.toml"
+)
+CONSTRAINTS = ROOT / "studio" / "backend" / "requirements" / "single-env" / "constraints.txt"
+
+
+def _plugin_pandas_range():
+ text = PLUGIN.read_text(encoding = "utf-8")
+ match = re.search(r'"pandas([^"]*)"', text)
+ assert match, "the plugin declares pandas"
+ return SpecifierSet(match.group(1))
+
+
+def _constraint_pandas_pins():
+ pins = []
+ for line in CONSTRAINTS.read_text(encoding = "utf-8").splitlines():
+ if line.startswith("pandas"):
+ spec = line.split(";", 1)[0][len("pandas") :].strip()
+ pins.append(SpecifierSet(spec))
+ assert pins, "constraints.txt pins pandas"
+ return pins
+
+
+def test_every_constrained_pandas_is_inside_the_plugins_range():
+ plugin = _plugin_pandas_range()
+ for pin in _constraint_pandas_pins():
+ # The lowest version each constraint admits is the one that gets installed.
+ floor = next(s.version for s in pin if s.operator in ("==", ">="))
+ assert plugin.contains(
+ floor
+ ), f"constraints install pandas {floor}, outside the plugin's {plugin}"
+
+
+def test_the_arm64_row_installs_pandas_3():
+ """The row this test exists for: without it the range check would pass on pandas 2 alone."""
+ rows = [
+ l for l in CONSTRAINTS.read_text(encoding = "utf-8").splitlines() if l.startswith("pandas>=3")
+ ]
+ assert len(rows) == 1 and 'platform_machine == "ARM64"' in rows[0]
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 332c7123908..faa1af5a8ec 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -3019,6 +3019,137 @@ class TestPublishedWindowsCudaAttemptsDynamicMajor:
assert result[0].runtime_line == "cuda12"
+class TestPublishedLegacyNamedArm64BundlesAreOrdered:
+ """The legacy-minor ordering synthesised -x64.zip names and called windows_cuda_attempts
+ without the arch, so an approved llama-<tag>-bin-win-cuda-13.1-arm64.zip produced no
+ runtime line and was skipped for the unchecksummed upstream fallback."""
+
+ TAG = "b8508"
+
+ def _release(
+ self,
+ minors_lines,
+ ranks = None,
+ cudart = False,
+ ):
+ artifacts = [
+ make_artifact(
+ f"llama-{self.TAG}-bin-win-cuda-{minor}-arm64.zip",
+ install_kind = "windows-arm64-cuda",
+ runtime_line = line,
+ supported_sms = ["75", "80", "86", "89", "90", "100", "120"],
+ max_sm = 120,
+ rank = (ranks or {}).get(minor, 100),
+ )
+ for minor, line in minors_lines
+ ]
+ release = make_release(artifacts, upstream_tag = self.TAG)
+ if cudart:
+ for minor, _ in minors_lines:
+ name = f"cudart-llama-bin-win-cuda-{minor}-arm64.zip"
+ release.assets[name] = f"https://example.com/{name}"
+ return release
+
+ def _host(self, driver):
+ return make_host(
+ system = "Windows", machine = "ARM64", driver_cuda_version = driver, compute_caps = ["120"]
+ )
+
+ def test_the_arm64_legacy_bundle_is_selected(self, monkeypatch):
+ mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+ release = self._release([("13.1", "cuda13"), ("12.8", "cuda12")])
+ result = published_windows_cuda_attempts(self._host((13, 1)), release, None, arch = "arm64")
+ assert result, "no attempt at all: the arch was lost in the legacy ordering"
+ assert result[0].runtime_line == "cuda13"
+ assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.1-arm64.zip"
+
+ def test_the_minor_gate_applies_to_arm64_too(self, monkeypatch):
+ mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+ release = self._release([("13.3", "cuda13"), ("12.8", "cuda12")])
+ result = published_windows_cuda_attempts(self._host((13, 1)), release, None, arch = "arm64")
+ assert result and result[0].runtime_line == "cuda12"
+ assert all(not a.name.endswith("13.3-arm64.zip") for a in result)
+
+ def test_the_artifact_gate_reads_the_arm64_name(self, monkeypatch):
+ """Two legacy minors on one line, the higher one ranked first: the line survives on
+ the lower minor, and the per-artifact gate must parse the -arm64 name to drop the
+ higher one; an x64 spelling never matches, and the preferred 13.3 build slips through."""
+ mock_windows_runtime(monkeypatch, ["cuda13"])
+ release = self._release([("13.3", "cuda13"), ("13.1", "cuda13")], ranks = {"13.3": 10})
+ result = published_windows_cuda_attempts(self._host((13, 1)), release, None, arch = "arm64")
+ names = [a.name for a in result]
+ assert names == [f"llama-{self.TAG}-bin-win-cuda-13.1-arm64.zip"], names
+
+ def test_the_cudart_bundle_pairs_by_the_arm64_name(self, monkeypatch):
+ """The same match feeds the cudart pairing: the arm64 runtime archive rides along."""
+ mock_windows_runtime(monkeypatch, ["cuda13"])
+ release = self._release([("13.1", "cuda13")], cudart = True)
+ result = published_windows_cuda_attempts(self._host((13, 1)), release, None, arch = "arm64")
+ assert result and result[0].runtime_name == f"cudart-llama-bin-win-cuda-13.1-arm64.zip"
+
+ def test_the_explicit_arch_wins_over_the_host(self, monkeypatch):
+ """The arch argument is the contract: it must reach the legacy ordering rather than
+ being re-derived from the host, or an x64 host resolving arm64 bundles finds none."""
+ mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+ release = self._release([("13.1", "cuda13"), ("12.8", "cuda12")])
+ host = make_host(
+ system = "Windows", machine = "AMD64", driver_cuda_version = (13, 1), compute_caps = ["120"]
+ )
+ result = published_windows_cuda_attempts(host, release, None, arch = "arm64")
+ assert result and result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.1-arm64.zip"
+
+
+class TestAnUpstreamLookupFailureCostsOnlyCuda:
+ """On a Windows ARM64 NVIDIA host with no approved CUDA bundle, the upstream asset list is
+ fetched from the release API. A rate limit or an outage there raised out of the planner,
+ which catches only PrebuiltFallback, so the whole install aborted although the published
+ ARM64 CPU bundle was there to fall through to. It now costs the CUDA bundle only, like the
+ digest fetch beside it."""
+
+ TAG = "b8508"
+ CPU = "app-b8508-windows-arm64-cpu.zip"
+
+ def _plan(self, monkeypatch, assets):
+ mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+ monkeypatch.setattr(
+ INSTALL_LLAMA_PREBUILT,
+ "detect_torch_cuda_runtime_preference",
+ lambda host: CudaRuntimePreference(runtime_line = None, selection_log = []),
+ )
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "github_release_assets", assets)
+ monkeypatch.setattr(
+ INSTALL_LLAMA_PREBUILT, "github_release_asset_digests", lambda repo, tag: {}
+ )
+ monkeypatch.delenv("UNSLOTH_LLAMA_ARM64_CUDA", raising = False)
+ host = make_host(
+ system = "Windows", machine = "ARM64", driver_cuda_version = (13, 4), compute_caps = ["121"]
+ )
+ release = make_release(
+ [
+ make_artifact(
+ self.CPU,
+ install_kind = "windows-arm64",
+ runtime_line = None,
+ bundle_profile = "windows-cpu-arm64",
+ )
+ ],
+ upstream_tag = self.TAG,
+ )
+ return resolve_release_asset_choice(host, self.TAG, release, make_checksums([self.CPU]))
+
+ def test_an_api_failure_falls_through_to_the_cpu_bundle(self, monkeypatch):
+ def _boom(repo, tag):
+ raise RuntimeError("429 rate limited")
+
+ result = self._plan(monkeypatch, _boom)
+ assert [a.name for a in result] == [self.CPU]
+ assert result[0].install_kind == "windows-arm64"
+
+ def test_an_empty_listing_lands_in_the_same_place(self, monkeypatch):
+ result = self._plan(monkeypatch, lambda repo, tag: {})
+ assert [a.name for a in result] == [self.CPU]
+
+
# ===========================================================================
# N.1e. resolve_release_asset_choice -- pin on the published install path
# ===========================================================================
@@ -4288,8 +4419,7 @@ class TestCudaDriverToolkitMismatchMessage:
"exceeds driver CUDA major 12 (12.9)."
) in output
assert (
- "Update the NVIDIA GPU driver to run CUDA Toolkit 13.3, or install "
- "a CUDA 12.x toolkit."
+ "Update the NVIDIA GPU driver to run CUDA Toolkit 13.3, or install a CUDA 12.x toolkit."
) in output
assert "prebuilt CUDA bundle" in output
diff --git a/tests/studio/install/test_windows_torch_flavor_invariant.py b/tests/studio/install/test_windows_torch_flavor_invariant.py
index e04d176b15a..5f7460acf05 100644
--- a/tests/studio/install/test_windows_torch_flavor_invariant.py
+++ b/tests/studio/install/test_windows_torch_flavor_invariant.py
@@ -661,3 +661,41 @@ def test_the_rocm_trio_is_reinstalled_when_the_architecture_index_moves():
# The record follows the install, never precedes it: a failed trio must not be recorded.
failed = text.index("AMD ROCm PyTorch install failed -- falling back to CPU")
assert failed < record
+
+
+class TestSetupPs1WindowsOnArmCudaPreservation:
+ """The win_arm64 CUDA shortcut is for an INFERRED expectation, not a stated one.
+
+ It runs ahead of the pin branch that raises $script:PinChangedForceReinstall, and that
+ flag is the only thing that clears $SkipPythonDeps. So without the exemption an
+ explicit pin skipped the dependency pass, install_python_stack.py and every
+ --force-reinstall at once, and `studio update` kept the old CUDA build while reporting
+ success. Exempting only /cpu was not enough: a user moving the venv to their own
+ cu129 mirror is stating an instruction just as much, and the index selection further
+ down is written to let a pin outrank the persisted NVIDIA channel.
+ """
+
+ _GUARD = "if ((Test-WinArm64Venv) -and $installedTorchTag -and"
+
+ def _condition(self) -> str:
+ start = _SETUP_SRC.index(self._GUARD)
+ return _SETUP_SRC[start : _SETUP_SRC.index("{", start + len(self._GUARD))]
+
+ def test_any_explicit_pin_is_exempt(self):
+ condition = self._condition()
+ assert "-not $_pinnedIdx" in condition
+ assert (
+ "$_woaCpuPinned" not in condition
+ ), "a cu129 mirror pin is as much an instruction as a /cpu one"
+
+ def test_the_exemption_reads_a_variable_that_is_always_assigned(self):
+ # Not $_pinLeaf: it is assigned only inside `if ($_pinnedIdx)`, so reading it here would
+ # be fatal under Set-StrictMode. $_pinnedIdx is assigned unconditionally above.
+ block = _SETUP_SRC[: _SETUP_SRC.index(self._GUARD)]
+ assert "$_pinnedIdx = Get-PinnedTorchIndexUrl" in block
+ assert "$_pinLeaf" not in self._condition()
+
+ def test_it_still_sits_ahead_of_the_pin_branch(self):
+ shortcut = _line_of(_SETUP_SRC, self._GUARD)
+ pin_branch = _line_of(_SETUP_SRC, "Torch-index pin changed ($installedTorchTag)")
+ assert shortcut < pin_branch
diff --git a/tests/studio/install/test_woa_torch_index_persistence.py b/tests/studio/install/test_woa_torch_index_persistence.py
new file mode 100644
index 00000000000..3b8a10bd746
--- /dev/null
+++ b/tests/studio/install/test_woa_torch_index_persistence.py
@@ -0,0 +1,6269 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""What a Windows-on-ARM install has to recover when it is not install.ps1.
+
+install.ps1 hands its resolver decisions to setup.ps1 through process-scoped environment
+variables, and a direct `unsloth studio update` runs in a fresh shell where all of them are
+gone. Windows on ARM is the only platform whose CUDA torch wheels live nowhere on
+download.pytorch.org, so nothing here can be re-derived from the host: the index has to come
+off disk (the manifest and the marker below) and so do the generated requirement overrides
+(TestResolverEnvironmentRestore).
+
+Recording the index at all is a deliberate exception to the rule the manifest documents for
+itself -- the FLAVOR, never the URL it came from, because a pinned index can carry a token in
+its userinfo, query or fragment and this file is printed back by verify-install. The exception
+only holds while the guard does, so both halves are tested: the Python that writes it and the
+PowerShell that reads it back, each of which must refuse independently.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+
+import pytest
+
+from woa_ps_harness import (
+ CONSTRAINTS_SRC,
+ CORP_INDEX,
+ INSTALL_PS1,
+ INSTALL_SRC,
+ INVOKE_RESTMETHOD_NO_NETWORK,
+ INVOKE_RESTMETHOD_OFFLINE,
+ JOIN_URL_PATH,
+ JOIN_URL_RETURNS_BASE,
+ JOIN_URL_RETURNS_PATH,
+ LLAMA_SRC,
+ MANIFEST_PY,
+ MARKER_FUNCS,
+ NV_GA,
+ NV_NIGHTLY,
+ PACKAGE_ROOT,
+ PWSH,
+ PYARROW_FLOOR,
+ PYARROW_USABLE_FUNCS,
+ PYPI,
+ SETUP_PS1,
+ SETUP_SRC,
+ STACK_PY,
+ STACK_SRC,
+ SUBSTEP_NOOP,
+ UV_INDEX_ENV,
+ UV_ONLY_INDEX_ENV,
+ UV_POLICY_ENV,
+ UV_SAFE_PATH,
+ WHEEL_TAG_FUNCS,
+ _function_source,
+ _ps,
+ _ps_copies,
+ _ps_function,
+ _ps_kv,
+ _ps_last,
+ _ps_ok,
+ _script,
+ clear_env,
+ functions,
+ invoke_restmethod,
+ native_probe_script,
+ pyarrow_source_script,
+ requires_pwsh,
+ slice_between,
+ substep_collector,
+)
+
+
+# PowerShell's Join-Path uses the HOST separator, so a hardcoded POSIX home only ever exercises
+# POSIX and fails on Windows. Both sides are built the way the host builds them.
+FAKE_HOME = (
+ "C:\\Users\\u\\AppData\\Local\\unsloth" if os.name == "nt" else "/home/u/AppData/Local/unsloth"
+)
+
+
+def _native_path_value(template: str) -> str:
+ """Fill in the fake home and speak the host's separator, entries and expectations alike."""
+ return template.format(home = FAKE_HOME).replace("/", os.sep)
+
+
+def _load_manifest_module():
+ spec = importlib.util.spec_from_file_location("studio_install_manifest_woa", MANIFEST_PY)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+im = _load_manifest_module()
+
+# TestTheDependencyIndexFollowsTheResolverPolicy shadows PYPI with the --extra-index-url form
+# it expects on a command line, so the bare URL keeps a second name for use inside it.
+PYPI_URL = PYPI
+WORKFLOW = PACKAGE_ROOT / ".github" / "workflows" / "windows-arm64-ci.yml"
+
+
+def _persistence_block(text: str) -> str:
+ """The live `if (...) { ... }` that writes both index records, sliced out rather than
+ restated: a copy of it passes forever after the original stops matching it."""
+ start = text.index("$_woaPinnedIndex = if ($WinArm64Venv)")
+ guard = text.index("if ($WinArm64TorchIndexUrl -or $_woaPinnedIndex) {", start)
+ depth = 0
+ for index in range(text.index("{", guard), len(text)):
+ if text[index] == "{":
+ depth += 1
+ elif text[index] == "}":
+ depth -= 1
+ if depth == 0:
+ return text[start : index + 1]
+ raise AssertionError("unbalanced braces in the persistence block")
+
+
+# (url, may_be_persisted, why)
+CANDIDATES = (
+ (NV_GA, True, "the GA channel install.ps1 probes"),
+ (NV_NIGHTLY + "/", True, "the nightly channel, trailing slash"),
+ ("https://user:[email protected]/nvtorch_oot", False, "userinfo is exactly the leak"),
+ ("https://pypi.nvidia.com/nvtorch_oot?token=abc", False, "a token in the query"),
+ ("https://pypi.nvidia.com/nvtorch_oot#token=abc", False, "a token in the fragment"),
+ ("https://mirror.corp.example/whl", False, "a mirror the user pinned"),
+ ("http://pypi.nvidia.com/nvtorch_oot", False, "plaintext, so not our channel"),
+ ("https://pypi.nvidia.com.evil.example/whl", False, "a host that merely starts the same"),
+ ("https://evilpypi.nvidia.com/whl", False, "a host that merely ends the same"),
+ ("", False, "empty"),
+ (None, False, "absent"),
+)
+
+
+class TestWriteSide:
+ """studio/install_manifest.py: what is allowed into the file at all."""
+
+ @pytest.mark.parametrize("url, allowed, why", CANDIDATES)
+ def test_only_a_credential_free_nvidia_channel_is_recorded(
+ self, tmp_path: pathlib.Path, url, allowed: bool, why: str
+ ):
+ path = im.write_manifest(root = tmp_path, req_root = tmp_path, woa_torch_index = url)
+ assert path is not None
+ payload = json.loads(pathlib.Path(path).read_text(encoding = "utf-8"))
+ recorded = "woa_torch_index" in payload
+ assert recorded is allowed, (
+ f"{url!r} ({why}) was {'dropped' if allowed else 'persisted'}; "
+ "the manifest is printed back by verify-install and read by setup.ps1"
+ )
+ if allowed:
+ assert payload["woa_torch_index"] == str(url).strip().rstrip("/")
+
+ @pytest.mark.parametrize(
+ "url, persisted",
+ [
+ ("HTTPS://PYPI.NVIDIA.COM/nvtorch_oot", NV_GA),
+ ("https://PyPI.nvidia.com/nvtorch_oot_nightly/", NV_NIGHTLY),
+ ("https://pypi.nvidia.com/NVTORCH_oot", "https://pypi.nvidia.com/NVTORCH_oot"),
+ ],
+ )
+ def test_scheme_and_host_case_is_normalised_and_the_path_kept(self, tmp_path, url, persisted):
+ """RFC 3986: scheme and host compare case-insensitively; a path does not."""
+ path = im.write_manifest(root = tmp_path, req_root = tmp_path, woa_torch_index = url)
+ payload = json.loads(pathlib.Path(path).read_text(encoding = "utf-8"))
+ assert payload["woa_torch_index"] == persisted
+
+ def test_the_key_is_absent_when_no_index_was_chosen(self, tmp_path: pathlib.Path):
+ """Every other host, and every WoA host that stayed on the x64 stack."""
+ im.write_manifest(root = tmp_path, req_root = tmp_path)
+ payload = json.loads((tmp_path / im.MANIFEST_NAME).read_text(encoding = "utf-8"))
+ assert "woa_torch_index" not in payload
+
+ def test_the_addition_is_backwards_compatible(self, tmp_path: pathlib.Path):
+ """An additive optional key: older readers see the schema they already parse."""
+ im.write_manifest(root = tmp_path, req_root = tmp_path, woa_torch_index = NV_GA)
+ payload = json.loads((tmp_path / im.MANIFEST_NAME).read_text(encoding = "utf-8"))
+ assert payload["schema"] == 1, "the key is additive; bumping the schema is not"
+ state = im.verify_install(root = tmp_path, req_root = tmp_path)
+ assert state["manifest_ok"] is True, state["reason"]
+
+ def test_the_installer_passes_the_handover_variable_through(self):
+ """install.ps1 exports it; nothing else supplies this value."""
+ assert re.search(
+ r"woa_torch_index\s*=\s*os\.environ\.get\(\s*[\"']UNSLOTH_WOA_SELECTED_TORCH_INDEX[\"']",
+ STACK_SRC,
+ ), "install_python_stack.py no longer forwards the index install.ps1 selected"
+
+
+class TestReadSide:
+ """studio/setup.ps1: what Get-PersistedWoaTorchIndex hands back to the resolver."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize("url, allowed, why", [c for c in CANDIDATES if c[0]])
+ def test_a_hand_edited_manifest_cannot_redirect_the_install(
+ self, tmp_path: pathlib.Path, url: str, allowed: bool, why: str
+ ):
+ """The write guard is not enough on its own: the file sits in the user's venv and
+ anything can put a line in it."""
+ (tmp_path / "unsloth_install_manifest.json").write_text(
+ json.dumps({"schema": 1, "woa_torch_index": url}),
+ encoding = "utf-8",
+ )
+ got = self._invoke(tmp_path)
+ assert got == (
+ url.strip().rstrip("/") if allowed else ""
+ ), f"{url!r} ({why}) came back as {got!r} and would be passed to uv"
+
+ @requires_pwsh
+ def test_a_missing_or_unreadable_manifest_is_empty_not_an_error(self, tmp_path: pathlib.Path):
+ """Older installs have no such key, and a truncated file must not throw."""
+ assert self._invoke(tmp_path) == "", "no manifest at all"
+ path = tmp_path / "unsloth_install_manifest.json"
+ path.write_text('{"schema": 1, "torch_flavor": "cu130"}', encoding = "utf-8")
+ assert self._invoke(tmp_path) == "", "an older manifest without the key"
+ path.write_text('{"schema": 1, "woa_torch_ind', encoding = "utf-8")
+ assert self._invoke(tmp_path) == "", "a manifest truncated by a killed installer"
+ path.write_text("", encoding = "utf-8")
+ assert self._invoke(tmp_path) == "", "an empty manifest"
+
+ @staticmethod
+ def _invoke(venv: pathlib.Path) -> str:
+ body = _function_source(SETUP_SRC, "Get-PersistedWoaTorchIndex")
+ script = f"{body}\nWrite-Output (Get-PersistedWoaTorchIndex -VenvPath '{venv}')"
+ return _ps_ok(script).stdout.strip()
+
+
+class TestResolverEnvironmentRestore:
+ """The other half of what a fresh shell loses.
+
+ install.ps1 writes StudioHome\\woa\\overrides.txt and stages a win_arm64 wheelhouse beside
+ it, then exports both through UV_OVERRIDE / UV_FIND_LINKS / PIP_FIND_LINKS. Those exports
+ are process-scoped, so a direct `unsloth studio update` starts without them -- and the
+ dependency pass resolves `ddgs`, which requires httpx[brotli], which requires Brotli on
+ CPython, which publishes no win_arm64 wheel. Without the overrides the resolver reaches for
+ the sdist and builds a C extension on a host that exists to avoid exactly that.
+ """
+
+ def _invoke(
+ self,
+ tmp_path: pathlib.Path,
+ *,
+ is_woa: bool = True,
+ preset: str = "",
+ ) -> dict:
+ script = _script(
+ substep_collector("Warnings"),
+ f"$StudioHome = '{tmp_path}'",
+ f"function Test-WinArm64Venv {{ ${str(is_woa).lower()} }}",
+ preset,
+ functions(SETUP_SRC, "Get-UvSafePath", "Restore-WoaResolverEnvironment"),
+ "Restore-WoaResolverEnvironment",
+ "[pscustomobject]@{",
+ " ov = $env:UV_OVERRIDE; uvfl = $env:UV_FIND_LINKS; pipfl = $env:PIP_FIND_LINKS",
+ " warned = ($script:Warnings -join ' ')",
+ "} | ConvertTo-Json -Compress",
+ )
+ # The function assigns real environment variables; keep them out of the parent.
+ done = _ps_ok(
+ script,
+ env = {**os.environ, "UV_OVERRIDE": "", "UV_FIND_LINKS": "", "PIP_FIND_LINKS": ""},
+ )
+ return json.loads(done.stdout.strip().splitlines()[-1])
+
+ @staticmethod
+ def _stage(tmp_path: pathlib.Path, *, wheels: bool = True) -> pathlib.Path:
+ woa = tmp_path / "woa"
+ woa.mkdir(parents = True, exist_ok = True)
+ overrides = woa / "overrides.txt"
+ overrides.write_text(
+ "# Generated by install.ps1 for Windows on ARM (win_arm64).\n"
+ 'brotli ; platform_machine == "AMD64"\n'
+ 'brotlicffi ; platform_machine == "AMD64"\n'
+ "torch>=2.4\n",
+ encoding = "utf-8",
+ )
+ if wheels:
+ (woa / "wheels").mkdir(exist_ok = True)
+ return overrides
+
+ @requires_pwsh
+ def test_a_native_venv_gets_its_overrides_back(self, tmp_path: pathlib.Path):
+ overrides = self._stage(tmp_path)
+ got = self._invoke(tmp_path)
+ assert got["ov"] == str(overrides), "the drop list install.ps1 generated"
+ assert got["uvfl"] == str(tmp_path / "woa" / "wheels")
+ assert got["pipfl"] == str(tmp_path / "woa" / "wheels")
+
+ @requires_pwsh
+ def test_no_wheelhouse_still_restores_the_overrides(self, tmp_path: pathlib.Path):
+ """The drops are what stop the brotli sdist; the wheelhouse is a separate favour."""
+ overrides = self._stage(tmp_path, wheels = False)
+ got = self._invoke(tmp_path)
+ assert got["ov"] == str(overrides)
+ assert not got["uvfl"] and not got["pipfl"]
+
+ @requires_pwsh
+ def test_every_other_host_is_untouched(self, tmp_path: pathlib.Path):
+ """An x64 venv resolves brotli from a win_amd64 wheel, as it always has."""
+ self._stage(tmp_path)
+ got = self._invoke(tmp_path, is_woa = False)
+ assert not got["ov"] and not got["uvfl"] and not got["pipfl"]
+ assert not got["warned"], "and it says nothing about a platform it is not on"
+
+ @requires_pwsh
+ def test_a_caller_that_already_set_them_keeps_their_file(self, tmp_path: pathlib.Path):
+ """The caller's own override file is never dropped."""
+ overrides = self._stage(tmp_path)
+ got = self._invoke(tmp_path, preset = "$env:UV_OVERRIDE = 'C:\\caller\\ov.txt'")
+ assert "C:\\caller\\ov.txt" in got["ov"], "the caller's file survives"
+ assert str(overrides) in got["ov"], "and ours is there too"
+
+ @requires_pwsh
+ @pytest.mark.parametrize("held", ["UV_FIND_LINKS", "PIP_FIND_LINKS"])
+ def test_an_unrelated_find_links_does_not_cost_the_exclusions(
+ self, tmp_path: pathlib.Path, held: str
+ ):
+ """The three are restored independently."""
+ overrides = self._stage(tmp_path)
+ got = self._invoke(tmp_path, preset = f"$env:{held} = 'https://mirror.example/whl'")
+ assert got["ov"] == str(overrides), f"{held} is unrelated to the overrides"
+ # Ours is PREPENDED rather than skipped, and the caller's entry still has to survive.
+ value = got[{"UV_FIND_LINKS": "uvfl", "PIP_FIND_LINKS": "pipfl"}[held]]
+ assert "https://mirror.example/whl" in value, "the caller's own value survives"
+ assert value.endswith("https://mirror.example/whl"), "and ours goes in front of it"
+
+ @requires_pwsh
+ def test_a_deleted_overrides_file_says_so_rather_than_guessing(self, tmp_path: pathlib.Path):
+ """Which packages were dropped depends on what the wheelhouse turned out to hold."""
+ (tmp_path / "woa").mkdir()
+ got = self._invoke(tmp_path)
+ assert not got["ov"]
+ assert "missing" in got["warned"] and "install.ps1" in got["warned"]
+
+ def test_the_helper_is_a_faithful_copy_of_install_ps1s(self):
+ """Get-UvSafePath exists in both scripts because neither can dot-source the other."""
+ install, setup = _ps_copies("Get-UvSafePath")
+ assert install == setup
+
+ def test_the_dependency_that_makes_this_necessary_is_still_there(self):
+ """If studio.txt ever drops ddgs, this restore stops being load-bearing for brotli."""
+ studio_txt = PACKAGE_ROOT / "studio" / "backend" / "requirements" / "studio.txt"
+ assert "ddgs" in studio_txt.read_text(encoding = "utf-8")
+
+ def test_the_restore_runs_before_the_dependency_pass(self):
+ """After it, the brotli resolve has already been attempted."""
+ restore = SETUP_SRC.index("\nRestore-WoaResolverEnvironment")
+ stack = SETUP_SRC.index('python "$PSScriptRoot\\install_python_stack.py"')
+ assert restore < stack
+
+
+class TestTheRecoveryReachesEveryModeThatNeedsIt:
+ """Placement, which is what decided whether the two recoveries above fire at all."""
+
+ @staticmethod
+ def _enclosing_blocks(text: str, needle: str) -> list:
+ """The `{`-opening lines still unclosed where `needle` appears."""
+ target = text.index(needle)
+ stack = []
+ for index, char in enumerate(text[:target]):
+ if char == "{":
+ stack.append(text.rfind("\n", 0, index) + 1)
+ elif char == "}" and stack:
+ stack.pop()
+ return [text[start : text.index("\n", start)].strip() for start in stack]
+
+ def test_the_restore_is_not_trapped_in_the_no_torch_guard(self):
+ blocks = self._enclosing_blocks(SETUP_SRC, "\nRestore-WoaResolverEnvironment")
+ assert not any("NoTorchMode" in b for b in blocks), (
+ "UNSLOTH_NO_TORCH=1 still installs studio.txt, and ddgs -> httpx[brotli] -> "
+ f"Brotli has no win_arm64 wheel. Enclosing blocks: {blocks}"
+ )
+
+ def test_the_index_re_export_is_not_trapped_either(self):
+ blocks = self._enclosing_blocks(
+ SETUP_SRC, "$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex"
+ )
+ assert not any(
+ "NoTorchMode" in b for b in blocks
+ ), f"the manifest is rewritten in no-torch mode too. Enclosing blocks: {blocks}"
+
+ def test_the_recovered_index_is_put_back_in_the_environment(self):
+ """The bug this guards: recovering the index into a local variable only."""
+ assign = SETUP_SRC.index("$WinArm64TorchIndexUrl = if (")
+ export = SETUP_SRC.index("$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex")
+ stack = SETUP_SRC.index('python "$PSScriptRoot\\install_python_stack.py"')
+ assert assign < export < stack, "recovered, re-exported, then read by the stack"
+ block = SETUP_SRC.rindex("if ($WinArm64TorchIndexUrl -or $_woaPinnedIndex) {", 0, export)
+ assert (
+ "$_woaMarkerIndex = $_woaPinnedIndex" in SETUP_SRC[block:export]
+ ), "guarded: neither record present must not export an empty value"
+
+ def test_studio_txt_is_installed_in_no_torch_mode(self):
+ """The premise of the placement test above.
+
+ The step sits behind _skip_step, which asks whether the file is ALREADY satisfied --
+ a cache gate, not a mode gate. Anything reading NO_TORCH or the platform here would
+ mean a no-torch venv never installs studio.txt, and the recovery above would be
+ guarding a step that never runs.
+ """
+ call = STACK_SRC.index('req = REQ_ROOT / "studio.txt"')
+ gate_line = STACK_SRC.rindex("\n", 0, STACK_SRC.rindex("pip_install(", 0, call)) + 1
+ gate = STACK_SRC[STACK_SRC.rindex("\n", 0, gate_line - 1) + 1 : gate_line]
+ assert '_skip_step(REQ_ROOT / "studio.txt"' in gate, gate
+ assert "NO_TORCH" not in gate and "IS_WINDOWS" not in gate, gate
+ indent = len(gate) - len(gate.lstrip())
+ assert indent == 4, "the studio.txt step moved inside another branch"
+ skip_list = STACK_SRC[STACK_SRC.index("NO_TORCH_SKIP_PACKAGES = {") :][:400]
+ assert "ddgs" not in skip_list, "ddgs is still installed when NO_TORCH is set"
+
+
+class TestTheRecoveryHappensWhileThereIsStillSomethingToRead:
+ """Ordering against the manifest drop, which decides whether any of this works."""
+
+ def test_the_index_is_read_before_the_manifest_is_deleted(self):
+ read = SETUP_SRC.index("Get-PersistedWoaTorchIndex -VenvPath $VenvDir")
+ drop = SETUP_SRC.index("install_manifest.remove_manifest()")
+ assert read < drop, (
+ "the recovery reads unsloth_install_manifest.json; after the drop there is "
+ "nothing left to read and the fresh-shell path silently gets no index"
+ )
+
+ def test_both_still_sit_inside_the_dependency_guard(self):
+ """No point recovering for a run that installs nothing."""
+ guard = SETUP_SRC.index("if (-not $SkipPythonDeps) {")
+ read = SETUP_SRC.index("Get-PersistedWoaTorchIndex -VenvPath $VenvDir")
+ restore = SETUP_SRC.index("\nRestore-WoaResolverEnvironment")
+ assert guard < read and guard < restore
+
+
+class TestThePublishedIndexIsTheOneTorchCameFrom:
+ """What install_python_stack.py is told to repair from."""
+
+ def test_the_publish_block_reads_the_effective_index(self):
+ assert "$_expectedLeaf = Get-TorchIndexLeaf $_effectiveTorchIndexUrl" in SETUP_SRC
+ assert "$env:UNSLOTH_TORCH_INSTALL_INDEX_URL = $_effectiveTorchIndexUrl" in SETUP_SRC
+
+ def test_it_defaults_to_the_old_value_and_only_torch_moves_it(self):
+ """Every non-CUDA path must publish exactly what it published before."""
+ default = SETUP_SRC.index("$_effectiveTorchIndexUrl = $TorchInstallIndexUrl")
+ assign = SETUP_SRC.index("$_effectiveTorchIndexUrl = $_cudaIndexUrl")
+ publish = SETUP_SRC.index("$_expectedLeaf = Get-TorchIndexLeaf $_effectiveTorchIndexUrl")
+ assert default < assign < publish, "default, then the install, then the publish"
+ assert (
+ SETUP_SRC.count("$_effectiveTorchIndexUrl = ") == 2
+ ), "only the CUDA install may move it"
+
+ def test_the_nvidia_channel_publishes_no_flavor_tag(self):
+ """Get-TorchIndexLeaf on the NVIDIA channel yields `nvtorch_oot`, which is not a CUDA
+ family name, so the tag resolves to $null and nothing is published."""
+ if PWSH is None:
+ pytest.skip("pwsh not available")
+ script = _script(
+ functions(SETUP_SRC, "Get-TorchIndexLeaf", "Test-CudaFamilyLeaf"),
+ f"$leaf = Get-TorchIndexLeaf '{NV_GA}'",
+ 'Write-Output "$leaf|$(Test-CudaFamilyLeaf $leaf)"',
+ )
+ leaf, is_cuda = _ps_last(script).split("|")
+ assert leaf == "nvtorch_oot"
+ assert is_cuda == "False", "a CUDA family leaf here would publish a wrong flavor"
+
+
+class TestTheLlamaArm64CudaOptOut:
+ """UNSLOTH_LLAMA_ARM64_CUDA=0, honoured on every path that can reach the branch."""
+
+ @staticmethod
+ def _arm64_nvidia_branches() -> list:
+ """Every `if ...has_usable_nvidia...` whose enclosing branches select ARM64."""
+ import ast
+
+ tree = ast.parse(LLAMA_SRC)
+ found = []
+
+ def uses(node, name: str) -> bool:
+ return any(isinstance(n, ast.Attribute) and n.attr == name for n in ast.walk(node))
+
+ def uses_positively(node, name: str) -> bool:
+ """`not host.has_usable_nvidia` selects the CPU path and is not our business."""
+ negated = {
+ id(n.operand)
+ for n in ast.walk(node)
+ if isinstance(n, ast.UnaryOp) and isinstance(n.op, ast.Not)
+ }
+ return any(
+ isinstance(n, ast.Attribute) and n.attr == name and id(n) not in negated
+ for n in ast.walk(node)
+ )
+
+ def visit(node, arm64: bool):
+ if isinstance(node, ast.If):
+ # `elif` is an If inside orelse, so each one re-decides for itself.
+ here = arm64 or (
+ uses(node.test, "is_arm64")
+ and not uses(node.test, "is_linux")
+ and not uses(node.test, "is_macos")
+ )
+ if here and uses_positively(node.test, "has_usable_nvidia"):
+ found.append((node.lineno, ast.unparse(node.test)))
+ for stmt in node.body:
+ visit(stmt, here)
+ for stmt in node.orelse:
+ visit(stmt, arm64)
+ return
+ for child in ast.iter_child_nodes(node):
+ visit(child, arm64)
+
+ visit(tree, False)
+ return found
+
+ def test_every_arm64_cuda_branch_is_gated(self):
+ """Three entry points reach ARM64 CUDA independently: direct_upstream_release_plan,
+ resolve_upstream_asset_choice, and resolve_asset_choice's published-artifact branch."""
+ branches = self._arm64_nvidia_branches()
+ assert len(branches) >= 3, branches
+ ungated = [b for b in branches if "_upstream_arm64_cuda_allowed" not in b[1]]
+ assert not ungated, f"ungated ARM64 CUDA branch(es): {ungated}"
+
+ def test_the_x64_paths_are_not_gated_by_the_arm64_opt_out(self):
+ """The negative control: this flag must not disable CUDA on ordinary hardware."""
+ import ast
+
+ tree = ast.parse(LLAMA_SRC)
+ arm64_lines = {line for line, _ in self._arm64_nvidia_branches()}
+ for node in ast.walk(tree):
+ if isinstance(node, ast.If) and node.lineno not in arm64_lines:
+ test = ast.unparse(node.test)
+ if "has_usable_nvidia" in test:
+ assert "_upstream_arm64_cuda_allowed" not in test, test
+
+ def test_the_published_artifact_branch_is_gated_too(self):
+ """The published windows-arm64-cuda branch returns before the unverified-upstream tail,
+ so gating only the tail meant the opt-out worked right up until the fork published an
+ approved artifact, then silently stopped."""
+ start = LLAMA_SRC.index("def resolve_asset_choice(")
+ body = LLAMA_SRC[start:]
+ marker = body.index("host.is_windows and host.is_arm64")
+ branch = body[marker : marker + 4000]
+ gate = branch.index("if host.has_usable_nvidia")
+ published = branch.index("published_windows_cuda_attempts(")
+ assert "_upstream_arm64_cuda_allowed()" in branch[gate : gate + 120]
+ assert gate < published, "the gate must precede the published lookup"
+
+ def test_the_now_unreachable_inner_check_is_gone(self):
+ """With the branch gated, a second test inside it could only ever be true."""
+ start = LLAMA_SRC.index("def resolve_asset_choice(")
+ assert "if _upstream_arm64_cuda_allowed():" not in LLAMA_SRC[start:]
+
+ def test_the_docstring_matches_the_scope(self):
+ """The helper documented itself as upstream-only; it now gates every bundle."""
+ start = LLAMA_SRC.index("def _upstream_arm64_cuda_allowed(")
+ doc = LLAMA_SRC[start : LLAMA_SRC.index('"""', LLAMA_SRC.index('"""', start) + 3)]
+ assert "published or upstream" in doc
+
+ def test_the_upstream_resolver_branch_specifically(self):
+ start = LLAMA_SRC.index("def resolve_upstream_asset_choice(")
+ end = LLAMA_SRC.index("\ndef ", start + 10)
+ body = LLAMA_SRC[start:end]
+ marker = body.index("if host.is_windows and host.is_arm64:")
+ arm64_block = body[marker : marker + 900]
+ assert (
+ "_upstream_arm64_cuda_allowed()" in arm64_block
+ ), "the Windows ARM64 CUDA branch of resolve_upstream_asset_choice is ungated"
+
+
+class TestAMigratedX64VenvIsRebuiltAsArm64:
+ """install.ps1: an upgrade must not leave a WoA NVIDIA host on the emulated stack."""
+
+ REBUILD = "$script:WoaNativeCudaTorch -and $_Migrated"
+
+ def _rebuild_block(self) -> str:
+ return INSTALL_SRC[INSTALL_SRC.index(self.REBUILD) :][:1800]
+
+ def test_the_rebuild_runs_before_venv_creation(self):
+ """It works by making $VenvPython absent, so the existing creation block builds an
+ ARM64 venv."""
+ rebuild = INSTALL_SRC.index(self.REBUILD)
+ create = INSTALL_SRC.index("if (-not (Test-Path -LiteralPath $VenvPython)) {")
+ assert rebuild < create
+
+ def test_it_preserves_the_old_environment(self):
+ """Same rollback the new-layout branch uses; the user's packages are recoverable."""
+ assert "Start-StudioVenvRollback -ExistingDir $VenvDir" in self._rebuild_block()
+
+ def test_a_failed_rollback_keeps_the_old_behaviour(self):
+ """Losing the user's environment is never worth a native stack."""
+ block = self._rebuild_block()
+ assert "} catch {" in block
+ assert "using the x64 stack instead" in block
+
+ def test_the_rebuild_clears_the_migrated_flag(self):
+ """The regression that would otherwise follow: $_Migrated drives an upgrade-in-place far
+ below, which installs unsloth with --no-deps and --reinstall-package."""
+ block = self._rebuild_block()
+ rollback = block.index("Start-StudioVenvRollback")
+ cleared = block.index("$_Migrated = $false")
+ assert rollback < cleared, "cleared only after the environment is safely moved"
+ # And the flag really does still gate that path.
+ assert "if ($_Migrated) {" in INSTALL_SRC
+
+ def test_it_only_touches_a_venv_this_run_migrated(self):
+ """A new-layout venv was already moved aside above, and a venv created moments ago came
+ from the interpreter this run chose."""
+ line = INSTALL_SRC[INSTALL_SRC.index(f"if ({self.REBUILD}") :].split("\n")[0]
+ assert "$_Migrated" in line
+ assert "Test-Path -LiteralPath $VenvPython" in line
+
+ def test_the_platform_guard_below_still_has_the_final_say(self):
+ """Belt and braces: if the rollback failed the venv is still x64, and the existing guard
+ must disable native mode rather than install win_arm64-only specs into it."""
+ rebuild = INSTALL_SRC.index(self.REBUILD)
+ guard = INSTALL_SRC.index('if ($_woaVenvPlatform -ne "win-arm64") {')
+ assert rebuild < guard
+ block = INSTALL_SRC[guard:][:600]
+ assert "$script:WoaNativeCudaTorch = $false" in block
+ assert "$script:WoaTorchIndexUrl = $null" in block
+
+
+# The live `if`/`else` that decides which llama.cpp bundles the mismatch check will accept.
+OPT_OUT_KINDS = slice_between(
+ SETUP_SRC,
+ "$_arm64CudaOptOut =",
+ '} else { @("windows-cuda", "windows-vulkan") }',
+ include_end = True,
+).strip()
+
+CUDA = "windows-arm64-cuda,windows-arm64,windows-vulkan"
+NO_CUDA = "windows-arm64,windows-vulkan"
+
+
+class TestTheOptOutBundleSurvivesTheKindCheck:
+ """setup.ps1's mismatch check must expect the bundle the selector actually installs."""
+
+ @staticmethod
+ def _kinds(
+ value: str,
+ *,
+ arm64: bool = True,
+ separator: str = ",",
+ ) -> str:
+ script = _script(
+ f"function Test-WinArm64Venv {{ ${str(arm64).lower()} }}",
+ OPT_OUT_KINDS,
+ f"Write-Output ($_nvidiaKinds -join '{separator}')",
+ )
+ return _ps_last(script, env = {**os.environ, "UNSLOTH_LLAMA_ARM64_CUDA": value})
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "value, expected",
+ [
+ # Not opted out: CUDA is preferred, and the CPU fallback bundle is valid too.
+ ("", CUDA),
+ ("1", CUDA),
+ ("true", CUDA),
+ ("0", NO_CUDA),
+ ("false", NO_CUDA),
+ ("no", NO_CUDA),
+ ("off", NO_CUDA),
+ ("OFF", NO_CUDA),
+ (" 0 ", NO_CUDA),
+ ],
+ )
+ def test_the_expected_kind_follows_the_opt_out(self, value: str, expected: str):
+ assert self._kinds(value) == expected
+
+ @requires_pwsh
+ def test_an_x64_venv_is_unaffected_by_the_flag(self):
+ """The flag is ARM64-only; an emulated x64 venv installs windows-cuda regardless."""
+ for value in ("", "0"):
+ assert self._kinds(value, arm64 = False) == "windows-cuda,windows-vulkan"
+
+ @requires_pwsh
+ def test_the_opt_out_arm_stays_exclusive(self):
+ """A CUDA bundle installed before the flag was set must still be replaced by the one the
+ flag asks for, so the opt-out arm expects the CPU kind INSTEAD of the CUDA kind."""
+ assert (
+ self._kinds("0", separator = " ") == "windows-arm64 windows-vulkan"
+ ), "opted out: CUDA is no longer valid"
+ assert self._kinds("", separator = " ") == "windows-arm64-cuda windows-arm64 windows-vulkan"
+
+ def test_the_cpu_fallback_is_a_real_selector_outcome(self):
+ """The premise of widening: resolve_asset_choice falls through to the published
+ windows-arm64 bundle when no ARM64 CUDA asset is available on an NVIDIA host."""
+ start = LLAMA_SRC.index("def resolve_asset_choice(")
+ body = LLAMA_SRC[start:]
+ marker = body.index("host.is_windows and host.is_arm64")
+ assert (
+ 'published_asset_choice_for_kind(release, "windows-arm64")'
+ in body[marker : marker + 5200]
+ )
+
+ def test_widening_does_not_strand_anyone_on_cpu(self):
+ """The installer's already-satisfied short-circuit is per candidate, and CUDA is
+ attempted first, so a CPU bundle accepted here is still replaced the day an ARM64 CUDA
+ asset appears."""
+ raise_at = LLAMA_SRC.index("raise ExistingInstallSatisfied(attempt, tried_fallback)")
+ window = LLAMA_SRC[max(0, raise_at - 1200) : raise_at]
+ assert (
+ "choice = attempt" in window
+ ), "the reuse check is per attempt; a plan-level one would pin the user to CPU"
+
+ def test_the_falsy_spellings_match_the_python_helper(self):
+ """One vocabulary; the two must not drift apart."""
+ start = LLAMA_SRC.index("def _upstream_arm64_cuda_allowed(")
+ body = LLAMA_SRC[start : LLAMA_SRC.index("\ndef ", start + 10)]
+ python_set = set(re.findall(r'"(0|false|no|off)"', body))
+ ps_line = SETUP_SRC[SETUP_SRC.index("$_arm64CudaOptOut =") :].split("\n")[0]
+ ps_set = set(re.findall(r'"(0|false|no|off)"', ps_line))
+ assert python_set == ps_set == {"0", "false", "no", "off"}
+
+
+# The CUDA wheel scan, with the tag matcher it calls. Driven against synthetic PEP 503 pages
+# with Invoke-RestMethod stubbed, so these are offline and deterministic; the live NVIDIA
+# channels are exercised separately in temp/sim10282/probe_test.ps1.
+CUDA_PROBE_FUNCS = _script(
+ WHEEL_TAG_FUNCS, _function_source(INSTALL_SRC, "Get-WoaCudaWheelVersion")
+)
+
+
+def _wheel_links(*names: str) -> str:
+ """A PEP 503 index page listing exactly these wheels."""
+ return " ".join(f'<a href="{name}">t</a>' for name in names)
+
+
+def _torch_links(
+ *versions: str,
+ py: str = "cp313",
+ abi: str = "cp313",
+) -> str:
+ return _wheel_links(*(f"torch-{v}-{py}-{abi}-win_arm64.whl" for v in versions))
+
+
+class TestTheCudaWheelProbeIsNotFooled:
+ """install.ps1: what the probe accepts as proof of a win_arm64 CUDA wheel."""
+
+ @staticmethod
+ def _probe(
+ body: str,
+ project: str = "torch",
+ minor: str = "3.13",
+ ) -> str:
+ script = _script(
+ JOIN_URL_PATH,
+ invoke_restmethod(body),
+ CUDA_PROBE_FUNCS,
+ f"$v = Get-WoaCudaWheelVersion -IndexUrl 'https://x.test/i' -PythonMinor '{minor}'"
+ f" -Project '{project}'",
+ 'Write-Output "[$v]"',
+ )
+ return _ps_last(script)[1:-1]
+
+ @requires_pwsh
+ def test_a_percent_encoded_cpu_wheel_is_rejected(self):
+ """PEP 503 hrefs encode `+` as %2B. Matching a literal `\\+cpu` never fired on the
+ encoded spelling, so a CPU-only mirror read as CUDA and the host went native on CPU
+ torch -- worse than staying emulated, because the GPU then goes unused."""
+ assert self._probe(_torch_links("2.14.0%2Bcpu")) == ""
+
+ @requires_pwsh
+ def test_an_untagged_wheel_is_rejected(self):
+ """PyPI's own win_arm64 torch wheels carry no local version at all."""
+ assert self._probe(_torch_links("2.14.0")) == ""
+
+ @requires_pwsh
+ @pytest.mark.parametrize("spelling", ["2.14.0%2Bcu134", "2.14.0+cu134"])
+ def test_both_spellings_of_a_cuda_wheel_are_accepted(self, spelling: str):
+ assert self._probe(_torch_links(spelling)) == "2.14.0+cu134"
+
+ @requires_pwsh
+ def test_the_interpreter_tag_still_has_to_match(self):
+ body = _torch_links("2.14.0%2Bcu134", py = "cp311", abi = "cp311")
+ assert self._probe(body, minor = "3.13") == ""
+ assert self._probe(body, minor = "3.11") == "2.14.0+cu134"
+
+ @requires_pwsh
+ def test_the_platform_still_has_to_match(self):
+ body = '<a href="torch-2.14.0%2Bcu134-cp313-cp313-win_amd64.whl">t</a>'
+ assert self._probe(body) == ""
+
+ @requires_pwsh
+ def test_the_newest_release_wins(self):
+ body = _torch_links("2.9.0%2Bcu134", "2.14.0%2Bcu134", "2.11.0%2Bcu134")
+ assert self._probe(body) == "2.14.0+cu134"
+
+ @requires_pwsh
+ def test_a_dev_stamp_does_not_look_older_than_a_release(self):
+ """2.15.0.dev... is newer than 2.14.0; a plain string sort would disagree."""
+ body = _torch_links("2.14.0%2Bcu134", "2.15.0.dev20260819%2Bcu134")
+ assert self._probe(body) == "2.15.0.dev20260819+cu134"
+
+ @requires_pwsh
+ def test_the_newest_dev_stamp_of_one_release_wins(self):
+ body = _torch_links("2.15.0.dev20260819%2Bcu134", "2.15.0.dev20260728%2Bcu134")
+ assert self._probe(body) == "2.15.0.dev20260819+cu134"
+
+ @requires_pwsh
+ def test_an_empty_or_broken_page_is_not_a_wheel(self):
+ assert self._probe("") == ""
+ assert self._probe("<html><body>nothing here</body></html>") == ""
+
+
+class TestTorchaudioIsOnlyTakenAsAMatchedPair:
+ """The GA channel publishes torch 2.14.0+cu134 beside torchaudio 2.11.0+cu134."""
+
+ @staticmethod
+ def _match(torch_v: str, audio_v: str) -> bool:
+ script = _script(
+ _ps_function(INSTALL_PS1, "Test-WoaAudioMatchesTorch"),
+ f"Write-Output (Test-WoaAudioMatchesTorch -TorchVersion '{torch_v}'"
+ f" -AudioVersion '{audio_v}')",
+ )
+ return _ps_last(script) == "True"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "torch_v, audio_v, expected, why",
+ [
+ ("2.14.0+cu134", "2.11.0+cu134", False, "the pair the GA channel serves today"),
+ ("2.14.0+cu134", "2.14.0+cu134", True, "what a matched channel would serve"),
+ ("2.14.0+cu134", "2.14.1+cu134", True, "patch releases pair"),
+ ("2.15.0.dev20260819+cu134", "2.11.0.dev20260819+cu134", False, "nightly, mismatched"),
+ ("2.15.0.dev20260819+cu134", "2.15.0.dev20260728+cu134", True, "nightly, same minor"),
+ ("2.14.0+cu134", "", False, "no audio wheel at all"),
+ ("", "2.14.0+cu134", False, "no torch wheel at all"),
+ ],
+ )
+ def test_only_a_matching_major_minor_enables_audio(
+ self, torch_v: str, audio_v: str, expected: bool, why: str
+ ):
+ assert self._match(torch_v, audio_v) is expected, why
+
+ def test_the_probe_compares_versions_rather_than_existence(self):
+ # rindex, not index: the first occurrence is the reset at the top of the probe.
+ block = INSTALL_SRC[INSTALL_SRC.rindex("$script:WoaTorchAudio = ") :][:400]
+ assert "Test-WoaAudioMatchesTorch" in block, (
+ "torchaudio was enabled on existence alone, which is how the mismatched "
+ "GA pair became installable"
+ )
+
+
+# The live `if` that builds the resolver flags for the WoA torch install.
+INDEX_ARGS_BLOCK = slice_between(
+ SETUP_SRC, "$WinArm64IndexArgs = if (", "} else { @() }", include_end = True
+)
+
+
+class TestPrereleasesAreOnlyForTheNightlyChannel:
+ """setup.ps1 must gate --prerelease=allow the way install.ps1 already does. The URL spelling
+ is the SECOND signal now: install.ps1 reads the answer off the wheel it probed and hands it
+ over, because a mirror of a prerelease-only channel need not say "nightly"."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "index, handover, expect_pre",
+ [
+ (NV_GA, "0", False),
+ (NV_NIGHTLY, "0", True),
+ ("", "0", False),
+ ("https://mirror.test/simple", "1", True),
+ ("https://mirror.test/simple", "0", False),
+ ],
+ )
+ def test_the_flag_follows_the_channel(self, index: str, handover: str, expect_pre: bool):
+ script = _script(
+ "$WinArm64Venv = $true",
+ "$UseUv = $true",
+ f"$WinArm64TorchIndexUrl = '{index}'",
+ f"$WinArm64EffectiveTorchIndexUrl = '{index}'",
+ f"$WinArm64HandoffApplies = ${bool(index)}",
+ f"$env:UNSLOTH_WOA_TORCH_PRERELEASE = '{handover}'",
+ INDEX_ARGS_BLOCK,
+ "Write-Output ($WinArm64IndexArgs -join ' ')",
+ )
+ out = _ps_last(script)
+ assert ("--prerelease=allow" in out) is expect_pre, out
+ assert "unsafe-best-match" in out, "the other flags are unconditional"
+
+ @requires_pwsh
+ def test_every_other_host_gets_no_flags_at_all(self):
+ script = _script(
+ "$WinArm64Venv = $false",
+ "$UseUv = $true",
+ f"$WinArm64TorchIndexUrl = '{NV_NIGHTLY}'",
+ "$WinArm64EffectiveTorchIndexUrl = $WinArm64TorchIndexUrl",
+ "$WinArm64HandoffApplies = $false",
+ INDEX_ARGS_BLOCK,
+ "Write-Output \"[$($WinArm64IndexArgs -join ' ')]\"",
+ )
+ assert _ps_last(script) == "[]"
+
+ def test_both_scripts_gate_on_the_same_thing(self):
+ """One rule; two files. Drift here is invisible until a resolve goes wrong."""
+ for path in (INSTALL_PS1, SETUP_PS1):
+ text = path.read_text(encoding = "utf-8")
+ assert re.search(r"-match 'nightly'", text), f"{path.name} lost the gate"
+ for line in text.splitlines():
+ if "--prerelease=allow" not in line or "#" in line.split("--prerelease")[0]:
+ continue
+ # Producing the flag is what has to stay behind the gate, so only an @(...)
+ # will do. Comparing against it does not produce it: that is
+ # Remove-UvOnlyResolverFlags translating an argument the gate already allowed
+ # into pip's spelling, and it runs after the decision, not instead of it.
+ if "-eq '--prerelease=allow'" in line:
+ continue
+ assert "@(" in line, f"{path.name}: unexpected shape: {line.strip()}"
+
+
+class TestManifestWriterAndReaderAcceptTheSameSet:
+ """A value the writer persists and the reader refuses is worse than none at all."""
+
+ PORTED = "https://pypi.nvidia.com:443/nvtorch_oot"
+
+ def test_the_writer_refuses_a_url_the_reader_cannot_read(self, tmp_path: pathlib.Path):
+ im.write_manifest(root = tmp_path, req_root = tmp_path, woa_torch_index = self.PORTED)
+ payload = json.loads((tmp_path / im.MANIFEST_NAME).read_text(encoding = "utf-8"))
+ assert "woa_torch_index" not in payload
+
+ @requires_pwsh
+ def test_and_the_reader_still_refuses_it(self, tmp_path: pathlib.Path):
+ (tmp_path / "unsloth_install_manifest.json").write_text(
+ json.dumps({"schema": 1, "woa_torch_index": self.PORTED}),
+ encoding = "utf-8",
+ )
+ assert TestReadSide._invoke(tmp_path) == ""
+
+ @requires_pwsh
+ @pytest.mark.parametrize("url", [NV_GA, NV_NIGHTLY])
+ def test_the_two_agree_on_what_is_acceptable(self, tmp_path: pathlib.Path, url: str):
+ """The pair that matters: written, then read back unchanged."""
+ written = tmp_path / "w"
+ written.mkdir()
+ im.write_manifest(root = written, req_root = written, woa_torch_index = url)
+ payload = json.loads((written / im.MANIFEST_NAME).read_text(encoding = "utf-8"))
+ assert payload["woa_torch_index"] == url
+ assert TestReadSide._invoke(written) == url
+
+
+class TestTheSuppliedPyarrowWheelIsValidated:
+ """install.ps1: UNSLOTH_PYARROW_WHEEL decides whether the native path is taken."""
+
+ # A REAL archive: a PK header proves nothing about an interrupted download.
+ ZIP = "zip"
+ HEADER_ONLY = b"PK\x03\x04" + b"\0" * 64
+
+ @staticmethod
+ def _write(path: pathlib.Path, content) -> None:
+ if content == "zip":
+ import zipfile
+ with zipfile.ZipFile(path, "w") as zf:
+ zf.writestr("pyarrow/__init__.py", "")
+ else:
+ path.write_bytes(content)
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "name, content, expected, why",
+ [
+ ("pyarrow-21.0.0-cp313-cp313-win_arm64.whl", ZIP, "local", "the wheel this is for"),
+ ("pyarrow-21.0.0-cp312-cp312-win_arm64.whl", ZIP, "", "another interpreter minor"),
+ ("pyarrow-21.0.0-cp313-cp313-win_amd64.whl", ZIP, "", "an x64 wheel"),
+ ("pyarrow-21.0.0-cp313-cp313-win_arm64.whl", b"not a zip", "", "a truncated download"),
+ (
+ "pyarrow-21.0.0-cp313-cp313-win_arm64.whl",
+ HEADER_ONLY,
+ "",
+ "an interrupted one that still carries the PK signature",
+ ),
+ ("numpy-2.0.0-cp313-cp313-win_arm64.whl", ZIP, "", "a wheel for another project"),
+ ("pyarrow-21.0.0.tar.gz", ZIP, "", "an sdist, which cannot be staged"),
+ ],
+ )
+ def test_only_a_matching_readable_wheel_selects_native(
+ self, tmp_path: pathlib.Path, name: str, content, expected: str, why: str
+ ):
+ wheel = tmp_path / name
+ self._write(wheel, content)
+ assert self._probe(str(wheel)) == expected, why
+
+ @requires_pwsh
+ def test_a_missing_file_is_ignored_rather_than_fatal(self, tmp_path: pathlib.Path):
+ assert self._probe(str(tmp_path / "nope.whl")) == ""
+
+ @staticmethod
+ def _probe(wheel: str) -> str:
+ """Get-WoaPyarrowSource with its network branches stubbed out."""
+ return _ps_last(
+ pyarrow_source_script(
+ wheelhouse = "'https://example.test/wheels'",
+ preamble = (f"$env:UNSLOTH_PYARROW_WHEEL = '{wheel}'",),
+ )
+ )[1:-1]
+
+
+class TestCallerResolverConfigurationSurvives:
+ """install.ps1 must not discard what its own purge block just chose to keep."""
+
+ def test_the_overrides_are_kept_or_folded_never_dropped(self):
+ block = INSTALL_SRC[INSTALL_SRC.index("$_woaOwnNames = @{}") :][:3200]
+ assert "$env:UV_OVERRIDE -split" in block, "the caller's files are read"
+ assert "$_woaKeepFiles += $_woaOvFull" in block, (
+ "a file that names none of our packages is passed to uv where it is, which "
+ "keeps its relative -r and wheel paths resolving"
+ )
+ assert (
+ "$_woaSessionLines += (Resolve-WoaOverrideLine" in block
+ ), "and a conflicting one is folded line by line, rebased as it goes"
+ assert "$_woaOwnNames.ContainsKey($_woaOvName)" in block, (
+ "minus the packages this file declares -- uv combines override files and "
+ "errors on a duplicate package, so a blind append could fail the resolve"
+ )
+
+ def test_the_find_links_are_appended_with_the_right_separators(self):
+ assert (
+ '$env:UV_FIND_LINKS = if ($_woaCallerUvLinks) { "$WoaWheelDir,$_woaCallerUvLinks" }'
+ in INSTALL_SRC
+ ), "UV_FIND_LINKS is comma-separated"
+ assert (
+ '"$_woaSafeWheelDir $_woaCallerPipLinks"' in INSTALL_SRC
+ ), "PIP_FIND_LINKS is split on whitespace, and ours must be the 8.3-safe form"
+
+ def test_ours_is_searched_first(self):
+ """A win_arm64 wheel staged for this host must win a tie against the same name."""
+ assert '"$WoaWheelDir,$_woaCallerUvLinks"' in INSTALL_SRC
+ assert '"$_woaCallerUvLinks,$WoaWheelDir"' not in INSTALL_SRC
+
+ def test_the_python_side_can_read_an_appended_value(self, tmp_path):
+ """install_python_stack.py split find-links on os.pathsep alone, which would have read
+ "dirA,dirB" as one unusable path now that appending is possible. Asserted as behaviour
+ because the separator is per-variable: a shared split that also broke on whitespace tore
+ a directory whose name contains a space into two paths that do not exist."""
+ import importlib.util
+
+ spec = importlib.util.spec_from_file_location("_ips_findlinks_split", STACK_PY)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+
+ first = tmp_path / "a"
+ second = tmp_path / "private wheels"
+ for directory in (first, second):
+ directory.mkdir()
+ (first / "alpha-1.0.0-py3-none-any.whl").write_bytes(b"")
+ (second / "beta-2.0.0-py3-none-any.whl").write_bytes(b"")
+
+ os.environ["UV_FIND_LINKS"] = f"{first},{second}"
+ os.environ.pop("PIP_FIND_LINKS", None)
+ try:
+ module._find_links_wheel_versions.cache_clear()
+ found = module._find_links_wheel_versions()
+ finally:
+ os.environ.pop("UV_FIND_LINKS", None)
+ module._find_links_wheel_versions.cache_clear()
+ assert "alpha" in found, "an appended comma-separated entry is still read"
+ assert "beta" in found, (
+ "a UV_FIND_LINKS directory whose name contains a space was split into "
+ "fragments, so every wheel an air-gapped user hosted there went unseen"
+ )
+
+
+class TestTheProbeAsksForTheInterpretersAbi:
+ """install.ps1 keyed its wheel search on the minor alone."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "minor, free_threaded, expected",
+ [("3.13", False, "cp313"), ("3.13", True, "cp313t"), ("3.11", True, "cp311t")],
+ )
+ def test_the_abi_tag_follows_the_build(self, minor: str, free_threaded: bool, expected: str):
+ script = _script(
+ _ps_function(INSTALL_PS1, "Get-WoaAbiTag"),
+ f"Write-Output (Get-WoaAbiTag -PythonMinor '{minor}' "
+ f"-FreeThreaded ${str(free_threaded).lower()})",
+ )
+ assert _ps_last(script) == expected
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "abi, wheel_abi, found",
+ [
+ ("", "cp313", True), # a GIL interpreter, unchanged
+ ("cp313t", "cp313", False), # free-threaded must not take a GIL wheel
+ ("cp313t", "cp313t", True), # and does take its own
+ ],
+ )
+ def test_only_wheels_of_that_abi_are_found(self, abi: str, wheel_abi: str, found: bool):
+ script = _script(
+ JOIN_URL_PATH,
+ invoke_restmethod(_torch_links("2.14.0%2Bcu134", abi = wheel_abi)),
+ CUDA_PROBE_FUNCS,
+ "$v = Get-WoaCudaWheelVersion -IndexUrl 'https://x.test/i' -PythonMinor '3.13'"
+ f" -AbiTag '{abi}'",
+ 'Write-Output "[$v]"',
+ )
+ got = _ps_last(script)[1:-1]
+ assert bool(got) is found, got
+
+ def test_the_probe_takes_the_flag_and_the_call_sites_supply_it(self):
+ assert (
+ "function Initialize-WoaNativeCudaTorch {\n param([string]$PythonMinor,"
+ " [bool]$FreeThreaded = $false)" in INSTALL_SRC
+ )
+ # Both re-probes know which interpreter was chosen, so both must answer for it.
+ # The flag is read into a variable first: a same-minor free-threaded build re-probes too.
+ assert INSTALL_SRC.count("Test-PythonFreeThreaded -PythonExe $DetectedPython.Path") == 2
+ assert "-FreeThreaded $WoaDetectedFreeThreaded" in INSTALL_SRC
+ assert "-FreeThreaded $_woaNewFreeThreaded" in INSTALL_SRC
+
+ def test_the_staging_scan_uses_the_venv_abi(self):
+ """Keyed on the python tag, staging kept the cp313-cp313 wheels a free-threaded venv
+ cannot install and discarded the cp313-cp313t ones it can."""
+ assert "$WoaWheelAbi = Get-WoaAbiTag -PythonMinor $WoaVenvMinor" in INSTALL_SRC
+ assert "($abiTags -contains $WoaWheelAbi)" in INSTALL_SRC
+ assert (
+ "($WoaWheelStable -and ($abiTags -contains 'abi3'))" in INSTALL_SRC
+ ), "free-threaded builds do not implement the stable ABI"
+ assert (
+ "$script:WoaVenvFreeThreaded = Test-PythonFreeThreaded -PythonExe $VenvPython"
+ in INSTALL_SRC
+ )
+
+ @requires_pwsh
+ def test_an_unknown_interpreter_answers_gil(self):
+ """The historical assumption: unknown must not turn a working GIL host free-threaded."""
+ script = _script(
+ _ps_function(INSTALL_PS1, "Test-PythonFreeThreaded"),
+ "Write-Output (Test-PythonFreeThreaded -PythonExe 'C:\\nope\\python.exe')",
+ "Write-Output (Test-PythonFreeThreaded -PythonExe '')",
+ )
+ assert _ps_ok(script).stdout.split() == ["False", "False"]
+
+ @requires_pwsh
+ def test_it_reads_the_real_interpreter_correctly(self):
+ """Executed against the interpreter running this suite, whichever build that is."""
+ import sysconfig
+
+ expected = "True" if sysconfig.get_config_var("Py_GIL_DISABLED") else "False"
+ script = _script(
+ _ps_function(INSTALL_PS1, "Test-PythonFreeThreaded"),
+ f"Write-Output (Test-PythonFreeThreaded -PythonExe '{sys.executable}')",
+ )
+ assert _ps_last(script) == expected
+
+
+class TestTheAbiReprobeFiresOnAMatchingMinor:
+ """The hole left by keying the re-probe on the minor alone."""
+
+ def test_the_guard_compares_the_abi_as_well_as_the_minor(self):
+ assert "$WoaProbedFreeThreaded = $false" in INSTALL_SRC
+ assert (
+ "($WoaDetectedFreeThreaded -ne $WoaProbedFreeThreaded)" in INSTALL_SRC
+ ), "a 3.13t selected for a 3.13 request matches on minor and must still re-probe"
+
+ def test_the_second_reprobe_compares_it_too(self):
+ """After Install-PythonFromPythonOrg the ABI can change without the minor doing so."""
+ assert "($_woaNewFreeThreaded -ne $WoaProbedFreeThreaded)" in INSTALL_SRC
+
+ def test_the_detection_is_scoped_to_this_host(self):
+ """A subprocess per run on every Windows x64 host would buy nothing."""
+ block = INSTALL_SRC[INSTALL_SRC.index("$WoaDetectedFreeThreaded = $false") :][:600]
+ assert '(Get-HostMachineArch) -eq "arm64"' in block
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "probed_minor, probed_ft, minor, ft, should_reprobe, why",
+ [
+ ("3.13", False, "3.13", False, False, "nothing changed"),
+ ("3.13", False, "3.12", False, True, "a different minor, as before"),
+ ("3.13", False, "3.13", True, True, "THE BUG: same minor, free-threaded"),
+ ("3.13", True, "3.13", False, True, "and back again, after a GIL install"),
+ ],
+ )
+ def test_the_guard_decides_correctly(
+ self, probed_minor, probed_ft, minor, ft, should_reprobe, why
+ ):
+ script = _script(
+ f"$WoaProbedMinor = '{probed_minor}'",
+ f"$WoaProbedFreeThreaded = ${str(probed_ft).lower()}",
+ f"$DetectedPython = @{{ Version = '{minor}' }}",
+ f"$WoaDetectedFreeThreaded = ${str(ft).lower()}",
+ "if ($DetectedPython -and (",
+ " ($DetectedPython.Version -ne $WoaProbedMinor) -or",
+ " ($WoaDetectedFreeThreaded -ne $WoaProbedFreeThreaded))) {",
+ " Write-Output 'REPROBE' } else { Write-Output 'SKIP' }",
+ )
+ assert (_ps_last(script) == "REPROBE") is should_reprobe, why
+
+
+class TestAnExplicitPinOutranksThePersistedIndex:
+ """The recovery is a memory of what install.ps1 chose, not a decision."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "pinned, woa, install_url, expected, why",
+ [
+ ("", NV_GA, "https://d.pytorch.org/whl/cu130", NV_GA, "unpinned fresh shell"),
+ (
+ "https://mirror.test/cu129",
+ NV_GA,
+ "https://mirror.test/cu129",
+ "https://mirror.test/cu129",
+ "an explicit pin wins",
+ ),
+ (
+ "",
+ "",
+ "https://d.pytorch.org/whl/cu130",
+ "https://d.pytorch.org/whl/cu130",
+ "no recovery, no pin: unchanged",
+ ),
+ ],
+ )
+ def test_the_pin_wins(self, pinned, woa, install_url, expected, why):
+ script = _script(
+ f"$PinnedTorchIndexUrl = '{pinned}'",
+ f"$WinArm64TorchIndexUrl = '{woa}'",
+ f"$TorchInstallIndexUrl = '{install_url}'",
+ slice_between(
+ SETUP_SRC,
+ "$_cudaIndexUrl = if ($PinnedTorchIndexUrl)",
+ "else { $TorchInstallIndexUrl }",
+ include_end = True,
+ ).strip(),
+ "Write-Output $_cudaIndexUrl",
+ )
+ assert _ps_last(script) == expected, why
+
+
+class TestTheRestoreMergesRatherThanStandsDown:
+ """A caller override must not cost the win_arm64 drop list."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "line, expected_name",
+ [
+ ('Brotli ; platform_machine == "AMD64"', "brotli"),
+ ("brotli_cffi>=1.0", "brotli-cffi"),
+ ("torch>=2.4", "torch"),
+ ("pyarrow==21.0.0", "pyarrow"),
+ ("# a comment", ""),
+ ("", ""),
+ ("-r other.txt", ""),
+ ],
+ )
+ def test_requirement_names_are_canonical(self, line: str, expected_name: str):
+ """PEP 503 normalisation, so Brotli and brotli_cffi compare as one name."""
+ script = _script(
+ _function_source(SETUP_SRC, "Get-RequirementName"),
+ f"Write-Output \"[$(Get-RequirementName -Line '{line}')]\"",
+ )
+ assert _ps_last(script) == f"[{expected_name}]"
+
+ def test_disjoint_files_are_both_passed_and_conflicts_are_merged(self):
+ block = SETUP_SRC[SETUP_SRC.index("$_woaOursNames = Get-RequirementNames") :][:2600]
+ assert '$env:UV_OVERRIDE = "$safeOverrides $($env:UV_OVERRIDE)"' in block, (
+ "disjoint files need no rewriting, which keeps each file's relative "
+ "references resolving against its own directory"
+ )
+ assert "overrides.merged.txt" in block, "only an actual conflict is merged"
+ assert "(Get-RequirementName -Line $_woaOvLine) -in $_woaOursNames" not in block
+
+ def test_the_caller_no_longer_suppresses_the_drop_list(self):
+ """The regression: the whole restore used to sit under `if (-not $env:UV_OVERRIDE)`."""
+ body = _function_source(SETUP_SRC, "Restore-WoaResolverEnvironment")
+ # The drop list is read whatever the caller set; only the LAST step reads UV_OVERRIDE.
+ head = body[: body.index("$safeOverrides = Get-UvSafePath $overrides")]
+ assert head.count("$env:UV_OVERRIDE") <= 1, (
+ "reaching the drop list must not depend on the caller having set nothing; "
+ f"head still tests it: {head[-300:]}"
+ )
+ assert (
+ "elseif (-not $env:UV_OVERRIDE) {" in body
+ ), "the no-caller case still assigns ours alone"
+
+
+# The live purge that drops a PREVIOUS run's resolver settings but not the caller's.
+PURGE_BLOCK = slice_between(
+ INSTALL_SRC,
+ '$_woaOwnedPrefix = Join-Path $StudioHome "woa"',
+ "if ($script:WoaNativeCudaTorch) {",
+)
+
+
+class TestThePurgeKeepsWhatIsNotOurs:
+ """The purge drops a PREVIOUS run's resolver settings, not the caller's."""
+
+ def test_the_block_works_entry_by_entry(self):
+ assert "$_woaKept" in PURGE_BLOCK, "entries are kept, not just the whole value dropped"
+ assert '"UV_FIND_LINKS" = ","' in PURGE_BLOCK, "each is rejoined with its own separator"
+ assert "$_woaSplitOn" in PURGE_BLOCK, (
+ "and SPLIT with that same one: uv takes UV_FIND_LINKS comma-separated, so a "
+ "shared whitespace split tore a path with a space into fragments and then "
+ "rejoined them with commas"
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "var, value, expected, why",
+ [
+ ("UV_FIND_LINKS", "{home}/woa/wheels", "", "ours alone still goes"),
+ (
+ "UV_FIND_LINKS",
+ "{home}/woa/wheels,/mnt/mirror",
+ "/mnt/mirror",
+ "the caller's mirror survives the comma form",
+ ),
+ (
+ "PIP_FIND_LINKS",
+ "{home}/woa/wheels /mnt/mirror",
+ "/mnt/mirror",
+ "the whitespace form",
+ ),
+ (
+ "PIP_FIND_LINKS",
+ "/a {home}/woa/wheels /b",
+ "/a /b",
+ "ours is removed from the middle without disturbing the rest",
+ ),
+ (
+ "UV_FIND_LINKS",
+ "/mnt/mirror",
+ "/mnt/mirror",
+ "a value that is entirely the caller's is untouched",
+ ),
+ ("UV_OVERRIDE", "{home}/woa/overrides.txt", "", "ours alone still goes"),
+ (
+ "UV_OVERRIDE",
+ "{home}/woa/overrides.txt /etc/ov.txt",
+ "/etc/ov.txt",
+ "a caller's override file survives",
+ ),
+ ],
+ )
+ def test_only_the_owned_entries_are_removed(self, var, value, expected, why):
+ script = _script(
+ f"$StudioHome = '{FAKE_HOME}'",
+ UV_SAFE_PATH,
+ f"$env:{var} = '{_native_path_value(value)}'",
+ PURGE_BLOCK,
+ f"Write-Output ('[' + $env:{var} + ']')",
+ )
+ assert _ps_last(script) == f"[{_native_path_value(expected)}]", why
+
+
+class TestAMalformedHandoffUrlDoesNotCostTheManifest:
+ """write_manifest documents that it never raises."""
+
+ @pytest.mark.parametrize(
+ "bad", ["https://[", "https://pypi.nvidia.com:notaport/x", "https://[::1", "://"]
+ )
+ def test_the_manifest_is_still_written(self, tmp_path, bad):
+ module = _load_manifest_module()
+ written = module.write_manifest(tmp_path, woa_torch_index = bad)
+ assert written is not None, "a bad URL must not take the manifest with it"
+ payload = json.loads(pathlib.Path(written).read_text(encoding = "utf-8"))
+ assert "woa_torch_index" not in payload, "and it is certainly not persisted"
+
+ def test_a_good_url_is_still_persisted(self, tmp_path):
+ module = _load_manifest_module()
+ written = module.write_manifest(tmp_path, woa_torch_index = NV_GA + "/")
+ payload = json.loads(pathlib.Path(written).read_text(encoding = "utf-8"))
+ assert payload["woa_torch_index"] == NV_GA
+
+
+class TestAStaleTorchaudioIsRemoved:
+ """A fresh-shell update on Windows on ARM cannot see UNSLOTH_WOA_HAS_TORCHAUDIO, so it
+ installs torch/torchvision alone."""
+
+ @staticmethod
+ def _block() -> str:
+ # Anchored on the code that follows rather than on its comment.
+ return slice_between(
+ SETUP_SRC,
+ "if ($WinArm64Venv -and $WinArm64NoAudio) {",
+ 'substep "installing Triton for Windows..."',
+ )
+
+ def test_the_removal_is_conditional_on_a_mismatch(self):
+ block = self._block()
+ assert "Fast-Uninstall torchaudio" in block
+ assert (
+ "Test-WoaPairsWithTorchParity -TorchVersion $_woaTorchVer -OtherVersion $_woaAudioVer"
+ in block
+ and "Test-WoaAudioMatchesTorchParity -TorchVersion $_woaTorchVer"
+ " -AudioVersion $_woaAudioVer"
+ in block
+ ), "a matching audio wheel is the one this venv was installed with and stays"
+ assert (
+ "$_woaAudioProbe.Ok" in block
+ ), "a probe that did not answer says nothing; it must not trigger a removal"
+
+ def test_it_only_runs_where_audio_was_dropped(self):
+ assert self._block().startswith("if ($WinArm64Venv -and $WinArm64NoAudio) {"), (
+ "on every other host, and on a WoA index that DOES publish torchaudio, the "
+ "trio asked for it and the resolver already matched the pair"
+ )
+
+ def test_it_runs_after_the_install_succeeded(self):
+ failed = SETUP_SRC.index('Exit-SetupFailure "PyTorch CUDA installation failed')
+ assert (
+ SETUP_SRC.index("if ($WinArm64Venv -and $WinArm64NoAudio) {") > failed
+ ), "removing audio before knowing torch installed would strip a working venv"
+
+
+class TestTheWheelTagsAreMatchedAsFields:
+ """`*cp313-cp313*` also matches cp313-cp313t."""
+
+ def test_no_substring_match_is_left(self):
+ assert "$tag-$AbiTag*" not in INSTALL_SRC, "every probe goes through the field parser"
+ # The six pyarrow sites go through Test-WoaPyarrowWheelUsable, a floor check around this.
+ assert (
+ INSTALL_SRC.count("Test-WoaWheelTags") + INSTALL_SRC.count("Test-WoaPyarrowWheelUsable")
+ ) >= 7, (
+ "the pyarrow probe (supplied wheel, PyPI, local wheelhouse, remote index), "
+ "the CUDA wheel scan, and both staging sites"
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "name, py, abi, expected, why",
+ [
+ (
+ "pyarrow-21.0.0-cp313-cp313t-win_arm64.whl",
+ "cp313",
+ "cp313",
+ False,
+ "the regression: a free-threaded wheel on a GIL interpreter",
+ ),
+ ("pyarrow-21.0.0-cp313-cp313-win_arm64.whl", "cp313", "cp313", True, "its own"),
+ (
+ "pyarrow-21.0.0-cp313-cp313t-win_arm64.whl",
+ "cp313",
+ "cp313t",
+ True,
+ "and the free-threaded interpreter still finds its own",
+ ),
+ (
+ "pyarrow-21.0.0-cp313-cp313-win_arm64.whl",
+ "cp313",
+ "cp313t",
+ False,
+ "which is not the GIL one",
+ ),
+ ("pyarrow-21.0.0-cp311-cp311-win_arm64.whl", "cp313", "cp313", False, "another minor"),
+ (
+ "torch-2.14.0+cu134-cp312.cp313-cp312.cp313-win_arm64.whl",
+ "cp313",
+ "cp313",
+ True,
+ "a dot-separated tag set is expanded, as PEP 425 says",
+ ),
+ (
+ "pyarrow-21.0.0-1-cp313-cp313-win_arm64.whl",
+ "cp313",
+ "cp313",
+ True,
+ "an optional build tag does not shift the last three fields",
+ ),
+ ("garbage.whl", "cp313", "cp313", False, "unparseable is not installable"),
+ ],
+ )
+ def test_the_matcher(self, name, py, abi, expected, why):
+ script = _script(
+ WHEEL_TAG_FUNCS,
+ f"Write-Output (Test-WoaWheelTags -Name '{name}' -PyTag '{py}' -AbiTag '{abi}')",
+ )
+ assert _ps_last(script) == str(expected), why
+
+
+class TestThePurgeNeedsAPathBoundary:
+ """<StudioHome>\\woa-mirror is a caller's own wheel source, not ours."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "value, expected, why",
+ [
+ ("{home}/woa-mirror", "{home}/woa-mirror", "a sibling directory survives"),
+ ("{home}/woa-custom.txt", "{home}/woa-custom.txt", "and a sibling file"),
+ ("{home}/woa", "", "the prefix itself is ours"),
+ ("{home}/woa/wheels", "", "and anything under it"),
+ (
+ "{home}/woa/wheels,{home}/woa-mirror",
+ "{home}/woa-mirror",
+ "ours goes, the sibling stays",
+ ),
+ ],
+ )
+ def test_only_the_prefix_or_its_descendants_are_owned(self, value, expected, why):
+ script = _script(
+ f"$StudioHome = '{FAKE_HOME}'",
+ UV_SAFE_PATH,
+ f"$env:UV_FIND_LINKS = '{_native_path_value(value)}'",
+ PURGE_BLOCK,
+ "Write-Output ('[' + $env:UV_FIND_LINKS + ']')",
+ )
+ assert _ps_last(script) == f"[{_native_path_value(expected)}]", why
+
+
+class TestAHostedDropCandidateMustMeetItsFloor:
+ """The override drop list recorded names only."""
+
+ def test_versions_are_recorded_and_the_floor_is_consulted(self):
+ assert "$WoaWheelNames[$_woaWheelKey] += $parts[1]" in INSTALL_SRC, "versions are kept"
+ assert '$WoaDropFloors = @{ "xformers" = "0.0.22.post7" }' in INSTALL_SRC
+ assert "Test-WoaVersionAtLeast -Version $_woaHostedVer -Floor $_woaFloor" in INSTALL_SRC
+
+ def test_the_floor_still_matches_the_metadata(self):
+ """The one duplicated constant, pinned to its source so it cannot drift."""
+ pyproject = (PACKAGE_ROOT / "pyproject.toml").read_text(encoding = "utf-8")
+ assert (
+ "xformers>=0.0.22.post7 ; (sys_platform == 'win32')" in pyproject
+ ), "if this floor moves, $WoaDropFloors in install.ps1 moves with it"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "have, floor, expected, why",
+ [
+ ("0.0.22", "0.0.22.post7", "False", "the regression: post7 outranks the release"),
+ ("0.0.22.post7", "0.0.22.post7", "True", "the floor itself"),
+ ("0.0.22.post8", "0.0.22.post7", "True", "above it"),
+ ("0.0.23", "0.0.22.post7", "True", "a later release"),
+ ("0.0.30", "0.0.22.post7", "True", "compared numerically, not as text"),
+ ("0.0.21", "0.0.22.post7", "False", "an earlier release"),
+ ("0.0.23+cu134", "0.0.22.post7", "True", "a local tag is not part of the order"),
+ ("garbage", "0.0.22.post7", "False", "unreadable keeps the drop"),
+ # PEP 440 hangs .devN off whatever precedes it, so a development release sorts BELOW
+ # that segment. Read as a pre-release of the RELEASE it got the post case backwards.
+ ("0.0.22.post7.dev0", "0.0.22.post7", "False", "a dev of post7 is below post7"),
+ ("0.0.22.post8.dev0", "0.0.22.post7", "True", "but still above post6 and post7"),
+ ("0.0.22.post7", "0.0.22.post7.dev0", "True", "and the release outranks its dev"),
+ ("0.0.23.dev0", "0.0.22.post7", "True", "a later release line wins outright"),
+ ("0.0.22.dev0", "0.0.22.post7", "False", "a dev of the release is below post7"),
+ ("0.0.22.post7.dev1", "0.0.22.post7.dev0", "True", "dev stamps still order"),
+ ("0.0.22.post7.dev0", "0.0.22.post7.dev1", "False", "and order in both directions"),
+ ("0.0.23rc1", "0.0.23", "False", "rc still sorts below its release"),
+ ("0.0.23", "0.0.23rc1", "True", "and the release above the rc"),
+ ],
+ )
+ def test_the_comparison(self, have, floor, expected, why):
+ script = _script(
+ _function_source(INSTALL_SRC, "Test-WoaVersionAtLeast"),
+ f"Write-Output (Test-WoaVersionAtLeast -Version '{have}' -Floor '{floor}')",
+ )
+ assert _ps_last(script) == expected, why
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "hosted, dropped, why",
+ [
+ ("'0.0.22'", True, "the regression: below the released floor, the drop stays"),
+ ("'0.0.22.post7'", False, "at the floor, the wheelhouse wheel is usable"),
+ ("'0.0.23'", False, "above it"),
+ ("'0.0.22','0.0.23'", False, "one satisfying version among several is enough"),
+ ("", True, "nothing hosted at all"),
+ ],
+ )
+ def test_the_loop_keeps_the_drop(self, hosted, dropped, why):
+ """Executed, not just read: the version has to reach the decision."""
+ start = INSTALL_SRC.index(" foreach ($candidate in $WoaDropCandidates) {")
+ end = INSTALL_SRC.index('$WoaOverrideLines += "$candidate ; platform_machine', start)
+ end = INSTALL_SRC.index("}", INSTALL_SRC.index("\n", end)) + 1
+ wheel_names = "@{}" if not hosted else "@{ 'xformers' = @(%s) }" % hosted
+ script = _script(
+ _function_source(INSTALL_SRC, "Test-WoaVersionAtLeast"),
+ SUBSTEP_NOOP,
+ "$WoaDropCandidates = @('xformers')",
+ '$WoaDropFloors = @{ "xformers" = "0.0.22.post7" }',
+ f"$WoaWheelNames = {wheel_names}",
+ "$WoaOverrideLines = @()",
+ "$WoaReported = @{}",
+ INSTALL_SRC[start:end],
+ "Write-Output ('[' + ($WoaOverrideLines -join '|') + ']')",
+ )
+ line = _ps_last(script)
+ assert ("xformers" in line) is dropped, f"{why}: {line}"
+
+
+class TestAFreeThreadedInterpreterIsPreflightedForAv:
+ """torch and pyarrow were not the whole story."""
+
+ def test_the_probe_gates_native_mode(self):
+ block = INSTALL_SRC[INSTALL_SRC.index("$pyarrowSource = Get-WoaPyarrowSource") :][:2200]
+ assert '$FreeThreaded -and -not (Test-WoaWheelAvailable -Project "av"' in block, (
+ "asked only on a free-threaded build; a GIL one takes the abi3 wheel and "
+ "must not gain a network call or a new way to fail"
+ )
+ assert block.index("Test-WoaWheelAvailable") < block.index(
+ "$script:WoaNativeCudaTorch = $true"
+ ), "before the commit, not after: the point is to keep the x64 fallback"
+
+ def test_the_constraint_that_makes_this_matter_is_still_there(self):
+ assert (
+ 'av>=17.0.0; sys_platform == "win32" and platform_machine == "ARM64"' in CONSTRAINTS_SRC
+ )
+
+ @staticmethod
+ def _available(rest_method: str, minor: str, abi: str) -> str:
+ script = _script(
+ rest_method,
+ "$script:WoaWheelhouse = $null",
+ functions(
+ INSTALL_SRC,
+ "Test-WoaWheelTags",
+ "Test-WoaWheelTagsUsable",
+ "Test-WoaVersionAtLeast",
+ "Test-WoaPyPIWheel",
+ ),
+ "function Test-WoaResolveReachesPyPI { $true }",
+ _function_source(INSTALL_SRC, "Test-WoaWheelAvailable"),
+ f"Write-Output (Test-WoaWheelAvailable -Project 'av' -PythonMinor '{minor}'"
+ f" -AbiTag '{abi}')",
+ )
+ return _ps_last(script)
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "listing, abi, expected, why",
+ [
+ (
+ "av-17.1.0-cp311-abi3-win_arm64.whl",
+ "cp313t",
+ "False",
+ "the regression: abi3 is not installable on a free-threaded build",
+ ),
+ (
+ "av-17.1.0-cp314-cp314t-win_arm64.whl",
+ "cp314t",
+ "True",
+ "PyAV does publish a free-threaded wheel, for 3.14t",
+ ),
+ ("av-17.1.0-cp314-cp314t-win_arm64.whl", "cp313t", "False", "but not for 3.13t"),
+ ("", "cp313t", "False", "nothing published at all"),
+ ],
+ )
+ def test_the_probe(self, listing, abi, expected, why):
+ body = f'<a href="{listing}">a</a>' if listing else "<html></html>"
+ minor = "3.14" if "314" in abi else "3.13"
+ assert self._available(invoke_restmethod(body), minor, abi) == expected, why
+
+ @requires_pwsh
+ def test_an_unreachable_index_answers_no(self):
+ """The x64 stack still works; a native venv that cannot build PyAV does not."""
+ assert self._available(INVOKE_RESTMETHOD_OFFLINE, "3.13", "cp313t") == "False"
+
+
+class TestACallerOverrideFileKeepsItsOwnDirectory:
+ """uv resolves a nested -r, and a relative wheel path, against the file that contains the
+ line."""
+
+ def test_a_non_conflicting_file_is_passed_through(self):
+ block = INSTALL_SRC[INSTALL_SRC.index("$_woaKeepFiles = @()") :][:2600]
+ assert "$_woaKeepFiles += $_woaOvFull" in block, "kept where it is"
+ assert "$_woaOvConflicts" in block, "only a package clash forces a rewrite"
+ assert (
+ "Resolve-WoaOverrideLine -Line $_woaOvEntry.Line -BaseDir $_woaOvEntry.BaseDir" in block
+ ), "and a folded line has its relative references made absolute, against its own file"
+
+ def test_the_kept_files_reach_uv(self):
+ assert (
+ "foreach ($_woaKeepFile in $_woaKeepFiles) { $_woaOverrideValue += "
+ "(Get-UvSafePath $_woaKeepFile) }" in INSTALL_SRC
+ )
+ assert (
+ '$env:UV_OVERRIDE = ($_woaOverrideValue -join " ")' in INSTALL_SRC
+ ), "uv splits UV_OVERRIDE on whitespace and combines the files"
+
+ # The rewriter calls GetFullPath, and os.path.abspath applies the same rule on every host.
+ BASE = "/opt/corp/ov"
+
+ @staticmethod
+ def _rebased(relative: str) -> str:
+ return os.path.abspath(
+ os.path.join(TestACallerOverrideFileKeepsItsOwnDirectory.BASE, relative)
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "line, prefix, rebased, why",
+ [
+ ("-r nested.txt", "-r ", "nested.txt", "a nested include"),
+ ("--requirement=sub/n.txt", "--requirement=", "sub/n.txt", "long form"),
+ ("-c cons.txt", "-c ", "cons.txt", "a constraint file"),
+ ("-f wheels", "-f ", "wheels", "a find-links directory"),
+ ("dist/a.whl", "", "dist/a.whl", "a bare relative wheel path"),
+ ],
+ )
+ def test_a_relative_reference_is_rebased(self, line, prefix, rebased, why):
+ assert self._run(line) == prefix + self._rebased(rebased), why
+
+ @requires_pwsh
+ def test_a_relative_file_url_is_rebased_as_a_uri(self):
+ """The file: rows cannot be checked by pasting a path after "file://": a rebased Windows
+ path is C:\\opt\\corp\\ov\\dist\\a.whl, whose URL is file:///C:/opt/corp/ov/dist/a.whl.
+ Concatenating only happened to match where the separator is already "/"."""
+ expected = pathlib.Path(self._rebased("dist/a.whl")).as_uri()
+ assert self._run("foo @ file:dist/a.whl") == f"foo @ {expected}"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "line, why",
+ [
+ ("-r /etc/n.txt", "an absolute path is already right"),
+ ("-r https://x.test/n.txt", "so is a URL"),
+ ("brotli==1.1.0", "an ordinary requirement is untouched"),
+ ('foo ; platform_machine == "AMD64"', "and so is a marker"),
+ ("foo @ https://x.test/a.whl", "a direct URL"),
+ ("a.whl", "a bare name with no directory is a requirement, not a path"),
+ ("# note", "a comment"),
+ ],
+ )
+ def test_everything_else_is_returned_unchanged(self, line, why):
+ assert self._run(line) == line, why
+
+ @staticmethod
+ def _run(line: str) -> str:
+ script = _script(
+ _function_source(INSTALL_SRC, "Resolve-WoaOverrideLine"),
+ "Write-Output ('[' + (Resolve-WoaOverrideLine -Line '{}' -BaseDir '{}') + ']')".format(
+ line, TestACallerOverrideFileKeepsItsOwnDirectory.BASE
+ ),
+ )
+ return _ps_last(script)[1:-1]
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "caller_lines, folded, why",
+ [
+ (
+ ["-r nested.txt"],
+ False,
+ "the regression: no package clash, so the file stays where it was written",
+ ),
+ (["brotli==1.1.0"], False, "an unrelated package is still no clash"),
+ (
+ ["torch==2.9.0", "-r nested.txt"],
+ True,
+ "torch is one of ours, so this file has to be folded, rebased as it goes",
+ ),
+ ],
+ )
+ def test_the_block_end_to_end(self, tmp_path, caller_lines, folded, why):
+ """Executed: a source-level assertion cannot tell a live branch from a dead one."""
+ start = INSTALL_SRC.index(" $_woaOwnNames = @{}")
+ end = INSTALL_SRC.index('$env:UV_OVERRIDE = ($_woaOverrideValue -join " ")', start)
+ end = INSTALL_SRC.index("\n", end)
+ caller_dir = tmp_path / "corp"
+ caller_dir.mkdir()
+ (caller_dir / "nested.txt").write_text("idna==3.10\n", encoding = "utf-8")
+ caller = caller_dir / "ov.txt"
+ caller.write_text("\n".join(caller_lines) + "\n", encoding = "utf-8")
+ managed = tmp_path / "woa.txt"
+ script = _script(
+ # PowerShell does not hoist, so the scanner the block calls has to be here too.
+ functions(INSTALL_SRC, "Resolve-WoaOverrideLine", "Get-WoaRequirementEntries"),
+ UV_SAFE_PATH,
+ "$WoaOverrideLines = @('# generated', 'torch>=2.4', 'torchvision>=0.19')",
+ f"$WoaOverrides = '{managed}'",
+ f"$env:UV_OVERRIDE = '{caller}'",
+ INSTALL_SRC[start:end],
+ 'Write-Output ("OVERRIDE=" + $env:UV_OVERRIDE)',
+ )
+ done = _ps_ok(script)
+ value = [line for line in done.stdout.splitlines() if line.startswith("OVERRIDE=")][-1][
+ len("OVERRIDE=") :
+ ].split()
+ written = managed.read_text(encoding = "utf-8")
+ session = tmp_path / "overrides.session.txt"
+ if folded:
+ assert value == [str(managed), str(session)], why
+ # The include is FLATTENED as it folds, rebased against its own directory: the only
+ # way a conflict one level down can be removed. It lands in the per-run file.
+ folded_text = session.read_text(encoding = "utf-8")
+ assert (
+ "idna==3.10" in folded_text
+ ), "the include's own lines did not come across, so folding dropped them"
+ assert "-r " not in folded_text, "an include line copied verbatim would move its base"
+ assert "torch==2.9.0" not in folded_text, "our own declaration still wins"
+ assert "idna" not in written, "the persistent file carries only our own lines"
+ else:
+ assert value == [str(managed), str(caller)], why
+ assert "-r nested.txt" not in written, "nothing was copied, so nothing moved"
+ assert not session.exists(), "nothing folded, so no per-run file"
+
+
+class TestTheRecoveryPrependsRatherThanStandsDown:
+ """A caller's own find-links must not cost the staged win_arm64 wheels."""
+
+ @staticmethod
+ def _block() -> str:
+ start = SETUP_SRC.index(" if (Test-Path -LiteralPath $wheels -PathType Container) {")
+ return SETUP_SRC[start : SETUP_SRC.index("\n}", start)]
+
+ def test_it_prepends(self):
+ block = self._block()
+ assert (
+ '$env:UV_FIND_LINKS = "$wheels,$($env:UV_FIND_LINKS)"' in block
+ ), "UV_FIND_LINKS is comma-separated, and ours goes first"
+ assert (
+ '$env:PIP_FIND_LINKS = "$_woaSafeWheels $($env:PIP_FIND_LINKS)"' in block
+ ), "PIP_FIND_LINKS is split on whitespace, and ours must be the 8.3-safe form"
+ assert "-notcontains" in block, "a second run must not keep prepending"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "var, before, expected, why",
+ [
+ ("UV_FIND_LINKS", "", "/home/u/woa/wheels", "nothing set: ours alone"),
+ (
+ "UV_FIND_LINKS",
+ "/mnt/mirror",
+ "/home/u/woa/wheels,/mnt/mirror",
+ "the regression: a caller mirror no longer suppresses ours",
+ ),
+ (
+ "UV_FIND_LINKS",
+ "/home/u/woa/wheels,/mnt/mirror",
+ "/home/u/woa/wheels,/mnt/mirror",
+ "already first: unchanged, not doubled",
+ ),
+ ("PIP_FIND_LINKS", "/mnt/mirror", "/home/u/woa/wheels /mnt/mirror", "pip whitespace"),
+ (
+ "PIP_FIND_LINKS",
+ "/home/u/woa/wheels",
+ "/home/u/woa/wheels",
+ "already present: unchanged",
+ ),
+ ],
+ )
+ def test_the_block(self, var, before, expected, why):
+ script = _script(
+ UV_SAFE_PATH,
+ "$wheels = '/home/u/woa/wheels'",
+ "Remove-Item Env:UV_FIND_LINKS,Env:PIP_FIND_LINKS -ErrorAction SilentlyContinue",
+ (f"$env:{var} = '{before}'" if before else ""),
+ self._block().replace(
+ "if (Test-Path -LiteralPath $wheels -PathType Container) {", "if ($true) {", 1
+ ),
+ f"Write-Output ('[' + $env:{var} + ']')",
+ )
+ assert _ps_last(script) == f"[{expected}]", why
+
+
+class TestTheMergedOverrideFileIsRebasedToo:
+ """install.ps1 rebases a folded line; setup.ps1's merge had the same problem."""
+
+ def test_the_merge_rebases(self):
+ block = SETUP_SRC[SETUP_SRC.index("$_woaMerged = Join-Path $woaDir") :][:1600]
+ assert "Resolve-WoaOverrideLine -Line $_woaEntry.Line -BaseDir $_woaEntry.BaseDir" in block
+ assert "$_woaLines += $_woaLine" not in block, "no line is copied verbatim"
+
+ def test_the_helper_is_a_faithful_copy_of_install_ps1s(self):
+ """Neither script can dot-source the other, so the copy is pinned instead."""
+ install, setup = _ps_copies("Resolve-WoaOverrideLine")
+ assert install == setup
+
+
+class TestAWheelhouseThatIsTheStagingDirectory:
+ r"""UNSLOTH_WOA_WHEELHOUSE may BE $StudioHome\woa\wheels -- that is how an offline run
+ reuses the installer's own cache."""
+
+ def test_every_staging_copy_is_guarded(self):
+ assert (
+ "if (-not (Test-WoaSamePath $found.FullName $_woaDest)) {" in INSTALL_SRC
+ ), "the wheelhouse pyarrow copy, which is not inside a try and so was fatal"
+ assert (
+ "if (-not (Test-WoaSamePath $wheel.FullName $_woaExtraDest)) {" in INSTALL_SRC
+ ), "the extra-wheel loop, which swallowed the error but miscounted"
+ assert "if (-not (Test-WoaSamePath $srcWheel $_woaLocalDest)) {" in INSTALL_SRC, (
+ "and the supplied-wheel copy, where the failure was caught but disabled "
+ "native mode after the ARM64 venv had already been chosen"
+ )
+
+ def test_no_staging_copy_is_left_unguarded(self):
+ """Counted, so a fourth copy added later cannot quietly skip the guard."""
+ # Anchored on code, not on a comment: a comment pass must not be able to break this.
+ staging = slice_between(
+ INSTALL_SRC,
+ 'if ($script:WoaPyarrowSource -eq "local") {',
+ "$WoaOverrides = Join-Path $WoaDir",
+ )
+ copies = staging.count("Copy-Item -LiteralPath")
+ guards = staging.count("Test-WoaSamePath")
+ assert copies == guards == 3, f"{copies} copies, {guards} guards"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "a, b, expected, why",
+ [
+ ("/x/woa/wheels/a.whl", "/x/woa/wheels/a.whl", "True", "the same file"),
+ (
+ "/x/woa/wheels/a.whl",
+ "/x/woa/wheels/../wheels/a.whl",
+ "True",
+ "the same file spelled differently",
+ ),
+ (
+ "/x/woa/wheels/a.whl",
+ "/X/WOA/WHEELS/A.WHL",
+ "True",
+ "Windows paths are case-insensitive, and this only runs there",
+ ),
+ ("/x/mirror/a.whl", "/x/woa/wheels/a.whl", "False", "different files"),
+ ("", "/x/woa/wheels/a.whl", "False", "nothing is not a path"),
+ ],
+ )
+ def test_the_comparison(self, a, b, expected, why):
+ script = _script(
+ _function_source(INSTALL_SRC, "Test-WoaSamePath"),
+ f"Write-Output (Test-WoaSamePath '{a}' '{b}')",
+ )
+ assert _ps_last(script) == expected, why
+
+ @requires_pwsh
+ def test_a_self_copy_would_otherwise_be_fatal(self, tmp_path):
+ """The behaviour this guards, executed, so the reason cannot go stale."""
+ wheel = tmp_path / "a.whl"
+ wheel.write_text("x", encoding = "utf-8")
+ done = _ps(
+ '$ErrorActionPreference = "Stop"; '
+ f"try {{ Copy-Item -LiteralPath '{wheel}' -Destination '{wheel}' -Force; "
+ "Write-Output 'OK' } catch { Write-Output 'THREW' }"
+ )
+ assert done.returncode == 0, done.stderr
+ assert done.stdout.strip().splitlines()[-1] == "THREW"
+
+
+class TestTheSuppliedWheelIsOpenedNotSniffed:
+ """A truncated download still starts with "PK"."""
+
+ def test_the_zip_helper_is_used(self):
+ block = INSTALL_SRC[INSTALL_SRC.index("if ($env:UNSLOTH_PYARROW_WHEEL) {") :][:1800]
+ assert 'if (Test-ZipArchiveReadable -Path $_paWheel) { return "local" }' in block
+ assert "ReadByte()" not in block, "the two-byte signature sniff is gone"
+
+ def test_the_helper_is_defined_before_this_runs(self):
+ """PowerShell does not hoist: a call above the definition is a runtime error."""
+ assert INSTALL_SRC.index("function Test-ZipArchiveReadable") < INSTALL_SRC.index(
+ "function Get-WoaPyarrowSource"
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "payload, expected, why",
+ [
+ (
+ b"PK\x03\x04" + b"\x00" * 64,
+ "False",
+ "the regression: a PK header with no central directory",
+ ),
+ (b"not a zip at all", "False", "nothing zip-like"),
+ (b"", "False", "an empty file"),
+ (None, "True", "a real archive"),
+ ],
+ )
+ def test_the_check(self, tmp_path, payload, expected, why):
+ import zipfile
+
+ wheel = tmp_path / "pyarrow-21.0.0-cp313-cp313-win_arm64.whl"
+ if payload is None:
+ with zipfile.ZipFile(wheel, "w") as zf:
+ zf.writestr("pyarrow/__init__.py", "")
+ else:
+ wheel.write_bytes(payload)
+ script = _script(
+ _function_source(INSTALL_SRC, "Test-ZipArchiveReadable"),
+ f"Write-Output (Test-ZipArchiveReadable -Path '{wheel}')",
+ )
+ assert _ps_last(script) == expected, why
+
+
+# The live chain that decides which index a WoA venv installs torch from.
+WOA_INDEX_CHAIN = slice_between(
+ SETUP_SRC, "$WinArm64TorchIndexUrl = if ($WinArm64Venv", '} else { "" }', include_end = True
+)
+CORP_WOA = "https://mirror.corp/woa"
+NV_OOT = "https://pypi.nvidia.com/oot"
+
+
+class TestAConfiguredWoaMirrorSurvivesAFreshShell:
+ """write_manifest persists only NVIDIA's own channels, because any other URL could carry a
+ credential, so UNSLOTH_WOA_TORCH_INDEX_URL has to be consulted on its own."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "configured, handover, persisted, expected, why",
+ [
+ (CORP_WOA, "", "", CORP_WOA, "the regression: a fresh shell with only the user's own"),
+ (CORP_WOA + "/", "", "", CORP_WOA, "trailing slash trimmed, as the other branches do"),
+ (CORP_WOA, NV_OOT, "", CORP_WOA, "the user's channel outranks the handover"),
+ ("", NV_OOT, "", NV_OOT, "unchanged when it is not set"),
+ ("", "", NV_OOT, NV_OOT, "and the manifest still answers when nothing else does"),
+ ],
+ )
+ def test_the_precedence(self, configured, handover, persisted, expected, why):
+ script = _script(
+ "$WinArm64Venv = $true",
+ "$VenvDir = '/nonexistent'",
+ f"function Get-PersistedWoaTorchIndex {{ param($VenvPath) return '{persisted}' }}",
+ f"$env:UNSLOTH_WOA_TORCH_INDEX_URL = '{configured}'",
+ f"$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = '{handover}'",
+ WOA_INDEX_CHAIN,
+ "Write-Output ('[' + $WinArm64TorchIndexUrl + ']')",
+ )
+ assert _ps_last(script) == f"[{expected}]", why
+
+ @requires_pwsh
+ def test_a_non_arm64_venv_still_reads_nothing(self):
+ """Every other host must see exactly the index choice it saw before."""
+ script = _script(
+ "$WinArm64Venv = $false",
+ "$VenvDir = '/nonexistent'",
+ "function Get-PersistedWoaTorchIndex { param($VenvPath) throw 'must not be called' }",
+ f"$env:UNSLOTH_WOA_TORCH_INDEX_URL = '{CORP_WOA}'",
+ f"$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = '{NV_OOT}'",
+ WOA_INDEX_CHAIN,
+ "Write-Output ('[' + $WinArm64TorchIndexUrl + ']')",
+ )
+ assert _ps_last(script) == "[]"
+
+ def test_install_ps1_still_does_not_write_that_variable(self):
+ """It is the user's INPUT."""
+ assert not re.search(r"\$env:UNSLOTH_WOA_TORCH_INDEX_URL\s*=", INSTALL_SRC)
+
+ def test_a_mirror_is_still_not_persisted(self):
+ """The reason this branch has to exist; if the manifest ever took one, the credential
+ rule would have been weakened instead."""
+ module = _load_manifest_module()
+ import tempfile
+
+ with tempfile.TemporaryDirectory() as tmp:
+ written = module.write_manifest(pathlib.Path(tmp), woa_torch_index = CORP_WOA)
+ payload = json.loads(pathlib.Path(written).read_text(encoding = "utf-8"))
+ assert "woa_torch_index" not in payload
+
+
+class TestAWheelhousePyarrowMustClearTheFloor:
+ """A tag-compatible pyarrow is not enough: staging turns whichever wheel it picks into an
+ exact `pyarrow==<version>` override, and constraints.txt floors the ARM64 row at 21.0.0, so
+ a 19.x wheel selected the native path and then made the dependency pass unsatisfiable."""
+
+ def test_the_floor_matches_the_constraint(self):
+ """Two places state it, so a bump to one that skips the other is caught here."""
+ floor = re.search(r'\$script:WoaPyarrowFloor\s*=\s*"([^"]+)"', INSTALL_SRC)
+ assert floor, "install.ps1 no longer declares the pyarrow floor"
+ pinned = re.search(
+ r'(?m)^pyarrow>=([0-9.]+);\s*sys_platform == "win32" and platform_machine == "ARM64"',
+ CONSTRAINTS_SRC,
+ )
+ assert pinned, "the ARM64 pyarrow row is gone from constraints.txt"
+ assert floor.group(1) == pinned.group(1), (
+ f"install.ps1 floors pyarrow at {floor.group(1)} but constraints.txt requires "
+ f">={pinned.group(1)}, so the staged wheel would not satisfy the resolve"
+ )
+
+ def test_every_pyarrow_candidate_goes_through_the_floor(self):
+ """Counted: four in the preflight (supplied wheel, PyPI, wheelhouse directory, wheelhouse
+ index) and two in staging, so a seventh site added later cannot skip the check."""
+ assert INSTALL_SRC.count("Test-WoaPyarrowWheelUsable") == 7, (
+ "one definition and six call sites; a pyarrow candidate is being accepted on "
+ "its tags alone somewhere"
+ )
+
+ @staticmethod
+ def _usable(
+ name: str,
+ py: str = "cp313",
+ abi: str = "cp313",
+ ) -> str:
+ script = _script(
+ PYARROW_USABLE_FUNCS,
+ f"Write-Output ([bool](Test-WoaPyarrowWheelUsable -Name '{name}' "
+ f"-PyTag '{py}' -AbiTag '{abi}'))",
+ )
+ return _ps_last(script)
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "name, expected, why",
+ [
+ ("pyarrow-21.0.0-cp313-cp313-win_arm64.whl", "True", "at the floor"),
+ ("pyarrow-23.0.1-cp313-cp313-win_arm64.whl", "True", "above it"),
+ # The shape upstream is going to ship: cp311-abi3 (apache/arrow#48539).
+ ("pyarrow-26.0.0-cp311-abi3-win_arm64.whl", "True", "abi3 from below this venv"),
+ ("pyarrow-26.0.0-cp39-abi3-win_arm64.whl", "True", "abi3 from further below"),
+ # abi3 reaches forward from what it was built against, never backward.
+ ("pyarrow-26.0.0-cp314-abi3-win_arm64.whl", "False", "abi3 built for a newer one"),
+ # A floor still applies to an abi3 wheel; the tag is not a bypass.
+ ("pyarrow-19.0.0-cp311-abi3-win_arm64.whl", "False", "abi3 below the floor"),
+ ("pyarrow-19.0.1-cp313-cp313-win_arm64.whl", "False", "below it"),
+ ("pyarrow-21.0.0-cp312-cp312-win_arm64.whl", "False", "wrong interpreter"),
+ ("pyarrow-notaversion-cp313-cp313-win_arm64.whl", "False", "unreadable version"),
+ ],
+ )
+ def test_the_floor_is_applied(self, name, expected, why):
+ assert self._usable(name) == expected, why
+
+
+class TestThePrereleaseAnswerComesFromTheWheel:
+ """Not from the URL: a mirror of a prerelease-only channel need not say "nightly". Without
+ --prerelease=allow uv takes the stable win_arm64 CPU torch from the PyPI extra index instead
+ of the 2.15.0.dev CUDA build the probe just proved."""
+
+ def test_the_installer_reads_the_probed_version(self):
+ assert re.search(
+ r"\$script:WoaTorchIsPrerelease\s*=\s*\[bool\]\(\$_woaTorchVersion\s*-match",
+ INSTALL_SRC,
+ ), "install.ps1 no longer derives the prerelease answer from the probed wheel"
+ assert (
+ "if ($script:WoaTorchIsPrerelease -or ($script:WoaTorchIndexUrl -match 'nightly'))"
+ in INSTALL_SRC
+ ), "the --prerelease=allow gate is back to testing only the URL spelling"
+
+ def test_the_answer_is_handed_to_setup(self):
+ """setup.ps1 cannot probe the index itself, so install.ps1 has to tell it."""
+ assert "UNSLOTH_WOA_TORCH_PRERELEASE" in INSTALL_SRC
+ assert "UNSLOTH_WOA_TORCH_PRERELEASE" in SETUP_SRC
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "version, expected",
+ [
+ ("2.15.0.dev20260101+cu134", "True"),
+ ("2.14.0rc1+cu134", "True"),
+ ("2.14.0a1+cu134", "True"),
+ ("2.14.0+cu134", "False"),
+ ("", "False"),
+ ],
+ )
+ def test_the_version_test_itself(self, version, expected):
+ script = (
+ f"$v = '{version}'\nWrite-Output ([bool]($v -match '(?i)\\d(a|b|rc)\\d|\\.dev\\d'))"
+ )
+ assert _ps_last(script) == expected, version
+
+
+class TestAChangedPinInvalidatesTheHandover:
+ """install.ps1's flags describe the index IT chose. Change UNSLOTH_TORCH_INDEX_URL and re-run
+ in the same shell and the pin outranks the handover for the install itself, while the
+ torchaudio and prerelease answers still came from the previous channel: the trio asks a new
+ index for an audio wheel it does not publish and the whole torch update aborts."""
+
+ def test_the_handover_index_is_read_before_it_is_overwritten(self):
+ capture = SETUP_SRC.index("$_woaHandoffIndex = if ($env:UNSLOTH_WOA_SELECTED_TORCH_INDEX)")
+ rewrite = SETUP_SRC.index("$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex")
+ assert capture < rewrite, (
+ "the handover value is read after setup.ps1 overwrites it, so the comparison "
+ "always succeeds and the staleness check does nothing"
+ )
+
+ def test_both_flags_are_gated_on_it(self):
+ assert (
+ "$WinArm64NoAudio = $WinArm64Venv -and -not ($WinArm64HandoffApplies -and"
+ ' $env:UNSLOTH_WOA_HAS_TORCHAUDIO -eq "1")' in SETUP_SRC
+ )
+ assert (
+ '($WinArm64HandoffApplies -and $env:UNSLOTH_WOA_TORCH_PRERELEASE -eq "1")' in SETUP_SRC
+ )
+
+ def test_the_effective_index_prefers_the_pin(self):
+ """The same order the install itself uses, or the two would disagree."""
+ assert "$WinArm64EffectiveTorchIndexUrl = if ($PinnedTorchIndexUrl)" in SETUP_SRC
+ assert "$_cudaIndexUrl = if ($PinnedTorchIndexUrl) { $TorchInstallIndexUrl }" in SETUP_SRC
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "pinned, handoff, audio, expect_no_audio, why",
+ [
+ ("", NV_GA, "1", "False", "unpinned and unchanged: the handover describes this index"),
+ (NV_GA, NV_GA, "1", "False", "pinned to the same index: still current"),
+ (NV_GA + "/", NV_GA, "1", "False", "a trailing slash is not a different index"),
+ (
+ "https://mirror.test/simple",
+ NV_GA,
+ "1",
+ "True",
+ "pinned elsewhere: the audio answer belongs to the old channel",
+ ),
+ ("", "", "1", "True", "no handover to trust"),
+ ("", NV_GA, "0", "True", "the handover says no audio"),
+ ],
+ )
+ def test_the_staleness_rule(self, pinned, handoff, audio, expect_no_audio, why):
+ script = _script(
+ f"$_woaHandoffIndex = '{handoff}'",
+ f"$PinnedTorchIndexUrl = '{pinned}'",
+ "$WinArm64TorchIndexUrl = $_woaHandoffIndex",
+ "$WinArm64Venv = $true",
+ f"$env:UNSLOTH_WOA_HAS_TORCHAUDIO = '{audio}'",
+ "$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")',
+ "Write-Output ([bool]$WinArm64NoAudio)",
+ )
+ assert _ps_last(script) == expect_no_audio, why
+
+
+class TestAnOverrideConflictCanHideInAnInclude:
+ """uv follows a nested -r inside an override file, so the top-level scan was not enough: two
+ override files naming the same package is an error to uv, so calling them disjoint turns a
+ working install into a resolution failure."""
+
+ @staticmethod
+ def _names(tmp_path, install: bool):
+ source = INSTALL_PS1 if install else SETUP_PS1
+ name = "Get-WoaRequirementEntries" if install else "Get-RequirementEntries"
+ top = (tmp_path / "top.txt").as_posix()
+ script = _script(
+ _ps_function(source, name),
+ f"$e = @({name} -Path '{top}')",
+ "foreach ($x in $e) { Write-Output ($x.Line.Trim() + '|'"
+ " + [System.IO.Path]::GetFileName($x.BaseDir)) }",
+ )
+ return [line for line in _ps_ok(script).stdout.strip().splitlines() if line]
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ def test_an_included_file_is_read(self, tmp_path, install):
+ nested = tmp_path / "managed"
+ nested.mkdir()
+ (nested / "nested.txt").write_text("torch<2.9\n", encoding = "utf-8")
+ (tmp_path / "top.txt").write_text(
+ "# a comment\nrich>=13\n-r managed/nested.txt\n", encoding = "utf-8"
+ )
+ lines = self._names(tmp_path, install)
+ assert any(
+ line.startswith("torch<2.9|managed") for line in lines
+ ), f"the include was not followed, so a torch conflict reads as disjoint: {lines}"
+ assert any(line.startswith("rich>=13|") for line in lines)
+ assert not any(
+ line.startswith("-r ") for line in lines
+ ), "the include line survived as a line"
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ def test_a_cycle_terminates(self, tmp_path, install):
+ (tmp_path / "top.txt").write_text("-r other.txt\nrich>=13\n", encoding = "utf-8")
+ (tmp_path / "other.txt").write_text("-r top.txt\ntorch<2.9\n", encoding = "utf-8")
+ lines = self._names(tmp_path, install)
+ assert any(line.startswith("torch<2.9|") for line in lines)
+ assert any(line.startswith("rich>=13|") for line in lines)
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ def test_a_missing_include_is_not_fatal(self, tmp_path, install):
+ (tmp_path / "top.txt").write_text("-r gone.txt\nrich>=13\n", encoding = "utf-8")
+ lines = self._names(tmp_path, install)
+ assert [line.split("|")[0] for line in lines] == ["rich>=13"]
+
+ def test_the_scan_and_the_fold_read_the_same_thing(self):
+ """Detecting a conflict one level down and then folding only the top file would drop the
+ line that caused the conflict, which is worse than not folding at all."""
+ assert (
+ INSTALL_SRC.count("$_woaOvEntries") == 3
+ ), "the conflict scan and the fold have diverged"
+ assert "foreach ($_woaEntry in (Get-RequirementEntries -Path $_woaFile))" in SETUP_SRC
+
+
+class TestAFloorIsPep440AboutPrereleases:
+ """21.0.0rc1 does not satisfy >=21.0.0, and staging writes an exact == from what it picks, so
+ the ordering has to place a pre-release below its own release. A LARGER release is untouched:
+ a wheelhouse nightly like the pyarrow 24.0.0.dev260 a GB10 run staged still clears 21.0.0,
+ which is what makes hosting a wheel the only step needed to enable a feature there."""
+
+ CASES = [
+ ("24.0.0.dev260", "21.0.0", True, "a nightly of a later release clears the floor"),
+ ("22.0.0rc1", "21.0.0", True, "and so does an rc of a later release"),
+ ("21.0.0", "21.0.0", True, "the release itself clears its own floor"),
+ ("21.0.1", "21.0.0", True, "a later patch clears it"),
+ ("21.0.0rc1", "21.0.0", False, "an rc sorts below the release it is for"),
+ ("21.0.0.dev1", "21.0.0", False, "and so does a dev build"),
+ ("19.0.1", "21.0.0", False, "plainly below the floor"),
+ ("0.0.22.post7", "0.0.22.post7", True, "the xformers drop floor still holds"),
+ ("0.0.22", "0.0.22.post7", False, "a bare release is below its own post"),
+ ("0.0.23", "0.0.22.post7", True, "a later release outranks a post"),
+ ("nonsense", "21.0.0", False, "unreadable compares as too old, keeping the drop"),
+ ]
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "version, floor, expected, why", CASES, ids = [f"{v}_vs_{f}" for v, f, _, _ in CASES]
+ )
+ def test_the_ordering(self, version, floor, expected, why):
+ script = _script(
+ _ps_function(INSTALL_PS1, "Test-WoaVersionAtLeast"),
+ f"Write-Output ([bool](Test-WoaVersionAtLeast -Version '{version}' -Floor '{floor}'))",
+ )
+ assert (_ps_last(script) == "True") is expected, why
+
+ def test_the_table_agrees_with_packaging(self):
+ """The PowerShell cannot import packaging, so the expectations are checked against it here
+ instead of being asserted from memory."""
+ specifiers = pytest.importorskip("packaging.specifiers")
+ for version, floor, expected, why in self.CASES:
+ try:
+ reference = specifiers.SpecifierSet(f">={floor}").contains(
+ version, prereleases = True
+ )
+ except Exception:
+ continue # "nonsense" is not a version; the PowerShell rule stands alone
+ assert reference is expected, (
+ f"{version} >= {floor}: packaging says {reference}, the table says "
+ f"{expected} ({why})"
+ )
+
+ @requires_pwsh
+ def test_abi3_is_refused_on_a_free_threaded_venv(self):
+ """Free-threaded CPython has no stable ABI (CPython #111506), so abi3 is not an option
+ there. Accepting usable tags must not have loosened this."""
+ got = TestAWheelhousePyarrowMustClearTheFloor._usable(
+ "pyarrow-26.0.0-cp311-abi3-win_arm64.whl", abi = "cp313t"
+ )
+ assert (
+ got == "False"
+ ), "an abi3 wheel was accepted on a free-threaded venv, where it cannot import"
+
+ @requires_pwsh
+ def test_the_wheel_the_gb10_run_staged_is_still_accepted(self):
+ """Named explicitly: a floor that rejected it would break a verified install."""
+ got = TestAWheelhousePyarrowMustClearTheFloor._usable(
+ "pyarrow-24.0.0.dev260-cp313-cp313-win_arm64.whl"
+ )
+ assert got == "True"
+
+
+class TestAFindLinksPathWithASpaceSurvivesThePurge:
+ """UV_FIND_LINKS is comma-separated to uv, so "C:\\private wheels" is ONE directory. Splitting
+ it on whitespace as well tore it into two fragments, dropped the managed entry and rejoined
+ the pieces with commas, leaving an air-gapped user pointed at paths that do not exist."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "var, value, expected, why",
+ [
+ (
+ "UV_FIND_LINKS",
+ r"C:\private wheels,{owned}",
+ r"C:\private wheels",
+ "the caller's spaced directory survives whole and ours is dropped",
+ ),
+ (r"UV_FIND_LINKS", r"C:\a,C:\b", r"C:\a,C:\b", "two unrelated entries, unchanged"),
+ (
+ "PIP_FIND_LINKS",
+ r"C:\a {owned}",
+ r"C:\a",
+ "pip splits on whitespace, so that is how its value is read",
+ ),
+ (
+ "UV_OVERRIDE",
+ r"C:\a.txt {owned}\overrides.txt",
+ r"C:\a.txt",
+ "uv splits UV_OVERRIDE on whitespace, which is why 8.3 exists for it",
+ ),
+ ],
+ )
+ def test_the_purge_reads_each_variable_its_own_way(self, tmp_path, var, value, expected, why):
+ owned = str(tmp_path / "woa")
+ script = _script(
+ UV_SAFE_PATH,
+ f"$StudioHome = '{tmp_path}'",
+ f"$env:{var} = '{value.format(owned = owned)}'",
+ PURGE_BLOCK,
+ f"Write-Output ('[' + [Environment]::GetEnvironmentVariable('{var}') + ']')",
+ )
+ assert _ps_last(script)[1:-1] == expected.format(owned = owned), why
+
+
+class TestThePipFallbackKeepsTheIndexArguments:
+ """When uv cannot be obtained at all, Fast-Install uses pip -- and pip needs these. The NVIDIA
+ channel publishes only the trio, so an install given just --index-url has nowhere to resolve
+ their shared dependencies. Remove-UvOnlyResolverFlags is what makes handing pip the same list
+ safe: it drops --index-strategy and rewrites --prerelease=allow as --pre."""
+
+ def test_the_arguments_are_not_gated_on_uv(self):
+ assert (
+ "$WinArm64IndexArgs = if ($WinArm64Venv) {" in SETUP_SRC
+ ), "gating on $UseUv means the pip fallback gets no --extra-index-url at all"
+
+ @staticmethod
+ def _index_args_block():
+ return INDEX_ARGS_BLOCK
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "use_uv, pre, expect_pre, wheels",
+ [
+ (True, "1", True, True),
+ (False, "1", True, True),
+ (False, "0", False, True),
+ (False, "1", True, False),
+ ],
+ )
+ def test_pip_receives_a_translated_list(self, tmp_path, use_uv, pre, expect_pre, wheels):
+ """Executed end to end: build the list, then run it through the pip translation."""
+ if wheels:
+ (tmp_path / "woa" / "wheels").mkdir(parents = True)
+ script = _script(
+ _function_source(SETUP_SRC, "Remove-UvOnlyResolverFlags"),
+ # The dependency index follows the resolver policy; with none configured it is PyPI.
+ clear_env(UV_INDEX_ENV),
+ "$env:UV_NO_CONFIG = '1'",
+ UV_SAFE_PATH,
+ functions(SETUP_SRC, "Get-WoaUvConfigIndexPolicy", "Get-WoaDependencyIndexArgs"),
+ f"$StudioHome = '{tmp_path}'",
+ "$WinArm64Venv = $true",
+ f"$UseUv = ${str(use_uv).lower()}",
+ f"$WinArm64TorchIndexUrl = '{NV_GA}'",
+ "$WinArm64EffectiveTorchIndexUrl = $WinArm64TorchIndexUrl",
+ "$WinArm64HandoffApplies = $true",
+ f"$env:UNSLOTH_WOA_TORCH_PRERELEASE = '{pre}'",
+ INDEX_ARGS_BLOCK,
+ "$pipArgs = Remove-UvOnlyResolverFlags -Arguments $WinArm64IndexArgs",
+ "Write-Output ('[' + ($pipArgs -join ' ') + ']')",
+ )
+ got = _ps_last(script)[1:-1]
+ assert (
+ f"--extra-index-url {PYPI}" in got
+ ), f"pip cannot resolve the trio's shared dependencies without it: {got!r}"
+ assert "--index-strategy" not in got, "a uv-only flag would make pip print usage"
+ assert "--prerelease" not in got, "likewise the uv spelling"
+ assert ("--pre" in got) is expect_pre, got
+ # Fast-Install clears PIP_FIND_LINKS beside UV_FIND_LINKS, so pip is told on the line too.
+ if wheels:
+ assert f"--find-links {tmp_path / 'woa' / 'wheels'}" in got, got
+ else:
+ assert (
+ "--find-links" not in got
+ ), "uv fails outright on a --find-links directory that is missing"
+
+ # Both call sites spell it --prerelease=allow, so the rest of the grammar is untested by the
+ # run above. uv accepts a space-separated value too, and five values, only one of which means
+ # what --pre means. The first spelling used to drop both tokens and lose the permission;
+ # every other value used to become --pre and invert it.
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ ("argv", "expected"),
+ [
+ (["--prerelease=allow", "numpy"], ["--pre", "numpy"]),
+ (["--prerelease", "allow", "numpy"], ["--pre", "numpy"]),
+ (["--prerelease=disallow", "numpy"], ["numpy"]),
+ (["--prerelease", "disallow", "numpy"], ["numpy"]),
+ (["--prerelease=if-necessary", "numpy"], ["numpy"]),
+ (["--prerelease", "explicit", "numpy"], ["numpy"]),
+ (["--index-strategy=unsafe-best-match", "numpy"], ["numpy"]),
+ (["--index-strategy", "unsafe-best-match", "numpy"], ["numpy"]),
+ # The value is only swallowed by the flag it belongs to.
+ (["numpy", "allow"], ["numpy", "allow"]),
+ (
+ ["--prerelease", "allow", "--index-strategy", "first-index", "numpy"],
+ ["--pre", "numpy"],
+ ),
+ ],
+ ids = lambda v: " ".join(v),
+ )
+ def test_every_spelling_of_the_uv_only_flags(self, argv, expected):
+ quoted = ", ".join("'" + a + "'" for a in argv)
+ script = _script(
+ _function_source(SETUP_SRC, "Remove-UvOnlyResolverFlags"),
+ f"$out = Remove-UvOnlyResolverFlags -Arguments @({quoted})",
+ "Write-Output ('[' + ($out -join ' ') + ']')",
+ )
+ assert _ps_last(script)[1:-1] == " ".join(expected)
+
+
+class TestTheWoaIndexOutlivesTheManifest:
+ """The dependency pass deletes the manifest before rebuilding it. A run that dies in that
+ window used to leave nothing behind: the next update finds no handover and no manifest, falls
+ back to the driver-derived cu130, and fails on an index with no win_arm64 wheel."""
+
+ def test_the_marker_is_written_before_the_manifest_is_dropped(self):
+ saved = SETUP_SRC.index("Save-WoaTorchIndexMarker -IndexUrl $_woaMarkerIndex")
+ dropped = SETUP_SRC.index("$_ManifestDropped = $true")
+ assert saved < dropped, (
+ "written after the drop, the marker would not survive the very interruption "
+ "it exists for"
+ )
+
+ def test_the_manifest_is_still_preferred(self):
+ """The marker is a fallback, not a replacement: the manifest is rewritten each run."""
+ assert "$_woaFromManifest = Get-PersistedWoaTorchIndex -VenvPath $VenvDir" in SETUP_SRC
+ assert (
+ "if ($_woaFromManifest) { $_woaFromManifest } else { Get-WoaTorchIndexMarker }"
+ in SETUP_SRC
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "url, persisted, why",
+ [
+ (NV_GA, True, "NVIDIA's own channel"),
+ (NV_NIGHTLY, True, "and its nightly"),
+ ("https://mirror.corp.test/simple", False, "a pinned mirror is not persisted"),
+ ("https://user:[email protected]/x", False, "userinfo could carry a token"),
+ ("https://pypi.nvidia.com/x?token=abc", False, "nor may a query"),
+ ("https://pypi.nvidia.com/x#f", False, "nor a fragment"),
+ ("http://pypi.nvidia.com/x", False, "https only"),
+ ("https://pypi.nvidia.com.evil.test/x", False, "a lookalike host"),
+ ],
+ )
+ def test_the_marker_persists_only_what_the_manifest_would(self, tmp_path, url, persisted, why):
+ """Same set as write_manifest, so this file cannot become the softer way in."""
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ MARKER_FUNCS,
+ f"Save-WoaTorchIndexMarker -IndexUrl '{url}'",
+ "Write-Output ('[' + (Get-WoaTorchIndexMarker) + ']')",
+ )
+ got = _ps_last(script)[1:-1]
+ assert (got == url.rstrip("/")) is persisted, f"{why}: got {got!r}"
+
+ @requires_pwsh
+ def test_a_hand_edited_marker_cannot_redirect_the_install(self, tmp_path):
+ """Checked on read as well as on write, exactly as the manifest is."""
+ woa = tmp_path / "woa"
+ woa.mkdir()
+ (woa / "torch-index.txt").write_text("https://evil.test/whl", encoding = "utf-8")
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ MARKER_FUNCS,
+ "Write-Output ('[' + (Get-WoaTorchIndexMarker) + ']')",
+ )
+ assert _ps_last(script) == "[]"
+
+ @requires_pwsh
+ def test_the_marker_lives_where_the_dependency_pass_does_not_reach(self, tmp_path):
+ """Beside overrides.txt, which survives the pass for the same reason."""
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ _function_source(SETUP_SRC, "Get-WoaTorchIndexMarkerPath"),
+ "Write-Output ('[' + (Get-WoaTorchIndexMarkerPath) + ']')",
+ )
+ got = _ps_last(script)[1:-1]
+ assert got.endswith("torch-index.txt")
+ assert (tmp_path / "woa").name in got, "the woa directory, not the venv"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "url",
+ [
+ "https://user:[email protected]/nvtorch_oot",
+ "https://pypi.nvidia.com/nvtorch_oot?token=s3cret",
+ "https://mirror.corp.test/simple?token=s3cret",
+ ],
+ )
+ def test_a_credential_never_reaches_the_disk(self, tmp_path, url):
+ """The FILE, not the round-trip: a reader that refuses the value afterwards is no help at
+ all if the token was written out in the first place."""
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ MARKER_FUNCS,
+ f"Save-WoaTorchIndexMarker -IndexUrl '{url}'",
+ )
+ _ps_ok(script)
+ marker = tmp_path / "woa" / "torch-index.txt"
+ written = marker.read_text(encoding = "utf-8") if marker.exists() else ""
+ assert "s3cret" not in written, f"the marker file holds a credential: {written!r}"
+ assert written == "", "nothing unpersistable should be written at all"
+
+
+class TestTheTorchMergeRebasesWhatItFolds:
+ """Two override files is the NORMAL case on the native path. A non-conflicting caller file is
+ kept where it sits, so UV_OVERRIDE names it alongside the generated one; the merge used to
+ write itself into the caller's directory to keep relative references working, which only
+ helped when there was exactly ONE directory -- with two it fell to %TEMP%."""
+
+ @staticmethod
+ def _merge(tmp_path, override_files):
+ # A shebang script is not executable on Windows, so the merge would fail about an empty
+ # path rather than about rebasing. A .cmd stub runs everywhere.
+ if os.name == "nt":
+ fake_py = tmp_path / "fakepython.cmd"
+ fake_py.write_text(
+ "@echo off\r\necho torch==2.11.0+cu130\r\necho torchvision==0.26.0+cu130\r\n",
+ encoding = "ascii",
+ )
+ else:
+ fake_py = tmp_path / "fakepython"
+ fake_py.write_text(
+ "#!/usr/bin/env bash\n"
+ "printf 'torch==2.11.0+cu130\\ntorchvision==0.26.0+cu130\\n'\n",
+ encoding = "ascii",
+ )
+ fake_py.chmod(0o755)
+ script = _script(
+ "$SkipTorch = $false",
+ functions(
+ INSTALL_SRC,
+ "Get-WoaRequirementEntries",
+ "Resolve-WoaOverrideLine",
+ "New-UnslothTorchOverridesFile",
+ ),
+ "$env:UV_OVERRIDE = '{}'".format(" ".join(str(f) for f in override_files)),
+ f"$m = New-UnslothTorchOverridesFile -PythonExe '{fake_py}'",
+ "Write-Output ('<<<' + [System.IO.File]::ReadAllText($m) + '>>>')",
+ )
+ out = _ps_ok(script, timeout = 180).stdout
+ return out[out.index("<<<") + 3 : out.rindex(">>>")]
+
+ @requires_pwsh
+ def test_two_override_directories_still_rebase(self, tmp_path):
+ first = tmp_path / "managed"
+ second = tmp_path / "corp"
+ for directory in (first, second):
+ directory.mkdir()
+ (first / "nested.txt").write_text("idna==3.6\n", encoding = "utf-8")
+ (first / "a.txt").write_text("-r nested.txt\nrich>=13\n", encoding = "utf-8")
+ (second / "b.txt").write_text("./local.whl\nplainpkg==2.0\n", encoding = "utf-8")
+
+ merged = self._merge(tmp_path, [first / "a.txt", second / "b.txt"])
+ assert "idna==3.6" in merged, "the include one directory down was not followed"
+ assert "-r " not in merged, "a relative include survived as a relative line"
+ assert str(second / "local.whl") in merged.replace(
+ "/", os.sep
+ ), f"the bare relative wheel path was not rebased onto its own directory: {merged!r}"
+ assert "rich>=13" in merged and "plainpkg==2.0" in merged
+
+ @requires_pwsh
+ def test_the_frozen_trio_still_wins(self, tmp_path):
+ """Rebasing must not disturb what the merge is FOR: pinning the installed trio."""
+ caller = tmp_path / "corp"
+ caller.mkdir()
+ (caller / "a.txt").write_text("torch==1.0\ntorchvision==0.1\nrich>=13\n", encoding = "utf-8")
+ merged = self._merge(tmp_path, [caller / "a.txt"])
+ assert merged.lstrip().startswith("torch==2.11.0+cu130")
+ assert "torch==1.0" not in merged and "torchvision==0.1" not in merged
+ assert "rich>=13" in merged
+
+
+class TestThePipFallbackIsRefusedOnTheNativeStack:
+ """pip has no override mechanism, so falling back to it does not recover here: the WoA
+ overrides lift the released torch cap and drop the packages with no win_arm64 build at all,
+ and constraints cannot stand in. Running pip anyway downgrades a working CUDA torch or fails
+ later with nothing to say why, so it is refused with a reason."""
+
+ @pytest.fixture
+ def ips(self):
+ import importlib.util
+
+ spec = importlib.util.spec_from_file_location("_ips_pip_fallback", STACK_PY)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+ HEADER = "# Generated by install.ps1 for Windows on ARM (win_arm64). See the WoA block there."
+
+ @pytest.mark.parametrize(
+ "arm64, files, expected, why",
+ [
+ (True, ["ours"], True, "the native stack, with overrides in force"),
+ (True, ["merged"], True, "setup.ps1's merge copies the generated file first"),
+ (True, ["caller", "ours"], True, "ours in force behind a caller's file"),
+ (True, ["missing", "ours"], True, "and behind a path that does not open"),
+ (True, ["bom"], True, "an editor's BOM does not hide the header"),
+ (True, ["caller"], False, "a caller's own override never configured the stack"),
+ (True, ["missing"], False, "a path uv cannot open is not one of ours"),
+ (True, [], False, "an ARM64 run that configured none is not this case"),
+ (True, ["blank"], False, "a blank value is not an override file"),
+ (False, ["ours"], False, "x64 keeps the fallback it always had"),
+ (False, [], False, "and so does every other host"),
+ ],
+ )
+ def test_when_the_refusal_applies(
+ self, ips, monkeypatch, tmp_path, arm64, files, expected, why
+ ):
+ texts = {
+ "ours": self.HEADER + "\ntorch>=2.4\n",
+ "merged": self.HEADER + "\ntorch>=2.4\nrich>=13\n",
+ "bom": "\ufeff" + self.HEADER + "\n",
+ "caller": "rich>=13\n",
+ }
+ paths = []
+ for kind in files:
+ if kind == "blank":
+ paths.append(" ")
+ continue
+ path = tmp_path / f"{kind}.txt"
+ if kind != "missing":
+ path.write_text(texts[kind], encoding = "utf-8")
+ paths.append(str(path))
+ monkeypatch.setattr(ips, "_is_win_arm64_interpreter", lambda: arm64)
+ if paths:
+ monkeypatch.setenv("UV_OVERRIDE", " ".join(paths))
+ else:
+ monkeypatch.delenv("UV_OVERRIDE", raising = False)
+ assert ips._woa_overrides_are_load_bearing() is expected, why
+
+ def test_the_header_is_the_one_install_ps1_writes(self):
+ assert f"'{self.HEADER}'" in INSTALL_SRC
+ assert self.HEADER.startswith(
+ re.search(r'WOA_OVERRIDES_HEADER = "([^"]+)"', STACK_SRC).group(1)
+ )
+
+ def test_both_fallback_paths_are_covered(self):
+ """uv failing and uv never being available reach pip by different routes."""
+ assert STACK_SRC.count("_woa_overrides_are_load_bearing()") == 3, (
+ "one definition and both fallback sites; a route that skips the check would "
+ "silently resolve the wrong stack"
+ )
+ after_uv_failed = STACK_SRC.index("if _woa_overrides_are_load_bearing():")
+ pip_build = STACK_SRC.index("pip_cmd, pip_env = _pinned_cmd_and_env(")
+ assert after_uv_failed < pip_build, "the check has to precede the pip command"
+
+ def test_the_message_names_the_remedy(self):
+ assert (
+ "Install uv and re-run" in STACK_SRC
+ ), "a refusal with no way forward is worse than the silent fallback it replaces"
+
+
+class TestAnAnnotatedIncludeStillOpens:
+ """`-r nested.txt # corporate pins` is a valid line, and the comment is not the path. Capturing
+ it meant the include never opened, so a torch conflict inside it went unseen and the two
+ override files were handed to uv as disjoint -- which uv then rejected."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "include_line, hashed_name, why",
+ [
+ ("-r nested.txt # corporate pins", False, "an inline comment is not the path"),
+ ("-r nested.txt\t# tab before the hash", False, "any whitespace opens one"),
+ ("--requirement nested.txt # long form", False, "and the long spelling too"),
+ ("-r nested.txt", False, "the plain case is unchanged"),
+ ("-r a#b.txt", True, "a hash with no space before it belongs to the filename"),
+ ],
+ )
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ def test_the_target_is_read_without_its_comment(
+ self, tmp_path, install, include_line, hashed_name, why
+ ):
+ source = INSTALL_PS1 if install else SETUP_PS1
+ name = "Get-WoaRequirementEntries" if install else "Get-RequirementEntries"
+ target = "a#b.txt" if hashed_name else "nested.txt"
+ (tmp_path / target).write_text("idna==3.10\n", encoding = "utf-8")
+ (tmp_path / "top.txt").write_text(f"{include_line}\nrich>=13\n", encoding = "utf-8")
+ script = _script(
+ _ps_function(source, name),
+ f"$e = @({name} -Path '{(tmp_path / 'top.txt').as_posix()}')",
+ "foreach ($x in $e) { Write-Output $x.Line.Trim() }",
+ )
+ lines = [line for line in _ps_ok(script).stdout.strip().splitlines() if line]
+ assert "idna==3.10" in lines, f"{why}: the include did not open ({lines})"
+
+
+class TestAnUnrecordableIndexInheritsNothing:
+ """A marker we may not overwrite must not be left saying something else. An install that first
+ used NVIDIA's channel and later moved to a credentialed corporate mirror kept the old marker,
+ so the next fresh-shell update put torch back on the channel the user had moved off."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "second, expect_left, why",
+ [
+ ("https://mirror.corp.test/simple", "", "a private mirror clears it"),
+ ("https://user:[email protected]/x", "", "so does a credentialed one"),
+ ("https://pypi.nvidia.com/x?token=a", "", "and one carrying a query"),
+ (NV_NIGHTLY, NV_NIGHTLY, "a recordable index simply replaces it"),
+ ],
+ )
+ def test_the_marker_does_not_outlive_its_index(self, tmp_path, second, expect_left, why):
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ MARKER_FUNCS,
+ f"Save-WoaTorchIndexMarker -IndexUrl '{NV_GA}'",
+ f"Save-WoaTorchIndexMarker -IndexUrl '{second}'",
+ "Write-Output ('[' + (Get-WoaTorchIndexMarker) + ']')",
+ )
+ assert _ps_last(script)[1:-1] == expect_left, why
+
+ @requires_pwsh
+ def test_clearing_removes_the_file_rather_than_blanking_it(self, tmp_path):
+ """A zero-byte marker would read as empty anyway, but leaving one behind invites the next
+ reader to treat "present" as meaningful."""
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ MARKER_FUNCS,
+ f"Save-WoaTorchIndexMarker -IndexUrl '{NV_GA}'",
+ "Save-WoaTorchIndexMarker -IndexUrl 'https://mirror.corp.test/simple'",
+ )
+ _ps_ok(script)
+ assert not (tmp_path / "woa" / "torch-index.txt").exists()
+
+
+class TestWheelsAnEarlierWheelhouseLeftArePruned:
+ """The managed woa\\wheels directory persists across runs, so after UNSLOTH_WOA_WHEELHOUSE
+ changed a wheel the earlier wheelhouse staged (tiktoken, say) stayed in it, the scan below
+ read it as hosted now, and UV_FIND_LINKS installed it from a source no longer configured.
+ Reconciled against the current listing; kept when the listing could not be read (offline
+ reuse). The managed directory as its own wheelhouse lists exactly what it holds."""
+
+ STALE = "tiktoken-0.9.0-cp313-cp313-win_arm64.whl"
+ HOSTED = "hf_transfer-0.1.9-cp313-cp313-win_arm64.whl"
+ PYARROW = "pyarrow-25.0.1-cp313-cp313-win_arm64.whl"
+
+ @classmethod
+ def _run(
+ cls,
+ tmp_path,
+ wheelhouse,
+ extra_stubs = (),
+ ):
+ managed = tmp_path / "woa" / "wheels"
+ managed.mkdir(parents = True)
+ (managed / cls.STALE).write_text("")
+ (managed / cls.PYARROW).write_text("")
+ script = _script(
+ substep_collector(),
+ functions(INSTALL_SRC, "Test-WoaWheelhouseIsLocal", "Test-WoaSamePath", "Join-UrlPath"),
+ "function Get-WoaAbiTag { param($PythonMinor, $FreeThreaded) 'cp313' }",
+ "function Test-WoaWheelhouseWheelIsRedundant { param($Name, $PyTag, $AbiTag) $false }",
+ "function Test-ZipArchiveReadable { param($Path) $true }",
+ "function Invoke-WebRequest { param($Uri, $OutFile, [switch]$UseBasicParsing, $TimeoutSec, $ErrorAction) Set-Content -Path $OutFile -Value 'x' }",
+ *extra_stubs,
+ "$WoaVenvMinor = '3.13'",
+ "$script:WoaVenvFreeThreaded = $false",
+ "$script:WoaPyPIProvided = @{}",
+ "$script:WoaPyPIMatchedVersion = $null",
+ f"$script:WoaPyarrowWheelName = '{cls.PYARROW}'",
+ f"$WoaWheelDir = '{managed}'",
+ f"$script:WoaWheelhouse = '{wheelhouse}'",
+ slice_between(
+ INSTALL_SRC, "$WoaExtraStaged = 0", " if ($WoaExtraStaged -gt 0) {"
+ ),
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
+ out = _ps_ok(script).stdout
+ return sorted(p.name for p in managed.glob("*.whl")), out
+
+ @requires_pwsh
+ def test_a_local_wheelhouse_prunes_what_it_no_longer_hosts(self, tmp_path):
+ house = tmp_path / "house"
+ house.mkdir()
+ (house / self.HOSTED).write_text("")
+ names, out = self._run(tmp_path, house)
+ assert names == sorted([self.HOSTED, self.PYARROW]), names
+ assert "removed 1 wheel(s) an earlier wheelhouse left" in out
+
+ @requires_pwsh
+ def test_a_url_wheelhouse_prunes_against_its_index(self, tmp_path):
+ names, out = self._run(
+ tmp_path,
+ "https://wheels.test/woa",
+ [invoke_restmethod(f"{self.HOSTED}\n{self.PYARROW}\n")],
+ )
+ assert names == sorted([self.HOSTED, self.PYARROW]), names
+
+ @requires_pwsh
+ def test_the_selected_pyarrow_is_kept_even_when_the_listing_lacks_it(self, tmp_path):
+ """UNSLOTH_PYARROW_WHEEL supplies a wheel no wheelhouse lists."""
+ names, _ = self._run(
+ tmp_path, "https://wheels.test/woa", [invoke_restmethod(f"{self.HOSTED}\n")]
+ )
+ assert self.PYARROW in names, names
+ assert self.STALE not in names, names
+
+ @requires_pwsh
+ def test_an_unreadable_listing_keeps_the_offline_copies(self, tmp_path):
+ names, out = self._run(tmp_path, "https://wheels.test/woa", [INVOKE_RESTMETHOD_OFFLINE])
+ assert self.STALE in names, "offline, the staged copies are the only source"
+ assert "earlier wheelhouse" not in out
+
+ @requires_pwsh
+ def test_the_managed_directory_as_its_own_wheelhouse_is_left_alone(self, tmp_path):
+ names, out = self._run(tmp_path, tmp_path / "woa" / "wheels")
+ assert self.STALE in names, "self-sourced: every wheel there is the wheelhouse"
+ assert "earlier wheelhouse" not in out
+
+
+class TestALocalWheelIsOpenedBeforeItCounts:
+ """The wheelhouse mirror trusted a filename; the resolver then trusted the mirror.
+ _find_links_wheel_versions reads names, so a truncated wheel copied into the managed directory
+ took its package off the ARM64 skip list and uv failed the whole dependency pass on it."""
+
+ @staticmethod
+ def _staging() -> str:
+ return slice_between(
+ INSTALL_SRC, "$WoaExtraStaged = 0", "$WoaOverrides = Join-Path $WoaDir"
+ )
+
+ def test_both_staging_branches_validate(self):
+ block = self._staging()
+ assert block.count("Test-ZipArchiveReadable") >= 3, (
+ "the local mirror, the reused download and the fresh download all have to "
+ f"open what they count: {block.count('Test-ZipArchiveReadable')}"
+ )
+ local = block[: block.index("} else {")]
+ assert (
+ "Test-ZipArchiveReadable" in local
+ ), "the local branch counted a wheel on its filename alone"
+
+ def test_the_check_precedes_the_copy(self):
+ local = slice_between(INSTALL_SRC, "$WoaExtraStaged = 0", "} else {")
+ assert local.index("Test-ZipArchiveReadable") < local.index("Copy-Item -LiteralPath"), (
+ "validating after the copy would still put a corrupt wheel in the cache, "
+ "where the resolver reads it"
+ )
+
+
+class TestTheMandatoryPyarrowWheelIsOpened:
+ """pyarrow decides the ROUTE, so a truncated one must not select native mode: staging writes
+ an exact pyarrow== override from whichever file it picks, so a wheel that only looks right
+ took the native path and then failed the resolve, with x64 already given up."""
+
+ def test_the_probe_and_the_staging_agree(self):
+ """Different filters would let the probe clear one file and staging take another."""
+ assert (
+ INSTALL_SRC.count(
+ "(Test-WoaPyarrowWheelUsable -Name $_.Name -PyTag $tag -AbiTag $AbiTag) -and"
+ )
+ == 2
+ ), "the local probe and the local staging both filter on tags AND readability"
+ assert INSTALL_SRC.count("(Test-ZipArchiveReadable -Path $_.FullName)") == 2
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "content, expected, why",
+ [
+ ("zip", "wheelhouse", "a readable archive selects the native path"),
+ ("truncated", "", "a truncated one does not, so the x64 path is kept"),
+ ("empty", "", "nor does an empty file"),
+ ],
+ )
+ def test_a_local_wheel_is_opened_before_native_is_chosen(
+ self, tmp_path, content, expected, why
+ ):
+ import zipfile
+
+ wheel = tmp_path / "pyarrow-24.0.0-cp313-cp313-win_arm64.whl"
+ if content == "zip":
+ with zipfile.ZipFile(wheel, "w") as archive:
+ archive.writestr("pyarrow/__init__.py", "")
+ elif content == "truncated":
+ wheel.write_bytes(b"PK\x03\x04truncated")
+ else:
+ wheel.write_bytes(b"")
+
+ script = pyarrow_source_script(wheelhouse = f"'{tmp_path}'", local = "$true")
+ assert _ps_last(script, timeout = 180)[1:-1] == expected, why
+
+
+class TestARebasedOptionPathKeepsItsQuoting:
+ """-r/-c/-f take ONE file argument, so an unquoted space truncates the path. Two ways in: a
+ caller who quoted the value had the quotes stripped and not put back, and a caller who had no
+ reason to quote a plain relative name gets a space anyway when it rebases onto a directory
+ that has one."""
+
+ @staticmethod
+ def _rebase(source, line, base):
+ # Here-strings, because the values under test contain both quote characters and spaces.
+ script = _script(
+ _ps_function(source, "Resolve-WoaOverrideLine"),
+ f"$l = @'\n{line}\n'@",
+ f"$b = @'\n{base}\n'@",
+ "Write-Output ('[' + (Resolve-WoaOverrideLine -Line $l -BaseDir $b) + ']')",
+ )
+ return _ps_last(script)[1:-1]
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ @pytest.mark.parametrize(
+ "line, base, quoted, why",
+ [
+ (
+ '-c "corp pins/constraints.txt"',
+ "/opt/corp",
+ True,
+ "the value was quoted because it needed to be",
+ ),
+ ("-r nested.txt", "/opt/my corp", True, "and here the base brings the space in"),
+ ("-f wheels", "/opt/my corp", True, "find-links too"),
+ (
+ "--constraint 'corp pins/c.txt'",
+ "/opt/corp",
+ True,
+ "a single-quoted value is unwrapped and re-quoted the same way",
+ ),
+ ("-r nested.txt", "/opt/corp", False, "nothing with a space stays unquoted, as ever"),
+ ("-c /already/absolute.txt", "/opt/corp", False, "an absolute path is untouched"),
+ ],
+ )
+ def test_the_result_is_quoted_exactly_when_it_has_to_be(self, install, line, base, quoted, why):
+ source = INSTALL_PS1 if install else SETUP_PS1
+ got = self._rebase(source, line, base)
+ assert (
+ got.split(None, 1)[0] == line.split(None, 1)[0]
+ ), f"the option itself was dropped, leaving a bare path: {got!r}"
+ has_quotes = '"' in got
+ assert has_quotes is quoted, f"{why}: {got!r}"
+ if quoted:
+ # The quotes wrap the WHOLE path, or they solve nothing.
+ inner = got[got.index('"') + 1 : got.rindex('"')]
+ assert " " in inner, f"quoted but the space is outside them: {got!r}"
+ assert (
+ got.rindex('"') == len(got.rstrip()) - 1
+ ), f"the closing quote has to end the value: {got!r}"
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ def test_a_rebased_line_still_names_one_file(self, install, tmp_path):
+ """Read back the way a resolver reads it: split the option's argument on spaces and the
+ path must still exist."""
+ source = INSTALL_PS1 if install else SETUP_PS1
+ base = tmp_path / "my corp"
+ base.mkdir()
+ (base / "constraints.txt").write_text("idna==3.10\n", encoding = "utf-8")
+ got = self._rebase(source, "-c constraints.txt", base.as_posix())
+ argument = got.split(None, 1)[1].strip()
+ assert argument.startswith('"') and argument.endswith('"'), got
+ assert pathlib.Path(
+ argument[1:-1]
+ ).exists(), f"the rebased path does not resolve to the file it names: {got!r}"
+
+ def test_the_two_copies_stay_identical(self):
+ """setup.ps1 carries a parity copy; a fix applied to one is a bug in the other."""
+ install, setup = _ps_copies("Resolve-WoaOverrideLine")
+ assert install == setup
+
+
+class TestALocalDirectoryRequirementIsRebasedToo:
+ """The line forms the fold moved and left behind. New-UnslothTorchOverridesFile writes to
+ %TEMP% now and rebases each line on the way, but only for the forms Resolve-WoaOverrideLine
+ knows: ``-e ./pkg`` and a bare ``./pkg`` are requirements pip and uv accept, and both pointed
+ at nothing after the move. The fold runs for every Windows host with UV_OVERRIDE set, so the
+ regression reached hosts this feature never touches."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ @pytest.mark.parametrize(
+ "line, expected_suffix, why",
+ [
+ ("-e ./localproj", "ovdir/localproj", "editable, forward slashes"),
+ ("--editable ..\\sibling", "sibling", "the long spelling and a parent segment"),
+ ("./localproj", "ovdir/localproj", "a bare relative directory"),
+ (".", "ovdir", "the current directory, which is the commonest spelling of all"),
+ ("-e .[dev]", "ovdir[dev]", "extras stay outside the path"),
+ ("./localproj[dev]", "ovdir/localproj[dev]", "and on the bare form too"),
+ ],
+ )
+ def test_a_local_project_path_is_made_absolute(
+ self, install, line, expected_suffix, why, tmp_path
+ ):
+ source = INSTALL_PS1 if install else SETUP_PS1
+ base = tmp_path / "ovdir"
+ base.mkdir()
+ got = TestARebasedOptionPathKeepsItsQuoting._rebase(source, line, base.as_posix())
+ # The value, not the option token in front of it, and without any extras suffix.
+ value = got.split(None, 1)[1] if got.startswith("-") else got
+ assert os.path.isabs(
+ re.sub(r"\[[^\]]*\]$", "", value.strip())
+ ), f"{why}: the line was left relative and now resolves against %TEMP%: {got!r}"
+ assert got.rstrip().replace(os.sep, "/").endswith(expected_suffix), f"{why}: {got!r}"
+
+ @requires_pwsh
+ @pytest.mark.parametrize("install", [True, False], ids = ["install.ps1", "setup.ps1"])
+ @pytest.mark.parametrize(
+ "line",
+ [
+ "packaging>=20",
+ "torch==2.6.0",
+ "some-pkg",
+ "pkg ; python_version < '3.11'",
+ "-e git+https://example.test/p.git#egg=p",
+ "-e /already/absolute",
+ ],
+ )
+ def test_a_line_with_no_relative_path_is_untouched(self, install, line):
+ """A package name may not begin with a dot, which is the whole of the test above's licence
+ to rewrite one. Nothing else may move."""
+ source = INSTALL_PS1 if install else SETUP_PS1
+ assert TestARebasedOptionPathKeepsItsQuoting._rebase(source, line, "/opt/corp") == line
+
+
+class TestTheMarkerRecordsTheIndexActuallyUsed:
+ """A generic pin never reached the marker, only the WoA chain did: $_cudaIndexUrl prefers
+ $PinnedTorchIndexUrl, while $WinArm64TorchIndexUrl consults only UNSLOTH_WOA_TORCH_INDEX_URL,
+ the handover, the manifest and the marker. So a run pinned elsewhere installed from the pin
+ and recorded an NVIDIA channel it had not used."""
+
+ def test_the_saved_value_prefers_the_pin(self):
+ assert "$_woaMarkerIndex = $_woaPinnedIndex" in SETUP_SRC
+ assert "else { $_woaMarkerIndex = $WinArm64TorchIndexUrl }" in SETUP_SRC
+ assert "Save-WoaTorchIndexMarker -IndexUrl $_woaMarkerIndex" in SETUP_SRC
+ # The same value the marker gets, or the manifest shadows it on the next fresh shell.
+ assert "$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex" in SETUP_SRC
+
+ def test_the_pin_is_read_before_it_is_used(self):
+ """Get-PinnedTorchIndexUrl is a function, so only its DEFINITION has to precede this."""
+ assert SETUP_SRC.index("function Get-PinnedTorchIndexUrl") < SETUP_SRC.index(
+ "$_woaPinnedIndex = if ($WinArm64Venv) { Get-PinnedTorchIndexUrl }"
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "pinned, chain, expected, why",
+ [
+ ("", NV_GA, NV_GA, "no pin: the WoA chain is what the run uses, so it is recorded"),
+ (NV_NIGHTLY, NV_GA, NV_NIGHTLY, "a pin to another NVIDIA channel replaces it"),
+ (
+ "https://download.pytorch.org/whl/cu130",
+ NV_GA,
+ "",
+ "a pin to a recognised non-NVIDIA index clears it rather than leaving a lie",
+ ),
+ ("https://mirror.corp.test/simple", NV_GA, "", "and so does a private mirror"),
+ ],
+ )
+ def test_what_ends_up_on_disk(self, tmp_path, pinned, chain, expected, why):
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ f"function Get-PinnedTorchIndexUrl {{ return '{pinned}' }}",
+ f"$WinArm64TorchIndexUrl = '{chain}'",
+ MARKER_FUNCS,
+ # A previous run recorded the public channel; this run may not inherit it.
+ f"Save-WoaTorchIndexMarker -IndexUrl '{NV_GA}'",
+ "$WinArm64Venv = $true",
+ "$_woaHandoffIndex = ''",
+ _persistence_block(SETUP_SRC),
+ "Write-Output ('[' + (Get-WoaTorchIndexMarker) + ']')",
+ )
+ assert _ps_last(script)[1:-1] == expected, why
+
+
+class TestTheManifestRecordsTheSameIndexAsTheMarker:
+ """The marker was corrected; the manifest kept the old answer and outranked it, because
+ $WinArm64TorchIndexUrl reads the manifest BEFORE the marker. Exporting the WoA chain while
+ saving the pin left the two records disagreeing, and the losing one was the correct one."""
+
+ def test_the_export_and_the_save_carry_one_value(self):
+ export = SETUP_SRC.index("$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex")
+ save = SETUP_SRC.index("Save-WoaTorchIndexMarker -IndexUrl $_woaMarkerIndex")
+ resolve = SETUP_SRC.index("$_woaMarkerIndex = $_woaPinnedIndex")
+ assert resolve < export < save, "resolved once, then written to both records"
+
+ def test_the_stack_writes_that_variable_into_the_manifest(self):
+ """The premise: without this read the export would reach nothing."""
+ assert "UNSLOTH_WOA_SELECTED_TORCH_INDEX" in STACK_SRC
+ assert "woa_torch_index" in STACK_SRC
+
+ def test_the_manifest_is_preferred_over_the_marker_on_read(self):
+ """Which is why the two must agree rather than the marker being enough."""
+ chain = SETUP_SRC.index("$_woaFromManifest = Get-PersistedWoaTorchIndex -VenvPath $VenvDir")
+ assert (
+ "if ($_woaFromManifest) { $_woaFromManifest } else { Get-WoaTorchIndexMarker }"
+ in SETUP_SRC[chain : chain + 300]
+ )
+
+ def test_a_moved_pin_drops_the_probed_indexs_flags(self):
+ """torchaudio and prerelease were measured on the index install.ps1 probed."""
+ guard = SETUP_SRC.index("if ($_woaMarkerIndex -ne $_woaHandoffIndex) {")
+ body = SETUP_SRC[guard : SETUP_SRC.index("$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX", guard)]
+ assert "Remove-Item Env:UNSLOTH_WOA_HAS_TORCHAUDIO" in body
+ assert "Remove-Item Env:UNSLOTH_WOA_TORCH_PRERELEASE" in body
+ assert guard < SETUP_SRC.index(
+ "$env:UNSLOTH_WOA_SELECTED_TORCH_INDEX = $_woaMarkerIndex"
+ ), "compared before the overwrite, or the two are always equal"
+
+
+class TestThePypiPyarrowWheelIsPinnedToo:
+ """ "PyPI has a compatible wheel" is not "the newest release is one". The probe cleared the
+ native route on a wheel it then forgot, and with just pyarrow>=21.0.0 in force uv takes the
+ newest release -- which, if it ships only an sdist for this interpreter, builds Arrow from
+ source, the outcome this preflight exists to prevent."""
+
+ def test_the_probe_records_what_it_matched(self):
+ body = slice_between(
+ INSTALL_SRC, "function Get-WoaPyarrowSource", "function Test-WoaNvidiaPresent"
+ )
+ assert (
+ "$script:WoaPyarrowWheelName = $match.Value" in body
+ ), "the PyPI branch returns without naming the wheel it cleared"
+ assert (
+ "$script:WoaPyarrowWheelName = $null" in body
+ ), "and it clears the name on entry, so a re-probe cannot inherit the first answer"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "body, expected_pin, why",
+ [
+ (
+ "pyarrow-24.0.0-cp313-cp313-win_arm64.whl",
+ "24.0.0",
+ "the wheel that cleared the route is the one pinned",
+ ),
+ (
+ "pyarrow-19.0.1-cp313-cp313-win_arm64.whl",
+ "",
+ "below the floor: nothing is cleared, so nothing is pinned",
+ ),
+ ],
+ )
+ def test_the_recorded_name_yields_the_pin(self, body, expected_pin, why):
+ script = pyarrow_source_script(
+ wheelhouse = "''",
+ rest_method = invoke_restmethod(body),
+ reaches_pypi = "$true",
+ tail = (
+ "$null = Get-WoaPyarrowSource -PythonMinor '3.13'",
+ # The emission, verbatim from the override block.
+ "$pin = ''",
+ "if ($script:WoaPyarrowWheelName -and $script:WoaPyarrowWheelName"
+ " -match '^pyarrow-([^-]+)-') {",
+ " $pin = $Matches[1] }",
+ "Write-Output ('[' + $pin + ']')",
+ ),
+ )
+ assert _ps_last(script, timeout = 180)[1:-1] == expected_pin, why
+
+ def test_the_override_is_emitted_for_every_source(self):
+ """The pin is keyed on the recorded name, which all three routes now set."""
+ assert INSTALL_SRC.count("$script:WoaPyarrowWheelName = ") == 6, (
+ "the script-level init, the per-probe reset, and one per source: pypi, the "
+ "supplied UNSLOTH_PYARROW_WHEEL, the wheelhouse directory, the wheelhouse index"
+ )
+
+
+class TestEveryPyarrowRouteOpensWhatItKeeps:
+ """Four ways in, and the last one was trusting a 200 response. A mirror can serve a truncated
+ body with a successful status, and this wheel decides the route and the exact pyarrow==
+ override, so an unreadable download kept native mode and then failed uv on the override."""
+
+ DOWNLOAD = "Invoke-WebRequest -Uri (Join-UrlPath $script:WoaWheelhouse $wheelName)"
+
+ def test_every_mandatory_route_validates(self):
+ """Staging opens the two files it chooses itself; the probe opens the other two. Staging
+ trusts the probe's answer for UNSLOTH_PYARROW_WHEEL, which is why that one is checked
+ there and not again here."""
+ block = slice_between(
+ INSTALL_SRC, 'if ($script:WoaPyarrowSource -eq "local") {', "$WoaExtraStaged = 0"
+ )
+ assert block.count("Test-ZipArchiveReadable") == 2, (
+ "the wheelhouse directory selection and the download: "
+ f"{block.count('Test-ZipArchiveReadable')}"
+ )
+ probe = slice_between(
+ INSTALL_SRC, "function Get-WoaPyarrowSource", "function Test-WoaNvidiaPresent"
+ )
+ assert probe.count("Test-ZipArchiveReadable") == 2, (
+ "the probe opens the supplied wheel and the local wheelhouse candidate before "
+ f"it clears the native route: {probe.count('Test-ZipArchiveReadable')}"
+ )
+
+ def test_a_bad_download_is_removed_not_left_in_the_cache(self):
+ start = INSTALL_SRC.index(self.DOWNLOAD)
+ block = INSTALL_SRC[start : start + 900]
+ assert "Remove-Item -LiteralPath $_woaPaDest" in block, (
+ "a corrupt wheel left in the managed directory is read by the resolver on "
+ "every later run, and by _find_links_wheel_versions as proof of availability"
+ )
+ assert block.index("Remove-Item") < block.index("throw"), "removed before it gives up"
+
+ def test_the_failure_falls_back_rather_than_continuing(self):
+ """It throws into the existing catch, which is what disables the native route."""
+ start = INSTALL_SRC.index(self.DOWNLOAD)
+ block = INSTALL_SRC[start : start + 1400]
+ assert "$script:WoaNativeCudaTorch = $false" in block
+ assert block.index("throw") < block.index("$script:WoaNativeCudaTorch = $false")
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "readable, expect_native, why",
+ [
+ (True, "True", "a readable download keeps the native route"),
+ (False, "False", "a truncated one gives it up rather than failing later"),
+ ],
+ )
+ def test_the_branch_end_to_end(self, tmp_path, readable, expect_native, why):
+ """Executed, because a source-level assertion cannot tell a live branch from a dead one,
+ and because the point is what is left on disk afterwards."""
+ import zipfile
+
+ served = tmp_path / "served.whl"
+ if readable:
+ with zipfile.ZipFile(served, "w") as archive:
+ archive.writestr("pyarrow/__init__.py", "")
+ else:
+ served.write_bytes(b"PK\x03\x04truncated")
+ wheel_dir = tmp_path / "wheels"
+ wheel_dir.mkdir()
+
+ branch = slice_between(
+ INSTALL_SRC,
+ " if ($wheelName) {",
+ " } else {\n $script:WoaNativeCudaTorch = $false",
+ )
+ script = _script(
+ SUBSTEP_NOOP,
+ JOIN_URL_RETURNS_PATH,
+ "function Invoke-WebRequest {",
+ " param([Parameter(ValueFromRemainingArguments=$true)]$a)",
+ f" Copy-Item -LiteralPath '{served.as_posix()}'"
+ " -Destination $a[$a.IndexOf('-OutFile') + 1] -Force }",
+ _ps_function(INSTALL_PS1, "Test-ZipArchiveReadable"),
+ f"$WoaWheelDir = '{wheel_dir.as_posix()}'",
+ "$script:WoaWheelhouse = 'https://mirror.test/wheels'",
+ "$script:WoaNativeCudaTorch = $true",
+ "$script:WoaPyarrowWheelName = $null",
+ "$wheelName = 'pyarrow-24.0.0-cp313-cp313-win_arm64.whl'",
+ # The slice stops before the "} else {", so that closing brace is not in it.
+ branch + "\n }",
+ "Write-Output ('[' + [bool]$script:WoaNativeCudaTorch + ']')",
+ )
+ assert _ps_last(script, timeout = 180)[1:-1] == expect_native, why
+ staged = list(wheel_dir.glob("*.whl"))
+ assert (
+ bool(staged) is readable
+ ), f"a rejected wheel must not stay in the managed directory: {staged}"
+
+
+class TestAnExplicitPinIsPersistedWithoutAnOldRecord:
+ """The persistence block was gated on the WoA chain alone. A native venv installed through a
+ credentialed mirror has nothing to recover, so the chain is empty; pin UNSLOTH_TORCH_INDEX_URL
+ at an NVIDIA channel on a later direct update and the torch install used it while the guard
+ skipped both records, leaving the next fresh shell on an index with no win_arm64 wheel."""
+
+ def test_either_record_opens_the_block(self):
+ assert "if ($WinArm64TorchIndexUrl -or $_woaPinnedIndex) {" in SETUP_SRC
+
+ def test_the_pin_is_only_consulted_on_a_native_venv(self):
+ """Every other host must reach the block exactly as it did before."""
+ assert (
+ "$_woaPinnedIndex = if ($WinArm64Venv) { Get-PinnedTorchIndexUrl } else { $null }"
+ in SETUP_SRC
+ )
+
+ def test_the_pin_is_resolved_once(self):
+ """Two reads of the getter are two chances to disagree about what was installed."""
+ assert "$_woaMarkerIndex = $_woaPinnedIndex" in SETUP_SRC
+ opens = SETUP_SRC.index("if ($WinArm64TorchIndexUrl -or $_woaPinnedIndex) {")
+ closes = SETUP_SRC.index("Restore-WoaResolverEnvironment", opens)
+ assert (
+ "Get-PinnedTorchIndexUrl" not in SETUP_SRC[opens:closes]
+ ), "the block calls the getter again instead of using the value the guard tested"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "pinned, chain, expected, why",
+ [
+ (NV_GA, "", NV_GA, "nothing to recover, but the pin is what the install used"),
+ ("", NV_GA, NV_GA, "no pin: the recovered chain, exactly as before"),
+ ("", "", "", "neither: the block does not run at all"),
+ ],
+ )
+ def test_what_the_guard_lets_through(self, tmp_path, pinned, chain, expected, why):
+ script = _script(
+ f"$StudioHome = '{tmp_path}'",
+ "$WinArm64Venv = $true",
+ f"function Get-PinnedTorchIndexUrl {{ return '{pinned}' }}",
+ f"$WinArm64TorchIndexUrl = '{chain}'",
+ "$_woaHandoffIndex = ''",
+ MARKER_FUNCS,
+ _persistence_block(SETUP_SRC),
+ "Write-Output ('[' + $env:UNSLOTH_WOA_SELECTED_TORCH_INDEX + ']')",
+ )
+ assert _ps_last(script)[1:-1] == expected, why
+
+
+class TestTheProbedCudaWheelIsWhatGetsInstalled:
+ """A floor plus unsafe-best-match is not a request for the wheel that was probed: uv selects
+ the best version from the combined candidate set of every index, and the PyPI extra index is
+ there because NVIDIA's channel publishes only the trio. So the moment PyPI's stable win_arm64
+ CPU torch is one release ahead, `torch>=2.4` takes it and the native GPU path is replaced by a
+ CPU build that imports perfectly."""
+
+ @staticmethod
+ def _block() -> str:
+ # Anchored on the code that follows rather than on its comment.
+ return slice_between(
+ INSTALL_SRC,
+ 'if ($script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64") {',
+ "if ($script:PrevTorchPin -and $script:WoaNativeCudaTorch -and $VenvPlatform -eq"
+ ' "win-arm64") {',
+ )
+
+ def test_the_trio_is_pinned_to_the_probed_versions(self):
+ block = self._block()
+ for spec in (
+ '"torch==$($script:WoaTorchWheelVersion)"',
+ '"torchvision==$($script:WoaVisionWheelVersion)"',
+ '"torchaudio==$($script:WoaAudioWheelVersion)"',
+ ):
+ assert spec in block, f"{spec} is not what gets installed"
+
+ def test_an_unreadable_version_keeps_the_old_floor(self):
+ """Strictly better than before is the bar; no worse is the floor."""
+ block = self._block()
+ assert 'else { "torch>=2.4" }' in block
+ assert 'else { "torchvision>=0.19" }' in block
+ assert 'else { "torchaudio>=2.4" }' in block
+
+ def test_the_versions_come_from_the_probe(self):
+ for name in ("WoaTorchWheelVersion", "WoaAudioWheelVersion", "WoaVisionWheelVersion"):
+ assert f"$script:{name} = " in INSTALL_SRC, f"{name} is never set"
+ assert '-Project "torchvision"' in INSTALL_SRC, "torchvision is never probed"
+
+ def test_the_pin_is_set_before_the_install_reads_it(self):
+ assert INSTALL_SRC.index("$script:WoaVisionWheelVersion = ") < INSTALL_SRC.index(
+ '"torchvision==$($script:WoaVisionWheelVersion)"'
+ )
+
+ def test_audio_still_needs_the_pairing(self):
+ """The exact pin does not replace Test-WoaAudioMatchesTorch: a paired version is what
+ makes torchaudio installable at all, and this only fixes which one lands."""
+ block = self._block()
+ assert "if ($script:WoaTorchAudio) {" in block[: block.index("torchaudio==")]
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "torch_v, vision_v, audio_v, has_audio, expected, why",
+ [
+ (
+ "2.15.0.dev20260101+cu134",
+ "0.26.0.dev20260101+cu134",
+ "2.11.0+cu134",
+ "$true",
+ "torch==2.15.0.dev20260101+cu134 torchvision==0.26.0.dev20260101+cu134"
+ " torchaudio==2.11.0+cu134",
+ "every probed version pinned, local tag included",
+ ),
+ (
+ "2.14.0+cu134",
+ "0.25.0+cu134",
+ "",
+ "$false",
+ "torch==2.14.0+cu134 torchvision==0.25.0+cu134",
+ "no paired audio: the trio is a pair, as before",
+ ),
+ (
+ "",
+ "",
+ "",
+ "$false",
+ "torch>=2.4 torchvision>=0.19",
+ "nothing readable: exactly the specs this used to send",
+ ),
+ (
+ "2.14.0+cu134",
+ "",
+ "",
+ "$false",
+ "torch==2.14.0+cu134 torchvision>=0.19",
+ "a half-readable probe pins what it read and floors the rest",
+ ),
+ ],
+ )
+ def test_what_the_specs_come_out_as(self, torch_v, vision_v, audio_v, has_audio, expected, why):
+ script = _script(
+ SUBSTEP_NOOP,
+ '$VenvPlatform = "win-arm64"',
+ "$script:WoaNativeCudaTorch = $true",
+ f"$script:WoaTorchWheelVersion = '{torch_v}'",
+ f"$script:WoaVisionWheelVersion = '{vision_v}'",
+ f"$script:WoaAudioWheelVersion = '{audio_v}'",
+ f"$script:WoaTorchAudio = {has_audio}",
+ "$script:WoaTorchIsPrerelease = $false",
+ f"$script:WoaTorchIndexUrl = '{NV_GA}'",
+ self._block(),
+ "Write-Output ($_torchSpecs -join ' ')",
+ )
+ assert _ps_last(script) == expected, why
+
+
+class TestTheCompanionWheelsArePairedWithTorch:
+ """Newest-of-each is not a pair on a channel that publishes on separate schedules. NVIDIA's
+ nightly channel stamps each project independently and nightly torchvision metadata pins its
+ exact torch, so maximizing the two separately and pinning both exactly can name a pair no
+ index can satisfy -- after the installer has committed to the ARM64 path."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "torch_v, other_v, pairs, why",
+ [
+ ("2.15.0.dev20260101+cu134", "0.26.0.dev20260101+cu134", True, "same stamp and tag"),
+ ("2.15.0.dev20260101+cu134", "0.26.0.dev20260102+cu134", False, "staggered nightly"),
+ ("2.15.0.dev20260101+cu134", "0.26.0+cu134", False, "a release is not that build"),
+ ("2.14.0+cu134", "0.29.0+cu134", True, "GA: torchvision 0.(M+15) pairs with torch 2.M"),
+ ("2.14.0+cu134", "0.25.0+cu134", False, "GA, same tag, another release line"),
+ ("2.14.0+cu134", "0.29.0+cu130", False, "a different CUDA build"),
+ ("2.14.0+cu134", "", False, "nothing to pair with"),
+ ],
+ )
+ def test_what_counts_as_a_pair(self, torch_v, other_v, pairs, why):
+ script = _script(
+ _ps_function(INSTALL_PS1, "Test-WoaWheelPairsWithTorch"),
+ f"Write-Output (Test-WoaWheelPairsWithTorch -TorchVersion '{torch_v}'"
+ f" -OtherVersion '{other_v}')",
+ )
+ assert (_ps_last(script) == "True") is pairs, why
+
+ def test_both_companions_are_probed_as_a_pair(self):
+ for project in ("torchvision", "torchaudio"):
+ line = [
+ l
+ for l in INSTALL_SRC.splitlines()
+ if f'-Project "{project}"' in l and "Get-WoaCudaWheelVersion" in l
+ ]
+ assert line, f"{project} is not probed"
+ assert all(
+ "-PairWith $_woaTorchVersion" in l for l in line
+ ), f"{project} is still maximized independently of torch"
+
+ def test_an_unpaired_torchvision_is_a_gate_not_a_floor(self):
+ """A pin the index cannot satisfy is worse than the floor it replaced, and the floor
+ resolved against the wrong torch: the pairing now decides whether the index is used at
+ all, so the trio only ever sees a paired pin."""
+ fn = _function_source(INSTALL_SRC, "Initialize-WoaNativeCudaTorch")
+ assert "if (-not $_woaVisionVersion) {" in fn
+ assert "$script:WoaVisionWheelVersion = $_woaVisionVersion" in fn
+
+
+class TestTheRepairPathPinsTheSameWayTheInstallDoes:
+ """setup.ps1's forced repair carries the same flags, so it had the same defect: those specs
+ are resolved with unsafe-best-match against a public PyPI extra index, and the repair replaces
+ the CUDA stack with CPU wheels the moment PyPI is one release ahead."""
+
+ def test_the_repair_probes_the_effective_index(self):
+ assert "if ($WinArm64Venv -and $WinArm64EffectiveTorchIndexUrl) {" in SETUP_SRC
+ assert '$WinArm64TorchSpec = "torch==$_woaTorchV"' in SETUP_SRC
+
+ def test_the_companions_are_paired_here_too(self):
+ for project in ("torchvision", "torchaudio"):
+ assert f'-Project "{project}" -PairWith $_woaTorchV' in SETUP_SRC
+
+ def test_an_unanswered_index_leaves_every_spec_alone(self):
+ """Best effort: no probe, no change, which is exactly today's behaviour."""
+ block = slice_between(SETUP_SRC, '$WinArm64TorchSpec = "torch>=2.4"', "$_tritonSpec = ")
+ assert block.index('"torch>=2.4"') < block.index(
+ "Get-WoaCudaWheelVersionParity"
+ ), "the floor must be the default the probe overrides, not the other way round"
+ assert "if ($_woaTorchV) {" in block, "an empty probe must not pin anything"
+
+ @pytest.mark.parametrize(
+ "install_fn, setup_fn",
+ [
+ ("Test-WoaWheelTags", "Test-WoaWheelTagsParity"),
+ ("Test-WoaWheelPairsWithTorch", "Test-WoaPairsWithTorchParity"),
+ ],
+ )
+ def test_the_parity_copies_have_not_drifted(self, install_fn, setup_fn):
+ """Two copies of a rule is two chances for one of them to be wrong."""
+ original = _ps_function(INSTALL_PS1, install_fn)
+ copy = _function_source(SETUP_SRC, setup_fn)
+
+ def body(text: str) -> list:
+ lines = text.split("\n")[1:]
+ return [l.strip() for l in lines if l.strip() and not l.strip().startswith("#")]
+
+ assert body(original) == body(copy), f"{setup_fn} has drifted from {install_fn}"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "pair_with, expected, why",
+ [
+ ("", "0.26.0.dev20260102+cu134", "unpaired: the newest wheel on the index"),
+ (
+ "2.15.0.dev20260101+cu134",
+ "0.26.0.dev20260101+cu134",
+ "paired: the newest wheel from THIS torch build, not the newest overall",
+ ),
+ ("2.15.0.dev20251231+cu134", "", "no wheel from that build: nothing to pin"),
+ ],
+ )
+ def test_the_parity_probe_pairs_when_asked(self, pair_with, expected, why):
+ """The signatures differ, so the whole-body comparison above cannot cover this one:
+ dropping the filter here leaves setup.ps1 pinning an unpairable companion."""
+ listing = " ".join(
+ f'<a href="{name}">{name}</a>'
+ for name in (
+ "torchvision-0.26.0.dev20260101%2Bcu134-cp313-cp313-win_arm64.whl",
+ "torchvision-0.26.0.dev20260102%2Bcu134-cp313-cp313-win_arm64.whl",
+ # NEWER, and tagged for another interpreter: it must lose on the tag alone.
+ "torchvision-0.27.0.dev20260103%2Bcu134-cp312-cp312-win_arm64.whl",
+ )
+ )
+ script = _script(
+ invoke_restmethod(listing),
+ functions(
+ SETUP_SRC,
+ "Test-WoaWheelTagsParity",
+ "Test-WoaPairsWithTorchParity",
+ "Get-WoaCudaWheelVersionParity",
+ ),
+ f"$v = Get-WoaCudaWheelVersionParity -IndexUrl '{NV_GA}'"
+ f" -PyTag 'cp313' -AbiTag 'cp313' -Project 'torchvision' -PairWith '{pair_with}'",
+ "Write-Output ('[' + $v + ']')",
+ )
+ assert _ps_last(script)[1:-1] == expected, why
+
+
+class TestTheOverrideFileDoesNotOutrankTheTorchPin:
+ """uv's --overrides replace a version even for a requirement named on the command line
+ (verified against uv 0.10.7). The generated file carries torch>=2.4 and torchvision>=0.19, so
+ it discarded the exact CUDA pins the probe had just selected and best-match took PyPI's newer
+ CPU wheel."""
+
+ SWAP = "$_woaStep = New-WoaTorchStepOverrideValue -Value $_woaOverrideSaved"
+
+ def test_the_trio_is_dropped_for_that_one_command(self):
+ assert "function New-WoaTorchStepOverrideValue {" in INSTALL_SRC
+ body = _ps_function(INSTALL_PS1, "New-WoaTorchStepOverrideValue")
+ assert '@("torch", "torchvision", "torchaudio") -contains $name' in body
+
+ def test_it_is_applied_around_the_native_install_only(self):
+ swap = INSTALL_SRC.index(self.SWAP)
+ guard = INSTALL_SRC.rindex(
+ 'if ($script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64" -and'
+ " $env:UV_OVERRIDE) {",
+ 0,
+ swap,
+ )
+ assert guard < swap, "every other host must keep the overrides it had"
+
+ def test_the_original_value_is_restored(self):
+ """The later unsloth resolve still needs the drop list."""
+ swap = INSTALL_SRC.index(self.SWAP)
+ tail = INSTALL_SRC[swap : swap + 2600]
+ assert "} finally {" in tail
+ assert "if ($_woaOverrideSwapped) { $env:UV_OVERRIDE = $_woaOverrideSaved }" in tail
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "lines, expect_kept, why",
+ [
+ (
+ ["torch>=2.4", "torchvision>=0.19", 'hf-transfer ; platform_machine == "AMD64"'],
+ ["hf-transfer"],
+ "the trio goes, the drop list stays",
+ ),
+ (
+ ['hf-transfer ; platform_machine == "AMD64"', "pyarrow==21.0.0"],
+ ["hf-transfer", "pyarrow"],
+ "nothing to drop: the file is passed through untouched",
+ ),
+ (
+ ["torch_geometric>=2.0"],
+ ["torch_geometric"],
+ "a different package that starts with torch",
+ ),
+ ],
+ )
+ def test_what_survives_the_filter(self, tmp_path, lines, expect_kept, why):
+ src = tmp_path / "ovr.txt"
+ src.write_text("\n".join(lines) + "\n", encoding = "utf-8")
+ script = _script(
+ UV_SAFE_PATH,
+ functions(
+ INSTALL_SRC,
+ "Get-WoaRequirementEntries",
+ "Resolve-WoaOverrideLine",
+ "New-WoaTorchStepOverrideValue",
+ ),
+ f"$v = (New-WoaTorchStepOverrideValue -Value '{src}' -Dir '{tmp_path}').Value",
+ "Get-Content -LiteralPath $v | ForEach-Object { Write-Output $_ }",
+ )
+ out = _ps_ok(script).stdout
+ for name in expect_kept:
+ assert name in out, f"{name} was dropped: {why}"
+ for name in ("torch>=", "torchvision>=", "torchaudio>="):
+ assert name not in out, f"{name} survived: {why}"
+
+
+class TestATransientProbeFailureKeepsTheCudaBundle:
+ """nvidia-smi is a probe, and one that did not answer is not evidence the GPU is gone. During
+ a direct update of a native ARM64 CUDA install, a transiently missing nvidia-smi dropped
+ windows-arm64-cuda from the expected kinds, deleted the working llama.cpp tree, and ran the
+ selector with no NVIDIA evidence, which installs the CPU bundle instead."""
+
+ def test_the_persisted_cuda_index_counts_as_evidence(self):
+ assert "$_nvidiaEvidence = $HasNvidiaSmi -or ((Test-WinArm64Venv)" in SETUP_SRC
+ assert "elseif ($_nvidiaEvidence) { $_nvidiaKinds }" in SETUP_SRC
+
+ def test_only_a_persistable_index_counts(self):
+ """Test-WoaPersistableIndex passes only NVIDIA's own channels, so a /cpu pin cannot claim
+ to be NVIDIA evidence."""
+ start = SETUP_SRC.index("$_nvidiaEvidence = ")
+ assert "Test-WoaPersistableIndex $_woaEvidenceIndex" in SETUP_SRC[start : start + 400]
+
+ def test_rocm_still_wins_the_branch(self):
+ """The ROCm arm is first and unchanged: this only widens the NVIDIA one."""
+ line = [l for l in SETUP_SRC.splitlines() if "$expectedKinds = if (" in l][0]
+ assert line.index("$HasROCm") < line.index("$_nvidiaEvidence")
+
+
+class TestStableCompanionsPairByReleaseLine:
+ """Every stable release has an empty dev stamp, so the CUDA tag alone paired a companion from
+ any release the index still served and the exact-pin install then asked for a pair that does
+ not exist. torchvision 0.(M+15) requires torch 2.M exactly (PyPI metadata: 0.25.0 ->
+ torch==2.10.0, 0.19.0 -> torch==2.4.0); torchaudio agrees on major.minor."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "project, torch_v, other_v, pairs, why",
+ [
+ ("torchvision", "2.10.0+cu134", "0.25.0+cu134", True, "the PyPI-documented pair"),
+ ("torchvision", "2.10.0+cu134", "0.26.0+cu134", False, "the next GA, published early"),
+ (
+ "torchvision",
+ "2.10.0+cu134",
+ "0.24.0+cu134",
+ False,
+ "the previous one, still served",
+ ),
+ ("torchaudio", "2.10.0+cu134", "2.10.1+cu134", True, "audio: major.minor"),
+ ("torchaudio", "2.14.0+cu134", "2.11.0+cu134", False, "the GA mismatch round 9 found"),
+ (
+ "torchvision",
+ "2.15.0.dev20260101+cu134",
+ "0.30.0.dev20260101+cu134",
+ True,
+ "nightly: the stamp still decides",
+ ),
+ (
+ "torchvision",
+ "2.15.0.dev20260101+cu134",
+ "0.26.0.dev20260101+cu134",
+ True,
+ "nightly: the release offset is NOT applied to a stamped build",
+ ),
+ ],
+ )
+ def test_the_pairing(self, project, torch_v, other_v, pairs, why):
+ script = _script(
+ _ps_function(INSTALL_PS1, "Test-WoaWheelPairsWithTorch"),
+ f"Write-Output (Test-WoaWheelPairsWithTorch -TorchVersion '{torch_v}'"
+ f" -OtherVersion '{other_v}' -Project '{project}')",
+ )
+ assert (_ps_last(script) == "True") is pairs, why
+
+ def test_the_probe_passes_the_project_through(self):
+ for path, fn in (
+ (INSTALL_PS1, "Test-WoaWheelPairsWithTorch"),
+ (SETUP_PS1, "Test-WoaPairsWithTorchParity"),
+ ):
+ text = path.read_text(encoding = "utf-8")
+ assert (
+ f"{fn} -TorchVersion $PairWith -OtherVersion $version -Project $Project" in text
+ ), path.name
+
+
+class TestTheFilteredOverrideIsUvSafeAndShortLived:
+ """GetTempFileName() lands in %TEMP%, which follows the profile: a spaced one produced a quoted
+ path in UV_OVERRIDE, and uv rejects quoting there, so the torch command failed before
+ installing anything. And the copies were never deleted, and a flattened caller file can carry
+ an authenticated URL."""
+
+ @requires_pwsh
+ def test_the_copy_lands_in_the_given_directory_and_is_reported(self, tmp_path):
+ src = tmp_path / "ovr.txt"
+ src.write_text('torch>=2.4\nhf-transfer ; platform_machine == "AMD64"\n', encoding = "utf-8")
+ woa = tmp_path / "woa"
+ woa.mkdir()
+ script = _script(
+ UV_SAFE_PATH,
+ functions(
+ INSTALL_SRC,
+ "Get-WoaRequirementEntries",
+ "Resolve-WoaOverrideLine",
+ "New-WoaTorchStepOverrideValue",
+ ),
+ f"$r = New-WoaTorchStepOverrideValue -Value '{src}' -Dir '{woa}'",
+ "Write-Output ('VALUE=' + $r.Value)",
+ "Write-Output ('TEMPS=' + ($r.Temps -join ';'))",
+ )
+ out = _ps_kv(script)
+ assert out["TEMPS"], "the created copy is not reported, so nothing can delete it"
+ assert out["TEMPS"].startswith(str(woa)), "the copy must live under the uv-safe directory"
+ assert out["VALUE"] == out["TEMPS"]
+
+ def test_every_path_goes_through_the_uv_safe_helper(self):
+ body = _ps_function(INSTALL_PS1, "New-WoaTorchStepOverrideValue")
+ assert "$safe = foreach ($f in $files) { Get-UvSafePath $f }" in body
+
+ def test_the_caller_deletes_the_copies_on_every_exit(self):
+ swap = INSTALL_SRC.index(
+ "New-WoaTorchStepOverrideValue -Value $_woaOverrideSaved -Dir $script:WoaDir"
+ )
+ tail = INSTALL_SRC[swap : swap + 2600]
+ fin = tail.index("} finally {")
+ assert (
+ "foreach ($_woaTmp in $_woaOverrideTemps) { Remove-Item -LiteralPath $_woaTmp"
+ in tail[fin:]
+ )
+
+ def test_the_woa_directory_is_published_to_script_scope(self):
+ assert "$script:WoaDir = $WoaDir" in INSTALL_SRC
+
+
+class TestSetupSwapsTheOverrideAroundItsOwnTorchInstall:
+ """Restore-WoaResolverEnvironment puts the generated overrides.txt back before setup's CUDA
+ trio is installed, so the same floors undid the same exact pins there."""
+
+ def test_the_swap_wraps_the_install_and_restores_in_finally(self):
+ restore = SETUP_SRC.index("\nRestore-WoaResolverEnvironment")
+ swap = SETUP_SRC.index("New-WoaTorchStepOverrideValueParity -Value $_woaStepSaved")
+ assert (
+ restore < swap
+ ), "the swap must come after the overrides are restored, or it swaps nothing"
+ tail = SETUP_SRC[swap : swap + 3000]
+ assert "Fast-Install @_cudaTrio" in tail
+ fin = tail.index("} finally {")
+ assert "if ($_woaStepSwapped) { $env:UV_OVERRIDE = $_woaStepSaved }" in tail[fin:]
+ assert (
+ "foreach ($_woaTmp in $_woaStepTemps) { Remove-Item -LiteralPath $_woaTmp" in tail[fin:]
+ )
+
+ def test_only_a_native_venv_swaps(self):
+ assert "if ($WinArm64Venv -and $env:UV_OVERRIDE) {" in SETUP_SRC
+
+ @requires_pwsh
+ def test_the_parity_helper_drops_the_trio(self, tmp_path):
+ src = tmp_path / "ovr.txt"
+ src.write_text("torch>=2.4\ntorchvision>=0.19\npyarrow==21.0.0\n", encoding = "utf-8")
+ script = _script(
+ UV_SAFE_PATH,
+ functions(
+ SETUP_SRC,
+ "Get-RequirementEntries",
+ "Resolve-WoaOverrideLine",
+ "New-WoaTorchStepOverrideValueParity",
+ ),
+ f"$r = New-WoaTorchStepOverrideValueParity -Value '{src}' -Dir '{tmp_path}'",
+ "Get-Content -LiteralPath $r.Value | ForEach-Object { Write-Output $_ }",
+ )
+ lines = [l for l in _ps_ok(script).stdout.splitlines() if l.strip()]
+ assert lines == ["pyarrow==21.0.0"], lines
+
+
+class TestNvidiaEvidenceSurvivesTheFastPath:
+ """When the manifest verifies, $SkipPythonDeps skips the whole dependency block, so
+ $WinArm64EffectiveTorchIndexUrl is never set and the llama.cpp check read "no evidence": a
+ transient nvidia-smi failure on a no-op update then deleted the working CUDA bundle."""
+
+ def test_the_index_is_read_at_the_check_when_the_pass_did_not_run(self):
+ block = slice_between(
+ SETUP_SRC,
+ "$_woaEvidenceIndex = if ($WinArm64EffectiveTorchIndexUrl)",
+ "$_nvidiaEvidence = ",
+ )
+ assert "Get-PinnedTorchIndexUrl" in block
+ assert "Get-PersistedWoaTorchIndex -VenvPath $VenvDir" in block
+ assert "Get-WoaTorchIndexMarker" in block
+ assert (
+ block.index("Get-PinnedTorchIndexUrl")
+ < block.index("Get-PersistedWoaTorchIndex")
+ < block.index("Get-WoaTorchIndexMarker")
+ ), "same order as the dependency pass"
+
+ def test_the_evidence_uses_that_index(self):
+ assert "(Test-WinArm64Venv) -and $_woaEvidenceIndex -and" in SETUP_SRC
+ assert "Test-WoaPersistableIndex $_woaEvidenceIndex" in SETUP_SRC
+
+ def test_the_check_sits_outside_the_dependency_guard(self):
+ """The premise: if it were inside, the fast path would never reach it at all."""
+ guard = SETUP_SRC.index("\nif (-not $SkipPythonDeps) {")
+ depth = 0
+ for i in range(guard + 1, len(SETUP_SRC)):
+ depth += (SETUP_SRC[i] == "{") - (SETUP_SRC[i] == "}")
+ if depth == 0:
+ break
+ assert SETUP_SRC.index("$_nvidiaEvidence = ") > i
+
+
+def _uv_toml(body: str, where: str = "proj/uv.toml") -> dict:
+ """One configuration file, written where uv would discover it."""
+ return {where: body}
+
+
+class TestThePyPIProbeHonoursUvConfiguration:
+ """A direct HTTP probe can see pypi.org while uv, under a uv.toml with no-index or an
+ exclusive default-index, cannot. "pypi" then skipped a usable wheelhouse wheel for one the
+ resolve would never fetch."""
+
+ def test_the_pyarrow_probe_is_gated(self):
+ probe = INSTALL_SRC.index('Invoke-RestMethod -Uri "https://pypi.org/simple/pyarrow/"')
+ assert "if (Test-WoaResolveReachesPyPI) { try {" in INSTALL_SRC[probe - 400 : probe]
+
+ @staticmethod
+ def _reaches(tmp_path, files: dict, env: dict) -> str:
+ for name, body in files.items():
+ (tmp_path / name).parent.mkdir(parents = True, exist_ok = True)
+ (tmp_path / name).write_text(body, encoding = "utf-8")
+ script = _script(
+ clear_env(UV_POLICY_ENV),
+ f"$env:APPDATA = '{tmp_path / 'appdata'}'",
+ f"$env:ProgramData = '{tmp_path / 'programdata'}'",
+ f"Set-Location -LiteralPath '{tmp_path / 'proj'}'",
+ "\n".join(f"$env:{k} = '{v}'" for k, v in env.items()),
+ # Read-WoaUvTomlIndexKeys scans for quotes, so its two scanners come with it.
+ functions(
+ INSTALL_SRC,
+ "Test-WoaUrlIsPublicPyPI",
+ "Remove-WoaTomlComment",
+ "Split-WoaTomlKey",
+ "Read-WoaUvTomlIndexKeys",
+ "Get-WoaUvConfigIndexPolicy",
+ "Test-WoaResolveReachesPyPI",
+ ),
+ "Write-Output (Test-WoaResolveReachesPyPI)",
+ )
+ (tmp_path / "proj").mkdir(exist_ok = True)
+ return _ps_last(script)
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "files, env, expected, why",
+ [
+ ({}, {}, "True", "nothing configured: PyPI"),
+ (_uv_toml("no-index = true\n"), {}, "False", "project uv.toml no-index"),
+ (_uv_toml(f'default-index = "{CORP_INDEX}"\n'), {}, "False", "exclusive default-index"),
+ (_uv_toml(f'index-url = "{CORP_INDEX}"\n'), {}, "False", "the older spelling"),
+ (_uv_toml("[pip]\nno-index = true\n"), {}, "False", "under [pip], which uv pip reads"),
+ (
+ _uv_toml(f'[[index]]\nurl = "{CORP_INDEX}"\ndefault = true\n'),
+ {},
+ "False",
+ "an [[index]] with default = true replaces PyPI",
+ ),
+ (
+ _uv_toml(f'[[index]]\nurl = "{CORP_INDEX}"\n'),
+ {},
+ "True",
+ "an extra index leaves PyPI in play",
+ ),
+ (
+ _uv_toml("[tool.uv]\nno-index = true\n", "proj/pyproject.toml"),
+ {},
+ "False",
+ "pyproject [tool.uv]",
+ ),
+ (
+ _uv_toml('[project]\nname = "x"\n', "proj/pyproject.toml"),
+ {},
+ "True",
+ "a pyproject without [tool.uv] is ignored",
+ ),
+ (_uv_toml("no-index = true\n", "uv.toml"), {}, "False", "found in a parent directory"),
+ (
+ _uv_toml("no-index = true\n", "appdata/uv/uv.toml"),
+ {},
+ "False",
+ "the user file",
+ ),
+ (
+ {
+ **_uv_toml("no-index = false\n"),
+ **_uv_toml("no-index = true\n", "appdata/uv/uv.toml"),
+ },
+ {},
+ "True",
+ "project outranks user for a scalar",
+ ),
+ (
+ _uv_toml("no-index = true\n"),
+ {"UV_NO_CONFIG": "1"},
+ "True",
+ "UV_NO_CONFIG discovers nothing",
+ ),
+ (
+ _uv_toml("no-index = true\n"),
+ {"UV_DEFAULT_INDEX": PYPI},
+ "True",
+ "an index in the environment outranks every file",
+ ),
+ (
+ _uv_toml("no-index = true\n", "other.toml"),
+ {"UV_CONFIG_FILE": "__TMP__/other.toml"},
+ "False",
+ "UV_CONFIG_FILE names the one file read",
+ ),
+ (
+ _uv_toml(f'index = [{{ url = "{CORP_INDEX}", default = true }}]\n'),
+ {},
+ "False",
+ "an inline table this parser does not model is not guessed at",
+ ),
+ # The host, not a substring: a lookalike that merely contains the name is not PyPI.
+ (
+ {},
+ {"UV_DEFAULT_INDEX": "https://pypi.org.corp.example/simple"},
+ "False",
+ "a subdomain lookalike in the environment",
+ ),
+ (
+ {},
+ {"UV_DEFAULT_INDEX": "https://packages.example/api/pypi/pypi.org/simple"},
+ "False",
+ "the name in the path",
+ ),
+ ({}, {"UV_INDEX_URL": "HTTPS://PYPI.ORG/simple/"}, "True", "case does not matter"),
+ (
+ {},
+ {"UV_INDEX_URL": "https://user:[email protected]/simple"},
+ "True",
+ "credentials do not hide the host",
+ ),
+ (
+ {},
+ {"PIP_INDEX_URL": CORP_INDEX},
+ "True",
+ "pip's variable: uv, which resolves here, never reads it",
+ ),
+ (
+ {},
+ {"UV_INDEX_URL": CORP_INDEX, "PIP_EXTRA_INDEX_URL": PYPI},
+ "False",
+ "a pip extra does not put PyPI back for uv",
+ ),
+ ({}, {"UV_NO_INDEX": "1"}, "False", "uv's no-index"),
+ (
+ {},
+ {"UV_DEFAULT_INDEX": "https://test.pypi.org/simple"},
+ "False",
+ "TestPyPI does not carry these packages",
+ ),
+ (
+ _uv_toml('default-index = "https://pypi.org.corp.example/simple"\n'),
+ {},
+ "False",
+ "a subdomain lookalike in a config file",
+ ),
+ (
+ _uv_toml(f'default-index = "{PYPI}"\n'),
+ {},
+ "True",
+ "public PyPI named explicitly in a config file",
+ ),
+ # uv pip 0.10.7: [pip] scalars outrank top-level whatever the file order, and an
+ # [[index]] with default = true outranks [pip].index-url.
+ (
+ _uv_toml("no-index = false\n[pip]\nno-index = true\n"),
+ {},
+ "False",
+ "[pip].no-index = true beats the top-level false",
+ ),
+ (
+ _uv_toml("no-index = true\n[pip]\nno-index = false\n"),
+ {},
+ "True",
+ "[pip].no-index = false beats the top-level true",
+ ),
+ (
+ _uv_toml("[pip]\nno-index = true\n\n[other]\nx = 1\nno-index = false\n"),
+ {},
+ "False",
+ "a later section does not reopen the top level",
+ ),
+ (
+ _uv_toml(f'index-url = "{PYPI}"\n[pip]\nindex-url = "{CORP_INDEX}"\n'),
+ {},
+ "False",
+ "[pip].index-url beats the top-level index-url",
+ ),
+ (
+ _uv_toml(f'index-url = "{CORP_INDEX}"\n[pip]\nindex-url = "{PYPI}"\n'),
+ {},
+ "True",
+ "the other way round",
+ ),
+ (
+ _uv_toml(
+ f'[[index]]\nurl = "{CORP_INDEX}"\ndefault = true\n'
+ f'[pip]\nindex-url = "{PYPI}"\n'
+ ),
+ {},
+ "False",
+ "[[index]] default = true beats [pip].index-url",
+ ),
+ (
+ _uv_toml(
+ f'[pip]\nindex-url = "{CORP_INDEX}"\n'
+ f'[[index]]\nurl = "{PYPI}"\ndefault = true\n'
+ ),
+ {},
+ "True",
+ "and still does when it comes later in the file",
+ ),
+ (
+ _uv_toml(f'no-index = true\n[pip]\nindex-url = "{PYPI}"\n'),
+ {},
+ "False",
+ "no-index disables every registry, [pip].index-url included",
+ ),
+ (
+ _uv_toml(
+ "[tool.uv]\nno-index = false\n[tool.uv.pip]\nno-index = true\n",
+ "proj/pyproject.toml",
+ ),
+ {},
+ "False",
+ "the same under [tool.uv.pip]",
+ ),
+ # An extra index adds to the default rather than replacing it, so PyPI named as one
+ # is consulted.
+ (
+ {},
+ {"UV_INDEX_URL": CORP_INDEX, "UV_EXTRA_INDEX_URL": PYPI},
+ "True",
+ "UV_EXTRA_INDEX_URL names PyPI beside a corporate default",
+ ),
+ (
+ {},
+ {"UV_DEFAULT_INDEX": CORP_INDEX, "UV_INDEX": f"https://mirror.test/simple {PYPI}"},
+ "True",
+ "UV_INDEX, space-separated",
+ ),
+ (
+ {},
+ {"PIP_INDEX_URL": CORP_INDEX, "PIP_EXTRA_INDEX_URL": PYPI},
+ "True",
+ "pip's spelling",
+ ),
+ (
+ {},
+ {
+ "UV_INDEX_URL": CORP_INDEX,
+ "UV_EXTRA_INDEX_URL": "https://pypi.org.corp.example/simple",
+ },
+ "False",
+ "an extra that is not PyPI changes nothing",
+ ),
+ (
+ _uv_toml(f'index-url = "{CORP_INDEX}"\nextra-index-url = ["{PYPI}"]\n'),
+ {},
+ "True",
+ "extra-index-url in a config file",
+ ),
+ (
+ _uv_toml(
+ f'[[index]]\nurl = "{CORP_INDEX}"\ndefault = true\n\n'
+ f'[[index]]\nurl = "{PYPI}"\n'
+ ),
+ {},
+ "True",
+ "a second [[index]] without default = true is an extra",
+ ),
+ (
+ _uv_toml(f'no-index = true\nextra-index-url = ["{PYPI}"]\n'),
+ {},
+ "False",
+ "no-index disables extras too",
+ ),
+ (
+ _uv_toml(f'index-url = "{CORP_INDEX}"\n[pip]\nextra-index-url = ["{PYPI}"]\n'),
+ {},
+ "True",
+ "under [pip]",
+ ),
+ ],
+ )
+ def test_where_the_resolve_will_look(self, tmp_path, files, env, expected, why):
+ env = {k: v.replace("__TMP__", str(tmp_path)) for k, v in env.items()}
+ assert self._reaches(tmp_path, files, env) == expected, why
+
+
+class TestARedundantWheelLeavesTheManagedDirectoryToo:
+ """Skipping the copy was not enough: the managed directory is prepended to UV_FIND_LINKS, so a
+ copy already there still wins the tie over the upstream wheel."""
+
+ def _redundant_branches(self):
+ out = []
+ for marker in (
+ 'substep "windows on arm: PyPI publishes $($wheel.Name) itself -- taking it from'
+ ' there, not the wheelhouse."',
+ 'substep "windows on arm: PyPI publishes $name itself -- taking it from there, not'
+ ' the wheelhouse."',
+ ):
+ i = INSTALL_SRC.index(marker)
+ out.append(INSTALL_SRC[i : INSTALL_SRC.index("continue", i)])
+ return out
+
+ def test_both_wheelhouse_modes_remove_the_managed_copy(self):
+ local, url = self._redundant_branches()
+ assert "Remove-Item -LiteralPath (Join-Path $WoaWheelDir $wheel.Name) -Force" in local
+ assert "Remove-Item -LiteralPath (Join-Path $WoaWheelDir $name) -Force" in url
+
+ def test_only_the_managed_copy_goes(self):
+ """An external wheelhouse file is never the target: the path is built from $WoaWheelDir."""
+ for branch in self._redundant_branches():
+ assert "$wheel.FullName" not in branch.split("Remove-Item")[1]
+ assert "$script:WoaWheelhouse" not in branch.split("Remove-Item")[1]
+
+ @requires_pwsh
+ def test_the_removal_line_deletes_a_stale_copy_and_leaves_the_source(self, tmp_path):
+ src = tmp_path / "house"
+ src.mkdir()
+ managed = tmp_path / "wheels"
+ managed.mkdir()
+ (src / "tiktoken-0.9.0-cp313-cp313-win_arm64.whl").write_bytes(b"x")
+ (managed / "tiktoken-0.9.0-cp313-cp313-win_arm64.whl").write_bytes(b"x")
+ local, _ = self._redundant_branches()
+ line = [l.strip() for l in local.splitlines() if l.strip().startswith("Remove-Item")][0]
+ script = _script(
+ f"$WoaWheelDir = '{managed}'",
+ f"$wheel = Get-Item -LiteralPath '{src / 'tiktoken-0.9.0-cp313-cp313-win_arm64.whl'}'",
+ line,
+ "Write-Output ('SRC=' + (Test-Path -LiteralPath $wheel.FullName))",
+ "Write-Output ('MANAGED=' + (Test-Path -LiteralPath"
+ f" '{managed / 'tiktoken-0.9.0-cp313-cp313-win_arm64.whl'}'))",
+ )
+ done = _ps_ok(script, timeout = 60)
+ assert "SRC=True" in done.stdout and "MANAGED=False" in done.stdout, done.stdout
+
+
+class TestTheEarlyNvidiaProbesAreBounded:
+ """Initialize-WoaNativeCudaTorch runs before the main GPU detection, and its two probes called
+ nvidia-smi unbounded: a wedged driver hung the installer before the bounded probe it already
+ had was ever reached. PowerShell does not hoist, so the helper must also be DEFINED first."""
+
+ def test_both_probes_use_the_bounded_helper(self):
+ for name in ("Test-WoaNvidiaPresent", "Get-WoaDriverCudaVersion"):
+ body = _function_source(INSTALL_SRC, name)
+ assert "Invoke-NvidiaSmiBounded $exe" in body, name
+ assert "& $exe" not in body, f"{name} still calls nvidia-smi unbounded"
+
+ def test_the_leaf_reads_the_shared_parse(self):
+ body = _function_source(INSTALL_SRC, "Get-WoaDriverCudaLeaf")
+ assert "Get-WoaDriverCudaVersion" in body and "& $exe" not in body
+
+ def test_the_helper_is_defined_before_its_first_early_caller(self):
+ assert INSTALL_SRC.index("function Invoke-NvidiaSmiBounded") < INSTALL_SRC.index(
+ "function Test-WoaNvidiaPresent"
+ )
+
+ @staticmethod
+ def _fake_nvidia_smi(directory, sh_body: str, cmd_body: str) -> None:
+ """A fake nvidia-smi the host will actually execute.
+
+ Windows has no shebang handling and PATHEXT covers no extensionless name, so a /bin/sh
+ script here is not an executable at all and the probe finds nothing. .cmd is what PATHEXT
+ does cover, and it is the idiom the rest of this suite already uses.
+ """
+ if os.name == "nt":
+ path = directory / "nvidia-smi.cmd"
+ path.write_text("@echo off\n" + cmd_body, encoding = "utf-8")
+ return
+ path = directory / "nvidia-smi"
+ path.write_text("#!/bin/sh\n" + sh_body, encoding = "utf-8")
+ path.chmod(0o755)
+
+ @requires_pwsh
+ def test_a_listing_with_a_gpu_row_is_present(self, tmp_path):
+ self._fake_nvidia_smi(
+ tmp_path,
+ "echo 'GPU 0: NVIDIA RTX (UUID: GPU-1)'\n",
+ "echo GPU 0: NVIDIA RTX (UUID: GPU-1)\n",
+ )
+ script = _script(
+ _function_source(INSTALL_SRC, "Invoke-NvidiaSmiBounded"),
+ # The probe resolves its executable through this; without it the call is
+ # unresolved and the probe answers False for a reason the test is not about.
+ _function_source(INSTALL_SRC, "Get-WoaNvidiaSmiPath"),
+ _function_source(INSTALL_SRC, "Test-WoaNvidiaPresent"),
+ f"$env:PATH = '{tmp_path}' + [System.IO.Path]::PathSeparator + $env:PATH",
+ "Write-Output (Test-WoaNvidiaPresent)",
+ )
+ assert _ps_last(script) == "True"
+
+ @requires_pwsh
+ def test_a_hung_nvidia_smi_returns_within_the_bound(self, tmp_path):
+ # ping, not timeout: timeout /t needs a console and fails when stdin is redirected.
+ self._fake_nvidia_smi(tmp_path, "sleep 30\n", "ping -n 31 127.0.0.1 > nul\n")
+ # The bound is the helper's default; the assertion is that the call comes back at all.
+ script = _script(
+ _function_source(INSTALL_SRC, "Invoke-NvidiaSmiBounded").replace(
+ "[int]$TimeoutSec = 10", "[int]$TimeoutSec = 2"
+ ),
+ # Required, and easy to miss: an unresolved lookup makes Get-WoaDriverCudaVersion
+ # return $null before it ever calls nvidia-smi, so the "[]" below would pass
+ # without the timeout this test exists to bound ever being exercised.
+ _function_source(INSTALL_SRC, "Get-WoaNvidiaSmiPath"),
+ _function_source(INSTALL_SRC, "Get-WoaDriverCudaVersion"),
+ f"$env:PATH = '{tmp_path}' + [System.IO.Path]::PathSeparator + $env:PATH",
+ "$v = Get-WoaDriverCudaVersion",
+ "Write-Output ('[' + ($v -join '.') + ']')",
+ )
+ assert _ps_last(script, timeout = 60) == "[]"
+
+
+class TestTheAvProbeHonoursResolverPolicy:
+ """A free-threaded install probed public PyPI for PyAV directly, so under UV_OFFLINE, no-index
+ or an exclusive index the native path was selected for an av the resolve could never fetch.
+ The pyarrow probe was already gated the same way."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize("reaches, expected", [("$false", "False"), ("$true", "True")])
+ def test_pypi_counts_only_where_the_resolve_looks(self, reaches, expected):
+ script = _script(
+ f"function Test-WoaResolveReachesPyPI {{ {reaches} }}",
+ "function Test-WoaPyPIWheel"
+ " { param([Parameter(ValueFromRemainingArguments=$true)]$a) $true }",
+ "$script:WoaWheelhouse = $null",
+ _function_source(INSTALL_SRC, "Test-WoaWheelAvailable"),
+ "Write-Output (Test-WoaWheelAvailable -Project 'av' -PythonMinor '3.14'"
+ " -AbiTag 'cp314t')",
+ )
+ assert _ps_last(script) == expected
+
+
+class TestARedundantWheelMeansTheSameVersionOnPyPI:
+ """The guard compared with >=, so a wheelhouse tiktoken 0.13.0 was dropped once PyPI published
+ 0.14.0; extras.txt pins tiktoken==0.13.0, which 0.14.0 cannot satisfy, and the dependency pass
+ then filtered tiktoken out. A newer upstream release leaves the staged copy alone."""
+
+ @staticmethod
+ def _redundant(pypi_versions):
+ listing = "\n".join(
+ f'<a href="tiktoken-{v}-cp313-cp313-win_arm64.whl">x</a>' for v in pypi_versions
+ )
+ script = _script(
+ invoke_restmethod(listing),
+ "function Test-WoaResolveReachesPyPI { $true }",
+ functions(
+ INSTALL_SRC,
+ "Test-WoaVersionAtLeast",
+ "Test-WoaWheelTags",
+ "Test-WoaWheelTagsUsable",
+ "Test-WoaPyPIWheel",
+ "Test-WoaWheelhouseWheelIsRedundant",
+ ),
+ "Write-Output (Test-WoaWheelhouseWheelIsRedundant"
+ " -Name 'tiktoken-0.13.0-cp313-cp313-win_arm64.whl' -PyTag 'cp313' -AbiTag 'cp313')",
+ )
+ return _ps_last(script)
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "pypi, expected, why",
+ [
+ (["0.13.0"], "True", "the same version: upstream's copy is the one to use"),
+ (["0.14.0"], "False", "newer only: an exact pin on 0.13.0 still needs ours"),
+ (["0.12.0"], "False", "older only"),
+ (["0.12.0", "0.13.0", "0.14.0"], "True", "the same version among others"),
+ ],
+ )
+ def test_the_verdict(self, pypi, expected, why):
+ assert self._redundant(pypi) == expected, why
+
+ def test_the_guard_asks_for_the_exact_version(self):
+ body = _function_source(INSTALL_SRC, "Test-WoaWheelhouseWheelIsRedundant")
+ assert "-Floor $fields[1] -AllowAgnostic -Exact" in body
+
+
+class TestTheManagedScanReadsThePlatformTag:
+ """The offline cache is a directory the user fills, and a win_amd64 wheel there passed the
+ Python and ABI checks alone: its project left the drop list, uv rejected the foreign platform,
+ and the resolve fell through to an unbuildable ARM64 sdist."""
+
+ def test_the_platform_is_checked_before_the_abi(self):
+ block = slice_between(INSTALL_SRC, "$WoaWheelNames = @{}", "$WoaDropCandidates = @(")
+ plat = block.index("$platTags = $parts[-1] -split")
+ assert "($platTags -contains 'win_arm64') -or ($platTags -contains 'any')" in block
+ assert plat < block.index("$abiTags = $parts[-2]")
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "name, listed",
+ [
+ ("tiktoken-0.13.0-cp313-cp313-win_arm64.whl", True),
+ ("tiktoken-0.13.0-cp313-cp313-win_amd64.whl", False),
+ ("hf_transfer-0.1.9-cp38-abi3-win_arm64.whl", True),
+ ("brotli-1.1.0-py3-none-any.whl", True),
+ ("brotli-1.1.0-py3-none-manylinux_2_17_aarch64.whl", False),
+ ],
+ )
+ def test_the_scan_executed(self, tmp_path, name, listed):
+ (tmp_path / name).write_text("", encoding = "utf-8")
+ # Anchored on the code that follows rather than on its comment.
+ scan = slice_between(
+ INSTALL_SRC,
+ " $WoaWheelNames = @{}",
+ " foreach ($_woaProvided in $script:WoaPyPIProvided.Keys) {",
+ )
+ script = _script(
+ f"$WoaWheelDir = '{tmp_path}'",
+ "$WoaWheelTag = 'cp313'; $WoaWheelAbi = 'cp313'; $WoaWheelStable = $true;"
+ " $WoaWheelMinor = 13",
+ scan,
+ "Write-Output ('KEYS=' + (($WoaWheelNames.Keys | Sort-Object) -join ','))",
+ )
+ keys = _ps_kv(script)["KEYS"]
+ project = name.split("-")[0].replace("_", "-").lower()
+ assert (project in keys.split(",")) is listed, (name, keys)
+
+
+class TestAFinalBuildOutranksADevelopmentBuildOfTheSameRelease:
+ """On equal numeric releases the tie was broken by a raw string comparison, where '.' sorts
+ after '+', so 2.15.0.dev20260901+cu134 beat 2.15.0+cu134 and the installer pinned a
+ development build and enabled prereleases for it. PEP 440 orders the dev build first."""
+
+ @staticmethod
+ def _pick(source, fn, versions):
+ parity = fn != "Get-WoaCudaWheelVersion"
+ lines = [
+ invoke_restmethod(_torch_links(*versions)),
+ JOIN_URL_RETURNS_BASE,
+ functions(
+ source,
+ "Test-WoaWheelTagsParity" if parity else "Test-WoaWheelTags",
+ "Test-WoaPairsWithTorchParity" if parity else "Test-WoaWheelPairsWithTorch",
+ fn,
+ ),
+ ]
+ if parity:
+ lines.append(f"$v = {fn} -IndexUrl 'https://i.test' -PyTag 'cp313' -AbiTag 'cp313'")
+ else:
+ lines.append(
+ f"$v = {fn} -IndexUrl 'https://i.test' -PythonMinor '3.13' -AbiTag 'cp313'"
+ )
+ lines.append("Write-Output ('[' + $v + ']')")
+ return _ps_last(_script(*lines))[1:-1]
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "fn, source",
+ [("Get-WoaCudaWheelVersion", "INSTALL"), ("Get-WoaCudaWheelVersionParity", "SETUP")],
+ )
+ @pytest.mark.parametrize(
+ "versions, expected, why",
+ [
+ (
+ ["2.15.0.dev20260901%2Bcu134", "2.15.0%2Bcu134"],
+ "2.15.0+cu134",
+ "the final build, listed second",
+ ),
+ (
+ ["2.15.0%2Bcu134", "2.15.0.dev20260901%2Bcu134"],
+ "2.15.0+cu134",
+ "the final build, listed first",
+ ),
+ (
+ ["2.15.0.dev20260901%2Bcu134", "2.15.0.dev20260904%2Bcu134"],
+ "2.15.0.dev20260904+cu134",
+ "among dev builds the later stamp",
+ ),
+ (
+ ["2.15.0.dev20260904%2Bcu134", "2.15.0.dev20260901%2Bcu134"],
+ "2.15.0.dev20260904+cu134",
+ "in either order",
+ ),
+ (
+ ["2.14.0%2Bcu134", "2.15.0.dev20260901%2Bcu134"],
+ "2.15.0.dev20260901+cu134",
+ "a newer release still wins as a dev build",
+ ),
+ (
+ ["2.15.0rc1%2Bcu134", "2.15.0%2Bcu134"],
+ "2.15.0+cu134",
+ "a release candidate ranks below the final build",
+ ),
+ (["2.15.0%2Bcu134", "2.15.0rc1%2Bcu134"], "2.15.0+cu134", "in either order"),
+ (
+ ["2.15.0a1%2Bcu134", "2.15.0b1%2Bcu134", "2.15.0rc1%2Bcu134"],
+ "2.15.0rc1+cu134",
+ "rc above beta above alpha",
+ ),
+ (
+ ["2.15.0rc2%2Bcu134", "2.15.0rc1%2Bcu134"],
+ "2.15.0rc2+cu134",
+ "a later number wins within a kind",
+ ),
+ (
+ ["2.15.0rc1%2Bcu134", "2.15.0.dev20260901%2Bcu134"],
+ "2.15.0rc1+cu134",
+ "and a dev build sits below every prerelease",
+ ),
+ (
+ ["2.15.0b1%2Bcu134", "2.15.0a1%2Bcu134"],
+ "2.15.0b1+cu134",
+ "beta above alpha, listed first",
+ ),
+ (
+ ["2.15.0a2%2Bcu134", "2.15.0b1%2Bcu134"],
+ "2.15.0b1+cu134",
+ "beta above a later alpha",
+ ),
+ ],
+ )
+ def test_the_pick(self, fn, source, versions, expected, why):
+ src = INSTALL_SRC if source == "INSTALL" else SETUP_SRC
+ assert self._pick(src, fn, versions) == expected, why
+
+
+class TestTheWheelsCudaMajorMustNotExceedTheDrivers:
+ """The NVIDIA channel was accepted on interpreter tags alone, so a CUDA 12 driver selected the
+ +cu134 wheel: the install finished and torch could not initialise CUDA. A CUDA 13 runtime does
+ not run on a CUDA 12 driver on Windows."""
+
+ @staticmethod
+ def _native(driver, wheel = "2.14.0+cu134"):
+ script = native_probe_script(
+ driver = "$null" if driver is None else "@(" + ", ".join(str(d) for d in driver) + ")",
+ driver_leaf = "'cu128'",
+ stubs = (
+ f"$script:WoaNvidiaTorchIndexUrls = @('{NV_GA}')",
+ "function Test-WoaCudaWheel { param($IndexUrl, $PythonMinor, $AbiTag, $Project)"
+ " $IndexUrl -like '*nvidia*' }",
+ "function Get-WoaCudaWheelVersion"
+ f" {{ param([Parameter(ValueFromRemainingArguments=$true)]$a) '{wheel}' }}",
+ ),
+ )
+ out = _ps_kv(script)
+ return out["NATIVE"], out.get("MSG", "")
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "driver, wheel, native, why",
+ [
+ ((12, 8), "2.14.0+cu134", "False", "a CUDA 12.8 driver cannot run a cu134 wheel"),
+ ((13, 0), "2.14.0+cu134", "True", "a CUDA 13.0 driver can"),
+ ((13, 4), "2.14.0+cu134", "True", "and a matching one"),
+ ((12, 8), "2.10.0+cu128", "True", "the same major is fine"),
+ ((11, 8), "2.10.0+cu128", "False", "cu128 on an 11.8 driver is the classic case"),
+ (None, "2.14.0+cu134", "True", "no driver answer: the probe decides"),
+ ],
+ )
+ def test_the_gate(self, driver, wheel, native, why):
+ got, msg = self._native(driver, wheel)
+ assert got == native, (why, msg)
+ if native == "False":
+ assert "Update the NVIDIA driver" in msg
+
+
+class TestAStagingFailureAfterTheVenvIsAStop:
+ """Once the native ARM64 venv exists, clearing the flag and continuing sent the torch step to
+ the driver-derived index, which has no win_arm64 wheel: a guaranteed failure three steps later
+ with nothing to say why. Now it stops here and says what to do."""
+
+ def test_the_block_exits_with_the_reason(self):
+ start = INSTALL_SRC.index(
+ " if (-not $script:WoaNativeCudaTorch) {\n"
+ " # The venv is already native ARM64"
+ )
+ block = INSTALL_SRC[start : start + 900]
+ assert 'return (Exit-InstallFailure "windows on arm: pyarrow could not be staged")' in block
+ assert "UNSLOTH_WOA_NATIVE=0" in block
+ assert "continuing without the native stack" not in INSTALL_SRC
+
+
+# The cutoff swap that wraps install.ps1's own trio command.
+INSTALL_CUTOFF_SWAP_START = (
+ ' if ($script:WoaNativeCudaTorch -and $VenvPlatform -eq "win-arm64") {\n'
+ " # The probe read the index page"
+)
+CUTOFF_RESTORE = (
+ "foreach ($_woaCutoffName in @($_woaCutoffSaved.Keys))"
+ ' { Set-Item "Env:$_woaCutoffName" $_woaCutoffSaved[$_woaCutoffName] }'
+)
+
+
+class TestTheExactCudaPinIgnoresAnUploadCutoff:
+ """UV_EXCLUDE_NEWER limits candidates by upload time. The probe reads the index page, which
+ carries no dates, and pins exactly, so an inherited cutoff rejected the selected wheel and the
+ native install aborted. Removed for that one command and restored after, in both installers;
+ an installed package audits fine under a cutoff, so the later passes are safe."""
+
+ @pytest.mark.parametrize(
+ "src, marker",
+ [
+ ("INSTALL", "-Dir $script:WoaDir"),
+ ("SETUP", "New-WoaTorchStepOverrideValueParity -Value $_woaStepSaved"),
+ ],
+ )
+ def test_removed_before_and_restored_in_finally(self, src, marker):
+ text = INSTALL_SRC if src == "INSTALL" else SETUP_SRC
+ tail = text[text.index(marker) :][:3000]
+ fin = tail.index("} finally {")
+ assert (
+ 'foreach ($_woaCutoffName in @("UV_EXCLUDE_NEWER", "UV_EXCLUDE_NEWER_PACKAGE"))'
+ in tail[:fin]
+ )
+ assert 'Remove-Item "Env:$_woaCutoffName"' in tail[:fin]
+ assert CUTOFF_RESTORE in tail[fin:]
+
+ @requires_pwsh
+ def test_the_swap_executed(self):
+ """The two loops, lifted out and run: the variable is gone inside and back after."""
+ script = _script(
+ SUBSTEP_NOOP,
+ "$script:WoaNativeCudaTorch = $true; $VenvPlatform = 'win-arm64';"
+ " $_woaCutoffSaved = @{}",
+ "$env:UV_EXCLUDE_NEWER = '2026-01-01'",
+ slice_between(INSTALL_SRC, INSTALL_CUTOFF_SWAP_START, " try {"),
+ "Write-Output ('INSIDE=[' + $env:UV_EXCLUDE_NEWER + ']')",
+ CUTOFF_RESTORE,
+ "Write-Output ('AFTER=[' + $env:UV_EXCLUDE_NEWER + ']')",
+ )
+ out = _ps_ok(script).stdout
+ assert "INSIDE=[]" in out and "AFTER=[2026-01-01]" in out
+
+
+class TestARebasedFileReferenceIsAUri:
+ """`pkg @ file:../wheels/p.whl` was rebased to `file:` plus a raw path, and under a spaced
+ profile that URL ended at the space and every later uv resolution failed."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize("src", ["INSTALL", "SETUP"])
+ def test_a_space_in_the_base_survives(self, tmp_path, src):
+ base = tmp_path / "First Last" / "woa"
+ base.mkdir(parents = True)
+ text = INSTALL_SRC if src == "INSTALL" else SETUP_SRC
+ script = _script(
+ _function_source(text, "Resolve-WoaOverrideLine"),
+ "Write-Output ('[' + (Resolve-WoaOverrideLine -Line 'pkg @ file:../wheels/p.whl'"
+ f" -BaseDir '{base}') + ']')",
+ )
+ got = _ps_last(script)[1:-1]
+ expected = "pkg @ " + (tmp_path / "First Last" / "wheels" / "p.whl").resolve().as_uri()
+ assert got == expected
+
+ @requires_pwsh
+ @pytest.mark.parametrize("src", ["INSTALL", "SETUP"])
+ @pytest.mark.parametrize(
+ "line, marker, why",
+ [
+ (
+ 'pkg @ file:../wheels/p.whl ; python_version < "3.13"',
+ ' ; python_version < "3.13"',
+ "a marker rides after the URI",
+ ),
+ (
+ "pkg @ file:../wheels/p.whl;python_version",
+ "",
+ "no whitespace before the semicolon: part of the path (PEP 508)",
+ ),
+ ],
+ )
+ def test_a_marker_is_kept_aside_while_the_path_is_rebased(
+ self, tmp_path, src, line, marker, why
+ ):
+ """The marker was captured with the target and handed to GetFullPath and System.Uri, so it
+ was either encoded into the URL or made the fallback rebase against the wrong base."""
+ base = tmp_path / "woa"
+ base.mkdir(parents = True)
+ text = INSTALL_SRC if src == "INSTALL" else SETUP_SRC
+ script = _script(
+ _function_source(text, "Resolve-WoaOverrideLine"),
+ f"Write-Output ('[' + (Resolve-WoaOverrideLine -Line '{line}'"
+ f" -BaseDir '{base}') + ']')",
+ )
+ got = _ps_last(script)[1:-1]
+ leaf = "p.whl" if marker else "p.whl;python_version"
+ # pathlib percent-encodes the ";" that System.Uri keeps in the path (a sub-delim).
+ uri = (tmp_path / "wheels" / leaf).resolve().as_uri().replace("%3B", ";")
+ assert got == "pkg @ " + uri + marker, why
+
+ @requires_pwsh
+ def test_a_marked_url_reference_is_left_alone(self, tmp_path):
+ script = _script(
+ _function_source(INSTALL_SRC, "Resolve-WoaOverrideLine"),
+ "Write-Output ('[' + (Resolve-WoaOverrideLine"
+ " -Line 'pkg @ https://x.test/a.whl ; os_name == \"nt\"'"
+ f" -BaseDir '{tmp_path}') + ']')",
+ )
+ assert _ps_last(script)[1:-1] == 'pkg @ https://x.test/a.whl ; os_name == "nt"'
+
+ def test_the_two_copies_are_identical(self):
+ install, setup = _ps_copies("Resolve-WoaOverrideLine")
+ assert install == setup
+
+
+class TestTheMergedOverrideFileDoesNotOutliveTheRun:
+ """It copies caller lines, which can carry credentials, into $StudioHome\\woa. It is now
+ removed when the run ends, on failure too, and any stale copy before the next is written."""
+
+ def test_the_lifecycle_is_wired(self):
+ assert "function Remove-WoaMergedOverrides" in SETUP_SRC
+ restore = _function_source(SETUP_SRC, "Restore-WoaResolverEnvironment")
+ assert (
+ 'Remove-Item -LiteralPath (Join-Path $woaDir "overrides.merged.txt") -Force' in restore
+ ), "a stale copy is removed first"
+ assert (
+ "$script:WoaMergedOverrides = $_woaMerged" in restore
+ ), "the written one is recorded for removal"
+ assert "Remove-WoaMergedOverrides" in _function_source(SETUP_SRC, "Exit-SetupFailure")
+ assert SETUP_SRC.rstrip().endswith(
+ "Remove-WoaMergedOverrides"
+ ), "the last statement of the script"
+
+ @requires_pwsh
+ def test_the_removal(self, tmp_path):
+ merged = tmp_path / "overrides.merged.txt"
+ merged.write_text("secret @ https://user:[email protected]/w.whl\n", encoding = "utf-8")
+ script = _script(
+ _function_source(SETUP_SRC, "Remove-WoaMergedOverrides"),
+ f"$script:WoaMergedOverrides = '{merged}'",
+ "Remove-WoaMergedOverrides",
+ f"Write-Output (Test-Path -LiteralPath '{merged}')",
+ )
+ assert _ps_last(script) == "False"
+
+ @requires_pwsh
+ def test_a_failure_exit_still_reports_and_removes(self, tmp_path):
+ """Exit-SetupFailure itself, not a stub: the cleanup call sits after the param block (a
+ statement before it turns `param` into a command and the function into a crash), so the
+ desktop app still gets its [TAURI:ERROR] line and the file is gone."""
+ merged = tmp_path / "overrides.merged.txt"
+ merged.write_text("secret @ https://user:[email protected]/w.whl\n", encoding = "utf-8")
+ done = _ps(
+ _script(
+ functions(SETUP_SRC, "Remove-WoaMergedOverrides", "Exit-SetupFailure"),
+ f"$script:WoaMergedOverrides = '{merged}'",
+ '$env:UNSLOTH_TAURI_MODE = "1"',
+ 'Exit-SetupFailure "boom" -Code 3',
+ 'Write-Output "REACHED_UNREACHABLE"',
+ )
+ )
+ assert done.returncode == 3, done.stderr
+ assert "[TAURI:ERROR] boom" in done.stdout, done.stdout + done.stderr
+ assert "REACHED_UNREACHABLE" not in done.stdout
+ assert not merged.exists()
+
+
+class TestNativeNeedsAPairedTorchvision:
+ """torchvision is part of the stack. An index whose torch had no torchvision paired with it
+ still took the native path and left torchvision to a floor, so the exact torch pin and an
+ unpaired torchvision resolved against each other after the ARM64 venv existed. The pairing is
+ part of the gate now: the next index is tried, and with none pairing the x64 stack is kept."""
+
+ GA = NV_GA
+ NIGHTLY = NV_NIGHTLY
+
+ @classmethod
+ def _native(cls, torch_by_index, vision_by_index):
+ def table(d):
+ return "@{ " + "; ".join(f"'{k}' = '{v}'" for k, v in d.items()) + " }"
+
+ script = native_probe_script(
+ driver = "@(13, 4)",
+ stubs = (
+ f"$script:WoaNvidiaTorchIndexUrls = @('{cls.GA}', '{cls.NIGHTLY}')",
+ f"$script:Torch = {table(torch_by_index)}",
+ f"$script:Vision = {table(vision_by_index)}",
+ "function Test-WoaCudaWheel { param($IndexUrl, $PythonMinor, $AbiTag, $Project)"
+ " [bool]$script:Torch[$IndexUrl] }",
+ "function Get-WoaCudaWheelVersion { param($IndexUrl, $PythonMinor, $AbiTag,"
+ " $Project, $PairWith, $Below)",
+ " if ($Below) { return '' }",
+ " if ($Project -eq 'torchvision') { return $script:Vision[$IndexUrl] }",
+ " if ($Project -eq 'torchaudio') { return '' }",
+ " return $script:Torch[$IndexUrl] }",
+ ),
+ outputs = (
+ "Write-Output ('INDEX=' + $script:WoaTorchIndexUrl)",
+ "Write-Output ('TORCH=' + $script:WoaTorchWheelVersion)",
+ "Write-Output ('VISION=' + $script:WoaVisionWheelVersion)",
+ ),
+ )
+ return _ps_kv(script)
+
+ @requires_pwsh
+ def test_a_paired_index_is_taken_with_both_pins(self):
+ out = self._native({self.GA: "2.14.0+cu134"}, {self.GA: "0.29.0+cu134"})
+ assert out["NATIVE"] == "True"
+ assert out["INDEX"] == self.GA
+ assert (out["TORCH"], out["VISION"]) == ("2.14.0+cu134", "0.29.0+cu134")
+
+ @requires_pwsh
+ def test_the_first_paired_index_wins(self):
+ """Order is the maintenance story: the official index retires the NVIDIA one by
+ existing."""
+ out = self._native(
+ {self.GA: "2.14.0+cu134", self.NIGHTLY: "2.15.0.dev20260905+cu134"},
+ {self.GA: "0.29.0+cu134", self.NIGHTLY: "0.30.0.dev20260905+cu134"},
+ )
+ assert out["INDEX"] == self.GA
+ assert (out["TORCH"], out["VISION"]) == ("2.14.0+cu134", "0.29.0+cu134")
+
+ @requires_pwsh
+ def test_an_unpaired_index_yields_to_the_next(self):
+ out = self._native(
+ {self.GA: "2.14.0+cu134", self.NIGHTLY: "2.15.0.dev20260905+cu134"},
+ {self.GA: "", self.NIGHTLY: "0.30.0.dev20260905+cu134"},
+ )
+ assert out["NATIVE"] == "True"
+ assert out["INDEX"] == self.NIGHTLY, out["MSG"]
+ assert (out["TORCH"], out["VISION"]) == (
+ "2.15.0.dev20260905+cu134",
+ "0.30.0.dev20260905+cu134",
+ )
+ assert "no torchvision paired with it; trying the next index" in out["MSG"]
+
+ @requires_pwsh
+ def test_with_no_pairing_index_the_x64_stack_is_kept(self):
+ out = self._native(
+ {self.GA: "2.14.0+cu134", self.NIGHTLY: "2.15.0.dev20260905+cu134"},
+ {self.GA: "", self.NIGHTLY: ""},
+ )
+ assert out["NATIVE"] == "False"
+ assert out["INDEX"] == ""
+ assert "no index pairs a torchvision" in out["MSG"] and "x64 stack" in out["MSG"]
+
+ def test_the_vision_pin_is_the_gates_answer(self):
+ """One probe, not two: the pin the trio installs is the version the gate accepted."""
+ fn = _function_source(INSTALL_SRC, "Initialize-WoaNativeCudaTorch")
+ assert fn.count('-Project "torchvision"') == 1
+ assert "$script:WoaVisionWheelVersion = $_woaVisionVersion" in fn
+ assert "leaving torchvision unpinned" not in fn
+
+
+class TestAnUpdateKeepsTheInstalledPairWhenTheIndexLags:
+ """setup.ps1's fresh-shell probe pinned the index's newest torch and left torchvision at its
+ floor when no build paired with it. The venv already exists there, so the installed pair is
+ kept instead; with nothing installed to keep, the floor stays and the log says why."""
+
+ @staticmethod
+ def _block():
+ # Anchored on the code that follows rather than on its comment.
+ return slice_between(
+ SETUP_SRC,
+ '$WinArm64TorchSpec = "torch>=2.4"',
+ '$_tritonSpec = if ($WinArm64Venv) { "triton-windows>=3.8.0.post28" }',
+ )
+
+ @staticmethod
+ def _venv_with(tmp_path, installed):
+ """A REAL venv, with real .dist-info for whatever `installed` names.
+
+ The block runs `<VenvDir>/Scripts/python.exe -c ...` by that exact name, and a /bin/sh
+ script called python.exe is not an executable on Windows, so a fake came back empty there
+ and all three cases asserted the floor rather than the branch they were written for. On
+ POSIX the interpreter lands in bin/, so Scripts/python.exe is linked to it.
+ """
+ venv = tmp_path / "venv"
+ subprocess.run(
+ [sys.executable, "-m", "venv", "--without-pip", str(venv)],
+ check = True,
+ capture_output = True,
+ timeout = 300,
+ )
+ sites = list(venv.glob("Lib/site-packages")) + list(venv.glob("lib/*/site-packages"))
+ assert sites, f"no site-packages under {venv}"
+ for name, version in installed.items():
+ info = sites[0] / f"{name}-{version}.dist-info"
+ info.mkdir(parents = True)
+ (info / "METADATA").write_text(
+ f"Metadata-Version: 2.1\nName: {name}\nVersion: {version}\n", encoding = "utf-8"
+ )
+ if os.name != "nt":
+ scripts = venv / "Scripts"
+ scripts.mkdir(exist_ok = True)
+ (scripts / "python.exe").symlink_to(venv / "bin" / "python")
+ return venv
+
+ def _run(self, tmp_path, installed):
+ venv = self._venv_with(tmp_path, installed)
+ script = _script(
+ substep_collector(),
+ f"$VenvDir = '{venv}'",
+ "$WinArm64Venv = $true",
+ "$WinArm64NoAudio = $true",
+ "$WinArm64EffectiveTorchIndexUrl = 'https://i.test'",
+ "function Get-WoaCudaWheelVersionParity { param($IndexUrl, $PyTag, $AbiTag, $Project,"
+ " $PairWith, $Below)",
+ " if ($Below) { return '' }",
+ " if ($Project -eq 'torchvision') { return '' }",
+ " if ($Project -eq 'torchaudio') { return '' }",
+ " return '2.15.0.dev20260905+cu134' }",
+ functions(SETUP_SRC, "Test-WoaPairsWithTorchParity", "Test-WoaAudioMatchesTorchParity"),
+ self._block(),
+ "Write-Output ('TORCH=' + $WinArm64TorchSpec)",
+ "Write-Output ('VISION=' + $WinArm64VisionSpec)",
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
+ return _ps_kv(script)
+
+ @requires_pwsh
+ def test_the_installed_pair_is_kept(self, tmp_path):
+ out = self._run(tmp_path, {"torch": "2.14.0+cu134", "torchvision": "0.29.0+cu134"})
+ assert out["TORCH"] == "torch==2.14.0+cu134", out["MSG"]
+ assert out["VISION"] == "torchvision==0.29.0+cu134"
+ assert "keeping the installed torch 2.14.0+cu134 and torchvision 0.29.0+cu134" in out["MSG"]
+
+ @requires_pwsh
+ def test_an_installed_pair_that_does_not_pair_is_not_kept(self, tmp_path):
+ out = self._run(tmp_path, {"torch": "2.14.0+cu134", "torchvision": "0.28.0+cu134"})
+ assert out["TORCH"] == "torch==2.15.0.dev20260905+cu134"
+ assert out["VISION"] == "torchvision>=0.19"
+ assert "no installed pair can be kept" in out["MSG"]
+
+ @requires_pwsh
+ def test_nothing_installed_leaves_the_floor_and_says_so(self, tmp_path):
+ out = self._run(tmp_path, {})
+ assert out["VISION"] == "torchvision>=0.19"
+ assert "no installed pair can be kept" in out["MSG"]
+
+
+class TestASuppliedWheelUnderAnotherNameIsReadFromItsArchive:
+ """UNSLOTH_PYARROW_WHEEL saved as .bin or with no extension was rejected by the probe on its
+ file name, although staging reads the wheel name from the archive and accepts that shape. The
+ probe now reconstructs the name the same way before the project and tag checks."""
+
+ @staticmethod
+ def _archive(path, dist_info, tag):
+ import zipfile
+ with zipfile.ZipFile(path, "w") as zf:
+ zf.writestr(
+ f"{dist_info}.dist-info/WHEEL",
+ f"Wheel-Version: 1.0\nGenerator: test\nRoot-Is-Purelib: false\nTag: {tag}\n",
+ )
+ zf.writestr(f"{dist_info}.dist-info/METADATA", "Metadata-Version: 2.1\nName: pyarrow\n")
+ return path
+
+ @staticmethod
+ def _probe(wheel):
+ return _ps_last(
+ pyarrow_source_script(
+ wheelhouse = "'https://example.test/wheels'",
+ reaches_pypi = "$false",
+ lifts = ("Get-WheelFileNameFromArchive",),
+ preamble = (f"$env:UNSLOTH_PYARROW_WHEEL = '{wheel}'",),
+ )
+ )[1:-1]
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "name, tag, expected, why",
+ [
+ ("pyarrow.bin", "cp313-cp313-win_arm64", "local", "a .bin download of the right wheel"),
+ ("pyarrow_wheel", "cp313-cp313-win_arm64", "local", "no extension at all"),
+ (
+ "pyarrow.bin",
+ "cp313-cp313-win_amd64",
+ "",
+ "the archive says x64, whatever the file is called",
+ ),
+ ("pyarrow.bin", "cp312-cp312-win_arm64", "", "or another interpreter"),
+ ],
+ )
+ def test_the_name_comes_from_the_archive(self, tmp_path, name, tag, expected, why):
+ wheel = self._archive(tmp_path / name, "pyarrow-21.0.0", tag)
+ assert self._probe(str(wheel)) == expected, why
+
+ @requires_pwsh
+ def test_a_file_that_is_not_a_wheel_archive_is_still_ignored(self, tmp_path):
+ bogus = tmp_path / "pyarrow.bin"
+ bogus.write_bytes(b"not a zip at all")
+ assert self._probe(str(bogus)) == ""
+
+ @requires_pwsh
+ def test_a_real_wheel_name_still_passes(self, tmp_path):
+ wheel = self._archive(
+ tmp_path / "pyarrow-21.0.0-cp313-cp313-win_arm64.whl",
+ "pyarrow-21.0.0",
+ "cp313-cp313-win_arm64",
+ )
+ assert self._probe(str(wheel)) == "local"
+
+
+class TestAReselectedInterpreterIsProbedBeforeItIsTaken:
+ """After the re-probe flips native mode, Find-CompatiblePython runs again with the new arch
+ preference and ranks the requested minor first. It could hand back an ARM64 3.12 whose probe
+ had failed while the flip came from 3.13, and the 3.13 answers were then carried into a 3.12
+ venv. The reselected interpreter is probed too, and the accepted answer restored."""
+
+ @staticmethod
+ def _block():
+ # Anchored on the code either side rather than on the comments that head them.
+ return slice_between(
+ INSTALL_SRC,
+ " $WoaProbedMinor = $PythonVersion",
+ " if ($script:WoaNativeCudaTorch -and $DetectedPython -and $DetectedPython.Arch -eq"
+ ' "x86_64") {',
+ )
+
+ def _run(self, detected, reselected, native_minors):
+ natives = ", ".join(f"'{m}'" for m in native_minors)
+ script = _script(
+ "$PythonVersion = '3.12'",
+ substep_collector(),
+ "$script:Probes = @()",
+ "function step { param($a, $b, $c) }",
+ "function Get-HostMachineArch { 'arm64' }",
+ "function Remove-IndexUrlCredentials { param($u) $u }",
+ "function Test-PythonFreeThreaded { param($PythonExe) $false }",
+ "function Remove-SkippedPython { param($p) $p }",
+ f"$script:Natives = @({natives})",
+ "$script:WoaNativeCudaTorch = $false",
+ "function Initialize-WoaNativeCudaTorch { param($PythonMinor, $FreeThreaded)",
+ " $script:Probes += $PythonMinor",
+ " $script:WoaNativeCudaTorch = [bool]($script:Natives -contains $PythonMinor)",
+ " $script:WoaTorchIndexUrl = if ($script:WoaNativeCudaTorch) { 'https://i.test' }"
+ " else { $null } }",
+ f"$DetectedPython = @{{ Version = '{detected[0]}'; Path = 'p{detected[0]}';"
+ f" Arch = '{detected[1]}' }}",
+ f"function Find-CompatiblePython {{ @{{ Version = '{reselected[0]}';"
+ f" Path = 'p{reselected[0]}'; Arch = '{reselected[1]}' }} }}",
+ self._block(),
+ "Write-Output ('PY=' + $DetectedPython.Version)",
+ "Write-Output ('NATIVE=' + $script:WoaNativeCudaTorch)",
+ "Write-Output ('PROBED=' + $WoaProbedMinor)",
+ "Write-Output ('PROBES=' + ($script:Probes -join ','))",
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
+ return _ps_kv(script)
+
+ @requires_pwsh
+ def test_a_reselected_minor_without_a_stack_is_not_taken(self):
+ # Requested 3.12 (no stack); detected 3.13 goes native; the reselection offers ARM64 3.12.
+ out = self._run(("3.13", "arm64"), ("3.12", "arm64"), ["3.13"])
+ assert out["PY"] == "3.13", out["MSG"]
+ assert out["NATIVE"] == "True" and out["PROBED"] == "3.13"
+ assert (
+ out["PROBES"] == "3.13,3.12,3.13"
+ ), "probed the offer, then restored the accepted answer"
+ assert "keeping Python 3.13, which has one" in out["MSG"]
+
+ @requires_pwsh
+ def test_a_reselected_minor_with_a_stack_is_taken(self):
+ out = self._run(("3.13", "arm64"), ("3.12", "arm64"), ["3.13", "3.12"])
+ assert out["PY"] == "3.12" and out["NATIVE"] == "True" and out["PROBED"] == "3.12"
+ assert out["PROBES"] == "3.13,3.12"
+
+ @requires_pwsh
+ def test_the_same_interpreter_back_is_not_probed_again(self):
+ out = self._run(("3.13", "x86_64"), ("3.13", "arm64"), ["3.13"])
+ assert out["PY"] == "3.13" and out["NATIVE"] == "True"
+ assert out["PROBES"] == "3.13"
+
+
+class TestTheResolverVariablesDoNotOutliveTheInstaller:
+ """Under `irm | iex` the process-scoped UV_OVERRIDE, UV_FIND_LINKS and PIP_FIND_LINKS set for
+ the native stack were the caller's own session variables and stayed set, so every later
+ `uv pip` in that shell resolved with Studio's override file and wheelhouse. They are
+ snapshotted before the first assignment and put back in the script-level finally."""
+
+ def test_the_snapshot_precedes_the_first_assignment(self):
+ snap = INSTALL_SRC.index("$script:WoaResolverEnvSaved = @{")
+ first = INSTALL_SRC.index('$env:UV_OVERRIDE = ($_woaOverrideValue -join " ")')
+ assert snap < first
+ block = INSTALL_SRC[snap : snap + 200]
+ for name in ("UV_OVERRIDE", "UV_FIND_LINKS", "PIP_FIND_LINKS"):
+ assert f"{name} = $env:{name}" in block, name
+
+ def test_the_restore_is_in_the_script_level_finally(self):
+ run = INSTALL_SRC.index(" Install-UnslothStudio @args\n} finally {")
+ assert "$script:WoaResolverEnvSaved" in INSTALL_SRC[run:]
+ reset = INSTALL_SRC.rindex("$script:WoaResolverEnvSaved = $null\n", 0, run)
+ assert (
+ INSTALL_SRC.index("try {", reset) < run
+ ), "cleared right before the run, so an earlier session value cannot leak in"
+
+ @staticmethod
+ def _restore_block():
+ # Anchored on the code either side rather than on the comments that head them.
+ return slice_between(
+ INSTALL_SRC,
+ " if ($script:WoaResolverEnvSaved) {",
+ "\n Remove-Item Env:UNSLOTH_KEPT_TORCH -ErrorAction SilentlyContinue",
+ )
+
+ @requires_pwsh
+ def test_the_callers_values_come_back_and_absent_ones_are_removed(self):
+ script = _script(
+ "$env:UV_OVERRIDE = 'C:\\studio\\overrides.txt'",
+ "$env:UV_FIND_LINKS = 'C:\\studio\\wheels,C:\\mine'",
+ "$env:PIP_FIND_LINKS = 'C:\\studio\\wheels'",
+ "$script:WoaResolverEnvSaved = @{ UV_OVERRIDE = $null;"
+ " UV_FIND_LINKS = 'C:\\mine'; PIP_FIND_LINKS = $null }",
+ self._restore_block(),
+ "Write-Output ('OV=' + [string]$env:UV_OVERRIDE)",
+ "Write-Output ('UV=' + [string]$env:UV_FIND_LINKS)",
+ "Write-Output ('PIP=' + [string]$env:PIP_FIND_LINKS)",
+ "Write-Output ('SAVED=' + [string]($null -eq $script:WoaResolverEnvSaved))",
+ )
+ assert _ps_kv(script) == {"OV": "", "UV": "C:\\mine", "PIP": "", "SAVED": "True"}
+
+ @requires_pwsh
+ def test_nothing_snapshotted_touches_nothing(self):
+ script = _script(
+ "$env:UV_FIND_LINKS = 'C:\\mine'",
+ "$script:WoaResolverEnvSaved = $null",
+ self._restore_block(),
+ "Write-Output ('UV=' + [string]$env:UV_FIND_LINKS)",
+ )
+ assert _ps_last(script) == "UV=C:\\mine"
+
+
+class TestTheDependencyIndexFollowsTheResolverPolicy:
+ """The trio install passed a hard-coded public PyPI as the extra index for torch's shared
+ dependencies, while Invoke-InstallCommand clears every inherited index setting whenever
+ --default-index is given. A caller with an exclusive corporate index or no-index therefore had
+ public PyPI searched on their behalf, and a network that blocks it failed after the ARM64 venv
+ existed. The dependency index is now what the policy names."""
+
+ @classmethod
+ def _args(
+ cls,
+ tmp_path,
+ files,
+ env,
+ source = None,
+ resolver = "uv",
+ ):
+ src = INSTALL_SRC if source is None else source
+ for name, body in files.items():
+ (tmp_path / name).parent.mkdir(parents = True, exist_ok = True)
+ (tmp_path / name).write_text(body, encoding = "utf-8")
+ (tmp_path / "proj").mkdir(exist_ok = True)
+ script = _script(
+ clear_env(UV_POLICY_ENV),
+ f"$env:APPDATA = '{tmp_path / 'appdata'}'",
+ f"$env:ProgramData = '{tmp_path / 'programdata'}'",
+ f"Set-Location -LiteralPath '{tmp_path / 'proj'}'",
+ "\n".join(f"$env:{k} = '{v}'" for k, v in env.items()),
+ functions(
+ src,
+ "Remove-WoaTomlComment",
+ "Split-WoaTomlKey",
+ "Read-WoaUvTomlIndexKeys",
+ "Get-WoaUvConfigIndexPolicy",
+ "Get-WoaDependencyIndexArgs",
+ ),
+ f"Write-Output ('[' + ((Get-WoaDependencyIndexArgs -Resolver '{resolver}')"
+ " -join '|') + ']')",
+ )
+ return _ps_last(script)[1:-1]
+
+ PYPI = "--extra-index-url|https://pypi.org/simple"
+ CORP = "--extra-index-url|https://pypi.corp.test/simple"
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "body, expected, why",
+ [
+ (
+ f'[[index]]\nurl = "{CORP_INDEX}"\nexplicit = true\n',
+ "--extra-index-url|https://pypi.org/simple",
+ "an explicit index is not handed to the trio resolve; PyPI stays the default",
+ ),
+ (
+ f'[[index]]\nurl = "{CORP_INDEX}"\nexplicit = true\ndefault = true\n',
+ "",
+ "explicit and default is doubt, and doubt names nothing",
+ ),
+ ],
+ )
+ def test_an_explicit_index_is_never_an_extra_index_url(self, tmp_path, body, expected, why):
+ assert self._args(tmp_path, {"proj/uv.toml": body}, {}) == expected, why
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "files, env, expected, why",
+ [
+ ({}, {}, PYPI, "nothing configured: public PyPI"),
+ ({}, {"UV_NO_INDEX": "1"}, "", "uv no-index: the wheelhouse is the whole source"),
+ ({}, {"PIP_NO_INDEX": "true"}, PYPI, "pip's variable, which uv never reads"),
+ ({}, {"UV_NO_INDEX": "0"}, PYPI, "a false flag is not set"),
+ (
+ {},
+ {"UV_DEFAULT_INDEX": CORP_INDEX},
+ CORP,
+ "an exclusive default replaces PyPI",
+ ),
+ (
+ {},
+ {"UV_INDEX_URL": CORP_INDEX + "/"},
+ CORP + "/",
+ "the older spelling, kept as written",
+ ),
+ ({}, {"PIP_INDEX_URL": CORP_INDEX}, PYPI, "pip's default is not uv's"),
+ (
+ {},
+ {"UV_INDEX_URL": CORP_INDEX, "PIP_EXTRA_INDEX_URL": PYPI_URL},
+ CORP,
+ "a pip extra does not put PyPI back for uv",
+ ),
+ (
+ {},
+ {"UV_DEFAULT_INDEX": CORP_INDEX, "UV_EXTRA_INDEX_URL": PYPI_URL},
+ CORP + "|" + PYPI,
+ "PyPI named as an extra stays in play, after the default",
+ ),
+ (
+ {},
+ {"UV_EXTRA_INDEX_URL": CORP_INDEX},
+ PYPI + "|" + CORP,
+ "an extra alone adds to the PyPI default",
+ ),
+ (
+ {},
+ {"UV_INDEX": "https://a.test/simple https://b.test/simple"},
+ PYPI + "|--extra-index-url|https://a.test/simple"
+ "|--extra-index-url|https://b.test/simple",
+ "UV_INDEX is a space-separated list",
+ ),
+ (_uv_toml("no-index = true\n"), {}, "", "project uv.toml no-index"),
+ (
+ _uv_toml(f'default-index = "{CORP_INDEX}"\n'),
+ {},
+ CORP,
+ "project default-index",
+ ),
+ (
+ _uv_toml(f'default-index = "{CORP_INDEX}"\nextra-index-url = ["{PYPI_URL}"]\n'),
+ {},
+ CORP + "|" + PYPI,
+ "config default plus config extra",
+ ),
+ (
+ _uv_toml(
+ f'[[index]]\nurl = "{CORP_INDEX}"\ndefault = true\n\n'
+ '[[index]]\nurl = "https://extra.test/simple"\n'
+ ),
+ {},
+ CORP + "|--extra-index-url|https://extra.test/simple",
+ "[[index]] entries",
+ ),
+ (
+ _uv_toml(f'default-index = "{CORP_INDEX}"\n'),
+ {"UV_DEFAULT_INDEX": "https://env.test/simple"},
+ "--extra-index-url|https://env.test/simple",
+ "the environment beats the file",
+ ),
+ (
+ _uv_toml(f'default-index = "{CORP_INDEX}"\n'),
+ {"UV_NO_CONFIG": "1"},
+ PYPI,
+ "UV_NO_CONFIG hides the file, as it does for uv",
+ ),
+ (
+ {},
+ {"UV_DEFAULT_INDEX": PYPI_URL, "UV_EXTRA_INDEX_URL": PYPI_URL},
+ PYPI,
+ "a duplicate is listed once",
+ ),
+ ],
+ )
+ def test_the_index_arguments(self, tmp_path, files, env, expected, why):
+ assert self._args(tmp_path, files, env) == expected, why
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "files, env, expected, why",
+ [
+ ({}, {}, PYPI, "nothing configured: public PyPI"),
+ ({}, {"PIP_NO_INDEX": "1"}, "", "pip no-index"),
+ ({}, {"PIP_INDEX_URL": CORP_INDEX}, CORP, "pip's default replaces PyPI"),
+ (
+ {},
+ {"PIP_INDEX_URL": CORP_INDEX, "PIP_EXTRA_INDEX_URL": PYPI_URL},
+ CORP + "|" + PYPI,
+ "pip's extra",
+ ),
+ ({}, {"UV_NO_INDEX": "1"}, PYPI, "uv's variable, which pip never reads"),
+ ({}, {"UV_INDEX_URL": CORP_INDEX}, PYPI, "uv's default is not pip's"),
+ (_uv_toml("no-index = true\n"), {}, PYPI, "uv's configuration files are not pip's"),
+ ],
+ )
+ def test_the_pip_fallback_reads_pips_policy(self, tmp_path, files, env, expected, why):
+ assert self._args(tmp_path, files, env, resolver = "pip") == expected, why
+
+ @requires_pwsh
+ def test_setup_answers_the_same(self, tmp_path):
+ files = _uv_toml(f'default-index = "{CORP_INDEX}"\nextra-index-url = ["{PYPI_URL}"]\n')
+ assert self._args(tmp_path, files, {}, SETUP_SRC) == self.CORP + "|" + self.PYPI
+ assert self._args(tmp_path, {}, {"UV_NO_INDEX": "1"}, SETUP_SRC) == ""
+ assert self._args(tmp_path, {}, {"PIP_NO_INDEX": "1"}, SETUP_SRC, resolver = "pip") == ""
+
+ @pytest.mark.parametrize(
+ "name",
+ [
+ "Remove-WoaTomlComment",
+ "Split-WoaTomlKey",
+ "Read-WoaUvInlineIndexArray",
+ "Read-WoaUvTomlIndexKeys",
+ "Get-WoaUvConfigIndexPolicy",
+ "Test-WoaUvIndexPolicyUnreadable",
+ "Get-WoaDependencyIndexArgs",
+ ],
+ )
+ def test_the_two_copies_match(self, name):
+ install, setup = _ps_copies(name)
+ assert install == setup
+
+ def test_both_install_paths_use_it_and_neither_hard_codes_pypi(self):
+ trio = INSTALL_SRC[INSTALL_SRC.index("# NVIDIA's index publishes only the trio") :][:900]
+ assert "$_woaDependencyIndexArgs = @(Get-WoaDependencyIndexArgs)" in trio
+ assert f'"--extra-index-url", "{PYPI_URL}"' not in trio
+ # The whole block, not a fixed slice of it: a guard added ahead of the call pushed the
+ # call past a 500-character window and failed an assertion that was still true.
+ shared = SETUP_SRC[SETUP_SRC.index("$WinArm64IndexArgs = if ($WinArm64Venv) {") :]
+ shared = shared[: shared.index("\n} else {")]
+ assert (
+ '$_woaResolver = if ($UseUv) { "uv" } else { "pip" }' in shared
+ ), "the resolver that runs the install"
+ assert "@(Get-WoaDependencyIndexArgs -Resolver $_woaResolver)" in shared
+ assert f'"--extra-index-url", "{PYPI_URL}"' not in shared
+
+
+class TestTheArmJobRunsForEveryRequirementsInput:
+ """The path filter named constraints.txt alone, although the selected tests read pyproject.toml
+ and the other files under studio/backend/requirements/. A change to one of those skipped the
+ workflow, so a marker or pin regression merged without the ARM checks."""
+
+ def test_both_filters_name_the_requirements_tree_and_pyproject(self):
+ text = WORKFLOW.read_text(encoding = "utf-8")
+ head = text[: text.index("workflow_dispatch:")]
+ push = head[head.index(" push:") : head.index(" pull_request:")]
+ pull = head[head.index(" pull_request:") :]
+ for name, block in (("push", push), ("pull_request", pull)):
+ assert "- 'pyproject.toml'" in block, name
+ assert "- 'studio/backend/requirements/**'" in block, name
+
+
+class TestATerminatingErrorStillRemovesTheMergedOverrides:
+ """Exit-SetupFailure and the last statement of the script both remove the merged file, but a
+ throw after the restore (the unsupported-Vulkan one, for instance) reaches neither. A trap at
+ script scope removes it and rethrows."""
+
+ def test_the_trap_precedes_the_restore(self):
+ trap = SETUP_SRC.index("trap { Remove-WoaMergedOverrides; break }")
+ assert trap < SETUP_SRC.index("\nRestore-WoaResolverEnvironment\n")
+
+ @requires_pwsh
+ def test_a_throw_after_the_restore_removes_the_file_and_still_fails(self, tmp_path):
+ merged = tmp_path / "overrides.merged.txt"
+ merged.write_text("secret @ https://user:[email protected]/w.whl\n", encoding = "utf-8")
+ done = _ps(
+ _script(
+ _function_source(SETUP_SRC, "Remove-WoaMergedOverrides"),
+ f"$script:WoaMergedOverrides = '{merged}'",
+ "trap { Remove-WoaMergedOverrides; break }",
+ 'throw "Vulkan was requested, but no Windows ARM64 Vulkan bundle is published."',
+ 'Write-Output "REACHED_UNREACHABLE"',
+ )
+ )
+ assert done.returncode != 0
+ assert "REACHED_UNREACHABLE" not in done.stdout
+ assert (
+ "Vulkan was requested" in done.stderr + done.stdout
+ ), "the error is rethrown, not swallowed"
+ assert not merged.exists()
+
+
+class TestAnUnwritableWheelDirectoryIsAStop:
+ """The catch stood native mode down after the ARM64 venv existed, and the torch step then went
+ to the driver-derived index, which has no win_arm64 wheel. It stops with the reason now, as the
+ pyarrow staging failure does."""
+
+ @staticmethod
+ def _block():
+ return slice_between(
+ INSTALL_SRC,
+ ' if ($script:WoaNativeCudaTorch) {\n $WoaDir = Join-Path $StudioHome "woa"',
+ " if ($script:WoaNativeCudaTorch) {\n"
+ ' if ($script:WoaPyarrowSource -eq "local") {',
+ )
+
+ def test_the_catch_exits_with_the_reason(self):
+ block = self._block()
+ assert (
+ 'return (Exit-InstallFailure "windows on arm: could not create $WoaWheelDir")' in block
+ )
+ assert "UNSLOTH_WOA_NATIVE=0" in block
+ assert "falling back to the x64 stack" not in block
+
+ @requires_pwsh
+ def test_a_file_in_the_way_stops_the_install(self, tmp_path):
+ (tmp_path / "woa").write_text("not a directory", encoding = "utf-8")
+ script = _script(
+ "$script:Lines = @()",
+ "function Write-StudioLine { param($m, $ForegroundColor) $script:Lines += $m }",
+ "function substep { param($m, $c) $script:Lines += $m }",
+ 'function Exit-InstallFailure { param($m, $c) return "STOPPED: $m" }',
+ "function Install-Probe {",
+ " $script:WoaNativeCudaTorch = $true",
+ f" $StudioHome = '{tmp_path}'",
+ self._block(),
+ " return 'CONTINUED'",
+ "}",
+ "$r = Install-Probe",
+ "Write-Output ('RESULT=' + $r)",
+ "Write-Output ('NATIVE=' + $script:WoaNativeCudaTorch)",
+ "Write-Output ('MSG=' + ($script:Lines -join ' | '))",
+ )
+ out = _ps_kv(script)
+ assert out["RESULT"].startswith("STOPPED: windows on arm: could not create"), out
+ assert out["NATIVE"] == "True", "not silently stood down"
+ assert "[ERROR]" in out["MSG"] and "UNSLOTH_WOA_NATIVE=0" in out["MSG"]
+
+
+class TestANoIndexNativeTrioStillSeesItsSources:
+ """Under UV_NO_INDEX the trio command carried --default-index, so Invoke-InstallCommand cleared
+ UV_FIND_LINKS while --no-index stayed on: neither the CUDA index nor the staged wheelhouse was
+ visible and the exact pin failed. The wheelhouse now rides on the command line, and UV_NO_INDEX
+ yields for this one command and is put back after it."""
+
+ @staticmethod
+ def _extra_args(tmp_path, env):
+ # Anchored on the code either side rather than on the comments that head them.
+ block = slice_between(
+ INSTALL_SRC,
+ " $_woaDependencyIndexArgs = @(Get-WoaDependencyIndexArgs)",
+ " if ($script:WoaTorchIsPrerelease -or"
+ " ($script:WoaTorchIndexUrl -match 'nightly')) {",
+ )
+ script = _script(
+ clear_env(UV_ONLY_INDEX_ENV),
+ "$env:UV_NO_CONFIG = '1'",
+ "\n".join(f"$env:{k} = '{v}'" for k, v in env.items()),
+ SUBSTEP_NOOP,
+ functions(
+ INSTALL_SRC,
+ "Get-UvSafePath",
+ "Get-WoaUvConfigIndexPolicy",
+ "Get-WoaDependencyIndexArgs",
+ ),
+ f"$script:WoaDir = '{tmp_path / 'woa'}'",
+ block,
+ "Write-Output ('[' + ($_torchExtraArgs -join '|') + ']')",
+ )
+ return _ps_last(script)[1:-1].split("|")
+
+ @requires_pwsh
+ def test_the_wheelhouse_is_named_on_the_command_line(self, tmp_path):
+ args = self._extra_args(tmp_path, {})
+ i = args.index("--find-links")
+ assert args[i + 1] == str(tmp_path / "woa" / "wheels")
+ assert "--extra-index-url" in args, "with no policy the dependencies come from PyPI as well"
+
+ @requires_pwsh
+ def test_under_no_index_the_wheelhouse_is_the_only_dependency_source(self, tmp_path):
+ args = self._extra_args(tmp_path, {"UV_NO_INDEX": "1"})
+ assert "--find-links" in args
+ assert "--extra-index-url" not in args
+
+ @staticmethod
+ def _swap_block():
+ return slice_between(
+ INSTALL_SRC,
+ INSTALL_CUTOFF_SWAP_START,
+ " try {\n $torchInstallExit ="
+ ' Invoke-InstallCommandRetry -Label "install PyTorch"',
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "value, yields", [("1", True), ("true", True), ("0", False), ("false", False)]
+ )
+ def test_no_index_yields_for_the_command_and_is_put_back(self, value, yields):
+ script = _script(
+ substep_collector(),
+ "$script:WoaNativeCudaTorch = $true",
+ "$VenvPlatform = 'win-arm64'",
+ f"$env:UV_NO_INDEX = '{value}'",
+ "Remove-Item Env:UV_EXCLUDE_NEWER -ErrorAction SilentlyContinue",
+ "Remove-Item Env:UV_EXCLUDE_NEWER_PACKAGE -ErrorAction SilentlyContinue",
+ "$_woaCutoffSaved = @{}",
+ self._swap_block(),
+ "Write-Output ('DURING=' + [string]$env:UV_NO_INDEX)",
+ CUTOFF_RESTORE,
+ "Write-Output ('AFTER=' + [string]$env:UV_NO_INDEX)",
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
+ out = _ps_kv(script)
+ assert out["DURING"] == ("" if yields else value)
+ assert out["AFTER"] == value, "the caller's value comes back either way"
+ assert ("UV_NO_INDEX yields" in out["MSG"]) is yields
+
+
+class TestANoIndexNativeTrioStillSeesItsSourcesInSetup:
+ """setup.ps1's trio step had the same gap as install.ps1's: Fast-Install clears UV_FIND_LINKS
+ and PIP_FIND_LINKS whenever --index-url is given and leaves UV_NO_INDEX alone, so under
+ --no-index the update saw neither the wheelhouse nor the CUDA index."""
+
+ @staticmethod
+ def _index_args(tmp_path, env):
+ (tmp_path / "woa" / "wheels").mkdir(parents = True)
+ script = _script(
+ clear_env(UV_INDEX_ENV),
+ "$env:UV_NO_CONFIG = '1'",
+ "\n".join(f"$env:{k} = '{v}'" for k, v in env.items()),
+ UV_SAFE_PATH,
+ functions(SETUP_SRC, "Get-WoaUvConfigIndexPolicy", "Get-WoaDependencyIndexArgs"),
+ f"$StudioHome = '{tmp_path}'",
+ "$WinArm64Venv = $true",
+ "$UseUv = $true",
+ f"$WinArm64TorchIndexUrl = '{NV_GA}'",
+ "$WinArm64EffectiveTorchIndexUrl = $WinArm64TorchIndexUrl",
+ "$WinArm64HandoffApplies = $true",
+ "$env:UNSLOTH_WOA_TORCH_PRERELEASE = '0'",
+ INDEX_ARGS_BLOCK,
+ "Write-Output ('[' + ($WinArm64IndexArgs -join '|') + ']')",
+ )
+ return _ps_last(script)[1:-1].split("|")
+
+ @requires_pwsh
+ def test_the_wheelhouse_is_named_on_the_command_line(self, tmp_path):
+ args = self._index_args(tmp_path, {})
+ i = args.index("--find-links")
+ assert args[i + 1] == str(tmp_path / "woa" / "wheels")
+ assert "--extra-index-url" in args, "with no policy the dependencies come from PyPI as well"
+
+ @requires_pwsh
+ def test_under_no_index_the_wheelhouse_is_the_only_dependency_source(self, tmp_path):
+ args = self._index_args(tmp_path, {"UV_NO_INDEX": "1"})
+ assert "--find-links" in args
+ assert "--extra-index-url" not in args
+
+ def test_the_setting_fast_install_clears_is_the_one_put_on_the_command_line(self):
+ body = _function_source(SETUP_SRC, "Fast-Install")
+ assert "'UV_FIND_LINKS'" in body and "'PIP_FIND_LINKS'" in body
+ assert "--find-links" in INDEX_ARGS_BLOCK
+
+ @staticmethod
+ def _swap_block():
+ return slice_between(
+ SETUP_SRC,
+ " if ($WinArm64Venv) {\n"
+ " # The pins are exact and the index page carries no upload dates",
+ " try {\n if ($script:UnslothVerbose) {\n"
+ " Fast-Install @_cudaTrio",
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "value, yields", [("1", True), ("true", True), ("0", False), ("false", False)]
+ )
+ def test_no_index_yields_for_the_command_and_is_put_back(self, value, yields):
+ script = _script(
+ substep_collector(),
+ "$WinArm64Venv = $true",
+ f"$env:UV_NO_INDEX = '{value}'",
+ "$env:UV_EXCLUDE_NEWER = '2026-01-01'",
+ "Remove-Item Env:UV_EXCLUDE_NEWER_PACKAGE -ErrorAction SilentlyContinue",
+ "$_woaCutoffSaved = @{}",
+ self._swap_block(),
+ "Write-Output ('DURING=' + [string]$env:UV_NO_INDEX)",
+ "Write-Output ('CUTOFF=' + [string]$env:UV_EXCLUDE_NEWER)",
+ CUTOFF_RESTORE,
+ "Write-Output ('AFTER=' + [string]$env:UV_NO_INDEX)",
+ "Write-Output ('CUTOFFAFTER=' + [string]$env:UV_EXCLUDE_NEWER)",
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
+ out = _ps_kv(script)
+ assert out["DURING"] == ("" if yields else value)
+ assert out["AFTER"] == value, "the caller's value comes back either way"
+ assert ("UV_NO_INDEX yields" in out["MSG"]) is yields
+ assert (
+ out["CUTOFF"] == "" and out["CUTOFFAFTER"] == "2026-01-01"
+ ), "the cutoff swap is unchanged"
+
+ @requires_pwsh
+ def test_off_arm64_nothing_is_touched(self):
+ script = _script(
+ SUBSTEP_NOOP,
+ "$WinArm64Venv = $false",
+ "$env:UV_NO_INDEX = '1'",
+ "$_woaCutoffSaved = @{}",
+ self._swap_block(),
+ "Write-Output ('DURING=' + [string]$env:UV_NO_INDEX + ' SAVED='"
+ " + $_woaCutoffSaved.Count)",
+ )
+ assert _ps_last(script) == "DURING=1 SAVED=0"
+
+
+class TestProbeWarningsDoNotPrintIndexCredentials:
+ """Two warnings printed the candidate index URL as configured. An authenticated mirror that
+ lags on torchvision, or whose torch outruns the driver, put its token in the installer output
+ and the Tauri log."""
+
+ URL = "https://user:[email protected]/simple?token=abc"
+
+ def _native(self, driver, vision):
+ script = native_probe_script(
+ driver = f"@({driver[0]}, {driver[1]})",
+ stubs = (
+ f"$env:UNSLOTH_TORCH_INDEX_URL = '{self.URL}'",
+ "function Test-WoaCudaWheel"
+ " { param($IndexUrl, $PythonMinor, $AbiTag, $Project) $true }",
+ "function Get-WoaCudaWheelVersion { param($IndexUrl, $PythonMinor, $AbiTag,"
+ " $Project, $PairWith, $Below)",
+ " if ($Below) { return '' }",
+ f" if ($Project -eq 'torchvision') {{ return '{vision}' }}",
+ " if ($Project -eq 'torchaudio') { return '' }",
+ " return '2.14.0+cu134' }",
+ ),
+ lifts = ("Remove-IndexUrlCredentials",),
+ )
+ return _ps_kv(script)
+
+ @requires_pwsh
+ def test_the_unpaired_torchvision_warning(self):
+ out = self._native((13, 4), "")
+ assert out["NATIVE"] == "False"
+ assert "mirror.test" in out["MSG"] and "no torchvision paired" in out["MSG"]
+ assert "s3cret" not in out["MSG"] and "token=abc" not in out["MSG"]
+
+ @requires_pwsh
+ def test_the_driver_warning(self):
+ out = self._native((12, 8), "0.29.0+cu134")
+ assert out["NATIVE"] == "False"
+ assert "mirror.test" in out["MSG"] and "Update the NVIDIA driver" in out["MSG"]
+ assert "s3cret" not in out["MSG"] and "token=abc" not in out["MSG"]
+
+
+class TestTheNoAudioDecisionFollowsTheProbe:
+ """On a fresh-shell update there is no handoff, so $WinArm64NoAudio was fixed to true even when
+ the effective index pairs a torchaudio with the torch it selects: the trio was installed
+ without it and an older audio build removed."""
+
+ def test_the_probe_revises_the_decision(self):
+ start = SETUP_SRC.index("$_woaAudioV = Get-WoaCudaWheelVersionParity")
+ block = SETUP_SRC[start : start + 1400]
+ assert (
+ "$_woaProbeHasAudio = [bool]($_woaAudioV -and (Test-WoaAudioMatchesTorchParity"
+ " -TorchVersion $_woaTorchV -AudioVersion $_woaAudioV))" in block
+ )
+ assert "$WinArm64NoAudio = -not $_woaProbeHasAudio" in block
+
+ def test_the_parity_copy_has_not_drifted(self):
+ def normalized(source, name):
+ lines = [
+ l.strip()
+ for l in _function_source(source, name).splitlines()
+ if l.strip() and not l.strip().startswith("#")
+ ]
+ return "\n".join(lines[1:]) # the signature line carries the name
+
+ assert normalized(INSTALL_SRC, "Test-WoaAudioMatchesTorch") == normalized(
+ SETUP_SRC, "Test-WoaAudioMatchesTorchParity"
+ )
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "torch, audio, matches",
+ [
+ ("2.14.0+cu134", "2.11.0+cu134", "False"),
+ ("2.15.0.dev20260904+cu134", "2.15.0.dev20260904+cu134", "True"),
+ ("2.11.0+cu134", "2.11.0+cu134", "True"),
+ ],
+ )
+ def test_the_parity_predicate(self, torch, audio, matches):
+ script = _script(
+ _function_source(SETUP_SRC, "Test-WoaAudioMatchesTorchParity"),
+ f"Write-Output (Test-WoaAudioMatchesTorchParity -TorchVersion '{torch}'"
+ f" -AudioVersion '{audio}')",
+ )
+ assert _ps_last(script) == matches
+
+
+class TestARetainedTorchaudioMustPairWithTheNewTorch:
+ """The retention check compared major.minor only, while selection requires the dev stamp and
+ CUDA tag to match too: a nightly torchaudio one stamp behind the replaced torch was kept,
+ linked against a libtorch that is gone."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "torch, audio, kept",
+ [
+ ("2.15.0.dev20260904+cu134", "2.15.0.dev20260904+cu134", True),
+ ("2.15.0.dev20260904+cu134", "2.15.0.dev20260902+cu134", False),
+ ("2.14.0+cu134", "2.14.0+cu130", False),
+ ("2.14.0+cu134", "2.11.0+cu134", False),
+ ],
+ )
+ def test_the_predicate_pair(self, torch, audio, kept):
+ script = _script(
+ functions(SETUP_SRC, "Test-WoaAudioMatchesTorchParity", "Test-WoaPairsWithTorchParity"),
+ f"$a = Test-WoaAudioMatchesTorchParity -TorchVersion '{torch}'"
+ f" -AudioVersion '{audio}'",
+ f"$b = Test-WoaPairsWithTorchParity -TorchVersion '{torch}' -OtherVersion '{audio}'"
+ " -Project 'torchaudio'",
+ "Write-Output ($a -and $b)",
+ )
+ assert _ps_last(script) == str(kept)
+
+
+class TestTheArmJobFailsWhenARequiredTestSkips:
+ """-rs only reports skipped cases, so a guard that stopped a test running on the very row it
+ exists for still reported green."""
+
+ def test_the_summary_line_is_read_back(self):
+ text = WORKFLOW.read_text(encoding = "utf-8")
+ start = text.index("- name: WoA installer and wheelhouse tests")
+ step = text[start : text.index("- name: Uninstaller tests", start)]
+ assert "-q -rs" in step
+ assert "if ($rc -ne 0) { exit $rc }" in step
+ assert r"if ($summary -match '(\d+) skipped')" in step
+ assert "exit 1" in step[step.index("skipped") :]
+
+
+class TestBothNvidiaSmiProbesSearchTheSameLocations:
+ """The presence probe searched PATH, System32 and NVSMI while the version probe searched PATH
+ and System32 only. On a host carrying nvidia-smi.exe under NVSMI alone, Test-WoaNvidiaPresent
+ said yes and Get-WoaDriverCudaVersion returned $null, so Initialize-WoaNativeCudaTorch skipped
+ the CUDA-major guard entirely. A guard that silently does not run is the failure this covers."""
+
+ LOCATIONS = (
+ r"$env:SystemRoot\System32\nvidia-smi.exe",
+ r"$env:ProgramFiles\NVIDIA Corporation\NVSMI\nvidia-smi.exe",
+ )
+
+ def test_the_shared_helper_lists_every_supported_location(self):
+ body = _function_source(INSTALL_SRC, "Get-WoaNvidiaSmiPath")
+ assert "Get-Command nvidia-smi" in body
+ for location in self.LOCATIONS:
+ assert location in body, location
+
+ @pytest.mark.parametrize("name", ("Test-WoaNvidiaPresent", "Get-WoaDriverCudaVersion"))
+ def test_neither_probe_keeps_its_own_candidate_list(self, name):
+ body = _function_source(INSTALL_SRC, name)
+ assert "$exe = Get-WoaNvidiaSmiPath" in body, f"{name} does not use the shared lookup"
+ # The point of the shared helper: a second list is what let the two disagree.
+ for location in self.LOCATIONS:
+ assert location not in body, f"{name} still hardcodes {location}"
+
+ def test_the_helper_is_defined_before_both_callers(self):
+ # PowerShell does not hoist, so definition order is load-bearing here.
+ helper = INSTALL_SRC.index("function Get-WoaNvidiaSmiPath")
+ for name in ("Test-WoaNvidiaPresent", "Get-WoaDriverCudaVersion"):
+ assert helper < INSTALL_SRC.index(f"function {name}"), name
+
+ def test_every_composed_script_injects_the_helper_its_bodies_call(self):
+ """The pwsh tests paste real function bodies into a bare script, so a body that gains a
+ call to a helper the composition does not also inject leaves that call unresolved.
+ PowerShell writes an error and carries on with $null, so Get-WoaDriverCudaVersion returns
+ $null BEFORE reaching nvidia-smi and the "[]" assertion still passes: a silent false pass,
+ and on a host without pwsh the whole test skips. This guard needs no pwsh."""
+ callers = [
+ name
+ for name in ("Test-WoaNvidiaPresent", "Get-WoaDriverCudaVersion")
+ if "Get-WoaNvidiaSmiPath" in _function_source(INSTALL_SRC, name)
+ ]
+ assert callers, "neither probe routes through the shared lookup any more"
+ own = pathlib.Path(__file__).read_text(encoding = "utf-8")
+ for name in callers:
+ for match in re.finditer(rf'_function_source\(INSTALL_SRC, "{re.escape(name)}"\)', own):
+ # The _script(...) call this appears in, back to its opening paren.
+ start = own.rindex("_script(", 0, match.start())
+ block = own[start : own.index("\n )", match.end())]
+ assert '_function_source(INSTALL_SRC, "Get-WoaNvidiaSmiPath")' in block, (
+ f"a composed script injects {name}, which calls Get-WoaNvidiaSmiPath, "
+ "without injecting that helper"
+ )
+
+ def test_the_guard_this_protects_is_still_there(self):
+ # If the CUDA-major check ever goes away, this whole class is pointless; say so loudly.
+ body = _function_source(INSTALL_SRC, "Initialize-WoaNativeCudaTorch")
+ assert "$_woaDriver = Get-WoaDriverCudaVersion" in body
+ assert "if ($_woaDriver -and $_woaTorchVersion -match '\\+cu(\\d+)')" in body
+
+
+class TestAnExplicitBlockIndexIsNotAGeneralExtra:
+ """The block form `[[index]]` read url and default only, so `explicit = true` was flushed as a
+ general extra and Get-WoaDependencyIndexArgs handed the trio resolve an --extra-index-url
+ the user had restricted to explicitly pinned packages. Both readers, both scripts."""
+
+ A = "https://a.corp.test/simple"
+ B = "https://b.corp.test/simple"
+
+ @staticmethod
+ def _read(src, tmp_path, body, top):
+ cfg = tmp_path / ("pyproject.toml" if top else "uv.toml")
+ cfg.write_text(body, encoding = "utf-8")
+ script = _script(
+ functions(
+ src,
+ "Remove-WoaTomlComment",
+ "Split-WoaTomlKey",
+ "Read-WoaUvInlineIndexArray",
+ "Read-WoaUvTomlIndexKeys",
+ ),
+ f"$p = Read-WoaUvTomlIndexKeys -Path '{cfg}' -Top '{top}'",
+ "if ($null -eq $p) { Write-Output 'NULL' } else { "
+ "Write-Output (([string]$p.DefaultIndex) + '|' + (@($p.ExtraIndexes) -join ',')) }",
+ )
+ return _ps_last(script)
+
+ @requires_pwsh
+ @pytest.mark.parametrize("src", [INSTALL_SRC, SETUP_SRC], ids = ["install.ps1", "setup.ps1"])
+ @pytest.mark.parametrize(
+ "body, top, expected, why",
+ [
+ (f'[[index]]\nurl = "{A}"\nexplicit = true\n', "", "|", "explicit alone: nothing"),
+ (
+ f'[[index]]\nurl = "{A}"\nexplicit = true\n\n[[index]]\nurl = "{B}"\n',
+ "",
+ f"|{B}",
+ "the other entry is still an extra",
+ ),
+ (
+ f'[[index]]\nurl = "{A}"\ndefault = true\n\n[[index]]\nurl = "{B}"\nexplicit = true\n',
+ "",
+ f"{A}|",
+ "an explicit entry beside the default",
+ ),
+ (
+ f'[[index]]\nurl = "{A}"\nexplicit = false\n',
+ "",
+ f"|{A}",
+ "explicit = false is an extra",
+ ),
+ (
+ f'[[tool.uv.index]]\nurl = "{A}"\nexplicit = true\n',
+ "tool.uv",
+ "|",
+ "pyproject [[tool.uv.index]]",
+ ),
+ (
+ f'[[index]]\nurl = "{A}"\nexplicit = true\ndefault = true\n',
+ "",
+ "NULL",
+ "explicit AND default removes PyPI as the default: not modelled, so doubt",
+ ),
+ ],
+ )
+ def test_the_block_form(self, tmp_path, src, body, top, expected, why):
+ assert self._read(src, tmp_path, body, top) == expected, why
+
+
+class TestTheInlineIndexSpellingIsRead:
+ """`index = [{ url = "...", default = true }]` is valid, documented uv config, and the parser
+ refused it outright with `return $null`. Every downstream disagreement about Unreadable was a
+ symptom: a corporate mirror written this way read as "cannot know", and
+ Get-WoaDependencyIndexArgs then substituted public PyPI for it."""
+
+ @staticmethod
+ def _funcs(src):
+ return functions(
+ src,
+ "Remove-WoaTomlComment",
+ "Split-WoaTomlKey",
+ "Read-WoaUvInlineIndexArray",
+ "Read-WoaUvTomlIndexKeys",
+ )
+
+ @pytest.mark.parametrize(
+ "value, want_default, want_extras",
+ [
+ (f'[{{ url = "{CORP_INDEX}", default = true }}]', CORP_INDEX, []),
+ (f'[{{ url = "{PYPI}", default = true }}]', PYPI, []),
+ (
+ '[{ url = "https://a/simple" }, { url = "https://b/simple", default = true }]',
+ "https://b/simple",
+ ["https://a/simple"],
+ ),
+ (
+ '[{ name = "corp", url = "https://c/simple", default = true }]',
+ "https://c/simple",
+ [],
+ ),
+ ("[]", None, []),
+ # uv: explicit = true serves only packages pinned via [tool.uv.sources], so it is
+ # neither the default nor an extra for the trio's dependencies.
+ ('[{ url = "https://a/simple", explicit = true }]', None, []),
+ (
+ '[{ url = "https://a/simple", explicit = true }, { url = "https://b/simple" }]',
+ None,
+ ["https://b/simple"],
+ ),
+ ('[{ url = "https://a/simple", explicit = false }]', None, ["https://a/simple"]),
+ ],
+ )
+ @pytest.mark.parametrize("src", [INSTALL_SRC, SETUP_SRC], ids = ["install.ps1", "setup.ps1"])
+ @requires_pwsh
+ def test_a_flat_inline_array_is_read(self, tmp_path, src, value, want_default, want_extras):
+ cfg = tmp_path / "uv.toml"
+ cfg.write_text(f"index = {value}\n", encoding = "utf-8")
+ script = _script(
+ self._funcs(src),
+ f"$p = Read-WoaUvTomlIndexKeys -Path '{cfg}' -Top ''",
+ "if ($null -eq $p) { Write-Output 'NULL' } else { "
+ "Write-Output (([string]$p.DefaultIndex) + '|' + (@($p.ExtraIndexes) -join ',')) }",
+ )
+ assert _ps_last(script) == f"{want_default or ''}|{','.join(want_extras)}"
+
+ @pytest.mark.parametrize(
+ "value",
+ [
+ # Ambiguity that must stay Unreadable rather than be guessed at.
+ # explicit AND default also removes PyPI as the default (uv docs): not modelled.
+ '[{ url = "https://a/simple", explicit = true, default = true }]',
+ '[{ url = "https://a/simple", explicit = "yes" }]', # not a bool
+ "[{ default = true }]", # no url at all
+ '[{ url = "https://a/simple", default = "yes" }]', # not a bool
+ '[{ url = { host = "a" } }]', # nested table
+ '[{ url = "https://a/simple" }, "https://b"]', # a bare entry beside a table
+ '[{ url = "https://a/simple" }', # unbalanced / continues next line
+ ],
+ )
+ @pytest.mark.parametrize("src", [INSTALL_SRC, SETUP_SRC], ids = ["install.ps1", "setup.ps1"])
+ @requires_pwsh
+ def test_anything_ambiguous_stays_unreadable(self, tmp_path, src, value):
+ cfg = tmp_path / "uv.toml"
+ cfg.write_text(f"index = {value}\n", encoding = "utf-8")
+ script = _script(
+ self._funcs(src),
+ f"$p = Read-WoaUvTomlIndexKeys -Path '{cfg}' -Top ''",
+ "Write-Output $(if ($null -eq $p) { 'NULL' } else { 'READ' })",
+ )
+ assert _ps_last(script) == "NULL"
+
+ def test_the_parser_no_longer_refuses_the_key_outright(self):
+ """No pwsh needed, so this runs everywhere. `return $null` on sight of the key was the
+ defect; it must now go through the array reader, which still answers $null on doubt."""
+ for src, label in ((INSTALL_SRC, "install.ps1"), (SETUP_SRC, "setup.ps1")):
+ body = _function_source(src, "Read-WoaUvTomlIndexKeys")
+ assert "if ($key -eq 'index') { return $null }" not in body, label
+ assert "Read-WoaUvInlineIndexArray -Value $val" in body, label
+ # The conservative answer is still reachable from the caller.
+ assert "if ($null -eq $inline) { return $null }" in body, label
+
+ def test_an_unreadable_policy_never_substitutes_public_pypi(self):
+ """The consumer half. Get-WoaDependencyIndexArgs read NoIndex, DefaultIndex and
+ ExtraIndexes but not Unreadable, so it fell through to the public PyPI default and
+ silently overrode the mirror the file configured."""
+ for src, label in ((INSTALL_SRC, "install.ps1"), (SETUP_SRC, "setup.ps1")):
+ body = _function_source(src, "Get-WoaDependencyIndexArgs")
+ assert "if ($cfg.Unreadable -and -not $default) { return @() }" in body, label
+ # Ordering is the whole point: the guard must precede the PyPI fallback.
+ assert body.index("$cfg.Unreadable") < body.index(f'"{PYPI}"'), label
+
+ def test_the_site_that_cannot_read_config_stops_instead_of_guessing(self):
+ """setup.ps1's trio runs under Fast-Install with --index-url, which sets UV_NO_CONFIG and
+ scrubs UV_*, so uv cannot read the file itself and an empty answer would leave the trio
+ index as the only source. install.ps1 calls uv directly and can take the empty answer."""
+ block = SETUP_SRC[SETUP_SRC.index("$WinArm64IndexArgs = if ($WinArm64Venv) {") :]
+ block = block[: block.index("\n} else {")]
+ assert "Test-WoaUvIndexPolicyUnreadable" in block
+ assert "Exit-SetupFailure" in block
+ # The message has to be actionable: the file, the spelling, and both ways out.
+ assert "UnreadablePath" in block
+ assert "[[index]]" in block
+ assert "UV_DEFAULT_INDEX" in block
+ # install.ps1's trio step deliberately does NOT stop; it lets uv read the config.
+ assert "Test-WoaUvIndexPolicyUnreadable" not in _function_source(
+ INSTALL_SRC, "Get-WoaDependencyIndexArgs"
+ )
+
+
+class TestThePyPIProvidedHandoverIsExported:
+ """What install.ps1 learned about PyPI serving a wheelhouse wheel reaches
+ install_python_stack.py only through UNSLOTH_WOA_PYPI_PROVIDED."""
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "table, expected, why",
+ [
+ (
+ '@{ tiktoken = @("0.12.0"); "hf-transfer" = @("0.1.9", "0.1.9", "") }',
+ "hf-transfer==0.1.9 tiktoken==0.12.0",
+ "one name==version per finding, sorted, blanks and repeats dropped",
+ ),
+ ("@{}", "", "nothing found: assigned blank, never left over from an earlier run"),
+ ],
+ )
+ def test_the_value_install_python_stack_reads(self, table, expected, why):
+ script = _script(
+ f"$script:WoaPyPIProvided = {table}",
+ '$env:UNSLOTH_WOA_PYPI_PROVIDED = "stale==0.0.0"',
+ slice_between(
+ INSTALL_SRC,
+ "$_woaProvidedPairs = @()",
+ '$env:UNSLOTH_WOA_PYPI_PROVIDED = ($_woaProvidedPairs -join " ")',
+ include_end = True,
+ ),
+ 'Write-Output "[$env:UNSLOTH_WOA_PYPI_PROVIDED]"',
+ )
+ assert _ps_last(script) == f"[{expected}]", why
+
+
+class TestFoldedCallerOverridesDoNotOutliveTheRun:
+ """A caller file that clashes with one of ours is folded line by line, and those lines were
+ written into woa\\overrides.txt: the file setup.ps1 restores on every fresh-shell update. A
+ credentialed direct URL or a private index policy the caller set once was then on disk for
+ good and applied to every later update. They go to a per-run file instead."""
+
+ @staticmethod
+ def _block() -> str:
+ start = INSTALL_SRC.index(" $_woaOwnNames = @{}")
+ end = INSTALL_SRC.index('$env:UV_OVERRIDE = ($_woaOverrideValue -join " ")', start)
+ return INSTALL_SRC[start : INSTALL_SRC.index("\n", end)]
+
+ def _run(
+ self,
+ tmp_path,
+ caller_lines,
+ stale = None,
+ ):
+ caller = tmp_path / "ov.txt"
+ caller.write_text("\n".join(caller_lines) + "\n", encoding = "utf-8")
+ managed = tmp_path / "overrides.txt"
+ session = tmp_path / "overrides.session.txt"
+ if stale is not None:
+ session.write_text(stale, encoding = "utf-8")
+ script = _script(
+ functions(INSTALL_SRC, "Resolve-WoaOverrideLine", "Get-WoaRequirementEntries"),
+ UV_SAFE_PATH,
+ "$WoaOverrideLines = @('# generated', 'torch>=2.4')",
+ f"$WoaOverrides = '{managed}'",
+ f"$env:UV_OVERRIDE = '{caller}'",
+ self._block(),
+ 'Write-Output ("OVERRIDE=" + $env:UV_OVERRIDE)',
+ 'Write-Output ("SESSION=" + $script:WoaSessionOverrides)',
+ )
+ out = _ps_ok(script).stdout.splitlines()
+ value = [l for l in out if l.startswith("OVERRIDE=")][-1][len("OVERRIDE=") :].split()
+ recorded = [l for l in out if l.startswith("SESSION=")][-1][len("SESSION=") :]
+ return managed, session, value, recorded
+
+ SECRET = "corp-pkg @ https://user:[email protected]/corp_pkg-1.0-py3-none-any.whl"
+
+ @requires_pwsh
+ def test_a_folded_credential_never_reaches_the_persistent_file(self, tmp_path):
+ managed, session, value, recorded = self._run(tmp_path, ["torch==2.9.0", self.SECRET])
+ assert "s3cret" not in managed.read_text(encoding = "utf-8")
+ assert self.SECRET in session.read_text(encoding = "utf-8"), "still applied to this run"
+ assert value == [str(managed), str(session)], "both files reach uv"
+ assert recorded == str(session), "recorded, so the exit path can remove it"
+
+ @requires_pwsh
+ def test_a_stale_per_run_file_is_removed_even_when_nothing_folds(self, tmp_path):
+ managed, session, value, recorded = self._run(
+ tmp_path, ["brotli==1.1.0"], stale = "leftover==1\n"
+ )
+ assert not session.exists(), "an earlier interrupted run's copy would be re-read by uv"
+ assert value[0] == str(managed) and str(session) not in value
+ assert recorded == ""
+
+ def test_the_exit_path_removes_it(self):
+ """Beside the torch overrides file, which is deleted on exit for the same reason."""
+ tail = INSTALL_SRC[INSTALL_SRC.index("try {\n Install-UnslothStudio @args") :]
+ assert (
+ "Remove-Item -LiteralPath $script:WoaSessionOverrides -Force -ErrorAction SilentlyContinue"
+ in tail
+ )
+ head = INSTALL_SRC[: INSTALL_SRC.index("try {\n Install-UnslothStudio @args")]
+ assert head.rstrip().endswith(
+ "$script:WoaSessionOverrides = $null\n$script:TorchOverridesFile = $null"
+ ), "reset before the outer try: under irm | iex an earlier value must not leak"
+
+ def test_setup_restores_only_the_persistent_file(self):
+ body = _function_source(SETUP_SRC, "Restore-WoaResolverEnvironment")
+ assert 'Join-Path $woaDir "overrides.txt"' in body
+ assert (
+ 'Remove-Item -LiteralPath (Join-Path $woaDir "overrides.session.txt")' in body
+ ), "an interrupted install's copy is cleared, never restored"
+ assert body.count("overrides.session.txt") == 1, "and referenced nowhere else"
+
+
+class TestAnInlineCommentSurvivesTheRebase:
+ """`-c constraints.txt # shared pins` is a valid line: pip and uv treat whitespace then "#"
+ as a comment. The rebase read the comment as part of the path and quoted a file that does
+ not exist, so a folded caller override failed the very resolve it was kept for."""
+
+ # GetFullPath and os.path.abspath apply the same rule on every host (drive-rooted on Windows).
+ BASE = "/opt/corp/ov"
+
+ @classmethod
+ def _abs(cls, relative: str) -> str:
+ return os.path.abspath(os.path.join(cls.BASE, relative))
+
+ @classmethod
+ def cases(cls):
+ return [
+ (
+ "-c constraints.txt # shared pins",
+ f"-c {cls._abs('constraints.txt')} # shared pins",
+ "-c",
+ ),
+ (
+ "-f wheels # local builds",
+ f"-f {cls._abs('wheels')} # local builds",
+ "-f, spacing kept",
+ ),
+ ("-e ./pkg[dev] # editable", f"-e {cls._abs('pkg')}[dev] # editable", "-e with extras"),
+ (
+ 'pkg @ file:../x.whl ; python_version < "3.12" # note',
+ f'pkg @ {pathlib.Path(cls._abs("../x.whl")).as_uri()} ; python_version < "3.12" # note',
+ "a direct file reference keeps its marker AND its comment",
+ ),
+ ("./w/p.whl # local", f"{cls._abs('w/p.whl')} # local", "a bare wheel path"),
+ ("./pkg # local dir", f"{cls._abs('pkg')} # local dir", "a bare directory"),
+ (
+ "pkg @ https://h/x.whl#sha256=ab",
+ "pkg @ https://h/x.whl#sha256=ab",
+ "a fragment has no whitespace before it and is not a comment",
+ ),
+ ("rich>=13 # why", "rich>=13 # why", "a plain requirement is untouched"),
+ ]
+
+ @requires_pwsh
+ @pytest.mark.parametrize("path", [INSTALL_PS1, SETUP_PS1], ids = ["install", "setup"])
+ @pytest.mark.parametrize("case", range(8))
+ def test_the_comment_is_kept_and_the_path_is_not_polluted(self, path, case):
+ line, expected, why = self.cases()[case]
+ script = _script(
+ _ps_function(path, "Resolve-WoaOverrideLine"),
+ "Write-Output ('[' + (Resolve-WoaOverrideLine -Line '%s' -BaseDir '%s') + ']')"
+ % (line.replace("'", "''"), self.BASE),
+ )
+ assert _ps_last(script) == "[%s]" % expected, why
+
+
+class TestTheProbeCanLookBelowAVersion:
+ """-Below is what the backtrack walks on: the newest version ranked strictly under the one
+ given, by the same numeric-then-prerelease order the probe already uses."""
+
+ VERSIONS = [
+ "2.15.0rc1%2Bcu134",
+ "2.15.0.dev20260910%2Bcu134",
+ "2.15.0.dev20260909%2Bcu134",
+ "2.14.0%2Bcu134",
+ ]
+
+ @classmethod
+ def _pick(cls, source, fn, below):
+ parity = fn != "Get-WoaCudaWheelVersion"
+ tags = "-PyTag 'cp313' -AbiTag 'cp313'" if parity else "-PythonMinor '3.13' -AbiTag 'cp313'"
+ script = _script(
+ invoke_restmethod(_torch_links(*cls.VERSIONS)),
+ JOIN_URL_RETURNS_BASE,
+ functions(
+ source,
+ "Test-WoaWheelTagsParity" if parity else "Test-WoaWheelTags",
+ "Test-WoaPairsWithTorchParity" if parity else "Test-WoaWheelPairsWithTorch",
+ fn,
+ ),
+ "$v = %s -IndexUrl 'https://i.test' %s -Below '%s'" % (fn, tags, below),
+ "Write-Output ('[' + $v + ']')",
+ )
+ return _ps_last(script)[1:-1]
+
+ @requires_pwsh
+ @pytest.mark.parametrize(
+ "fn, source",
+ [("Get-WoaCudaWheelVersion", "INSTALL"), ("Get-WoaCudaWheelVersionParity", "SETUP")],
+ )
+ @pytest.mark.parametrize(
+ "below, expected, why",
+ [
+ ("", "2.15.0rc1+cu134", "no bound: the newest, as before"),
+ ("2.15.0rc1+cu134", "2.15.0.dev20260910+cu134", "under the rc: the newest dev build"),
+ ("2.15.0.dev20260910+cu134", "2.15.0.dev20260909+cu134", "strictly under, not itself"),
+ ("2.15.0.dev20260909+cu134", "2.14.0+cu134", "across the numeric release"),
+ ("2.14.0+cu134", "", "nothing under the oldest"),
+ ("2.15.0+cu134", "2.15.0rc1+cu134", "a final outranks every prerelease of its release"),
+ ("garbage", "", "an unreadable bound answers nothing rather than everything"),
+ ],
+ )
+ def test_the_version_under(self, fn, source, below, expected, why):
+ src = INSTALL_SRC if source == "INSTALL" else SETUP_SRC
+ assert self._pick(src, fn, below) == expected, why
+
+
+class TestAnUnpairedNewestTorchBacktracks:
+ """A nightly torchvision lags its torch by a day or two, and a partial mirror can lag longer.
+ The newest torch alone decided the index, so a lag with an older complete pair still on the
+ same index sent the install to the x64 stack, where Triton's x64 ptxas cannot serve SM121."""
+
+ NEWEST = "2.15.0.dev20260910+cu134"
+ OLDER = "2.15.0.dev20260909+cu134"
+ OLDER_VISION = "0.30.0.dev20260909+cu134"
+
+ @staticmethod
+ def _native(torch_versions, paired_vision):
+ """`torch_versions` newest first; `paired_vision` maps a torch to its torchvision."""
+ torch_list = ", ".join("'%s'" % v for v in torch_versions)
+ vision = "; ".join("'%s' = '%s'" % (k, v) for k, v in paired_vision.items())
+ script = native_probe_script(
+ driver = "@(13, 4)",
+ stubs = (
+ "$script:WoaNvidiaTorchIndexUrls = @('%s')" % NV_NIGHTLY,
+ "$script:TorchList = @(%s)" % torch_list,
+ "$script:Vision = @{ %s }" % vision,
+ "function Test-WoaCudaWheel { param($IndexUrl, $PythonMinor, $AbiTag, $Project)"
+ " $script:TorchList.Count -gt 0 }",
+ "function Get-WoaCudaWheelVersion { param($IndexUrl, $PythonMinor, $AbiTag,"
+ " $Project, $PairWith, $Below)",
+ " if ($Project -eq 'torchvision') { return $script:Vision[$PairWith] }",
+ " if ($Project -eq 'torchaudio') { return '' }",
+ " if ($Below) {",
+ " $i = [array]::IndexOf($script:TorchList, $Below)",
+ " if ($i -lt 0 -or $i -ge $script:TorchList.Count - 1) { return '' }",
+ " return $script:TorchList[$i + 1] }",
+ " return $script:TorchList[0] }",
+ ),
+ outputs = (
+ "Write-Output ('TORCH=' + $script:WoaTorchWheelVersion)",
+ "Write-Output ('VISION=' + $script:WoaVisionWheelVersion)",
+ ),
+ )
+ return _ps_kv(script)
+
+ @requires_pwsh
+ def test_the_newest_complete_pair_is_taken(self):
+ out = self._native([self.NEWEST, self.OLDER], {self.OLDER: self.OLDER_VISION})
+ assert out["NATIVE"] == "True", out["MSG"]
+ assert (out["TORCH"], out["VISION"]) == (self.OLDER, self.OLDER_VISION)
+ assert "no torchvision paired with it; trying torch %s" % self.OLDER in out["MSG"]
+
+ @requires_pwsh
+ def test_a_paired_newest_never_backtracks(self):
+ out = self._native([self.NEWEST, self.OLDER], {self.NEWEST: "0.30.0.dev20260910+cu134"})
+ assert (out["TORCH"], out["VISION"]) == (self.NEWEST, "0.30.0.dev20260910+cu134")
+ assert "trying torch" not in out["MSG"]
+
+ @requires_pwsh
+ def test_with_nothing_older_the_index_is_still_skipped(self):
+ out = self._native([self.NEWEST], {})
+ assert out["NATIVE"] == "False"
+ assert "trying the next index" in out["MSG"] and "trying torch" not in out["MSG"]
+
+ @requires_pwsh
+ def test_the_walk_is_bounded(self):
+ """Each step re-reads the index; a mirror missing torchvision for weeks is not searched
+ to its floor."""
+ versions = ["2.15.0.dev202609%02d+cu134" % d for d in range(30, 22, -1)]
+ out = self._native(versions, {versions[-1]: "0.30.0.dev20260923+cu134"})
+ assert out["NATIVE"] == "False", out["MSG"]
+ assert out["MSG"].count("trying torch") == 5
+
+
+class TestTheRepairBacktracksTheSameWay(TestAnUpdateKeepsTheInstalledPairWhenTheIndexLags):
+ """setup.ps1's repair kept the installed pair when the newest torch was unpaired, and left
+ torchvision at its floor with nothing installed. The newest complete pair on the index
+ comes first, as in install.ps1."""
+
+ def _run_with_older(self, tmp_path, installed, older_paired):
+ venv = self._venv_with(tmp_path, installed)
+ vision = "'0.30.0.dev20260904+cu134'" if older_paired else "''"
+ script = _script(
+ substep_collector(),
+ "$VenvDir = '%s'" % venv,
+ "$WinArm64Venv = $true",
+ "$WinArm64NoAudio = $true",
+ "$WinArm64EffectiveTorchIndexUrl = 'https://i.test'",
+ "function Get-WoaCudaWheelVersionParity { param($IndexUrl, $PyTag, $AbiTag, $Project,"
+ " $PairWith, $Below)",
+ " if ($Project -eq 'torchvision') {",
+ " if ($PairWith -eq '2.15.0.dev20260904+cu134') { return %s }" % vision,
+ " return '' }",
+ " if ($Project -eq 'torchaudio') { return '' }",
+ " if ($Below -eq '2.15.0.dev20260905+cu134') { return '2.15.0.dev20260904+cu134' }",
+ " if ($Below) { return '' }",
+ " return '2.15.0.dev20260905+cu134' }",
+ functions(SETUP_SRC, "Test-WoaPairsWithTorchParity", "Test-WoaAudioMatchesTorchParity"),
+ self._block(),
+ "Write-Output ('TORCH=' + $WinArm64TorchSpec)",
+ "Write-Output ('VISION=' + $WinArm64VisionSpec)",
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
+ return _ps_kv(script)
+
+ @requires_pwsh
+ def test_an_older_complete_pair_beats_the_installed_one(self, tmp_path):
+ out = self._run_with_older(
+ tmp_path, {"torch": "2.14.0+cu134", "torchvision": "0.29.0+cu134"}, True
+ )
+ assert out["TORCH"] == "torch==2.15.0.dev20260904+cu134", out["MSG"]
+ assert out["VISION"] == "torchvision==0.30.0.dev20260904+cu134"
+ assert "trying torch 2.15.0.dev20260904+cu134" in out["MSG"]
+ assert "keeping the installed" not in out["MSG"]
+
+ @requires_pwsh
+ def test_the_installed_pair_is_still_the_fallback(self, tmp_path):
+ out = self._run_with_older(
+ tmp_path, {"torch": "2.14.0+cu134", "torchvision": "0.29.0+cu134"}, False
+ )
+ assert out["TORCH"] == "torch==2.14.0+cu134", out["MSG"]
+ assert "keeping the installed torch 2.14.0+cu134" in out["MSG"]
diff --git a/tests/studio/install/test_woa_wheelhouse_guard_behaviour.py b/tests/studio/install/test_woa_wheelhouse_guard_behaviour.py
new file mode 100644
index 00000000000..5624c6b7438
--- /dev/null
+++ b/tests/studio/install/test_woa_wheelhouse_guard_behaviour.py
@@ -0,0 +1,260 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The PyPI-first wheelhouse guard, executed rather than read.
+
+test_woa_wheelhouse_prefers_pypi.py pins the SHAPE of the guard against install.ps1's
+source, which cannot catch a helper that is wired correctly and answers wrongly. The three
+bugs covered here, all found reviewing the guard's first version:
+
+1. A wheel the guard skipped stopped counting as available. $WoaWheelNames is rebuilt by
+ scanning the staging directory, and a $WoaDropCandidates name missing from it is emitted
+ as `name ; platform_machine == "AMD64"`, which EXCLUDES the package on ARM64. So the day
+ PyPI published a win_arm64 hf_transfer or brotli, the guard turned "installed from our
+ wheelhouse" into "not installed at all", firing on the event it exists for.
+
+2. abi3 was treated as universally compatible. It is forward compatible from the version it
+ was built against, so a cp314-abi3 wheel does not import on cp313, and calling ours
+ redundant against one would leave the package uninstallable.
+
+3. PyPI publishing a wheel is only availability if the resolve will look at PyPI. Offline,
+ or pointed at an exclusive mirror, dropping our copy leaves it obtainable from nowhere.
+
+Hermetic: no network. The live-PyPI leg of the guard is exercised on hardware, not here.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import shutil
+import subprocess
+import textwrap
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+INSTALL_PS1 = REPO_ROOT / "install.ps1"
+
+#: A corporate index that is not PyPI, and PyPI itself: the only distinction these make.
+CORP = "https://corp.example/simple"
+PYPI = "https://pypi.org/simple"
+
+requires_pwsh = pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
+
+HELPERS = (
+ "Test-WoaVersionAtLeast",
+ "Test-WoaWheelTags",
+ "Test-WoaWheelTagsUsable",
+ # Everything Test-WoaResolveReachesPyPI calls: a missing helper answers True and lets a
+ # lookalike index pass unnoticed.
+ "Test-WoaUrlIsPublicPyPI",
+ "Remove-WoaTomlComment",
+ "Split-WoaTomlKey",
+ "Read-WoaUvInlineIndexArray",
+ "Read-WoaUvTomlIndexKeys",
+ "Get-WoaUvConfigIndexPolicy",
+ "Test-WoaResolveReachesPyPI",
+)
+
+
+INSTALL_SRC = INSTALL_PS1.read_text(encoding = "utf-8-sig")
+
+
+def _function(source: str, name: str) -> str:
+ match = re.search(r"(?ms)^ function " + re.escape(name) + r"\b.*?^ \}\r?$", source)
+ assert match, f"install.ps1 no longer defines {name}"
+ # Lifted out of Install-UnslothStudio, so the four-space body indent comes with it.
+ return textwrap.dedent(match.group(0))
+
+
+def _drop_list_block(source: str) -> str:
+ """The real block that builds $WoaWheelNames and emits the override drop lines."""
+ start = re.search(r"(?m)^ \$WoaWheelNames = @\{\}\s*$", source)
+ end = re.search(r"(?m)^ \$WoaOverrideLines \+= 'torch>=2\.4'\s*$", source)
+ assert start and end, "the drop-list block moved"
+ return textwrap.dedent(source[start.start() : end.start()].replace("\r\n", "\n"))
+
+
+# PowerShell does not hoist, so every snippet below carries all of HELPERS in front of it.
+PRELUDE = "\n".join(_function(INSTALL_SRC, name) for name in HELPERS)
+
+
+def _run(script: str) -> str:
+ proc = subprocess.run(
+ ["pwsh", "-NoProfile", "-NonInteractive", "-Command", PRELUDE + "\n" + script],
+ capture_output = True,
+ text = True,
+ encoding = "utf-8",
+ errors = "replace",
+ timeout = 120,
+ )
+ assert proc.returncode == 0, f"pwsh failed: {proc.stdout}\n{proc.stderr}"
+ return proc.stdout.strip()
+
+
+def _dropped_names(provided: str) -> set[str]:
+ """Which $WoaDropCandidates get excluded on ARM64, given what PyPI supplies.
+
+ The staging directory is empty on purpose: the only thing standing between a name and
+ the AMD64 drop line is the $WoaPyPIProvided bookkeeping this exercises.
+ """
+ out = _run(f"""
+$dir = Join-Path ([System.IO.Path]::GetTempPath()) ([guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $dir -Force | Out-Null
+$WoaWheelDir = $dir
+$WoaVenvMinor = "3.13"
+$WoaWheelTag = "cp313"; $WoaWheelAbi = "cp313"; $WoaWheelStable = $true; $WoaWheelMinor = 13
+$script:WoaTorchAudio = $false
+$script:WoaPyarrowWheelName = $null
+$script:WoaPyPIProvided = {provided}
+function substep {{ param($a, $b) }}
+{_drop_list_block(INSTALL_SRC)}
+Remove-Item -LiteralPath $dir -Recurse -Force
+($WoaOverrideLines | Where-Object {{ $_ -like "*platform_machine*" }} |
+ ForEach-Object {{ ($_ -split ' ')[0] }} | Sort-Object -Unique) -join ","
+""")
+ return {name for name in out.split(",") if name}
+
+
+@requires_pwsh
+ ("wheel", "py_tag", "abi_tag", "usable"),
+ [
+ # The two interpreter-agnostic shapes the wheelhouse actually ships.
+ ("hf_transfer-0.1.9-cp38-abi3-win_arm64.whl", "cp313", "cp313", True),
+ ("sqlite_vec-0.1.9-py3-none-win_arm64.whl", "cp313", "cp313", True),
+ # Bug 2: abi3 does not reach BACKWARDS to an older interpreter.
+ ("hf_transfer-0.2.0-cp314-abi3-win_arm64.whl", "cp313", "cp313", False),
+ ("foo-1.0-py314-none-win_arm64.whl", "cp313", "cp313", False),
+ # Free-threaded CPython has no stable ABI (CPython #111506).
+ ("hf_transfer-0.1.9-cp38-abi3-win_arm64.whl", "cp313", "cp313t", False),
+ # An exact match needs no special case.
+ ("regex-2026.9.3-cp313-cp313-win_arm64.whl", "cp313", "cp313", True),
+ # A wheel built for another interpreter is not this venv's business either way.
+ ("regex-2026.9.3-cp312-cp312-win_arm64.whl", "cp313", "cp313", False),
+ ],
+)
+def test_a_wheel_is_usable_only_where_it_actually_imports(wheel, py_tag, abi_tag, usable):
+ out = _run(f'Test-WoaWheelTagsUsable -Name "{wheel}" -PyTag "{py_tag}" -AbiTag "{abi_tag}"')
+ assert out == str(usable), f"{wheel} on {py_tag}/{abi_tag}: expected {usable}, got {out}"
+
+
+@requires_pwsh
+ ("env", "reaches"),
+ [
+ ({}, True),
+ # Bug 3: these REPLACE the default index, so PyPI is not consulted at all.
+ ({"UV_DEFAULT_INDEX": CORP}, False),
+ ({"UV_INDEX_URL": CORP}, False),
+ # install.ps1 resolves with uv, which never reads pip's variables.
+ ({"PIP_INDEX_URL": CORP}, True),
+ ({"PIP_NO_INDEX": "1"}, True),
+ ({"UV_INDEX_URL": CORP, "PIP_EXTRA_INDEX_URL": PYPI}, False),
+ # Pointed at PyPI explicitly is still PyPI.
+ ({"UV_DEFAULT_INDEX": PYPI}, True),
+ ({"UV_OFFLINE": "1"}, False),
+ ({"UV_NO_INDEX": "1"}, False),
+ # An unset-looking value must not read as "offline".
+ ({"UV_OFFLINE": "0"}, True),
+ ({"UV_NO_INDEX": "false"}, True),
+ ],
+)
+def test_pypi_counts_only_when_the_resolve_would_reach_it(env, reaches):
+ sets = "".join(f'$env:{key} = "{value}"; ' for key, value in env.items())
+ assert _run(sets + "Test-WoaResolveReachesPyPI") == str(reaches)
+
+
+@requires_pwsh
+def test_a_wheel_taken_from_pypi_is_not_then_excluded_on_arm64():
+ """Bug 1, the one that matters: skipping our copy must not read as "no wheel exists"."""
+ nothing_anywhere = _dropped_names("@{}")
+ assert (
+ {"brotli", "hf-transfer", "hf_transfer"} <= nothing_anywhere
+ ), f"a name with no wheel anywhere must be dropped on ARM64, got {nothing_anywhere}"
+
+ from_pypi = _dropped_names('@{ "brotli" = @("1.3.0"); "hf-transfer" = @("0.2.0") }')
+ assert not (
+ {"brotli", "hf-transfer", "hf_transfer"} & from_pypi
+ ), f"PyPI supplies these, so they must not be excluded on ARM64; dropped {from_pypi}"
+ # What is genuinely unavailable is still dropped, so the fix did not blanket-allow.
+ assert {"xformers", "torchcodec", "brotlicffi"} <= from_pypi
+
+
+@requires_pwsh
+ ("version", "still_dropped"),
+ [("0.0.20", True), ("0.0.30", False)],
+)
+def test_a_pypi_version_below_a_floor_keeps_the_drop(version, still_dropped):
+ """xformers carries a floor because the released metadata does, so a PyPI version below
+ it is not a usable answer and the drop has to stay."""
+ dropped = _dropped_names(f'@{{ "xformers" = @("{version}") }}')
+ assert ("xformers" in dropped) is still_dropped
+
+
+# A uv config can take PyPI out of the resolve as decisively as UV_OFFLINE can. Every case below
+# is one install.ps1's subset parser got WRONG until it learned to scan for quotes, each answering
+# "PyPI is reachable" for a config that had disabled it, which deletes wheelhouse copies of wheels
+# the resolve can never fetch. Expectations derived with tomllib, not written by hand.
+UV_CONFIG_CASES = [
+ # A comment needs no whitespace in front of it. `(^|\s)#` missed this one entirely.
+ ("comment_nospace", "uv.toml", "no-index = true# offline lab\n", False),
+ ("value_hash_nospace", "uv.toml", f'index-url = "{CORP}"#corp\n', False),
+ # A quoted key is the same key as the bare spelling.
+ ("quoted_key", "uv.toml", f'"index-url" = "{CORP}"\n', False),
+ # A dotted key is the same statement as writing the leaf under [pip].
+ ("dotted_no_index", "uv.toml", "pip.no-index = true\n", False),
+ ("dotted_index_url", "uv.toml", f'pip.index-url = "{CORP}"\n', False),
+ ("pyproject_dotted", "pyproject.toml", "[tool.uv]\npip.no-index = true\n", False),
+ # The other side of the same scan: a `#` INSIDE a string is not a comment.
+ ("fragment_kept", "uv.toml", f'index-url = "{CORP}#frag"\n', False),
+ ("url_only_in_comment", "uv.toml", f'# index-url = "{CORP}"\n', True),
+ # Cases that must keep answering True, so the fix cannot be a blanket "not reachable".
+ ("extra_index_only", "uv.toml", f'extra-index-url = "{CORP}"\n', True),
+ ("index_default_false", "uv.toml", f'[[index]]\nurl = "{CORP}"\ndefault = false\n', True),
+ ("explicit_pypi", "uv.toml", f'index-url = "{PYPI}"\n', True),
+ ("no_index_false", "uv.toml", f'no-index = false\nindex-url = "{PYPI}"\n', True),
+ # [pip] outranks the top level, in both directions.
+ (
+ "pip_pypi_beats_top_corp",
+ "uv.toml",
+ f'index-url = "{CORP}"\n[pip]\nindex-url = "{PYPI}"\n',
+ True,
+ ),
+ (
+ "pip_corp_beats_top_pypi",
+ "uv.toml",
+ f'index-url = "{PYPI}"\n[pip]\nindex-url = "{CORP}"\n',
+ False,
+ ),
+ # A host that merely contains the name is not PyPI.
+ ("lookalike_host", "uv.toml", 'index-url = "https://pypi.org.evil.com/simple"\n', False),
+ # An inline `index = [...]` is not modelled, and unreadable resolves to "not PyPI".
+ ("inline_index_array", "uv.toml", f'index = [{{ url = "{CORP}", default = true }}]\n', False),
+]
+
+
+@requires_pwsh
+ ("name", "filename", "text", "reaches"),
+ UV_CONFIG_CASES,
+ ids = [case[0] for case in UV_CONFIG_CASES],
+)
+def test_a_uv_config_decides_whether_pypi_is_in_the_resolve(
+ tmp_path, name, filename, text, reaches
+):
+ work = tmp_path / name
+ work.mkdir()
+ (work / filename).write_text(text, encoding = "utf-8")
+ # APPDATA/ProgramData would let the developer's own uv.toml decide the answer.
+ out = _run(f"""
+Remove-Item Env:UV_OFFLINE,Env:PIP_NO_INDEX,Env:UV_DEFAULT_INDEX,Env:UV_INDEX_URL,\
+ Env:PIP_INDEX_URL,Env:UV_CONFIG_FILE,Env:UV_NO_CONFIG -ErrorAction SilentlyContinue
+$env:APPDATA = ''
+$env:ProgramData = ''
+Set-Location -LiteralPath '{work}'
+[string](Test-WoaResolveReachesPyPI)
+""")
+ assert out == str(reaches), f"{name}: expected reaches={reaches}, got {out}"
diff --git a/tests/studio/install/test_woa_wheelhouse_prefers_pypi.py b/tests/studio/install/test_woa_wheelhouse_prefers_pypi.py
new file mode 100644
index 00000000000..56845287153
--- /dev/null
+++ b/tests/studio/install/test_woa_wheelhouse_prefers_pypi.py
@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The wheelhouse is for wheels PyPI does not build, and only for those.
+
+The Windows on ARM wheelhouse exists because PyPI publishes no win_arm64 build of pyarrow,
+tiktoken, grpcio, brotli, hf_transfer or sqlite-vec. regex is different: PyPI has shipped
+win_arm64 regex since 2025.7.29, and the staging directory is first in UV_FIND_LINKS, so a
+user asking for regex got our binary rather than the one the project released.
+
+So staging asks PyPI first and skips the copy when PyPI publishes the same project at or
+above the version that would have been staged. The version half matters as much as the
+check: an upstream BEHIND the wheelhouse has to leave ours in place, or the guard turns
+into a downgrade.
+
+Text-level tests, like the rest of the installer suite: install.ps1 is PowerShell, so the
+shape is asserted against its source rather than by running it.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import shutil
+import subprocess
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+INSTALL_PS1 = REPO_ROOT / "install.ps1"
+
+
[email protected](scope = "module")
+def source() -> str:
+ return INSTALL_PS1.read_text(encoding = "utf-8-sig")
+
+
+def _function_body(source: str, name: str) -> str:
+ """One nested ` function Name {` block, to its closing ` }`."""
+ match = re.search(r"(?ms)^ function " + re.escape(name) + r"\b.*?^ \}$", source)
+ assert match, f"install.ps1 no longer defines {name}"
+ return match.group(0)
+
+
+def _staging_loop(source: str) -> str:
+ """The generic wheelhouse mirror: the block that copies everything but pyarrow."""
+ match = re.search(
+ r"(?ms)^ \$WoaExtraStaged = 0$.*?^ if \(\$WoaExtraStaged -gt 0\)", source
+ )
+ assert match, "the wheelhouse staging loop moved"
+ return match.group(0)
+
+
+def test_the_pypi_probe_is_pypi_only(source):
+ """Test-WoaWheelAvailable falls back to the wheelhouse, where the wheel being staged
+ always is, so the guard would never fire. This probe has to ask PyPI and nothing else."""
+ body = _function_body(source, "Test-WoaPyPIWheel")
+ assert "pypi.org/simple" in body
+ for other in ("WoaWheelhouse", "index.txt", "Get-ChildItem"):
+ assert other not in body, f"Test-WoaPyPIWheel consults {other}; it must ask PyPI alone"
+
+
+def test_both_staging_branches_skip_what_pypi_publishes(source):
+ """Both the local-directory branch and the URL branch mirror the wheelhouse, so a guard
+ on one of them leaves the other shipping our copy."""
+ loop = _staging_loop(source)
+ calls = re.findall(r"Test-WoaWheelhouseWheelIsRedundant", loop)
+ assert (
+ len(calls) == 2
+ ), f"expected the redundancy guard in both staging branches, found {len(calls)}"
+
+
+def test_the_guard_is_version_aware(source):
+ """Published is not enough: upstream behind the wheelhouse means dropping ours
+ downgrades the install, so the floor is the staged wheel's own version."""
+ body = _function_body(source, "Test-WoaWheelhouseWheelIsRedundant")
+ assert "-Floor $fields[1]" in body, "the guard must floor PyPI at the staged version"
+ probe = _function_body(source, "Test-WoaPyPIWheel")
+ assert "Test-WoaVersionAtLeast" in probe, "the probe must compare versions, not just presence"
+
+
+def test_the_guard_only_judges_wheels_this_venv_could_use(source):
+ """A cp312 wheel in the wheelhouse is not made redundant by a cp313 wheel on PyPI."""
+ body = _function_body(source, "Test-WoaWheelhouseWheelIsRedundant")
+ assert "Test-WoaWheelTagsUsable" in body
+
+
+def test_interpreter_agnostic_wheels_still_count(source):
+ """hf_transfer ships cp38-abi3 and sqlite_vec py3-none, both usable on cp313: an
+ exact-tag test would call them foreign and go on shipping ours forever."""
+ body = _function_body(source, "Test-WoaWheelTagsUsable")
+ assert '"abi3"' in body and '"none"' in body
+ # Free-threaded venvs are the exception the exact-tag helper exists for.
+ assert '$AbiTag -like "*t"' in body
+
+
+def test_pyarrow_keeps_its_own_pypi_first_path(source):
+ """Get-WoaPyarrowSource already asks PyPI first and the generic loop skips pyarrow for
+ that reason. Both halves have to stay, or pyarrow is staged twice or never probed."""
+ body = _function_body(source, "Get-WoaPyarrowSource")
+ assert 'return "pypi"' in body
+ loop = _staging_loop(source)
+ assert re.search(
+ r'-like "pyarrow-\*"\) \{ continue \}', loop
+ ), "the generic loop must leave pyarrow to Get-WoaPyarrowSource"
+
+
+# The default wheelhouse URL had no test at all: changing it to a working but wrong host left
+# the whole suite green. It is the only source for the pyarrow that gates the native path, so a
+# typo sends every Windows on ARM host back to the emulated x64 stack, and it is fetched over
+# the network, so a wrong host is a wrong download.
+DEFAULT_WHEELHOUSE = "https://huggingface.co/danielhanchen/unsloth-blackwell-docker/resolve/main/windows-arm64-wheels"
+
+PWSH = shutil.which("pwsh")
+requires_pwsh = pytest.mark.skipif(PWSH is None, reason = "pwsh not available")
+
+
+def _wheelhouse_assignment(source: str) -> str:
+ """The `$script:WoaWheelhouse = if (...) {...} else {...}` block, lifted verbatim."""
+ match = re.search(r"(?ms)^ \$script:WoaWheelhouse = if .*?^ \}$", source)
+ assert match, "install.ps1 no longer assigns $script:WoaWheelhouse in one block"
+ return match.group(0)
+
+
+def test_the_default_wheelhouse_url_is_exactly_this(source):
+ assert DEFAULT_WHEELHOUSE in _wheelhouse_assignment(source)
+
+
+def test_the_default_is_an_https_resolve_url_on_hugging_face(source):
+ """`resolve/main` serves the file; a plain repo URL serves an HTML page, which the
+ staging code would happily save as a .whl. The path may continue past `resolve/main`:
+ the wheelhouse is a folder of a repo we own."""
+ assert DEFAULT_WHEELHOUSE.startswith("https://huggingface.co/danielhanchen/")
+ assert "/resolve/main" in DEFAULT_WHEELHOUSE
+ assert not DEFAULT_WHEELHOUSE.endswith("/"), "Join-UrlPath adds the slash"
+
+
+@requires_pwsh
+ ("configured", "expected", "why"),
+ [
+ (None, DEFAULT_WHEELHOUSE, "unset falls back to the published wheelhouse"),
+ ("", DEFAULT_WHEELHOUSE, "empty is not a configuration"),
+ ("https://example.test/wheels", "https://example.test/wheels", "a mirror is honoured"),
+ ("https://example.test/wheels/", "https://example.test/wheels", "one trailing slash goes"),
+ ("https://example.test/wheels///", "https://example.test/wheels", "so do several"),
+ (
+ " https://example.test/wheels ",
+ "https://example.test/wheels",
+ "surrounding space goes",
+ ),
+ (r"C:\wheels", r"C:\wheels", "a local directory survives untouched"),
+ (
+ "C:" + chr(92) + "wheels" + chr(92),
+ "C:" + chr(92) + "wheels" + chr(92),
+ "TrimEnd takes '/' only, so a trailing backslash stays",
+ ),
+ ],
+)
+def test_the_wheelhouse_override_is_normalised(source, configured, expected, why):
+ setup = (
+ "Remove-Item Env:UNSLOTH_WOA_WHEELHOUSE -ErrorAction SilentlyContinue; "
+ if configured is None
+ else f"$env:UNSLOTH_WOA_WHEELHOUSE = '{configured}'; "
+ )
+ script = (
+ "$ErrorActionPreference = 'Stop'; "
+ + setup
+ + _wheelhouse_assignment(source).strip()
+ + '; Write-Output "<<<$script:WoaWheelhouse>>>"'
+ )
+ done = subprocess.run(
+ [PWSH, "-NoProfile", "-NonInteractive", "-Command", script],
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert done.returncode == 0, done.stderr
+ out = done.stdout
+ assert out[out.index("<<<") + 3 : out.rindex(">>>")] == expected, why
diff --git a/tests/studio/install/woa_ps_harness.py b/tests/studio/install/woa_ps_harness.py
new file mode 100644
index 00000000000..4a0f6390cc5
--- /dev/null
+++ b/tests/studio/install/woa_ps_harness.py
@@ -0,0 +1,314 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared plumbing for the Windows-on-ARM installer tests.
+
+install.ps1 and studio/setup.ps1 cannot dot-source each other and cannot be imported, so a
+behavioural test lifts a function body or a live block out of the script under test, pastes
+it into a bare pwsh session with the few stubs that block needs, and asserts on what it
+writes out. The sources, the lifting and the stub bundles are the same from one test to the
+next, so they live here rather than being restated in every module that wants them.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import shutil
+import subprocess
+
+import pytest
+
+
+PACKAGE_ROOT = pathlib.Path(__file__).resolve().parents[3]
+MANIFEST_PY = PACKAGE_ROOT / "studio" / "install_manifest.py"
+SETUP_PS1 = PACKAGE_ROOT / "studio" / "setup.ps1"
+STACK_PY = PACKAGE_ROOT / "studio" / "install_python_stack.py"
+STACK_LLAMA = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+INSTALL_PS1 = PACKAGE_ROOT / "install.ps1"
+
+# Read once. Well over a hundred tests want one of these whole files, and none of them
+# mutate what they read.
+INSTALL_SRC = INSTALL_PS1.read_text(encoding = "utf-8")
+SETUP_SRC = SETUP_PS1.read_text(encoding = "utf-8")
+STACK_SRC = STACK_PY.read_text(encoding = "utf-8")
+LLAMA_SRC = STACK_LLAMA.read_text(encoding = "utf-8")
+CONSTRAINTS_SRC = (
+ PACKAGE_ROOT / "studio" / "backend" / "requirements" / "single-env" / "constraints.txt"
+).read_text(encoding = "utf-8")
+
+PWSH = shutil.which("pwsh")
+requires_pwsh = pytest.mark.skipif(PWSH is None, reason = "pwsh not available")
+
+# The channels, mirrors and indexes these tests name over and over. Spelled once so a
+# parametrize row stays one readable line instead of six.
+NV_GA = "https://pypi.nvidia.com/nvtorch_oot"
+NV_NIGHTLY = "https://pypi.nvidia.com/nvtorch_oot_nightly"
+PYPI = "https://pypi.org/simple"
+CORP_INDEX = "https://pypi.corp.test/simple"
+
+
+def _script(*lines: str) -> str:
+ """The lines of a PowerShell snippet, joined the way pwsh -Command wants them."""
+ return "\n".join(lines)
+
+
+def _ps(
+ script,
+ timeout = 120,
+ **kwargs,
+):
+ """Run a PowerShell snippet and hand back the completed process."""
+ return subprocess.run(
+ [PWSH, "-NoProfile", "-NonInteractive", "-Command", script],
+ capture_output = True,
+ text = True,
+ timeout = timeout,
+ **kwargs,
+ )
+
+
+def _ps_ok(
+ script,
+ timeout = 120,
+ **kwargs,
+):
+ """Same, but fail the test with PowerShell's own stderr when it does not exit 0."""
+ done = _ps(script, timeout = timeout, **kwargs)
+ assert done.returncode == 0, done.stderr
+ return done
+
+
+def _ps_last(script, **kwargs) -> str:
+ """Run a snippet that must succeed and hand back its last line of output.
+
+ Every one of these scripts ends in a Write-Output the assertion is about, and a
+ PowerShell prelude can print before it, so the last line is the answer.
+ """
+ return _ps_ok(script, **kwargs).stdout.strip().splitlines()[-1]
+
+
+def _ps_kv(script, **kwargs) -> dict:
+ """A snippet whose Write-Outputs are NAME=value lines, read back as a dict."""
+ return dict(l.split("=", 1) for l in _ps_ok(script, **kwargs).stdout.splitlines() if "=" in l)
+
+
+def _function_source(text: str, name: str) -> str:
+ """Extract a PowerShell function by matching balanced braces."""
+ match = re.search(rf"(?im)^[ \t]*function[ \t]+{re.escape(name)}\b", text)
+ assert match, f"{name} is not defined in setup.ps1"
+ start = text.index("{", match.start())
+ depth = 0
+ for index in range(start, len(text)):
+ if text[index] == "{":
+ depth += 1
+ elif text[index] == "}":
+ depth -= 1
+ if depth == 0:
+ return text[match.start() : index + 1]
+ raise AssertionError(f"unbalanced braces in {name}")
+
+
+def functions(text: str, *names: str) -> str:
+ """Several bodies in one lift, in the order given.
+
+ PowerShell does not hoist and a helper the prelude does not lift is a
+ command-not-found, not a false answer, so a body's helpers come with it.
+ """
+ return "\n".join(_function_source(text, name) for name in names)
+
+
+def _ps_function(path: pathlib.Path, name: str) -> str:
+ """A function body by SCRIPT PATH, for the tests that parametrize over the two files."""
+ src = {INSTALL_PS1: INSTALL_SRC, SETUP_PS1: SETUP_SRC}.get(path)
+ return _function_source(src if src is not None else path.read_text(encoding = "utf-8"), name)
+
+
+def _ps_copies(name: str) -> tuple:
+ """install.ps1's and setup.ps1's copies of one function, bar comments and indentation.
+
+ Neither script can dot-source the other, so each is carried twice and the parity is
+ pinned instead. Returned as a pair rather than compared here so a mismatch fails with
+ pytest's own diff of the two bodies.
+ """
+
+ def normalized(source: str) -> str:
+ lines = [
+ line.rstrip()
+ for line in _function_source(source, name).splitlines()
+ if line.strip() and not line.strip().startswith("#")
+ ]
+ indent = min(len(line) - len(line.lstrip()) for line in lines)
+ return "\n".join(line[indent:] for line in lines)
+
+ return normalized(INSTALL_SRC), normalized(SETUP_SRC)
+
+
+def slice_between(
+ src: str,
+ start_marker: str,
+ end_marker: str,
+ *,
+ include_end = False,
+) -> str:
+ """The live text from one marker to the next, sliced out of the script itself.
+
+ Restating a block in the test instead means a copy that passes forever after the
+ original stopped matching it, which is the failure these tests exist to catch.
+ """
+ start = src.index(start_marker)
+ end = src.index(end_marker, start)
+ return src[start : end + len(end_marker)] if include_end else src[start:end]
+
+
+# ── Stub bundles ──────────────────────────────────────────────────────────────────────────
+
+SUBSTEP_NOOP = "function substep { param($m, $c) }"
+
+
+def substep_collector(var: str = "Messages") -> str:
+ """substep, collected into $script:<var> so a test can assert on what was said."""
+ return _script(
+ f"$script:{var} = @()",
+ f"function substep {{ param($m, $c) $script:{var} += $m }}",
+ )
+
+
+# The real one shortens a path to its 8.3 form; a passthrough is what every test that is
+# not about 8.3 wants, and it keeps the assertions readable.
+UV_SAFE_PATH = "function Get-UvSafePath { param([string]$Path) return $Path }"
+
+JOIN_URL_PATH = _script(
+ "function Join-UrlPath { param([string]$Base,[string]$Path)",
+ " return ($Base.TrimEnd('/') + '/' + $Path.TrimStart('/')) }",
+)
+JOIN_URL_RETURNS_BASE = "function Join-UrlPath { param($Base, $Path) return $Base }"
+JOIN_URL_RETURNS_PATH = "function Join-UrlPath { param($Base, $Path) return $Path }"
+
+
+def invoke_restmethod(body: str) -> str:
+ """Invoke-RestMethod serving one synthetic PEP 503 page, so the probes are offline."""
+ return (
+ "function Invoke-RestMethod { param([Parameter(ValueFromRemainingArguments=$true)]$a) "
+ f"return @'\n{body}\n'@ }}"
+ )
+
+
+INVOKE_RESTMETHOD_OFFLINE = (
+ "function Invoke-RestMethod { param([Parameter(ValueFromRemainingArguments=$true)]$a) "
+ "throw 'offline' }"
+)
+INVOKE_RESTMETHOD_NO_NETWORK = "function Invoke-RestMethod { throw 'no network in this test' }"
+
+# The resolver settings a lifted block must not inherit from the session running the tests.
+UV_INDEX_ENV = (
+ "UV_NO_INDEX",
+ "PIP_NO_INDEX",
+ "UV_DEFAULT_INDEX",
+ "UV_INDEX_URL",
+ "PIP_INDEX_URL",
+ "UV_INDEX",
+ "UV_EXTRA_INDEX_URL",
+ "PIP_EXTRA_INDEX_URL",
+ "UV_CONFIG_FILE",
+)
+UV_POLICY_ENV = ("UV_OFFLINE",) + UV_INDEX_ENV + ("UV_NO_CONFIG",)
+UV_ONLY_INDEX_ENV = (
+ "UV_NO_INDEX",
+ "UV_DEFAULT_INDEX",
+ "UV_INDEX_URL",
+ "UV_INDEX",
+ "UV_EXTRA_INDEX_URL",
+ "UV_CONFIG_FILE",
+)
+
+
+def clear_env(names) -> str:
+ """Remove every one of `names` from the environment the lifted block will read."""
+ listed = ",".join(f"'{name}'" for name in names)
+ return f'foreach ($n in {listed}) {{ Remove-Item "Env:$n" -ErrorAction SilentlyContinue }}'
+
+
+# The four marker helpers travel together: the path builder, the write guard, the writer and
+# the reader. Injecting one without the others is a command-not-found inside the body.
+MARKER_FUNCS = functions(
+ SETUP_SRC,
+ "Get-WoaTorchIndexMarkerPath",
+ "Test-WoaPersistableIndex",
+ "Save-WoaTorchIndexMarker",
+ "Get-WoaTorchIndexMarker",
+)
+
+# Tag matching, the version order it needs, the floor and the pyarrow gate built on both.
+PYARROW_FLOOR = '$script:WoaPyarrowFloor = "21.0.0"'
+WHEEL_TAG_FUNCS = functions(INSTALL_SRC, "Test-WoaWheelTags", "Test-WoaWheelTagsUsable")
+PYARROW_USABLE_FUNCS = _script(
+ WHEEL_TAG_FUNCS,
+ _function_source(INSTALL_SRC, "Test-WoaVersionAtLeast"),
+ PYARROW_FLOOR,
+ _function_source(INSTALL_SRC, "Test-WoaPyarrowWheelUsable"),
+)
+
+
+def pyarrow_source_script(
+ *,
+ wheelhouse: str,
+ local: str = "$false",
+ rest_method: str = INVOKE_RESTMETHOD_NO_NETWORK,
+ reaches_pypi: str | None = None,
+ lifts: tuple = (),
+ preamble: tuple = (),
+ tail: tuple = ("Write-Output ('[' + (Get-WoaPyarrowSource -PythonMinor '3.13') + ']')",),
+) -> str:
+ """Get-WoaPyarrowSource with its network branches stubbed out.
+
+ `wheelhouse` is the PowerShell expression for $script:WoaWheelhouse, `lifts` names any
+ extra install.ps1 helper the branch under test reaches for.
+ """
+ return _script(
+ SUBSTEP_NOOP,
+ JOIN_URL_RETURNS_BASE,
+ f"function Test-WoaWheelhouseIsLocal {{ {local} }}",
+ rest_method,
+ *((f"function Test-WoaResolveReachesPyPI {{ {reaches_pypi} }}",) if reaches_pypi else ()),
+ f"$script:WoaWheelhouse = {wheelhouse}",
+ PYARROW_USABLE_FUNCS,
+ functions(INSTALL_SRC, "Test-ZipArchiveReadable", *lifts, "Get-WoaPyarrowSource"),
+ *preamble,
+ *tail,
+ )
+
+
+def native_probe_script(
+ *,
+ driver: str,
+ driver_leaf: str = "$null",
+ stubs: tuple = (),
+ lifts: tuple = (),
+ outputs: tuple = (),
+) -> str:
+ """Initialize-WoaNativeCudaTorch run against a stubbed host.
+
+ `stubs` carries the index list and the wheel answers, which is all the callers differ
+ by; `outputs` names the extra script variables to read back between NATIVE and MSG.
+ """
+ return _script(
+ "$SkipTorch = $false",
+ substep_collector(),
+ "function Get-HostMachineArch { 'arm64' }",
+ "function Get-WoaAbiTag { param($PythonMinor, $FreeThreaded) 'cp313' }",
+ "function Test-WoaNvidiaPresent { $true }",
+ "function Test-WoaResolverPathsUsable { $true }",
+ f"function Get-WoaDriverCudaLeaf {{ {driver_leaf} }}",
+ f"function Get-WoaDriverCudaVersion {{ {driver} }}",
+ *stubs,
+ "function Get-WoaPyarrowSource { param($PythonMinor, $AbiTag) 'pypi' }",
+ "function Test-WoaWheelAvailable { $true }",
+ functions(
+ INSTALL_SRC, *lifts, "Test-WoaAudioMatchesTorch", "Initialize-WoaNativeCudaTorch"
+ ),
+ "Initialize-WoaNativeCudaTorch -PythonMinor '3.13'",
+ "Write-Output ('NATIVE=' + $script:WoaNativeCudaTorch)",
+ *outputs,
+ "Write-Output ('MSG=' + ($script:Messages -join ' | '))",
+ )
diff --git a/tests/studio/test_torch_overrides_merge.ps1 b/tests/studio/test_torch_overrides_merge.ps1
index ffbb2e73572..ea28eaedee1 100644
--- a/tests/studio/test_torch_overrides_merge.ps1
+++ b/tests/studio/test_torch_overrides_merge.ps1
@@ -3,8 +3,8 @@
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
# Unit test for install.ps1's New-UnslothTorchOverridesFile, the Windows twin of install.sh's
# _build_unsloth_torch_overrides. It folds a caller's UV_OVERRIDE file into the frozen torch-trio
-# pins without corrupting it: non-ASCII lines must survive, and the merged file must stay beside
-# the caller's override, as uv resolves `-r nested.txt` relative to THAT file's own directory.
+# pins without corrupting it: non-ASCII lines must survive, and every relative reference must come
+# across REBASED, since uv resolves them against the file that contains them.
# Run: pwsh -NoProfile -File tests/studio/test_torch_overrides_merge.ps1
$ErrorActionPreference = "Stop"
@@ -21,6 +21,14 @@ $fn = $ast.FindAll({ param($n)
$n.Name -eq "New-UnslothTorchOverridesFile"
}, $true)
if ($fn.Count -ne 1) { throw "expected exactly one New-UnslothTorchOverridesFile in install.ps1, found $($fn.Count)" }
+# PowerShell does not hoist, so the helpers the merge calls have to be defined here too.
+foreach ($helper in "Get-WoaRequirementEntries", "Resolve-WoaOverrideLine") {
+ $h = $ast.FindAll({ param($n)
+ $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq $helper
+ }, $true)
+ if ($h.Count -ne 1) { throw "expected exactly one $helper in install.ps1, found $($h.Count)" }
+ Invoke-Expression $h[0].Extent.Text
+}
Invoke-Expression $fn[0].Extent.Text
$failures = 0
@@ -77,14 +85,14 @@ try {
Check "non-ASCII caller requirement survives the merge (no '?' substitution)" `
($mergedText -match "caf${acute}pkg==1\.0" -and $mergedText -notmatch 'caf\?pkg')
- Check "merged file sits where the caller's relative includes still resolve" `
- (Test-Path -LiteralPath (Join-Path (Split-Path -Parent $merged) "nested.txt"))
+ Check "the caller's relative include is rebased, not carried as a relative line" `
+ ($mergedText -notmatch '(?m)^\s*-r\s')
+ Check "and its contents come across instead" ($mergedText -match '(?m)^idna==3\.6$')
# Guards on the behaviour that already worked, so the fix cannot regress it.
Check "frozen torch trio is pinned first" ($mergedText -match '^torch==2\.11\.0\+cu130')
Check "caller's torch-trio lines are dropped" `
($mergedText -notmatch '(?m)^torch==1\.0$' -and $mergedText -notmatch '(?m)^torchvision==0\.1$')
- Check "caller's relative include line is carried over" ($mergedText -match '(?m)^-r nested\.txt$')
Check "caller's ordinary requirements are carried over" ($mergedText -match '(?m)^plainpkg==2\.0$')
Check "merged file is newline terminated" ($mergedText.EndsWith("`n"))
@@ -141,7 +149,7 @@ try {
# Three Windows-only hazards, so each is asserted behaviourally where it can be and
# structurally from the AST, which runs everywhere.
- $env:UV_OVERRIDE = $ovPath
+ $env:UV_OVERRIDE = $callerOv
$script:TorchOverridesFile = $null
$merged = New-UnslothTorchOverridesFile -PythonExe $fakePy
$made += $merged
@@ -156,8 +164,14 @@ try {
# Get-Content decodes a BOM-less file with the ANSI code page on PS 5.1, which is where the
# mojibake came from. pwsh on Linux defaults to UTF-8, so the round trip cannot fail here
# even unfixed; the assertion holding the fix in place is the one on the reader.
+ # The reading moved into Get-WoaRequirementEntries; the non-ASCII check above holds it.
+ $scanSrc = ($ast.FindAll({ param($n)
+ $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and
+ $n.Name -eq "Get-WoaRequirementEntries"
+ }, $true))[0].Extent.Text
Check "the caller's override is read as UTF-8, not by the shell's default codepage" (
- ($src -match '\[System\.IO\.File\]::ReadAllLines\(') -and ($src -notmatch 'Get-Content -LiteralPath \$ovFile')
+ ($scanSrc -match '\[System\.IO\.File\]::ReadAllLines\(') -and
+ ($src -notmatch 'Get-Content -LiteralPath \$ovFile')
)
Check "the inherited ACL is replaced rather than kept" (
($src -match 'SetAccessRuleProtection\(\$true, \$false\)') -and ($src -match 'Set-Acl -LiteralPath \$f')
diff --git a/tests/studio/test_unsloth_torch_override.ps1 b/tests/studio/test_unsloth_torch_override.ps1
index e7ae30d5730..16415b54bd6 100644
--- a/tests/studio/test_unsloth_torch_override.ps1
+++ b/tests/studio/test_unsloth_torch_override.ps1
@@ -97,7 +97,8 @@ Remove-Item -LiteralPath $leakFile -Force -ErrorAction SilentlyContinue
Write-Host "the inherited-override filter drops the torch trio in any casing"
# PowerShell's -notmatch is case-insensitive, so a caller override `Torch<2.11` is dropped.
$filterPattern = $null
-if ($fnText -match '\$_ -notmatch ''([^'']+)''') { $filterPattern = $Matches[1] }
+# The merge folds entry by entry, so the trio filter reads `-match ... { continue }` instead.
+if ($fnText -match '\$ovEntry\.Line -match ''([^'']+)''') { $filterPattern = $Matches[1] }
Check "filter pattern extracted from the helper" ($null -ne $filterPattern)
$inherited = @(
"# comment survives",