Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""The torchao pick must match the resident torch, since its C++ extensions target one release."""
from __future__ import annotations
import importlib
import importlib.machinery
import sys
from pathlib import Path
from unittest.mock import MagicMock
import pytest
_INSTALL_SCRIPT = Path(__file__).resolve().parents[2] / "install_python_stack.py"
_EXTRAS_REQUIREMENTS = Path(__file__).resolve().parent.parent / "requirements" / "extras.txt"
def _load_module(monkeypatch):
"""(Re-)import install_python_stack and return it (mirrors test_pytorch_mirror)."""
sys.modules.pop("install_python_stack", None)
monkeypatch.syspath_prepend(str(_INSTALL_SCRIPT.parent))
import install_python_stack
return install_python_stack
@pytest.mark.parametrize(
"torch_version, expected",
[
# torch 2.10 on CUDA <= 12 -> 0.16.0 (cpp built for 2.10.0, CUDA-12).
("2.10.0+cu128", "torchao==0.16.0"),
("2.10.0+cu126", "torchao==0.16.0"),
("2.10.0+rocm6.4", "torchao==0.16.0"),
("2.10.0+cpu", "torchao==0.16.0"),
("2.10.1", "torchao==0.16.0"),
("2.10.0", "torchao==0.16.0"),
# torch 2.10 on CUDA >= 13: 0.16.0's CUDA-12 cpp fails (libcudart.so.12), use 0.17.0.
("2.10.0+cu130", "torchao==0.17.0"),
("2.10.0+cu140", "torchao==0.17.0"),
("2.10.0rc1", "torchao==0.16.0"),
("2.10.0.dev20250804+cu130", "torchao==0.17.0"),
("2.10.0.dev20250804+cu128", "torchao==0.16.0"),
("2.10rc1", "torchao==0.16.0"),
# torchao 0.17.0 cpp is built for torch 2.11.
("2.11.0+cu130", "torchao==0.17.0"),
("2.11.0", "torchao==0.17.0"),
("2.11.1+cu126", "torchao==0.17.0"),
# torchao 0.18.0 CI targets torch 2.13; torchao 0.17.0 supports only through torch 2.11.
("2.12.0", "torchao==0.18.0"),
("2.12.1+cu130", "torchao==0.18.0"),
("2.13.0+cu132", "torchao==0.18.0"),
("2.14.0+cu130", "torchao==0.18.0"),
("2.14.0+xpu", "torchao==0.18.0"),
("2.99.0", "torchao==0.18.0"),
# CUDA 13 selection applies only to torch 2.10.
("2.12.0+cu126", "torchao==0.18.0"),
("2.12.0.dev20260801+cu132", "torchao==0.18.0"),
# torchao 0.15.0 is the floor for diffusers 0.41's unconditional import (#13244).
("2.9.0+cu126", "torchao==0.15.0"),
("2.9.0+cu128", "torchao==0.15.0"),
("2.9.1", "torchao==0.15.0"),
("2.9.1+rocm6.4", "torchao==0.15.0"),
# torch <= 2.8 gets 0.15.0 too: transformers 5 and diffusers 0.41 refuse TorchAoConfig on 0.14.
("2.8.0", "torchao==0.15.0"),
("2.8.0+cu128", "torchao==0.15.0"),
("2.7.1+cu126", "torchao==0.15.0"),
("2.6.0+cu124", "torchao==0.15.0"),
# torchao 0.15 dropped torch <= 2.5, so those keep 0.14.0.
("2.5.1+cu124", "torchao==0.14.0"),
("2.4.0", "torchao==0.14.0"),
# malformed, missing, and non-2.x versions use the conservative default.
(None, "torchao==0.15.0"),
("", "torchao==0.15.0"),
("garbage", "torchao==0.15.0"),
("2", "torchao==0.15.0"),
("3.0.0", "torchao==0.15.0"),
],
)
def test_select_torchao_spec(monkeypatch, torch_version, expected):
mod = _load_module(monkeypatch)
assert mod._select_torchao_spec(torch_version) == expected
def test_default_spec_matches_table(monkeypatch):
"""torch 2.6-2.8 shares torch 2.9's torchao: below 0.15 transformers and diffusers refuse TorchAoConfig."""
mod = _load_module(monkeypatch)
assert mod._TORCHAO_DEFAULT_SPEC == "torchao==0.15.0"
assert mod._select_torchao_spec("2.8.0") == mod._TORCHAO_DEFAULT_SPEC
assert mod._TORCHAO_DEFAULT_SPEC == mod._TORCHAO_TORCH_29_SPEC
@pytest.mark.parametrize("installed", ["0.14.0", "0.14.0+cu128", "0.14.1+cu128", "0.13.0"])
def test_an_old_torch_install_on_torchao_014_is_repinned(monkeypatch, installed):
"""An existing torch <= 2.8 install keeps torchao 0.14 until its next dependency pass, which
must force 0.15.0 over it even when the pass has evidence to skip satisfied steps."""
mod = _load_module(monkeypatch)
monkeypatch.setattr(mod, "IS_WINDOWS", False)
monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: installed)
monkeypatch.setattr(mod, "_may_skip_on_evidence", lambda: True)
calls = []
monkeypatch.setattr(mod, "pip_install_try", lambda *a, **k: calls.append(a) or True)
monkeypatch.setattr(mod, "pip_install", lambda *a, **k: calls.append(a))
monkeypatch.setattr(mod, "_record_step", lambda *a, **k: None)
monkeypatch.setattr(mod, "_note", lambda *a, **k: None)
mod._install_torchao_for_torch("2.8.0+cu128")
assert len(calls) == 1, calls
args = calls[0]
assert "torchao==0.15.0" in args and "--force-reinstall" in args
assert "https://download.pytorch.org/whl/cu128" in args
def test_matching_torchao_pin_does_not_need_force_reinstall(monkeypatch):
mod = _load_module(monkeypatch)
monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: "0.17.0")
assert mod._exact_distribution_spec_is_installed("torchao==0.17.0")
assert not mod._exact_distribution_spec_is_installed("torchao==0.16.0")
@pytest.mark.parametrize(
"torch_version, leaf",
[
("2.12.0+cu126", "cu126"),
("2.13.0+cu132", "cu132"),
("2.14.0+cu130", "cu130"),
("2.11.0+rocm7.2", "rocm7.2"), # rocm DOES publish torchao, unlike torchcodec
("2.9.0+rocm6.4", "rocm6.4"),
("2.14.0+xpu", "xpu"),
("2.12.0+cpu", "cpu"),
# Untagged torch is PyPI's own build and its counterpart is PyPI's own torchao.
("2.14.0", None),
("2.11.0", None),
(None, None),
("", None),
("garbage", None),
],
)
def test_the_torchao_index_follows_the_resident_torch_build(monkeypatch, torch_version, leaf):
"""The torchao index must follow the resident torch build; PyPI's default torchao is CUDA-12."""
mod = _load_module(monkeypatch)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY", raising = False)
got = mod._torch_accelerator_index_url(torch_version)
assert got == (f"https://download.pytorch.org/whl/{leaf}" if leaf else None)
# only leaves missing a selected release are listed; omitted leaves cover their whole range.
_TORCHAO_INDEX_GAPS = {
"cu118": ({m: f"0.{m}.0" for m in range(3, 12)}, range(5, 8)),
"cu129": (
{12: "0.12.0", 13: "0.13.0", 14: "0.14.1", 15: "0.15.0", 16: "0.16.0", 17: "0.17.0"},
range(8, 14),
),
"rocm7.0": ({16: "0.16.0"}, range(9, 11)),
# Legacy leaves frozen before torchao 0.10 / 0.11: neither 0.14.0 nor 0.15.0 was ever there.
"cu124": ({m: f"0.{m}.0" for m in range(3, 10)}, range(4, 7)),
"rocm6.1": ({m: f"0.{m}.0" for m in range(7, 10)}, range(4, 7)),
}
def test_the_index_pin_starves_only_where_the_retry_covers_it(monkeypatch):
"""the default-index retry must cover every leaf missing its selected torchao release."""
mod = _load_module(monkeypatch)
starved = set()
for leaf, (published, torch_minors) in _TORCHAO_INDEX_GAPS.items():
for minor in torch_minors:
version = f"2.{minor}.0+{leaf}"
assert mod._torch_accelerator_index_url(version).endswith("/" + leaf)
wanted = mod._select_torchao_spec(version).split("==", 1)[1]
if wanted not in published.values():
starved.add((leaf, minor, wanted))
assert starved == {
# cu118 lacks every selected torchao release for torch 2.5 through 2.7.
("cu118", 5, "0.14.0"),
("cu118", 6, "0.15.0"),
("cu118", 7, "0.15.0"),
("cu124", 4, "0.14.0"),
("cu124", 5, "0.14.0"),
("cu124", 6, "0.15.0"),
("rocm6.1", 4, "0.14.0"),
("rocm6.1", 5, "0.14.0"),
("rocm6.1", 6, "0.15.0"),
# cu129 lacks releases after 0.17.0 (it does carry 0.15.0, which torch 2.8 now selects).
("cu129", 12, "0.18.0"),
("cu129", 13, "0.18.0"),
# rocm7.0 provides only torchao 0.16.0.
("rocm7.0", 9, "0.15.0"),
}, sorted(starved)
def _torchao_installer_source():
source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
body = source.split("def _install_torchao_for_torch(", 1)[1]
return body.split("\ndef ", 1)[0]
def test_the_torchao_step_pins_the_index_and_retries_without_it():
"""a lagging accelerator leaf retries the default index, but failure there remains fatal."""
body = _torchao_installer_source()
assert "index = None if default_index else _torchao_index_url(torch_version)" in body
assert '"--index-url", index, spec' in body
assert "retrying from the default index" in body
# The unpinned attempt is pip_install, not pip_install_try: still fatal on failure.
retry = body.split("retrying from the default index", 1)[1]
assert 'pip_install("Installing dependency overrides", *args, spec)' in retry
assert "--index-url" not in retry
# And the printed line redacts, since a mirror URL can carry credentials.
assert "_strip_index_url_credentials(index)" in body
def test_the_fallback_is_never_conditioned_on_the_accelerator(monkeypatch):
"""A wrong-accelerator torchao costs its kernels, not its import, so the fallback stays
unconditional -- guarding it on the CUDA major regressed CUDA-13/ROCm/XPU hosts from a
slow torchao to none. torchao/__init__.py has wrapped the cpp load since 0.12.0."""
body = _torchao_installer_source()
fallback = body.split("retrying from the default index", 1)[1]
assert 'pip_install("Installing dependency overrides", *args, spec)' in fallback
# No branch between the failed pin and the retry. Comments carry the word; compare code.
between = body.split("if pip_install_try(", 1)[1].split("retrying from the default index", 1)[0]
code = [l for l in between.split("\n") if not l.strip().startswith("#")]
assert not any(l.strip().startswith(("if ", "elif ")) for l in code), between
mod = _load_module(monkeypatch)
assert not hasattr(mod, "_default_index_torchao_can_load")
@pytest.mark.parametrize(
"installed, spec, want_tag, expected",
[
("0.18.0", "torchao==0.18.0", "<none>", False),
("0.18.0+cu130", "torchao==0.18.0", "<none>", True),
("0.17.0", "torchao==0.18.0", "<none>", True),
(None, "torchao==0.18.0", "<none>", True),
# Pinned: 0.18.0+cu126 satisfies ==0.18.0, so pip would keep the wrong build.
("0.18.0+cu130", "torchao==0.18.0", "cu130", False),
("0.18.0+cu126", "torchao==0.18.0", "cu130", True),
("0.18.0", "torchao==0.18.0", "cu130", True),
("0.18.0+rocm7.2", "torchao==0.18.0", "rocm7.2", False),
("0.17.0+cu130", "torchao==0.18.0", "cu130", True),
# An opaque mirror proves nothing, so an untagged wheel is replaced.
("0.18.0", "torchao==0.18.0", None, True),
("0.18.0+cu130", "torchao==0.18.0", None, True),
],
)
def test_pin_needs_reinstall(monkeypatch, installed, spec, want_tag, expected):
mod = _load_module(monkeypatch)
monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: installed)
tag = "" if want_tag == "<none>" else want_tag
assert mod._pin_needs_reinstall(spec, tag) is expected
def test_the_wanted_tag_follows_the_index_that_will_be_pinned(monkeypatch):
"""The wanted tag must come from the index the pin resolves to, or pip skips the cu130 build."""
mod = _load_module(monkeypatch)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu130")
assert mod._torch_accelerator_index_url("2.13.0+cu128").endswith("/cu130")
assert mod._torch_index_tag("2.13.0+cu128") == "cu130"
monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: "0.18.0+cu128")
assert mod._pin_needs_reinstall("torchao==0.18.0", mod._torch_index_tag("2.13.0+cu128"))
monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: "0.18.0+cu130")
assert not mod._pin_needs_reinstall("torchao==0.18.0", mod._torch_index_tag("2.13.0+cu128"))
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/whl/cu130")
assert mod._torch_index_tag("2.13.0+cu128") is None
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL")
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")
assert mod._torch_index_tag("2.13.0+cu128") == "cu128"
_PYTORCH_WHL = "https://download.pytorch.org/whl"
_MIRROR_WHL = "https://mirror.example/whl"
@pytest.mark.parametrize(
"is_windows, torch_version, family, url, base, expected",
[
(True, "2.13.0+cu130", "", "", _PYTORCH_WHL, None),
(True, "2.12.0+cu126", "", "", _PYTORCH_WHL, None),
(True, "2.10.0+cu128", "", "", _PYTORCH_WHL, None),
(True, "2.13.0+cu128", "cu130", "", _PYTORCH_WHL, None),
# The cpu and xpu leaves serve Windows a py3-none-any wheel.
(True, "2.12.0+cpu", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cpu"),
(True, "2.14.0+xpu", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/xpu"),
(True, "2.13.0+cu130", "cpu", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cpu"),
(True, "2.13.0", "", "", _PYTORCH_WHL, None),
# Mirrors and explicit indexes stay pinned.
(True, "2.13.0+cu130", "", "", _MIRROR_WHL, f"{_MIRROR_WHL}/cu130"),
(True, "2.13.0+cu130", "", f"{_MIRROR_WHL}/cu130", _PYTORCH_WHL, f"{_MIRROR_WHL}/cu130"),
# Not a CUDA leaf, though it starts with "cu".
(True, "2.13.0+cu130", "current", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/current"),
(False, "2.13.0+cu130", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cu130"),
(False, "2.12.0+cu126", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cu126"),
],
)
def test_windows_cuda_takes_torchao_unpinned(
monkeypatch, is_windows, torch_version, family, url, base, expected
):
mod = _load_module(monkeypatch)
monkeypatch.setattr(mod, "IS_WINDOWS", is_windows)
monkeypatch.setattr(mod, "_PYTORCH_WHL_BASE", base)
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", family)
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", url)
assert mod._torchao_index_url(torch_version) == expected
def test_a_windows_cuda_update_leaves_the_installed_torchao_alone(monkeypatch):
"""The untagged wheel the first run installs must satisfy the next run's tag check."""
mod = _load_module(monkeypatch)
monkeypatch.setattr(mod, "IS_WINDOWS", True)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY", raising = False)
monkeypatch.delenv(mod._FULL_DEPS_ENV, raising = False)
notes: list[str] = []
calls: list[tuple] = []
monkeypatch.setattr(mod, "_note", notes.append)
monkeypatch.setattr(mod, "pip_install", lambda *a, **k: calls.append(a))
monkeypatch.setattr(mod, "pip_install_try", lambda *a, **k: calls.append(a) or True)
installed = {"torchao": None}
monkeypatch.setattr(mod, "_installed_distribution_version", lambda n: installed.get(n))
monkeypatch.setattr(mod, "_PASS_EVIDENCE", None)
mod._install_torchao_for_torch("2.13.0+cu130")
assert len(calls) == 1 and "--index-url" not in calls[0], calls
assert not any("did not serve" in n for n in notes), notes
installed["torchao"] = "0.18.0"
monkeypatch.setattr(mod, "_PASS_EVIDENCE", {"pass_inputs": {}, "step_results": {}})
mod._install_torchao_for_torch("2.13.0+cu130")
assert len(calls) == 1, calls
assert mod._STEP_RESULTS.get("torchao") == "skipped"
def test_every_torchao_call_site_asks_for_the_pinned_tag():
"""Passing the torch version rather than the pinned tag would reintroduce the drift the
helper exists to remove, so no call site may spell it any other way."""
source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
assert source.count("_pin_needs_reinstall(") == 3 # the def plus both call sites
assert '_torch_index_tag(torch_version) if index else ""' in source
assert '_torch_index_tag(_label_after) if _ao_index else ""' in source
assert "_ao_index = _torchao_index_url(_label_after)" in source
def test_no_torchao_install_can_resolve_a_dependency():
"""Both call sites pass --no-deps; the post-repair one runs right after step 13 fixed the torch
build; no torchao release needs torch today, so keep it if one ever does."""
body = _torchao_installer_source()
assert 'args = ["--no-deps", "--no-cache-dir"]' in body
# --force-reinstall must not be able to widen the install back out.
for call in ("pip_install(", "pip_install_try("):
for fragment in body.split(call)[1:]:
assert "*args" in fragment.split(")")[0], fragment[:120]
source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
resync = source.split("def _resync_torch_coupled_packages", 1)[1]
ao = resync.split("_ao_index", 1)[1][:1200]
assert "--no-deps" in ao
def test_torchao_is_re_selected_after_the_linux_torch_repair():
"""torchao is re-selected after the Linux torch repair, since only the Windows repair resyncs it."""
source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
step = source.split('_progress(_torch_step_label("final"))', 1)[1]
step = step.split("# 13w.", 1)[0]
assert '_torch_before_repair = str(_probe_installed_torch_version() or "")' in step
assert "_install_torchao_for_torch(_torch_after_repair)" in step
# Guarded on an actual move, so an install where nothing shifted pays no second resolve.
assert "if _torch_after_repair and _torch_after_repair != _torch_before_repair:" in step
assert '"torch>=2.6,<2.11.0",' in source
def test_windows_first_hop_uses_einx_wheel_without_shared_test_tree():
requirements = _EXTRAS_REQUIREMENTS.read_text(encoding = "utf-8")
assert 'einx<0.4.3; sys_platform == "win32"' in requirements
# einx dropped 3.9 in 0.4.0, so the non-Windows side is split by interpreter.
assert 'einx==0.4.3; sys_platform != "win32" and python_version >= "3.10"' in requirements
assert 'einx==0.3.0; sys_platform != "win32" and python_version < "3.10"' in requirements
@pytest.mark.parametrize(
("rocm_windows_torch_installed", "installed_torch_is_windows_rocm"),
[
(True, False),
(False, True),
(True, True),
],
)
@pytest.mark.parametrize("torchao_install_ok", [True, False])
def test_installs_pypi_torchao_on_windows_rocm(
monkeypatch,
tmp_path,
rocm_windows_torch_installed,
installed_torch_is_windows_rocm,
torchao_install_ok,
):
"""Windows ROCm gets the torch-matched torchao from PyPI (download.pytorch.org's rocm leaves
serve Linux only); the export worker loads it through unsloth/_torchao_nodist.py. A failed
torchao install does not fail the install: only export needs it."""
mod = _load_module(monkeypatch)
pip_calls: list[list[str]] = []
progress_labels: list[str] = []
def _record_pip_install(*args, **kwargs):
pip_calls.append([str(arg) for arg in args])
return 0
unstructured_plugin = tmp_path / "unstructured"
github_plugin = tmp_path / "github"
unstructured_plugin.mkdir()
github_plugin.mkdir()
subprocess_result = MagicMock()
subprocess_result.returncode = 0
subprocess_result.stdout = ""
monkeypatch.setenv("SKIP_STUDIO_BASE", "1")
monkeypatch.setattr(mod, "IS_WINDOWS", True)
monkeypatch.setattr(mod, "IS_MACOS", False)
monkeypatch.setattr(mod, "IS_MAC_ARM", False)
monkeypatch.setattr(mod, "NO_TORCH", False)
monkeypatch.setattr(mod, "_rocm_windows_torch_installed", rocm_windows_torch_installed)
monkeypatch.setattr(
mod, "_installed_torch_is_windows_rocm", lambda: installed_torch_is_windows_rocm
)
# require_present refuses when a managed distribution is absent (SKIP_STUDIO_BASE
# guarantees that here); stub it so the test does not depend on the env.
monkeypatch.setattr(mod, "_repair_damaged_core_payload", lambda *a, **k: True)
monkeypatch.setattr(mod, "_bootstrap_uv", lambda: False)
monkeypatch.setattr(mod, "_repair_bad_anyio", lambda: None)
monkeypatch.setattr(mod, "_repair_bad_accelerate", lambda: None)
monkeypatch.setattr(mod, "_ensure_rocm_torch", lambda: None)
monkeypatch.setattr(mod, "_ensure_cuda_torch", lambda: None)
# A Windows ROCm box has no NVIDIA GPU; _expected_torch_flavor_tag reads this flag.
monkeypatch.setattr(mod, "_has_usable_nvidia_gpu", lambda: False)
# The installed torch is ambient; pin it so the verdict does not depend on the host.
monkeypatch.setattr(mod, "_RECORDED_TORCH_TAG", "")
monkeypatch.setattr(
mod, "_probe_torch_runtime", lambda *args, **kwargs: (True, True, "2.9.1+cpu", "", "")
)
monkeypatch.setattr(mod, "run", lambda *args, **kwargs: None)
def _fatal_pip_install(*args, **kwargs):
# pip_install exits the installer on failure.
_record_pip_install(*args, **kwargs)
if not torchao_install_ok and any(str(a).startswith("torchao") for a in args):
raise SystemExit(1)
return 0
monkeypatch.setattr(mod, "pip_install", _fatal_pip_install)
monkeypatch.setattr(
mod,
"pip_install_try",
lambda *a, **k: (
_record_pip_install(*a, **k),
torchao_install_ok or not any(str(x).startswith("torchao") for x in a),
)[1],
)
monkeypatch.setattr(mod, "_progress", lambda label: progress_labels.append(label))
monkeypatch.setattr(mod, "LOCAL_DD_UNSTRUCTURED_PLUGIN", unstructured_plugin)
monkeypatch.setattr(mod, "LOCAL_DD_GITHUB_PLUGIN", github_plugin)
monkeypatch.setattr(mod.subprocess, "run", lambda *args, **kwargs: subprocess_result)
# Checked first so a regression names its cause instead of `assert 1 == 0` below.
assert mod._expected_torch_flavor_tag() == "", (
"no CUDA expectation may exist on a Windows ROCm host: a non-empty tag means "
"the Windows flavor invariant will demand a cu* build, not find one, and fail "
"the install long after the torchao branch this test is about"
)
assert mod.install_python_stack() == 0
torchao_calls = [c for c in pip_calls if any(a.startswith("torchao") for a in c)]
assert torchao_calls
assert all("--index-url" not in c for c in torchao_calls)
assert "dependency overrides (Windows ROCm)" in progress_labels
# Windows ROCm torchao export: real torchao via unsloth/_torchao_nodist.py, the stub as fallback.
import types
import core._torchao_stub as _stub
_BACKEND = Path(__file__).resolve().parents[1]
_EXPORT_HELPERS = ("_torchao_export_supported", "_torchao_runtime_unavailable", "_is_torchao_alias")
def _export_helpers():
"""Exec the gate helpers alone, avoiding export.py's heavy import chain."""
import ast
src = (_BACKEND / "core" / "export" / "export.py").read_text(encoding = "utf-8")
ns: dict = {}
for node in ast.parse(src).body:
if isinstance(node, ast.FunctionDef) and node.name in _EXPORT_HELPERS:
exec(ast.get_source_segment(src, node), ns)
return ns
def _fake_normalize_torchao(save_method):
if not isinstance(save_method, str):
return None
key = save_method.lower().strip().replace("-", "_").replace(" ", "_")
ok = key in {"torchao_fp8", "torchao_int8", "portable_fp8", "portable_int8"}
return ("fp8", "torchao-fp8") if ok else None
def _install_fake_unsloth_save(monkeypatch, *, has_method):
unsloth = types.ModuleType("unsloth")
save = types.ModuleType("unsloth.save")
if has_method:
save._normalize_torchao_method = _fake_normalize_torchao
unsloth.save = save
monkeypatch.setitem(sys.modules, "unsloth", unsloth)
monkeypatch.setitem(sys.modules, "unsloth.save", save)
def _set_torchao(monkeypatch, state):
if state == "absent":
monkeypatch.delitem(sys.modules, "torchao", raising = False)
elif state == "stub":
monkeypatch.setitem(sys.modules, "torchao", _stub._make_mod_stub("torchao"))
else:
monkeypatch.setitem(sys.modules, "torchao", types.ModuleType("torchao"))
@pytest.mark.parametrize(
("win_rocm", "torchao", "has_method", "expected"),
[
(True, "stub", True, False),
(True, "absent", True, False),
(True, "real", True, True),
(False, "real", True, True),
(False, "absent", True, True),
(False, "real", False, False),
],
)
def test_torchao_export_gate(monkeypatch, win_rocm, torchao, has_method, expected):
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: win_rocm)
_set_torchao(monkeypatch, torchao)
_install_fake_unsloth_save(monkeypatch, has_method = has_method)
ns = _export_helpers()
ns["sys"] = sys
assert ns["_torchao_export_supported"]() is expected
def test_is_torchao_alias_recognizes_all_forms(monkeypatch):
_install_fake_unsloth_save(monkeypatch, has_method = True)
fn = _export_helpers()["_is_torchao_alias"]
for alias in ("torchao_fp8", "portable_int8", "portable-fp8", "Portable FP8"):
assert fn(alias) is True
for alias in ("fp8", "nvfp4", "w8a8", "", None):
assert fn(alias) is False
def _load_export_module_no_torch(monkeypatch):
"""Import core.export.export with torch/unsloth blocked, so the guard runs without a GPU."""
import builtins
import importlib
real_import = builtins.__import__
def blocking_import(name, *args, **kwargs):
top = name.split(".")[0]
if top in {"torch", "unsloth"} and top not in sys.modules:
raise ImportError(f"blocked: {name}")
return real_import(name, *args, **kwargs)
for m in [k for k in list(sys.modules) if k.split(".")[0] in {"torch", "unsloth"}]:
monkeypatch.delitem(sys.modules, m, raising = False)
monkeypatch.delitem(sys.modules, "core.export.export", raising = False)
monkeypatch.setattr(builtins, "__import__", blocking_import)
return importlib.import_module("core.export.export")
def _bare_backend(mod):
be = mod.ExportBackend.__new__(mod.ExportBackend)
be.current_model = object()
be.current_tokenizer = object()
be._audio_type = None
be.is_peft = True
return be
@pytest.mark.parametrize("alias", ["torchao_fp8", "portable_fp8"])
def test_torchao_export_rejected_early_when_stubbed(monkeypatch, alias):
mod = _load_export_module_no_torch(monkeypatch)
monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
_set_torchao(monkeypatch, "stub")
_install_fake_unsloth_save(monkeypatch, has_method = True)
ok, message, out = _bare_backend(mod).export_merged_model("/tmp/x", compressed_method = alias)
assert ok is False and out is None
assert "Windows ROCm" in message and "torchao" in message.lower()
def test_torchao_export_not_rejected_with_real_torchao_on_windows_rocm(monkeypatch):
mod = _load_export_module_no_torch(monkeypatch)
monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
_set_torchao(monkeypatch, "real")
_install_fake_unsloth_save(monkeypatch, has_method = True)
ok, message, _ = _bare_backend(mod).export_merged_model(
"/tmp/x", compressed_method = "torchao_int8"
)
assert ok is False and "Windows ROCm" not in message
@pytest.mark.parametrize(
("platform", "is_rocm", "loadable", "expected"),
[
("win32", True, False, False),
("win32", True, True, True),
# torchao_export_loadable is asked everywhere now: it also says no to torchao < 0.15.
("win32", False, False, False),
("win32", False, True, True),
("linux", True, False, False),
("linux", False, False, False),
("linux", False, True, True),
],
)
def test_export_capability_torchao_flag(monkeypatch, platform, is_rocm, loadable, expected):
import utils.hardware.hardware as hw
monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CUDA)
monkeypatch.setattr(sys, "platform", platform)
monkeypatch.setattr(hw, "IS_ROCM", is_rocm)
monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: loadable)
assert hw.export_capability()["torchao_export_supported"] is expected
@pytest.mark.parametrize(
("platform", "is_rocm", "expected"),
[("win32", True, False), ("win32", False, True), ("linux", False, True), ("linux", True, True)],
)
def test_export_capability_fails_open_off_windows_rocm(monkeypatch, platform, is_rocm, expected):
import utils.hardware.hardware as hw
def broken():
raise RuntimeError("probe failed")
monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CUDA)
monkeypatch.setattr(sys, "platform", platform)
monkeypatch.setattr(hw, "IS_ROCM", is_rocm)
monkeypatch.setattr(_stub, "torchao_export_loadable", broken)
assert hw.export_capability()["torchao_export_supported"] is expected
@pytest.mark.parametrize(
("installed", "too_old"),
[
("0.14.0", "0.14.0"),
("0.14.1+cu128", "0.14.1+cu128"),
("0.13.0", "0.13.0"),
# PEP 440, as transformers compares: prereleases of 0.15.0 are still below it.
("0.15.0rc1", "0.15.0rc1"),
("0.15.0.dev20250901", "0.15.0.dev20250901"),
("0.15.0", None),
("0.15.0+cu126", None),
("0.17.0", None),
("0.18.0+rocm7.2", None),
("1.0.0", None),
(None, None),
],
)
def test_torchao_export_loadable_needs_015_on_every_platform(monkeypatch, installed, too_old):
"""transformers 5 refuses torchao < 0.15 with "requires torchao to be installed"."""
import importlib.metadata as md
def version(name):
if installed is None:
raise md.PackageNotFoundError(name)
return installed
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: "0.15.0")
monkeypatch.setattr(_stub.importlib.metadata, "version", version)
saved = {n: m for n, m in sys.modules.items() if n == "torchao" or n.startswith("torchao.")}
for name in saved:
monkeypatch.delitem(sys.modules, name)
assert _stub.torchao_export_loadable() is (too_old is None)
# metadata only: never imports torchao.
assert "torchao" not in sys.modules
assert _stub.torchao_too_old_for_export() == too_old
@pytest.mark.parametrize("floor", ["0.4.0", None])
def test_torchao_014_stays_exportable_where_transformers_accepts_it(monkeypatch, floor):
"""transformers 4.57.6 (the Python 3.9 pin, torch 2.4 / 2.5 keep torchao 0.14) has a 0.4 floor;
an unreadable floor never hides the formats either."""
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: floor)
monkeypatch.setattr(_stub.importlib.metadata, "version", lambda name: "0.14.0")
assert _stub.torchao_too_old_for_export() is None
assert _stub.torchao_export_loadable() is True
@pytest.mark.parametrize(
("source", "expected"),
[
('TORCHAO_MIN_VERSION = "0.15.0"\n', "0.15.0"),
("x = 1\nTORCHAO_MIN_VERSION = '0.4.0'\n", "0.4.0"),
("x = 1\n", None),
],
)
def test_transformers_torchao_min_read_without_import(monkeypatch, tmp_path, source, expected):
pkg = tmp_path / "transformers"
(pkg / "utils").mkdir(parents = True)
(pkg / "__init__.py").write_text("raise RuntimeError('must not be imported')\n")
(pkg / "utils" / "import_utils.py").write_text(source)
for name in [n for n in sys.modules if n == "transformers" or n.startswith("transformers.")]:
monkeypatch.delitem(sys.modules, name)
monkeypatch.syspath_prepend(str(tmp_path))
assert _stub._transformers_torchao_min() == expected
assert "transformers" not in sys.modules
@pytest.mark.parametrize("alias", ["torchao_fp8", "portable_int8"])
def test_torchao_export_rejected_early_when_torchao_is_too_old(monkeypatch, alias):
mod = _load_export_module_no_torch(monkeypatch)
monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: "0.15.0")
monkeypatch.setattr(_stub.importlib.metadata, "version", lambda name: "0.14.0")
_set_torchao(monkeypatch, "real")
_install_fake_unsloth_save(monkeypatch, has_method = True)
ok, message, out = _bare_backend(mod).export_merged_model("/tmp/x", compressed_method = alias)
assert ok is False and out is None
assert "0.15" in message and "0.14.0" in message
def test_too_old_torchao_does_not_block_other_formats(monkeypatch):
mod = _load_export_module_no_torch(monkeypatch)
monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: "0.15.0")
monkeypatch.setattr(_stub.importlib.metadata, "version", lambda name: "0.14.0")
_install_fake_unsloth_save(monkeypatch, has_method = True)
ok, message, _ = _bare_backend(mod).export_merged_model("/tmp/x", compressed_method = None)
assert "0.15" not in (message or "")
def test_torchao_export_loadable_ignores_the_stub(monkeypatch):
# The main process has already stubbed torchao; only an installed torchao counts.
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
_set_torchao(monkeypatch, "stub")
real = importlib.machinery.PathFinder.find_spec
monkeypatch.setattr(
importlib.machinery.PathFinder,
"find_spec",
classmethod(lambda cls, name, *a, **k: None if name == "torchao" else real(name, *a, **k)),
)
assert _stub.torchao_export_loadable() is False
@pytest.mark.parametrize(
("installed", "expect"),
[
("0.14.0", False),
("0.15.0rc1", False),
("0.15.0", True),
("0.17.0", True),
("0.18.0+rocm", True),
],
)
def test_torchao_export_loadable_needs_transformers_minimum(
monkeypatch, tmp_path, installed, expect
):
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
(tmp_path / "unsloth").mkdir()
(tmp_path / "unsloth" / "_torchao_nodist.py").write_text("")
specs = {
"torchao": importlib.machinery.ModuleSpec("torchao", None),
"unsloth": importlib.machinery.ModuleSpec("unsloth", None, is_package = True),
}
specs["unsloth"].submodule_search_locations = [str(tmp_path / "unsloth")]
monkeypatch.setattr(
importlib.machinery.PathFinder,
"find_spec",
classmethod(lambda cls, name, *a, **k: specs.get(name)),
)
monkeypatch.setattr(importlib.util, "find_spec", lambda name, *a, **k: specs.get(name))
monkeypatch.setattr(importlib.metadata, "version", lambda name: installed)
assert _stub.torchao_export_loadable() is expect
@pytest.mark.parametrize(("fix_result", "expect_real"), [(True, True), (False, False)])
def test_real_or_stub(monkeypatch, fix_result, expect_real):
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: True)
monkeypatch.delitem(sys.modules, "torchao", raising = False)
calls = []
def fix():
calls.append(1)
if fix_result:
sys.modules["torchao"] = types.ModuleType("torchao")
return fix_result
monkeypatch.setattr(
_stub,
"_load_torchao_nodist",
lambda: types.SimpleNamespace(fix_torchao_without_torch_distributed = fix),
)
stubbed = []
monkeypatch.setattr(_stub, "install_torchao_windows_rocm_stub", lambda: stubbed.append(1))
try:
assert _stub.install_torchao_windows_rocm_real_or_stub() is expect_real
assert calls == [1]
assert bool(stubbed) is (not expect_real)
finally:
sys.modules.pop("torchao", None)
@pytest.mark.parametrize("consumer_loaded", [False, True])
def test_real_or_stub_replaces_a_stub_inherited_from_run_py(monkeypatch, consumer_loaded):
"""spawn re-runs run.py as __mp_main__, which stubs torchao before the export worker starts."""
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: True)
# Simulated "already imported" consumer: json is always loaded; none of the real ones is required.
monkeypatch.setattr(_stub, "_STUB_CONSUMERS", ("json",) if consumer_loaded else ())
saved = {n: m for n, m in sys.modules.items() if n == "torchao" or n.startswith("torchao.")}
for name in saved:
monkeypatch.delitem(sys.modules, name)
calls = []
def fix():
calls.append("torchao" in sys.modules)
sys.modules["torchao"] = types.ModuleType("torchao")
return True
monkeypatch.setattr(
_stub,
"_load_torchao_nodist",
lambda: types.SimpleNamespace(fix_torchao_without_torch_distributed = fix),
)
try:
_stub.install_torchao_windows_rocm_stub()
assert _stub.is_stubbed("torchao")
result = _stub.install_torchao_windows_rocm_real_or_stub()
if consumer_loaded:
assert result is False and calls == [] and _stub.is_stubbed("torchao")
else:
assert result is True and calls == [False] and not _stub.is_stubbed("torchao")
assert not any(n.startswith("torchao.") for n in sys.modules)
finally:
for name in [n for n in sys.modules if n == "torchao" or n.startswith("torchao.")]:
del sys.modules[name]
sys.modules.update(saved)
def test_real_or_stub_keeps_the_stub_when_torchao_is_not_loadable(monkeypatch):
"""an install still on torchao 0.14 (transformers 5 rejects it) never loads it."""
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: False)
monkeypatch.delitem(sys.modules, "torchao", raising = False)
monkeypatch.setattr(
_stub, "_load_torchao_nodist", lambda: pytest.fail("must not load the shim")
)
stubbed = []
monkeypatch.setattr(_stub, "install_torchao_windows_rocm_stub", lambda: stubbed.append(1))
assert _stub.install_torchao_windows_rocm_real_or_stub() is False
assert stubbed == [1]
def test_shim_found_through_an_editable_finder(monkeypatch, tmp_path):
"""setuptools editable installs can expose unsloth only through a meta-path finder."""
(tmp_path / "unsloth").mkdir()
(tmp_path / "unsloth" / "_torchao_nodist.py").write_text(
"def fix_torchao_without_torch_distributed():\n return 'ok'\n"
)
class EditableFinder:
def find_spec(
self,
name,
path = None,
target = None,
):
if name != "unsloth":
return None
spec = importlib.machinery.ModuleSpec("unsloth", None, is_package = True)
spec.submodule_search_locations = [str(tmp_path / "unsloth")]
return spec
monkeypatch.delitem(sys.modules, "unsloth", raising = False)
real = importlib.machinery.PathFinder.find_spec
monkeypatch.setattr(
importlib.machinery.PathFinder,
"find_spec",
classmethod(lambda cls, name, *a, **k: None if name == "unsloth" else real(name, *a, **k)),
)
monkeypatch.setattr(sys, "meta_path", [EditableFinder(), *sys.meta_path])
module = _stub._load_torchao_nodist()
assert module is not None and module.fix_torchao_without_torch_distributed() == "ok"
def test_real_or_stub_noop_off_windows_rocm(monkeypatch):
monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
monkeypatch.setattr(
_stub, "_load_torchao_nodist", lambda: pytest.fail("must not load the shim")
)
assert _stub.install_torchao_windows_rocm_real_or_stub() is False
def test_load_torchao_nodist_reads_unsloths_file():
module = _stub._load_torchao_nodist()
if importlib.util.find_spec("unsloth") is None:
assert module is None
else:
assert callable(module.fix_torchao_without_torch_distributed)