Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
"""install.ps1 must pin the xFormers wheel built for its torch: PyPI ships only the CUDA-12.8 flavour."""
from __future__ import annotations
import re
import shutil
from pathlib import Path
import pytest
from unsloth_pwsh_runner import run_pwsh
REPO_ROOT = Path(__file__).resolve().parents[2]
INSTALL_PS1 = REPO_ROOT / "install.ps1"
def _source() -> str:
return INSTALL_PS1.read_text(encoding = "utf-8")
def _extract(pattern: str, source: str) -> str:
match = re.search(pattern, source, flags = re.DOTALL | re.MULTILINE)
assert match is not None, f"installer block not found: {pattern}"
return match.group(0)
def _selector_harness() -> str:
"""`$script:XformersWheelVersions` + the two pure helpers, ready to dot-source."""
source = _source()
return "\n".join(
(
_extract(r"^ \$script:XformersWheelVersions = @\{.*?^ \}", source),
_extract(r"^ \$script:XformersStableAbiFloor = [^\n]*", source),
_extract(r"^ \$script:XformersStableAbiVersion = [^\n]*", source),
_extract(r"^ \$script:XformersStableAbiFamilies = [^\n]*", source),
_extract(r"^ function ConvertTo-TorchFlavorTag \{.*?^ \}", source),
_extract(r"^ function ConvertTo-TorchReleaseVersion \{.*?^ \}", source),
_extract(r"^ function Get-XformersWheelVersion \{.*?^ \}", source),
_extract(r"^ function Get-XformersExpectedTorchBuild \{.*?^ \}", source),
_extract(r"^ function Get-XformersFilenamePythonTag \{.*?^ \}", source),
)
)
def _run_pwsh(script: str) -> str:
# run_pwsh: a pwsh killed by a signal never ran this script and must not read as a wrong answer.
result = run_pwsh(
["pwsh", "-NoProfile", "-NonInteractive", "-Command", script],
check = True,
capture_output = True,
text = True,
)
return result.stdout.strip()
# (torch.__version__, expected xFormers version, or "" for no wheel).
SELECTION_CASES = [
("2.10.0+cu130", "0.0.34"),
("2.10.0+cu128", "0.0.34"),
("2.10.0+cu126", "0.0.34"),
("2.9.1+cu130", "0.0.33.post2"),
("2.9.1+cu128", "0.0.33.post2"),
("2.9.0+cu130", "0.0.33.post1"),
("2.9.0+cu126", "0.0.33.post1"),
("2.8.0+cu129", "0.0.32.post2"),
("2.7.1+cu128", "0.0.31.post1"),
# 0.0.30 predates the abi3 switch and has no cp313 wheel.
("2.7.0+cu128", ""),
# No cu130 xFormers for torch <= 2.8 and no cu118/cu124 win_amd64 build: refuse, do not serve a neighbour.
("2.8.0+cu130", ""),
("2.9.0+cu118", ""),
("2.10.0+cu124", ""),
# 0.0.35 is stable-ABI (built against 2.10.0) and loads on any later torch.
("2.11.0+cu130", "0.0.35"),
("2.13.0+cu128", "0.0.35"),
# Unlisted releases above the floor also get 0.0.35, since they ship after this script.
("2.10.1+cu130", "0.0.35"),
("2.11.1+cu128", "0.0.35"),
("2.12.4+cu126", "0.0.35"),
("2.14.0+cu130", "0.0.35"),
# Below the floor there is no stable ABI, and a CUDA family that publishes nothing gains no wheel.
("2.9.2+cu130", ""),
("2.12.0+cu124", ""),
("2.10.0+cpu", ""),
("2.10.0+rocm6.4", ""),
("2.10.0.dev20260101+cu130", ""),
]
@pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
@pytest.mark.parametrize(("torch_version", "expected"), SELECTION_CASES)
def test_selector_picks_the_matching_wheel(torch_version: str, expected: str):
out = _run_pwsh(
f"{_selector_harness()}\n"
f"$v = '{torch_version}'\n"
"$tag = ConvertTo-TorchFlavorTag $v\n"
"$sel = Get-XformersWheelVersion -TorchVersion $v -CudaTag $tag\n"
'Write-Output "[$sel]"\n'
)
assert out == f"[{expected}]", f"{torch_version} selected {out}, expected [{expected}]"
@pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
def test_selector_refuses_a_missing_or_blank_input():
out = _run_pwsh(
f"{_selector_harness()}\n"
"Write-Output \"[$(Get-XformersWheelVersion -TorchVersion '' -CudaTag 'cu130')]\"\n"
"Write-Output \"[$(Get-XformersWheelVersion -TorchVersion '2.10.0+cu130' -CudaTag '')]\"\n"
)
assert out.splitlines() == ["[]", "[]"]
def test_installer_installs_xformers_from_the_torch_index():
source = _source()
block = _extract(r" # ── Pin xFormers to the wheel built for the torch.*?^ \}\n", source)
assert "--no-deps" in block, (
"the xFormers wheel declares torch==<exact release>; without --no-deps uv can pull "
"a PyPI (CUDA 12.8) torch over the CUDA build just installed"
)
assert "--reinstall-package xformers" in block, (
"cu126/cu128/cu130 publish the SAME xformers version string, so a wrong-CUDA wheel "
"is invisible to a version check and must be force-replaced"
)
assert "--default-index $_xfIndexUrl" in block
assert "xformers==$_xfVersion" in block
assert "UNSLOTH_SKIP_XFORMERS" in block
# A full-URL pin is reused whole: it may be an authenticated mirror whose leaf is not a CUDA family.
assert (
"if ($TorchIndexUrl -and -not [string]::IsNullOrWhiteSpace($env:UNSLOTH_TORCH_INDEX_URL))"
in block
)
assert "$_xfIndexUrl = $TorchIndexUrl" in block
assert '$_xfWheelUrl = Join-UrlPath $_xfBase "$_xfCudaTag/$_xfWheelName"' in block
assert "--reinstall-package xformers $_xfWheelUrl" in block
# Compare against the wheel's own build target: the stable-ABI wheel records the floor release.
assert "Get-XformersExpectedTorchBuild -Version $_xfVersion" in block
def test_a_family_pin_still_gets_the_direct_wheel_url():
"""A family pin keeps the direct wheel URL, since --index is additive and can resolve the wrong CUDA."""
block = _extract(
r" # ── Pin xFormers to the wheel built for the torch.*?^ \}\n", _source()
)
condition = re.search(r"if \(\$TorchIndexUrl[^\n]*\) \{", block)
assert condition is not None, "the index branch must be gated on the full-URL override"
assert "UNSLOTH_TORCH_INDEX_URL" in condition.group(0)
assert "$TorchIndexPinned" not in condition.group(0)
assert '$_xfWheelUrl = Join-UrlPath $_xfBase "$_xfCudaTag/$_xfWheelName"' in block
def test_a_full_url_override_naming_a_cuda_leaf_gets_a_direct_url():
"""Every CUDA family publishes the same xFormers version, so an index resolve can pick the wrong one."""
block = _extract(
r" # ── Pin xFormers to the wheel built for the torch.*?^ \}\n", _source()
)
assert "$_xfOverrideLeaf = Get-TorchIndexLeafName $TorchIndexUrl" in block
assert "'^cu\\d+$'" in block
assert "$_xfWheelUrl = Join-UrlPath $TorchIndexUrl $_xfWheelName" in block
def test_the_index_fallback_hides_the_machine_level_indexes():
"""The one path that still resolves rather than fetching a URL: a mirror root whose leaf
is not a CUDA family. UV_INDEX / UV_EXTRA_INDEX_URL are cleared around that call so the
chosen index really is the only one, and restored afterwards."""
block = _extract(
r" # ── Pin xFormers to the wheel built for the torch.*?^ \}\n", _source()
)
assert "$env:UV_INDEX = $null" in block
assert "$env:UV_EXTRA_INDEX_URL = $null" in block
assert "$env:UV_INDEX = $_xfSavedIndex" in block
assert "$env:UV_EXTRA_INDEX_URL = $_xfSavedExtra" in block
assert "} finally {" in block, "the restore must survive a failing install"
@pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
def test_the_url_join_keeps_a_tokenized_mirrors_query():
"""Executed, not read: a mirror may authenticate by query string, and appending the wheel path
after it put the path inside the token; same rule as join_wheel_url on the Python side."""
joiner = _extract(r"^ function Join-UrlPath \{.*?^ \}", _source())
out = _run_pwsh(
f"{joiner}\n"
"Write-Output (Join-UrlPath 'https://m/whl?token=abc' 'cu130/x.whl')\n"
"Write-Output (Join-UrlPath 'https://m/whl/' 'cu130/x.whl')\n"
"Write-Output (Join-UrlPath 'https://m/whl#f' 'cu130/x.whl')\n"
)
assert out.splitlines() == [
"https://m/whl/cu130/x.whl?token=abc",
"https://m/whl/cu130/x.whl",
"https://m/whl/cu130/x.whl#f",
]
def test_installer_never_installs_an_unpinned_xformers():
"""A bare xformers resolves to the newest build the index serves, which may not match the CUDA
family of the resident torch; every spec must be pinned to the exact (torch, cuda) version."""
source = _source()
# The WoA drop list names packages to REMOVE, so a bare name must 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)
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 names one exact file, which is the 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}"
def test_xformers_step_runs_after_the_torch_flavor_repair():
"""The repair may reinstall torch from another index, so the xFormers pin must come after it."""
source = _source()
repair = source.index("$expectedTorchTag = Get-ExpectedTorchFlavorTag")
xformers = source.index("xformers==$_xfVersion")
overlay = source.index("UNSLOTH_CI_SOURCE_OVERLAY")
assert repair < xformers < overlay
def test_xformers_step_is_skipped_for_no_torch_installs():
block = _extract(
r" # ── Pin xFormers to the wheel built for the torch.*?^ \}\n", _source()
)
assert "if (-not $SkipTorch" in block
# cpu / rocm / xpu torch has no xFormers wheel on any index.
assert "'^cu\\d+$'" in block
def test_installed_build_probe_reads_cpp_lib_json():
"""The version string cannot distinguish cu128 from cu130, so the repair check has to read
the build metadata xFormers itself reports in its error message."""
block = _extract(r" function Get-InstalledXformersBuild \{.*?^ \}", _source())
assert "cpp_lib.json" in block
assert "find_spec" in block
# Reading cpp_lib.json, not importing xformers, keeps a mismatched .pyd's warning out of the probe.
# Every release since 0.0.31 ships it, so absence means an unbuilt or source install.
assert "import xformers" not in block
# Invoke-BoundedPythonProbe interpolates the code into a double-quoted -c argument.
assert '"' not in block.split("$code = ", 1)[1].split("\n", 1)[0].strip("'")
# install.ps1 and wheel_utils resolve the same machine, so both must give the same fallback answer.
STABLE_ABI_PARITY_CASES = [
("2.10.1+cu130", "13.0", "0.0.35"),
("2.11.1+cu128", "12.8", "0.0.35"),
("2.12.4+cu126", "12.6", "0.0.35"),
("2.14.0+cu130", "13.0", "0.0.35"),
("2.9.2+cu130", "13.0", ""),
("2.12.0+cu124", "12.4", ""),
]
@pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
@pytest.mark.parametrize(("torch_version", "cuda_version", "expected"), STABLE_ABI_PARITY_CASES)
def test_both_selectors_agree_outside_the_exact_tables(torch_version, cuda_version, expected):
import sys
sys.path.insert(0, str(REPO_ROOT / "studio" / "backend"))
try:
from utils import wheel_utils
finally:
sys.path.pop(0)
family = wheel_utils.xformers_cuda_family(cuda_version)
python_side = wheel_utils.xformers_wheel_version(torch_version, family) or ""
ps_side = _run_pwsh(
f"{_selector_harness()}\n"
f"$v = '{torch_version}'\n"
"$tag = ConvertTo-TorchFlavorTag $v\n"
'Write-Output "[$(Get-XformersWheelVersion -TorchVersion $v -CudaTag $tag)]"\n'
)
assert python_side == expected
assert ps_side == f"[{expected}]"
@pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
def test_the_already_installed_check_uses_the_wheels_own_build_target():
"""A resident 0.0.35 records the torch it was compiled against (the stable-ABI floor), not the
torch it runs under; comparing to the resident torch forced reinstalls and a false failure
warning when the index was unreachable."""
out = _run_pwsh(
f"{_selector_harness()}\n"
"Write-Output \"[$(Get-XformersExpectedTorchBuild -Version '0.0.35' "
"-TorchVersion '2.12.1+cu130' -CudaTag 'cu130')]\"\n"
"Write-Output \"[$(Get-XformersExpectedTorchBuild -Version '0.0.34' "
"-TorchVersion '2.10.0+cu128' -CudaTag 'cu128')]\"\n"
)
# The stable-ABI wheel reports the floor release; an exact-era wheel reports the resident torch.
assert out.splitlines() == ["[2.10.0+cu130]", "[2.10.0+cu128]"]
@pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
def test_the_direct_wheel_filename_tag_matches_the_python_resolver():
import sys
sys.path.insert(0, str(REPO_ROOT / "studio" / "backend"))
try:
from utils import wheel_utils
finally:
sys.path.pop(0)
versions = ["0.0.31.post1", "0.0.32.post2", "0.0.33.post2", "0.0.34", "0.0.35"]
ps_out = _run_pwsh(
f"{_selector_harness()}\n"
+ "\n".join(f"Write-Output \"[$(Get-XformersFilenamePythonTag '{v}')]\"" for v in versions)
)
assert ps_out.splitlines() == [
f"[{wheel_utils.xformers_filename_python_tag(v)}]" for v in versions
]