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.

13.7 KB
Raw Blame
# 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
    ]