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.
"""torch / torchcodec ABI guardrails (unslothai/unsloth#7225)."""
from __future__ import annotations
import importlib.util
import re
import sys
import types
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
PYPROJECT = REPO_ROOT / "pyproject.toml"
IMPORT_FIXES_PATH = REPO_ROOT / "unsloth" / "import_fixes.py"
EXTRAS_NO_DEPS_TXT = REPO_ROOT / "studio" / "backend" / "requirements" / "extras-no-deps.txt"
SECURITY_AUDIT_YML = REPO_ROOT / ".github" / "workflows" / "security-audit.yml"
COLAB_TORCH211 = {"torch": "2.11.0+cu128", "torchcodec": "0.11.0+cu128"}
TORCHCODEC_WHEEL = (
"https://download.pytorch.org/whl/torchcodec-0.13.0-cp312-cp312-manylinux_2_28_x86_64.whl"
)
def _tomllib():
if sys.version_info >= (3, 11):
import tomllib
return tomllib
return pytest.importorskip("tomli")
@pytest.fixture(autouse = True)
def _no_inherited_index_config(monkeypatch):
"""A developer's own UNSLOTH_TORCH_INDEX_URL must not decide what the suite asserts."""
for name in (
"UNSLOTH_TORCH_INDEX_URL",
"UNSLOTH_TORCH_INDEX_FAMILY",
"UNSLOTH_TORCH_INSTALL_INDEX_URL",
"UNSLOTH_PYTORCH_MIRROR",
):
monkeypatch.delenv(name, raising = False)
def _load_import_fixes_module():
spec = importlib.util.spec_from_file_location(
"unsloth_import_fixes_under_test",
IMPORT_FIXES_PATH,
)
assert spec and spec.loader
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
return mod
def test_pyproject_declares_torch210_audio_extra_with_python_gate():
text = PYPROJECT.read_text(encoding = "utf-8")
assert "audio-torch210 = [" in text
assert "torchcodec>=0.10.0,<0.11.0" in text
assert "python_version >= '3.10'" in text
assert "audio-torch290 = [" in text
assert "audio-torch280 = [" in text
assert "\naudio = [" not in text
def _stub_torch(monkeypatch, version: str):
torch_mod = types.ModuleType("torch")
torch_mod.__version__ = version
monkeypatch.setitem(sys.modules, "torch", torch_mod)
def test_torch210_extras_bundle_audio_torch210():
text = PYPROJECT.read_text(encoding = "utf-8")
for extra in (
"cu128-torch2100",
"cu126-ampere-torch2100",
"rocm72-torch2100",
):
match = re.search(rf"^{extra} = \[(.*?)^\]", text, re.MULTILINE | re.DOTALL)
assert match is not None, extra
assert "unsloth[audio-torch210]" in match.group(1)
def test_torchcodec_matrix_matches_notebook_validator():
from scripts import notebook_validator as nv
fixes = _load_import_fixes_module()
assert fixes._TORCH_TORCHCODEC_MINORS == nv.TORCH_TORCHCODEC
def test_torchcodec_exclusive_upper_bound():
fixes = _load_import_fixes_module()
assert fixes._torchcodec_exclusive_upper("0.10") == "<0.11.0"
assert fixes._torchcodec_exclusive_upper("0.9") == "<0.10.0"
# (torch, torchcodec, substrings the warning must carry or None for silent, forbidden substrings)
_GUARD_CASES = [
("2.9.0+cu128", "0.7.0", (), ("audio-torch210",)),
("2.8.0+cu128", "0.7.0", None, ()),
("2.10.0", "0.11.0", ("torchcodec 0.11.0", "audio-torch210", "<0.11.0"), ("<11.0",)),
(
"2.10.0+cu128",
"0.11.0",
("--index-url https://download.pytorch.org/whl/cu128", "<0.11.0"),
("audio-torch210",),
),
("2.10.0+cu128", "0.10.0+cu128", None, ()),
(
"2.11.0",
"0.10.0+cu128",
("torchcodec 0.10.0+cu128", "audio-torch211", ">=0.11", "<0.12.0"),
("audio-torch210",),
),
("2.11.0+cu128", "0.11.1+cu128", None, ()),
("2.10.0", "0.15.0", ("audio-torch210",), ()),
("2.4.0", "0.0.3", None, ()),
]
_GUARD_CASES += [
(torch_version, codec_version, None, ())
for torch_version in ("2.11.0+cu128", "2.12.0", "2.13.0+cu130")
for codec_version in ("0.12.0", "0.15.0+cu130")
]
_GUARD_CASES += [
(torch_version, codec_version, ("torchcodec>=0.12.0",), ("unsloth[audio-torch",))
for torch_version in ("2.12.1+cu130", "2.13.0")
for codec_version in ("0.11.1", "0.10.0")
]
@pytest.mark.parametrize(
"torch_version, codec_version, contains, absent",
_GUARD_CASES,
ids = [f"torch{t}-codec{c}" for t, c, _, _ in _GUARD_CASES],
)
def test_the_runtime_guard_reports_exactly_the_pairs_the_matrix_forbids(
monkeypatch, torch_version, codec_version, contains, absent
):
import importlib.metadata
fixes = _load_import_fixes_module()
_stub_torch(monkeypatch, torch_version)
monkeypatch.setattr(importlib.metadata, "version", lambda _name: codec_version)
hint = fixes._torchcodec_version_mismatch_hint()
if contains is None:
assert hint is None, f"{torch_version} + torchcodec {codec_version} is supported upstream"
return
assert hint is not None, f"{torch_version} + torchcodec {codec_version} must not go unreported"
for text in contains:
assert text in hint, f"{text!r} missing from {hint!r}"
for text in absent:
assert text not in hint, f"{text!r} should not appear in {hint!r}"
def test_import_fixes_loads_on_python39_syntax():
"""Regression: module must import on 3.9 (postponed annotations for str | None)."""
fixes = _load_import_fixes_module()
assert callable(fixes._torchcodec_version_mismatch_hint)
def _load_install_python_stack():
studio_dir = REPO_ROOT / "studio"
if str(studio_dir) not in sys.path:
sys.path.insert(0, str(studio_dir))
import install_python_stack
return install_python_stack
def _reload_install_python_stack():
"""A fresh private module, since _PYTORCH_WHL_BASE is read from the environment at import."""
import importlib.util
spec = importlib.util.spec_from_file_location(
"_install_python_stack_probe", REPO_ROOT / "studio" / "install_python_stack.py"
)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def test_pyproject_declares_torch211_audio_extra_with_python_gate():
text = PYPROJECT.read_text(encoding = "utf-8")
match = re.search(r"^audio-torch211 = \[(.*?)^\]", text, re.MULTILINE | re.DOTALL)
assert match is not None, "pyproject must declare an audio-torch211 extra"
assert "torchcodec>=0.11.0,<0.12.0" in match.group(1)
assert "python_version >= '3.10'" in match.group(1)
def test_security_audit_covers_every_installable_torchcodec_line():
"""Every torchcodec line needs its own audit input, since the per-torch ranges are disjoint."""
text = SECURITY_AUDIT_YML.read_text(encoding = "utf-8")
ips = _load_install_python_stack()
tomllib = _tomllib()
extras = tomllib.loads(PYPROJECT.read_text(encoding = "utf-8"))["project"][
"optional-dependencies"
]
audited = ["audio-torch211", "audio-torch210", "audio-torch290", "audio-torch280"]
# Either index shape counts; both workflow halves must still look the group up.
indexed = text.count('optional-dependencies"]["audio-torch211"]') + text.count(
'extra("audio-torch211")'
)
assert indexed == 2, f"both halves must index audio-torch211, found {indexed}"
assert text.count("for extra in audio-torch210 audio-torch290 audio-torch280; do") == 2
for extra in audited[1:]:
assert f"audit-reqs/{extra}.txt" in text, extra
assert f" {extra} " in text or f" {extra};" in text or f" {extra}'" in text, extra
# scan_packages keeps one requirement per name, so disjoint ranges need separate shards.
shards = re.findall(r"files: '([^']+)'", text)
for shard in shards:
assert (
sum(1 for extra in audited if extra in shard.split()) <= 1
), f"shard {shard!r} would have its torchcodec lines deduplicated to one"
scanned = {extra for shard in shards for extra in audited if extra in shard.split()}
assert scanned == {"audio-torch210", "audio-torch290", "audio-torch280"}
for torch_minor in ("2.10", "2.9", "2.8"):
spec = ips._select_torchcodec_spec(f"{torch_minor}.0")
assert any(
spec in dep for extra in audited for dep in extras[extra]
), f"torch {torch_minor} installs {spec}, which no audited extra declares"
def test_extras_no_deps_has_no_unconditional_torchcodec_pin():
"""A flat pin cannot serve both torch lines, so the installer picks the spec."""
lines = [
line.strip()
for line in EXTRAS_NO_DEPS_TXT.read_text(encoding = "utf-8").splitlines()
if line.strip() and not line.strip().startswith("#")
]
assert not any(line.lower().startswith("torchcodec") for line in lines), (
"extras-no-deps.txt must not pin torchcodec unconditionally; "
"install_python_stack._select_torchcodec_spec picks it per torch minor"
)
def test_select_torchcodec_spec_tracks_torch_minor():
ips = _load_install_python_stack()
assert ips._select_torchcodec_spec("2.11.0+cu128") == "torchcodec>=0.11.0,<0.12.0"
assert ips._select_torchcodec_spec("2.10.0+cu130") == "torchcodec>=0.10.0,<0.11.0"
assert ips._select_torchcodec_spec("2.9.1+cu128") == "torchcodec>=0.8.0,<0.10.0"
assert ips._select_torchcodec_spec("2.8.0+cu126") == "torchcodec>=0.6.0,<0.8.0"
def test_select_torchcodec_spec_never_caps_newer_torch_to_the_011_line():
"""0.11 is locked to torch 2.11 exactly, so torch >2.11 takes the open floor."""
ips = _load_install_python_stack()
for version in ("2.12.0", "2.12.1+cu132", "2.13.0+cu130", "2.99.0"):
spec = ips._select_torchcodec_spec(version)
assert spec == ips._TORCHCODEC_ABI_STABLE_SPEC, version
assert "<" not in spec, version
def test_select_torchcodec_spec_falls_back_on_unknown_torch():
ips = _load_install_python_stack()
for value in (None, "", "not-a-version", "3.0.0", "2.rc1"):
assert ips._select_torchcodec_spec(value) == ips._TORCHCODEC_DEFAULT_SPEC
def test_shell_torch_floors_below_codec_table_skip_torchcodec():
ips = _load_install_python_stack()
source = (REPO_ROOT / "install.sh").read_text(encoding = "utf-8")
floors = {int(m) for m in re.findall(r'TORCH_CONSTRAINT="torch>=2\.(\d+)', source)}
assert floors, "install.sh torch constraints were not found"
codec_floor = min(ips._TORCHCODEC_TORCH_SPECS)
# Moving either floor means the torch 2.4 notes in both files are stale (#10598).
assert (min(floors), codec_floor) == (4, 5)
for minor in floors:
spec = ips._select_torchcodec_spec(f"2.{minor}.0")
assert (spec is None) == (minor < codec_floor), (minor, spec)
def test_select_torchcodec_spec_skips_older_torch():
ips = _load_install_python_stack()
for minor in range(min(ips._TORCHCODEC_TORCH_SPECS)):
for suffix in (".0", ".1+cu121", ".0+cpu", ".0rc1"):
assert ips._select_torchcodec_spec(f"2.{minor}{suffix}") is None
@pytest.mark.parametrize("version", ["2.3.0", "2.4.0+cu121"])
def test_torchcodec_step_skips_older_torch(version):
from textwrap import dedent
from unittest.mock import Mock
ips = _load_install_python_stack()
namespace = vars(ips).copy()
namespace.update(
NO_TORCH = False,
PLATFORM_LACKS_TORCHCODEC_WHEEL = False,
_probe_installed_torch_version = lambda: version,
_progress = Mock(),
_note = Mock(),
_torchcodec_spec_is_installable = Mock(side_effect = AssertionError("must skip")),
pip_install_try = Mock(side_effect = AssertionError("must not install")),
)
source = Path(ips.__file__).read_text(encoding = "utf-8")
step = source.split("# 13b. torchcodec", 1)[1].split("# 14.", 1)[0]
exec(dedent(step[step.index(" _codec_torch_ver = None") :]), namespace)
namespace["_progress"].assert_called_once_with(
"torchcodec (skipped, unsupported torch version)"
)
namespace["_note"].assert_called_once_with(
f"torch {version} is below the oldest supported torchcodec pairing "
f"(torch 2.{ips._TORCHCODEC_MIN_KNOWN_MINOR}) -- leaving torchcodec alone"
)
def test_select_torchcodec_spec_matches_pyproject_audio_extras():
"""The installer's specs and the pip extras must not drift apart."""
ips = _load_install_python_stack()
text = PYPROJECT.read_text(encoding = "utf-8")
for torch_version, extra in (
("2.11.0", "audio-torch211"),
("2.10.0", "audio-torch210"),
("2.9.0", "audio-torch290"),
("2.8.0", "audio-torch280"),
):
match = re.search(rf"^{extra} = \[(.*?)^\]", text, re.MULTILINE | re.DOTALL)
assert match is not None, extra
assert ips._select_torchcodec_spec(torch_version) in match.group(1), extra
# Upstream torchcodec table, kept literal so our tables cannot all be wrong together.
# Source: meta-pytorch/torchcodec README; torch 2.4 omitted (installer floor is 2.5).
_UPSTREAM_TORCH_TO_TORCHCODEC_MINORS = {
"2.11": {"0.11"},
"2.10": {"0.10"},
"2.9": {"0.8", "0.9"},
"2.8": {"0.6", "0.7"},
"2.7": {"0.3", "0.4", "0.5"},
"2.6": {"0.2"},
"2.5": {"0.1"},
}
# Live per-index inventory; not contiguous (cu129 skips 0.8, 0.9, 0.12-0.14).
_INDEX_INVENTORY = {
"cpu": {"torch": range(5, 15), "codec": {3, 4, *range(6, 17)}},
"cu118": {"torch": range(5, 8), "codec": {3, 4}},
"cu126": {"torch": range(6, 15), "codec": {3, 4, *range(6, 17)}},
"cu128": {"torch": range(7, 12), "codec": {3, 4, *range(6, 12)}},
"cu129": {"torch": range(8, 14), "codec": {6, 7, 10, 11, 15, 16}},
"cu130": {"torch": range(9, 15), "codec": set(range(8, 17))},
"cu132": {"torch": range(12, 15), "codec": set(range(12, 17))},
}
def test_torchcodec_index_follows_the_resident_torch_build():
"""torchcodec has one wheel per accelerator, so a version from the wrong index fails to dlopen;
the index must match the torch build."""
ips = _load_install_python_stack()
base = "https://download.pytorch.org/whl/"
assert ips._torchcodec_index_url("2.11.0+cu128") == base + "cu128"
assert ips._torchcodec_index_url("2.11.0+cu126") == base + "cu126"
assert ips._torchcodec_index_url("2.14.0+cu130") == base + "cu130"
assert ips._torchcodec_index_url("2.11.0+cpu") == base + "cpu"
assert ips._torchcodec_index_url("2.14.0+xpu") == base + "cpu"
assert ips._torchcodec_index_url("2.9.0+xpu") == base + "cpu"
# On Linux an untagged torch is a CUDA build, so pinning cpu would be wrong.
assert ips._torchcodec_index_url("2.11.0") is None
# Every rocm leaf 404s for torchcodec.
assert ips._torchcodec_index_url("2.9.0+rocm6.4") is None
assert ips._torchcodec_index_url("2.11.0+rocm7.2") is None
assert ips._torchcodec_index_url(None) is None
assert ips._torchcodec_index_url("") is None
def _starved_index_cells():
"""Every (tag, torch minor) whose pinned index publishes nothing in the window."""
from packaging.specifiers import SpecifierSet
ips = _load_install_python_stack()
starved = []
for tag, inv in _INDEX_INVENTORY.items():
for minor in inv["torch"]:
version = f"2.{minor}.0+{tag}"
spec = ips._select_torchcodec_spec(version)
index = ips._torchcodec_index_url(version, spec)
if index is None:
continue
assert index.endswith("/" + tag), index
specifier = SpecifierSet(spec.split("torchcodec", 1)[1])
if not any(specifier.contains(f"0.{m}.0") for m in inv["codec"]):
starved.append((tag, minor, spec))
return starved
def test_pinning_the_index_starves_only_where_the_retry_covers_it():
"""Only cells the unpinned retry covers may starve from the pin; a new starved cell fails."""
starved = {(tag, minor) for tag, minor, _ in _starved_index_cells()}
assert starved == {("cu129", 9)}, sorted(starved)
def test_the_installer_retries_without_the_index_when_the_pin_finds_nothing():
"""The starved cells above are only survivable because the step falls back."""
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
step = source.split("# 13b. torchcodec", 1)[1].split("# 14.", 1)[0]
assert "retrying from the default index" in step
# --no-deps avoids undoing the repair; --force-reinstall stops pip calling the pin satisfied.
retry = step.split("retrying from the default index", 1)[1]
assert "_codec_retry_args = [" in retry
assert 'a != "--index-url" and _codec_args[i - 1] != "--index-url"' in retry
assert "*_codec_retry_args, _codec_spec" in retry
def test_an_accelerator_with_no_codec_build_of_its_own_takes_the_cpu_one():
"""torchcodec has no XPU build, so every XPU torch is served the `+cpu` wheel."""
ips = _load_install_python_stack()
assert ips._TORCHCODEC_INDEX_TAGS == {"xpu": "cpu"}
for minor in (7, 8, 9, 10, 11, 12, 13, 14):
version = f"2.{minor}.0+xpu"
spec = ips._select_torchcodec_spec(version)
assert ips._torchcodec_index_url(version, spec) == (
"https://download.pytorch.org/whl/cpu"
), spec
assert ips._torchcodec_index_url("2.9.0+cu126", ips._select_torchcodec_spec("2.9.0")) == (
"https://download.pytorch.org/whl/cu126"
)
assert ips._torch_accelerator_index_url("2.14.0+xpu") == "https://download.pytorch.org/whl/xpu"
def test_an_explicit_family_override_still_gets_the_substituted_leaf(monkeypatch):
"""UNSLOTH_TORCH_INDEX_FAMILY gets the xpu-to-cpu leaf substitution; a full URL is used verbatim."""
ips = _load_install_python_stack()
base = "https://download.pytorch.org/whl/"
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "xpu")
for version in ("2.9.0+xpu", "2.14.0+xpu"):
spec = ips._select_torchcodec_spec(version)
assert ips._torchcodec_index_url(version, spec) == base + "cpu", version
assert ips._torchcodec_index_tag(version) == "cpu"
assert ips._torch_accelerator_index_url("2.14.0+xpu") == base + "xpu"
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")
assert ips._torchcodec_index_url("2.11.0+cu128", "torchcodec>=0.11.0,<0.12.0") == base + "cu126"
# An explicit URL is opaque, so provenance is unknown, not absent.
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/whl/xpu/")
assert ips._torchcodec_index_url("2.14.0+xpu", "torchcodec>=0.12.0") == (
"https://mirror.corp.example/whl/xpu"
)
assert ips._torchcodec_index_tag("2.14.0+xpu") is None
def test_no_cuda_13_index_relies_on_the_unpinned_torchao_fallback():
"""PyPI's torchao fallback is the CUDA 12 build, so no CUDA 13 index may rely on it."""
ips = _load_install_python_stack()
published = {
"cu130": ({"0.14.0", "0.14.1", "0.15.0", "0.16.0", "0.17.0", "0.18.0"}, range(9, 15)),
"cu132": ({"0.18.0"}, range(12, 15)),
}
for leaf, (releases, torch_minors) in published.items():
for minor in torch_minors:
version = f"2.{minor}.0+{leaf}"
assert ips._cuda_major_from_torch_version(version) >= 13, version
wanted = ips._select_torchao_spec(version).split("==", 1)[1]
assert wanted in releases, (
f"{version} selects torchao {wanted}, which {leaf} does not publish, so the "
f"fallback would put PyPI's CUDA-12 wheel on a CUDA-13 host"
)
def test_the_provenance_check_compares_against_the_tag_the_pin_will_fetch():
"""Compare the codec tag with the one the pin fetches, since an xpu torch is served a +cpu wheel."""
ips = _load_install_python_stack()
assert ips._torchcodec_index_tag("2.14.0+xpu") == "cpu"
assert ips._torchcodec_index_tag("2.14.0+cu130") == "cu130"
assert ips._torchcodec_index_tag("2.14.0") == ""
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
step = source.split("# 13b. torchcodec", 1)[1].split("# 14.", 1)[0]
assert "_codec_want = _torchcodec_index_tag(_codec_torch_ver)" in step
assert '_codec_want = str(_codec_torch_ver).partition("+")' not in step
assert "_codec_want is None" in step
def test_an_opaque_mirror_replaces_a_codec_it_cannot_vouch_for(monkeypatch):
"""An opaque `UNSLOTH_TORCH_INDEX_URL` mirror cannot be vouched for, so its codec is always replaced."""
ips = _load_install_python_stack()
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/whl/cu130")
want = ips._torchcodec_index_tag("2.14.0+cu130")
assert want is None
for have in ("0.16.0", "0.16.0+cu126", "0.16.0+cu130"):
forced = bool(have) and (want is None or have.partition("+")[2].strip().lower() != want)
assert forced, have
def test_the_two_pypi_only_rows_stay_unpinned():
"""torchcodec 0.1 and 0.2 were never published to download.pytorch.org, so pinning torch
2.5 / 2.6 would guarantee a skip on the oldest venvs instead of leaving them as they are."""
ips = _load_install_python_stack()
for minor in (5, 6):
version = f"2.{minor}.0+cu126"
assert ips._torchcodec_index_url(version, ips._select_torchcodec_spec(version)) is None
assert (
ips._torchcodec_index_url("2.7.0+cu118", ips._select_torchcodec_spec("2.7.0")) is not None
)
# torchcodec has no sdist, so extras need markers matching install_python_stack.py.
# aarch64 wheels start at 0.11.0, so only audio-torch211 allows it.
# extra -> (first Python that must NOT select it, one that must, aarch64 wheel shipped?)
_AUDIO_EXTRA_GATES = {
"audio-torch211": ("3.15", "3.14", True),
"audio-torch210": ("3.15", "3.14", False),
"audio-torch290": ("3.15", "3.14", False),
"audio-torch280": ("3.14", "3.13", False),
}
_WHEELED_HOSTS = (
{"sys_platform": "linux", "platform_machine": "x86_64"},
{"sys_platform": "win32", "platform_machine": "AMD64"},
{"sys_platform": "darwin", "platform_machine": "arm64"},
)
_WHEELLESS_HOSTS = (
{"sys_platform": "win32", "platform_machine": "ARM64"},
{"sys_platform": "darwin", "platform_machine": "x86_64"},
)
def _audio_extras():
extras = _tomllib().loads(PYPROJECT.read_text(encoding = "utf-8"))["project"][
"optional-dependencies"
]
return {n: d for n, d in extras.items() if n.startswith("audio-torch")}
def test_every_audio_extra_has_a_gate_of_its_own():
"""A new extra added without a row here would go through the gates below untested."""
assert set(_audio_extras()) == set(_AUDIO_EXTRA_GATES)
@pytest.mark.parametrize("extra", sorted(_AUDIO_EXTRA_GATES))
def test_an_audio_extra_is_gated_to_the_hosts_and_pythons_its_wheels_cover(extra):
markers = pytest.importorskip("packaging.markers")
too_new, supported, allows_aarch64 = _AUDIO_EXTRA_GATES[extra]
deps = _audio_extras()[extra]
assert deps, extra
for dep in deps:
_, _, marker_text = dep.partition(";")
assert marker_text.strip(), f"{extra}: {dep!r} has no marker"
marker = markers.Marker(marker_text.strip())
base = {"python_version": "3.12", "platform_system": "Linux", "os_name": "posix"}
for case in _WHEELED_HOSTS:
assert marker.evaluate({**base, **case}), f"{extra} must install on {case}"
for case in _WHEELLESS_HOSTS:
assert not marker.evaluate(
{**base, **case}
), f"{extra} has no wheel for {case} and must not be resolved there"
aarch64 = marker.evaluate({**base, "sys_platform": "linux", "platform_machine": "aarch64"})
assert aarch64 == allows_aarch64, (
f"{extra} {'must not exclude' if allows_aarch64 else 'must not be resolved on'} "
"Linux aarch64"
)
linux = {**_WHEELED_HOSTS[0], "platform_system": "Linux", "os_name": "posix"}
assert not marker.evaluate(
{**linux, "python_version": too_new}
), f"{extra} still selects torchcodec on Python {too_new}, which has no wheel"
assert marker.evaluate(
{**linux, "python_version": supported}
), f"{extra} stopped selecting torchcodec on Python {supported}, which does"
def test_compat_matrix_matches_the_published_upstream_table():
"""Pin the runtime guard to upstream, not merely to our own other copies of it."""
fixes = _load_import_fixes_module()
assert fixes._TORCH_TORCHCODEC_MINORS == _UPSTREAM_TORCH_TO_TORCHCODEC_MINORS
def test_installer_never_selects_a_torchcodec_built_against_another_torch():
"""Pip's window must skip torchcodec builds for other torch, since pip takes the highest."""
from packaging.specifiers import SpecifierSet
ips = _load_install_python_stack()
probes = [f"0.{n}.0" for n in range(0, 16)]
for torch_minor, allowed in _UPSTREAM_TORCH_TO_TORCHCODEC_MINORS.items():
spec = ips._select_torchcodec_spec(f"{torch_minor}.0")
specifier = SpecifierSet(spec.split("torchcodec", 1)[1])
admitted = {p.rsplit(".", 1)[0] for p in probes if specifier.contains(p)}
assert admitted == allowed, (
f"torch {torch_minor}: {spec} admits {sorted(admitted)}, "
f"upstream builds only {sorted(allowed)} against it"
)
highest = max(
(p for p in probes if specifier.contains(p)),
key = lambda v: tuple(int(x) for x in v.split(".")),
)
assert (
highest.rsplit(".", 1)[0] in allowed
), f"torch {torch_minor}: pip would resolve {spec} to {highest}"
def test_validator_and_runtime_guard_agree_on_the_whole_matrix(monkeypatch):
"""Validator and runtime guard must agree on every pair; a half-ported ABI rule is how they drift."""
from scripts import notebook_validator as nv
fixes = _load_import_fixes_module()
pairs = [
("2.13.0", "0.10.0"),
("2.12.0", "0.11.1"),
("2.12.0", "0.12.0"),
("2.11.0", "0.10.0"),
("2.11.0", "0.11.0"),
("2.11.0", "0.15.0"),
("2.10.0", "0.10.0"),
("2.10.0", "0.12.0"),
("2.9.0", "0.8.0"),
("2.4.0", "0.1.0"),
]
for torch_v, codec_v in pairs:
validator_flags = bool(
nv.rule_inst_004_torchcodec_torch(
"", {"torch": torch_v, "torchcodec": codec_v}, "nb.ipynb", 0
)
)
guard_flags = _guard_reports(fixes, monkeypatch, torch_v, codec_v)
assert validator_flags == guard_flags, (
f"torch {torch_v} + torchcodec {codec_v}: "
f"validator={'reports' if validator_flags else 'silent'}, "
f"guard={'reports' if guard_flags else 'silent'}"
)
def _guard_reports(fixes, monkeypatch, torch_version: str, codec_version: str) -> bool:
"""Run the runtime guard against one pair, stubbed the way the cases above stub it."""
import importlib.metadata
_stub_torch(monkeypatch, torch_version)
monkeypatch.setattr(importlib.metadata, "version", lambda _name: codec_version)
return fixes._torchcodec_version_mismatch_hint() is not None
def test_the_installer_never_installs_what_the_guard_rejects(monkeypatch):
"""Every codec the installer's spec admits must pass the runtime guard, even past the matrix table."""
from packaging.specifiers import SpecifierSet
fixes = _load_import_fixes_module()
ips = _load_install_python_stack()
probes = [f"0.{n}.0" for n in range(0, 20)]
for minor in range(min(ips._TORCHCODEC_TORCH_SPECS), 15):
torch_v = f"2.{minor}.0"
specifier = SpecifierSet(ips._select_torchcodec_spec(torch_v).split("torchcodec", 1)[1])
admitted = [p for p in probes if specifier.contains(p)]
assert admitted, f"torch {torch_v}: installer spec admits nothing"
for codec_v in admitted:
assert not _guard_reports(fixes, monkeypatch, torch_v, codec_v), (
f"installer would put torchcodec {codec_v} on torch {torch_v}, "
f"which the runtime guard then reports as incompatible"
)
# From pypi.org: win_amd64 from 0.7.0, aarch64 from 0.11.0, macOS 14 minimum from 0.12.0.
_TORCHCODEC_WHEEL_HISTORY = {
"0.1.0": {"linux_x86_64", "macos_arm64_11"},
"0.2.0": {"linux_x86_64", "macos_arm64_11"},
"0.3.0": {"linux_x86_64", "macos_arm64_11"},
"0.4.0": {"linux_x86_64", "macos_arm64_11"},
"0.5": {"linux_x86_64", "macos_arm64_11"},
"0.6.0": {"linux_x86_64", "macos_arm64_11"},
"0.7.0": {"linux_x86_64", "macos_arm64_11", "win_amd64"},
"0.8.0": {"linux_x86_64", "macos_arm64_11", "win_amd64"},
"0.9.0": {"linux_x86_64", "macos_arm64_11", "win_amd64"},
"0.10.0": {"linux_x86_64", "macos_arm64_11", "win_amd64"},
"0.11.0": {"linux_x86_64", "linux_aarch64", "macos_arm64_11", "win_amd64"},
"0.11.1": {"linux_x86_64", "linux_aarch64", "macos_arm64_11", "win_amd64"},
"0.12.0": {"linux_x86_64", "linux_aarch64", "macos_arm64_14", "win_amd64"},
"0.15.0": {"linux_x86_64", "linux_aarch64", "macos_arm64_14", "win_amd64"},
}
# label -> (IS_LINUX, IS_WINDOWS, IS_MACOS, IS_MAC_ARM, IS_MAC_INTEL), machine, macos major
_SIM_HOSTS = {
"linux-x86_64": ((True, False, False, False, False), "x86_64", None),
"linux-aarch64": ((True, False, False, False, False), "aarch64", None),
"linux-ppc64le": ((True, False, False, False, False), "ppc64le", None),
"windows-amd64": ((False, True, False, False, False), "AMD64", None),
"windows-arm64": ((False, True, False, False, False), "ARM64", None),
"macos-arm64-14": ((False, False, True, True, False), "arm64", 14),
"macos-arm64-13": ((False, False, True, True, False), "arm64", 13),
"macos-intel": ((False, False, True, False, True), "x86_64", None),
}
def _host_key(label):
if label.startswith("linux"):
machine = _SIM_HOSTS[label][1]
return f"linux_{machine}" if machine in ("x86_64", "aarch64") else None
if label == "windows-amd64":
return "win_amd64"
if label.startswith("macos-arm64"):
return "macos_arm64"
return None
def _release_python_window(vt):
"""Upstream's published Python range for a release, independent of architecture."""
if vt < (0, 2, 0):
return (3, 9), (3, 12)
if vt < (0, 8, 0):
return (3, 9), (3, 13)
if vt < (0, 9, 0):
return (3, 10), (3, 13)
return (3, 10), (3, 14)
def _wheel_exists_in_window(label, floor, ceiling, python):
"""Does any release the window admits publish a wheel for this host AND interpreter?"""
key = _host_key(label)
if key is None:
return False
macos_major = _SIM_HOSTS[label][2]
for ver, plats in _TORCHCODEC_WHEEL_HISTORY.items():
vt = tuple(int(p) for p in ver.split("."))
vt = vt + (0,) * (3 - len(vt))
if vt < floor or (ceiling is not None and vt >= ceiling):
continue
py_min, py_max = _release_python_window(vt)
if not py_min <= python <= py_max:
continue
if key == "macos_arm64":
for p in plats:
if p.startswith("macos_arm64_") and macos_major >= int(p.rsplit("_", 1)[1]):
return True
elif key in plats:
return True
return False
def _patch_host(ips, monkeypatch, label):
flags, machine, macos_major = _SIM_HOSTS[label]
is_linux, is_windows, is_macos, is_mac_arm, is_mac_intel = flags
monkeypatch.setattr(ips, "IS_LINUX", is_linux)
monkeypatch.setattr(ips, "IS_WINDOWS", is_windows)
monkeypatch.setattr(ips, "IS_MACOS", is_macos)
monkeypatch.setattr(ips, "IS_MAC_ARM", is_mac_arm)
monkeypatch.setattr(ips, "IS_MAC_INTEL", is_mac_intel)
monkeypatch.setattr(ips.platform, "machine", lambda: machine)
monkeypatch.setattr(
ips.platform,
"mac_ver",
lambda: (f"{macos_major}.0" if macos_major else "", ("", "", ""), ""),
)
def test_the_installer_never_selects_a_spec_with_no_wheel_here(monkeypatch):
"""Skip torchcodec specs with no wheel on this platform, e.g. win_amd64 on cu118 or macOS below 14."""
ips = _load_install_python_stack()
for label in _SIM_HOSTS:
for python in ((3, 9), (3, 10), (3, 12), (3, 13), (3, 14)):
for minor in range(min(ips._TORCHCODEC_TORCH_SPECS), 15):
_patch_host(ips, monkeypatch, label)
monkeypatch.setattr(ips.sys, "version_info", python + (0, "final", 0))
spec = ips._select_torchcodec_spec(f"2.{minor}.0")
floor, ceiling = ips._torchcodec_spec_bounds(spec)
gate_says_yes = ips._torchcodec_spec_is_installable(spec)
really_has = _wheel_exists_in_window(label, floor, ceiling, python)
assert gate_says_yes == really_has, (
f"{label} py{python[0]}.{python[1]} torch 2.{minor}: gate says "
f"{'install' if gate_says_yes else 'skip'} for {spec}, but a wheel "
f"{'exists' if really_has else 'does not exist'}"
)
# Hand-written; the sweep checks only the history table. Columns: host, python, minor, install.
_WHEEL_GATE_ANCHORS = [
("linux-aarch64", (3, 12), 11, True),
("linux-aarch64", (3, 12), 10, False),
# torchcodec 0.12+ is macosx_14_0 only.
("macos-arm64-13", (3, 12), 12, False),
("macos-arm64-13", (3, 12), 11, True),
("macos-arm64-14", (3, 12), 12, True),
# torch 2.5 selects the 0.1 line, which has no cp313 wheel.
("linux-x86_64", (3, 12), 5, True),
("linux-x86_64", (3, 13), 5, False),
("linux-x86_64", (3, 9), 9, False),
("linux-x86_64", (3, 9), 8, True),
]
_WHEEL_GATE_ANCHORS += [
("windows-amd64", (3, 12), minor, minor >= 8) for minor in (5, 6, 7, 8, 10, 11, 12)
]
@pytest.mark.parametrize(
"label, python, torch_minor, installable",
_WHEEL_GATE_ANCHORS,
ids = [f"{h}-py{p[0]}.{p[1]}-torch2.{m}" for h, p, m, _ in _WHEEL_GATE_ANCHORS],
)
def test_the_wheel_gate_answers_the_transitions_it_was_written_for(
monkeypatch, label, python, torch_minor, installable
):
ips = _load_install_python_stack()
_patch_host(ips, monkeypatch, label)
monkeypatch.setattr(ips.sys, "version_info", python + (0, "final", 0))
spec = ips._select_torchcodec_spec(f"2.{torch_minor}.0")
assert ips._torchcodec_spec_is_installable(spec) == installable, spec
def test_python_windows_match_the_published_upstream_table():
"""Same reason as the compat-matrix pin: transcribed from upstream, not from ourselves."""
ips = _load_install_python_stack()
assert ips._TORCHCODEC_PYTHON_WINDOWS == (
((0, 1, 0), (3, 9), (3, 12)),
((0, 2, 0), (3, 9), (3, 13)),
((0, 8, 0), (3, 10), (3, 13)),
((0, 9, 0), (3, 10), (3, 14)),
)
def test_the_torchcodec_step_cannot_end_the_install():
"""Audio is optional, so the torchcodec step uses non-fatal `pip_install_try`, not `pip_install`."""
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
step = source.split("# 13b. torchcodec", 1)[1].split("# 14.", 1)[0]
assert "pip_install_try(" in step, "the torchcodec step must use the non-fatal install"
assert "\n pip_install(" not in step, "pip_install() exits on failure"
def test_the_runtime_hint_pins_the_index_it_tells_you_to_install_from(monkeypatch):
"""The remedy must pin the torch index, or it hands back the wrong accelerator build."""
import importlib.metadata
fixes = _load_import_fixes_module()
_stub_torch(monkeypatch, "2.11.0+cu128")
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.10.0")
hint = fixes._torchcodec_version_mismatch_hint()
assert "--index-url https://download.pytorch.org/whl/cu128 'torchcodec>=0.11" in hint
_stub_torch(monkeypatch, "2.12.0+cu130")
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.11.1")
assert (
"--index-url https://download.pytorch.org/whl/cu130 'torchcodec>=0.12.0'"
in fixes._torchcodec_version_mismatch_hint()
)
for version in ("2.11.0", "2.9.0+rocm6.4"):
_stub_torch(monkeypatch, version)
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.7.0")
assert "--index-url" not in (fixes._torchcodec_version_mismatch_hint() or "")
_stub_torch(monkeypatch, "2.5.0+cu118")
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.5.0")
assert "--index-url" not in fixes._torchcodec_version_mismatch_hint()
def test_the_remedy_drops_the_extra_when_an_index_pin_is_needed(monkeypatch):
"""An extra cannot carry an index, and --index-url on the whole command would resolve unsloth
from the torch index; on a tagged venv the extra gives the unloadable wheel"""
import importlib.metadata
fixes = _load_import_fixes_module()
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.10.0")
_stub_torch(monkeypatch, "2.11.0+cu128")
pinned = fixes._torchcodec_version_mismatch_hint()
assert "--index-url" in pinned
assert "unsloth[audio-torch211]" not in pinned
_stub_torch(monkeypatch, "2.11.0")
unpinned = fixes._torchcodec_version_mismatch_hint()
assert "--index-url" not in unpinned
assert "unsloth[audio-torch211]" in unpinned
def test_the_codec_index_honours_an_explicitly_pinned_torch_mirror(monkeypatch):
"""An explicit `UNSLOTH_TORCH_INDEX_URL` is reused for the codec, not rebuilt from public
PyTorch URLs."""
from studio import install_python_stack as ips
assert ips._torchcodec_index_url("2.11.0+cu128") == "https://download.pytorch.org/whl/cu128"
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/pytorch/cu128/")
assert ips._torchcodec_index_url("2.11.0+cu128") == "https://mirror.corp.example/pytorch/cu128"
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")
assert ips._torchcodec_index_url("2.11.0+cu128") == "https://download.pytorch.org/whl/cu126"
assert ips._torchcodec_index_url("2.11.0") == "https://download.pytorch.org/whl/cu126"
assert ips._torchcodec_index_url("2.11.0+rocm7.0") is None
def test_the_runtime_remedy_honours_a_configured_torch_index(monkeypatch):
"""A warning that tells an air-gapped or authenticated host to install from
download.pytorch.org either fails or bypasses the artifact source the install was
configured with. The mirror is where the matching build is."""
import importlib.metadata
fixes = _load_import_fixes_module()
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.11.0")
_stub_torch(monkeypatch, "2.10.0+cu128")
assert "--index-url https://download.pytorch.org/whl/cu128" in (
fixes._torchcodec_version_mismatch_hint() or ""
)
# Print the variable, not its value: a mirror URL can carry credentials.
monkeypatch.setenv(
"UNSLOTH_TORCH_INDEX_URL", "https://user:[email protected]/pytorch/cu128/"
)
hint = fixes._torchcodec_version_mismatch_hint()
assert f'--index-url {fixes._shell_env_ref("UNSLOTH_TORCH_INDEX_URL")} ' in hint
assert "secret" not in hint
assert "mirror.corp.example" not in hint
assert "download.pytorch.org" not in hint
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")
assert "--index-url https://download.pytorch.org/whl/cu126" in (
fixes._torchcodec_version_mismatch_hint() or ""
)
def test_a_mismatched_accelerator_build_is_named_when_the_codec_cannot_load(monkeypatch):
"""Name an accelerator mismatch only once the codec fails to load; a working pairing must never warn."""
import sys
import types
fixes = _load_import_fixes_module()
_stub_torch(monkeypatch, "2.11.0+cu128")
# Metadata is read first; report none so the stub answers, installed codec or not.
import importlib.metadata
def _no_metadata(name):
raise importlib.metadata.PackageNotFoundError(name)
monkeypatch.setattr(importlib.metadata, "version", _no_metadata)
codec = types.ModuleType("torchcodec")
codec.__version__ = "0.11.0"
monkeypatch.setitem(sys.modules, "torchcodec", codec)
hint = fixes._torchcodec_provenance_hint()
assert hint is not None
assert "https://download.pytorch.org/whl/cu128" in hint
assert "audio is disabled" in hint
codec.__version__ = "0.11.0+cu128"
assert fixes._torchcodec_provenance_hint() is None
codec.__version__ = "0.11.0"
_stub_torch(monkeypatch, "2.11.0+rocm7.0")
assert fixes._torchcodec_provenance_hint() is None
def test_the_printed_codec_index_is_redacted(monkeypatch):
"""The printed codec index must be redacted: the status line bypasses `_redact_install_output`."""
from studio import install_python_stack as ips
monkeypatch.setenv(
"UNSLOTH_TORCH_INDEX_URL", "https://user:[email protected]/pytorch/cu128/"
)
resolved = ips._torchcodec_index_url("2.11.0+cu128")
assert resolved == "https://user:[email protected]/pytorch/cu128"
shown = ips._strip_index_url_credentials(resolved)
assert shown == "https://mirror.corp.example/pytorch/cu128"
assert "secret" not in shown
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/simple?token=abc")
assert "abc" not in ips._strip_index_url_credentials(ips._torchcodec_index_url("2.11.0+cu128"))
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
assert 'f" from {_strip_index_url_credentials(_codec_index)}"' in source
assert 'f" from {_codec_index}"' not in source
def test_the_codec_index_follows_a_configured_pytorch_mirror(monkeypatch):
"""UNSLOTH_PYTORCH_MIRROR replaces the base every other index in install_python_stack is
built from, so a codec pinned to the public site cannot be fetched on an air-gapped host
and bypasses the artifact source on a corporate one."""
import importlib
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.corp.example/whl")
from studio import install_python_stack as ips
ips = importlib.reload(ips) # _PYTORCH_WHL_BASE is read at import time
try:
assert ips._torchcodec_index_url("2.11.0+cu128") == "https://mirror.corp.example/whl/cu128"
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://other.example/pytorch/cu128")
assert ips._torchcodec_index_url("2.11.0+cu128") == "https://other.example/pytorch/cu128"
finally:
monkeypatch.delenv("UNSLOTH_PYTORCH_MIRROR", raising = False)
importlib.reload(ips)
def test_the_runtime_remedy_follows_a_configured_pytorch_mirror(monkeypatch):
"""Same for the runtime warning, and by naming the variable rather than its value the
command still works without disclosing a mirror that may carry credentials."""
import importlib.metadata
fixes = _load_import_fixes_module()
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.11.0")
_stub_torch(monkeypatch, "2.10.0+cu128")
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://user:[email protected]/whl")
hint = fixes._torchcodec_version_mismatch_hint()
assert f'--index-url {fixes._shell_env_ref("UNSLOTH_PYTORCH_MIRROR")}/cu128' in hint
assert "secret" not in hint
assert "download.pytorch.org" not in hint
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")
assert f'--index-url {fixes._shell_env_ref("UNSLOTH_PYTORCH_MIRROR")}/cu126' in (
fixes._torchcodec_version_mismatch_hint() or ""
)
monkeypatch.delenv("UNSLOTH_PYTORCH_MIRROR")
assert "--index-url https://download.pytorch.org/whl/cu126" in (
fixes._torchcodec_version_mismatch_hint() or ""
)
def test_the_provenance_hint_does_not_assert_a_cause_it_has_not_established(monkeypatch):
"""A tag mismatch does not establish the cause of a load failure, so the hint must not claim one."""
import sys
import types
fixes = _load_import_fixes_module()
_stub_torch(monkeypatch, "2.12.0+cu128")
codec = types.ModuleType("torchcodec")
codec.__version__ = "0.12.0"
monkeypatch.setitem(sys.modules, "torchcodec", codec)
hint = fixes._torchcodec_provenance_hint()
assert hint is not None # 0.12+ is ABI-stable against torch, not accelerator-agnostic
assert "may be built for a different accelerator" in hint
assert "cannot load" not in hint
assert "FFmpeg" in hint
def test_the_remedy_uses_the_shell_of_the_host_it_prints_on(monkeypatch):
"""PowerShell does not expand `$NAME`, so the pasted POSIX form left --index-url empty."""
import importlib.metadata
fixes = _load_import_fixes_module()
monkeypatch.setattr(importlib.metadata, "version", lambda _name: "0.11.0")
_stub_torch(monkeypatch, "2.10.0+cu128")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://user:[email protected]/cu128")
monkeypatch.setattr(fixes.sys, "platform", "linux")
assert f'--index-url {fixes._shell_env_ref("UNSLOTH_TORCH_INDEX_URL")}' in (
fixes._torchcodec_version_mismatch_hint() or ""
)
monkeypatch.setattr(fixes.sys, "platform", "win32")
windows = fixes._torchcodec_version_mismatch_hint() or ""
assert "--index-url $env:UNSLOTH_TORCH_INDEX_URL" in windows
assert "secret" not in windows
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL")
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.corp.example/whl")
assert "--index-url $env:UNSLOTH_PYTORCH_MIRROR/cu128" in (
fixes._torchcodec_version_mismatch_hint() or ""
)
def test_the_provenance_remedy_pins_the_compatible_window(monkeypatch):
"""The accelerator indexes carry the whole codec line, so a bare `torchcodec` on torch 2.9 gets
a wrong-version wheel and audio stays off; pin the compatible window."""
import sys
import types
fixes = _load_import_fixes_module()
codec = types.ModuleType("torchcodec")
codec.__version__ = "0.8.0"
monkeypatch.setitem(sys.modules, "torchcodec", codec)
_stub_torch(monkeypatch, "2.9.0+cu128")
hint = fixes._torchcodec_provenance_hint()
assert "'torchcodec>=0.9,<0.10.0'" in hint, hint
assert "--index-url https://download.pytorch.org/whl/cu128 torchcodec`" not in hint
_stub_torch(monkeypatch, "2.12.0+cu128")
codec.__version__ = "0.11.0"
assert "'torchcodec>=0.12.0'" in (fixes._torchcodec_provenance_hint() or "")
def test_a_cuda_index_codec_also_installs_npp():
"""torchcodec's CUDA build dlopens libnppicc and libnppc, and NPP is not in torch's own
dependency set, so a --no-deps install from a cuNNN index reports success and then fails
to import. docker/Dockerfile installs nvidia-npp-cu12 beside the same wheel."""
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
assert '_npp_spec = _npp_requirement(_npp_major) if _npp_major else ""' in source
assert "Installing torchcodec CUDA runtime (NPP)" in source
import re
for url, want in (
("https://download.pytorch.org/whl/cu128", "12"),
("https://download.pytorch.org/whl/cu130", "13"),
("https://mirror.corp.example/whl/cu128/", "12"),
("https://download.pytorch.org/whl/cpu", None),
("https://download.pytorch.org/whl/rocm6.3", None),
):
match = re.search(r"/cu(\d+)/?$", url)
assert (match.group(1)[:2] if match else None) == want, url
dockerfile = (REPO_ROOT / "docker" / "Dockerfile").read_text(encoding = "utf-8")
assert "nvidia-npp-cu12" in dockerfile
def test_cuda_13_asks_for_the_unsuffixed_npp():
"""`nvidia-npp-cu13` is a wheel-less stub, so asking for it builds from source (or takes a
1.1 kB placeholder under --only-binary); plain `nvidia-npp` is the 13.x runtime."""
from studio.install_python_stack import _npp_requirement
assert _npp_requirement("11") == "nvidia-npp-cu11"
assert _npp_requirement("12") == "nvidia-npp-cu12"
assert _npp_requirement("13") == "nvidia-npp>=13,<14"
assert _npp_requirement("14") == "nvidia-npp>=14,<15"
assert not any(
_npp_requirement(str(major)).startswith("nvidia-npp-cu13") for major in range(11, 20)
)
assert _npp_requirement("not-a-major") == "nvidia-npp-cunot-a-major"
def test_the_npp_rename_is_per_package_not_a_rule_about_13():
""" "13 means no suffix" is WRONG: NCCL and cuDNN kept theirs, and their unsuffixed names
resolve to "A fake package to warn the user they are not installing the correct package".
Hence a named constant with the counterexamples beside it, not a bare 13."""
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
assert "_NPP_SUFFIXED_THROUGH_CUDA_MAJOR = 12" in source
assert "nvidia-cudnn" in source and "nvidia-nccl" in source
def test_the_unsuffixed_request_is_bounded_to_the_major():
"""`nvidia-npp` carries the same 0.0.0a0 junk the stub is made of, which an unbounded
resolve behind an exclude-newer cutoff or a partial mirror can select."""
from studio.install_python_stack import _npp_requirement
for major in ("13", "14", "15"):
spec = _npp_requirement(major)
assert spec.startswith(f"nvidia-npp>={major}"), spec
assert spec != "nvidia-npp", "a bare name can resolve to the 0.0.0a0 placeholder"
assert f",<{int(major) + 1}" in spec, spec
def test_no_major_can_kill_the_install_or_emit_an_unparseable_requirement():
"""`isdigit` accepts superscripts that crash `int()`, and non-ASCII digits make invalid requirements."""
from studio.install_python_stack import _npp_requirement
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
assert (
'if not re.fullmatch(r"[0-9]+", cuda_major):' in source
), "the major check must be an explicit ASCII digit match, not str.isdigit()"
for major in ("²", "³", "⁵"):
assert major.isdigit(), "fixture is only meaningful if isdigit() accepts it"
assert _npp_requirement(major) == f"nvidia-npp-cu{major}"
# int()-able but not PEP 440; only an ASCII check keeps them out.
for major in ("١٣", "۱۳", "१३"):
assert major.isdigit() and int(major) == 13
spec = _npp_requirement(major)
assert not spec.startswith(
"nvidia-npp>="
), f"{major!r} reached a PEP 440 version bound as {spec!r}"
assert spec == f"nvidia-npp-cu{major}"
packaging_req = pytest.importorskip("packaging.requirements").Requirement
for major in [str(n) for n in range(0, 100)]:
packaging_req(_npp_requirement(major))
for major in ("", " ", "12.0", "-1", "+13", "13a", "1" * 64, "\U0001d7d9\U0001d7db"):
assert isinstance(_npp_requirement(major), str)
def test_the_npp_major_comes_from_the_resident_torch_not_the_index_url():
"""Matching `/cuNNN$` against an authenticated mirror ending `/simple?token=...` skipped
NPP on a `+cu128` host, so the codec then failed to import without a CUDA toolkit."""
import re as _re
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
namespace: dict = {"re": _re}
exec(
_re.search(r"def _cuda_major_for_npp.*?\n(?=\n\ndef )", source, _re.S).group(0),
namespace,
)
npp_major = namespace["_cuda_major_for_npp"]
opaque = "https://mirror.example/simple?token=abc"
assert npp_major("2.11.0+cu128", opaque) == "12"
assert npp_major("2.11.0+cu130", opaque) == "13"
assert npp_major("2.11.0+cpu", "https://download.pytorch.org/whl/cpu") == ""
assert npp_major("2.11.0+rocm6.4", "https://download.pytorch.org/whl/rocm6.4") == ""
assert npp_major("2.11.0", "https://download.pytorch.org/whl/cu126") == "12"
assert npp_major("2.11.0", opaque) == ""
assert "_cuda_major_for_npp(_codec_torch_ver, _codec_index)" in source
def test_the_provenance_hint_reads_a_codec_it_cannot_import(monkeypatch):
"""Read the version from metadata, since a codec that failed to import is dropped and re-raises."""
import importlib.metadata
import sys
fixes = _load_import_fixes_module()
_stub_torch(monkeypatch, "2.11.0+cu128")
# None blocks the import even with a codec installed, as a failed initialisation does.
monkeypatch.setitem(sys.modules, "torchcodec", None)
def _version(name):
if name == "torchcodec":
return "0.11.0"
raise importlib.metadata.PackageNotFoundError(name)
monkeypatch.setattr(importlib.metadata, "version", _version)
hint = fixes._torchcodec_provenance_hint()
assert hint is not None
assert "torchcodec 0.11.0 came from the default index" in hint
assert "https://download.pytorch.org/whl/cu128" in hint
def _absent(name):
raise importlib.metadata.PackageNotFoundError(name)
monkeypatch.setattr(importlib.metadata, "version", _absent)
assert fixes._torchcodec_provenance_hint() is None
def test_an_explicit_index_wins_even_when_torch_carries_no_tag(monkeypatch):
"""Only download.pytorch.org stamps +cuNNN, so a private mirror ships torch bare, and
requiring a tag first sent that host to PyPI for both companions."""
mod = _load_install_python_stack()
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp/simple?token=abc")
for version in ("2.14.0", "2.13.0+cu130", "2.11.0+rocm7.2", "2.10.0+weird"):
assert mod._torch_accelerator_index_url(version) == "https://mirror.corp/simple?token=abc"
assert mod._torchcodec_index_url("2.11.0+rocm7.2") is None
assert mod._torchcodec_index_url("2.14.0") == "https://mirror.corp/simple?token=abc"
assert mod._torch_accelerator_index_url(None) is None
assert mod._torch_accelerator_index_url("") is None
assert mod._torch_index_tag("2.14.0") is None
def test_an_untagged_torch_without_an_explicit_index_stays_unpinned(monkeypatch):
"""With no override an untagged torch is PyPI's own build, already the right pairing."""
mod = _load_install_python_stack()
assert mod._torch_accelerator_index_url("2.14.0") is None
assert mod._torchcodec_index_url("2.14.0") is None
assert mod._torch_index_tag("2.14.0") == ""
def test_the_installed_codec_reports_the_cuda_major_it_actually_links(monkeypatch, tmp_path):
"""0.16.0 links libcudart.so.13 on PyPI, .12 on cu126; read the wheel, not the torch tag."""
mod = _load_install_python_stack()
class _Dist:
def __init__(self, files):
self.files = files
def _probe(blobs):
files = []
for name, payload in blobs.items():
target = tmp_path / name
target.write_bytes(payload)
class _Entry(str):
def locate(self, _t = target):
return str(_t)
files.append(_Entry(f"torchcodec/{name}"))
monkeypatch.setattr(mod, "_torchcodec_distribution_for_probe", lambda: _Dist(files))
return mod._installed_torchcodec_cuda_major()
assert _probe({"libtorchcodec_cuda.so": b"\x00pad\x00libcudart.so.13\x00more"}) == "13"
assert _probe({"libtorchcodec_cuda.so": b"\x00libcudart.so.12\x00"}) == "12"
# Windows natives are .dll/.pyd; an .so-only filter skipped the NPP install.
assert _probe({"libtorchcodec_core7.dll": b"\x00cudart64_12.dll\x00"}) == "12"
assert _probe({"libtorchcodec_pybind_ops.pyd": b"cudart64_13.dll"}) == "13"
# The win cu130 wheel names no CUDA major; None keeps the tag-derived answer.
assert _probe({"libtorchcodec_core7.dll": b"\x00nvcudart_hybrid64.dll\x00nvcuda.dll"}) is None
# "" means needs no NPP, not unknown.
assert _probe({"libtorchcodec_core.so": b"nothing interesting here"}) == ""
assert _probe({"libtorchcodec_core7.dll": b"nothing interesting here"}) == ""
assert _probe({"version.txt": b"libcudart.so.12"}) is None
monkeypatch.setattr(mod, "_torchcodec_distribution_for_probe", lambda: None)
assert mod._installed_torchcodec_cuda_major() is None
def test_the_remedy_spells_the_variable_for_the_shell_it_will_be_pasted_into(monkeypatch):
"""PowerShell does not expand $NAME, so the POSIX spelling produced an empty --index-url.
The tests above ask _shell_env_ref; this pins the rule so that cannot become circular."""
fixes = _load_import_fixes_module()
monkeypatch.setattr(fixes.sys, "platform", "win32")
assert fixes._shell_env_ref("UNSLOTH_TORCH_INDEX_URL") == "$env:UNSLOTH_TORCH_INDEX_URL"
for platform in ("linux", "darwin"):
monkeypatch.setattr(fixes.sys, "platform", platform)
assert fixes._shell_env_ref("UNSLOTH_TORCH_INDEX_URL") == '"$UNSLOTH_TORCH_INDEX_URL"'
def test_a_query_authenticated_mirror_is_not_pinned_at_all(monkeypatch):
"""No URL shape pins a query-auth index; declining beats a broken one, since --index-url makes
_install_env_for_cmd strip pip.conf and ~/.netrc, the only credential channel."""
for base in ("https://mirror.example/whl?token=abc", "https://mirror.example/whl#tok"):
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", base)
mod = _reload_install_python_stack()
warnings = []
monkeypatch.setattr(mod, "_safe_print", warnings.append)
assert mod._torch_accelerator_index_url("2.13.0+cu130") is None, base
assert mod._torchcodec_index_url("2.13.0+cu130") is None, base
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")
assert mod._torch_accelerator_index_url("2.13.0") is None, base
assert mod._detect_cuda_torch_index_url() is None, base
assert mod._explicit_torch_index_url() is None, base
assert mod._explicit_torch_index_family() == "cu126", base
assert mod._explicit_unknown_family_torch_index_url() is None, base
assert len(warnings) == 1 and "netrc" in warnings[0], warnings
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")
monkeypatch.delenv("UNSLOTH_PYTORCH_MIRROR")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.example/simple?token=abc")
mod = _reload_install_python_stack()
assert mod._torch_accelerator_index_url("2.13.0+cu130") == (
"https://mirror.example/simple?token=abc"
)
def test_query_authenticated_mirror_repairs_decline_instead_of_falling_back(monkeypatch):
"""The eight repair/flavor paths must neither mangle the token nor leave the mirror."""
# Hidden CUDA returns before the mirror is read; index/backend pins pick another path.
for name in (
"CUDA_VISIBLE_DEVICES",
"UNSLOTH_TORCH_INDEX_URL",
"UNSLOTH_TORCH_INDEX_FAMILY",
"UNSLOTH_TORCH_INSTALL_INDEX_URL",
"UNSLOTH_TORCH_BACKEND",
"UNSLOTH_ROCM_TORCH_INSTALLED",
"UNSLOTH_FORCE_ROCM_TORCH",
):
monkeypatch.delenv(name, raising = False)
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.example/whl?token=abc")
mod = _reload_install_python_stack()
def unexpected(*_args, **_kwargs):
raise AssertionError("a query-authenticated mirror must not reach an install command")
monkeypatch.setattr(mod, "_nvidia_smi_path", lambda: None)
assert mod._detect_cuda_torch_index_url() is None
monkeypatch.setattr(mod, "IS_MACOS", False)
monkeypatch.setattr(mod, "IS_WINDOWS", False)
monkeypatch.setattr(mod, "NO_TORCH", False)
monkeypatch.setattr(mod, "_TORCH_BACKEND", "")
monkeypatch.setattr(mod, "_has_usable_nvidia_gpu", lambda: True)
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+rocm7.2", "7.2", ""),
)
monkeypatch.setattr(mod, "pip_install", unexpected)
assert mod._ensure_cuda_torch() is False
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu130")
assert mod._ensure_cuda_torch() is False
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")
monkeypatch.setattr(mod, "_explicit_xpu_torch_index_url", lambda: None)
monkeypatch.setattr(mod, "_installed_torch_version_label", lambda: "2.10.0+xpu")
monkeypatch.setattr(mod.subprocess, "run", unexpected)
mod._ensure_xpu_triton()
monkeypatch.setattr(mod, "_rocm_miscomputing_host", lambda: True)
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+rocm7.2", "7.2", ""),
)
assert mod._ensure_cpu_torch() is False
monkeypatch.setattr(mod, "_rocm_miscomputing_host", lambda: False)
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cpu")
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cu130", "", "13.0"),
)
assert mod._ensure_cpu_torch() is False
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cpu", "", ""),
)
assert mod._ensure_cpu_torch() is not False
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
assert source.count("if _ensure_cuda_torch() is False:") == 2
assert source.count("if _ensure_rocm_torch() is False:") == 2
assert source.count("if _ensure_xpu_torch() is False:") == 2
assert source.count("if _ensure_cpu_torch() is False:") == 2
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cpu", "", ""),
)
assert mod._expected_torch_index_url("cu130") is None
assert mod._ensure_expected_torch_flavor("cu130") is False
for family, expected in (("xpu", "xpu"), ("current", "cu130")):
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", family)
assert mod._explicit_unknown_family_torch_index_url() == ""
if family == "xpu":
assert mod._ensure_xpu_torch() is False
assert mod._ensure_expected_torch_flavor(expected) is False
def test_an_unusable_family_pin_records_resident_flavor_provenance(monkeypatch):
"""Later dependency steps may change torch even though this pin installs nothing."""
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.example/whl?token=abc")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu130")
mod = _reload_install_python_stack()
monkeypatch.setattr(mod, "_RECORDED_TORCH_TAG", "cu128")
monkeypatch.setattr(mod, "_RECORDED_TORCH_TAG_PINNED", True)
monkeypatch.setattr(mod, "_TORCH_BACKEND", "")
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cpu", "", ""),
)
assert mod._expected_torch_flavor_tag() == "cu130"
assert mod._recordable_torch_flavor_tag("cu130") == "cpu"
assert mod._expected_torch_flavor_was_pinned("cpu") is False
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "xpu")
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.10.0+xpu", "", ""),
)
assert mod._expected_torch_flavor_tag() == "xpu"
assert mod._recordable_torch_flavor_tag("xpu") == "xpu"
assert mod._expected_torch_flavor_was_pinned("xpu") is True
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "current")
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cu128", "", "12.8"),
)
assert mod._explicit_unknown_family_torch_index_url() == ""
assert mod._expected_torch_flavor_tag() == "cu128"
assert mod._recordable_torch_flavor_tag("") == "cu128"
assert mod._expected_torch_flavor_was_pinned("cu128") is True
monkeypatch.setattr(mod, "_RECORDED_TORCH_TAG", "cpu")
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cu130", "", "13.0"),
)
assert mod._expected_torch_flavor_tag() == "cpu"
assert mod._ensure_expected_torch_flavor() is False
monkeypatch.setattr(
mod,
"_probe_torch_runtime",
lambda: (True, True, "2.11.0+cpu", "", ""),
)
assert mod._ensure_expected_torch_flavor() is True
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
install = source.split("def install_python_stack(", 1)[1]
resident_check = install.index("not _resident_torch_flavor_tag()")
assert install.rindex("_repair_damaged_core_payload(", 0, resident_check) < resident_check
assert resident_check < install.index("install_manifest.write_manifest(")
def test_a_full_query_authenticated_torch_index_stays_verbatim(monkeypatch):
"""A complete index URL is usable because no leaf has to be appended to it."""
full = "https://mirror.example/whl/cu130?token=secret"
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.example/whl?token=base")
monkeypatch.setenv("UNSLOTH_TORCH_INSTALL_INDEX_URL", full)
mod = _reload_install_python_stack()
assert mod._expected_torch_index_url("cu130") == full
monkeypatch.delenv("UNSLOTH_TORCH_INSTALL_INDEX_URL")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", full)
assert mod._detect_cuda_torch_index_url() == full
assert mod._explicit_torch_index_url() == full
assert mod._explicit_torch_index_family() == "cu130"
def test_a_multi_segment_family_classifies_by_its_leaf(monkeypatch):
"""install.sh accepts FAMILY=nightly/cu128; it is a CUDA pin, not an unknown one."""
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "nightly/cu128")
mod = _reload_install_python_stack()
assert mod._explicit_torch_index_family() == "cu128"
assert mod._explicit_unknown_family_torch_index_url() is None
assert mod._explicit_cuda_torch_index_url() == f"{mod._PYTORCH_WHL_BASE}/nightly/cu128"
assert mod._detect_cuda_torch_index_url() == f"{mod._PYTORCH_WHL_BASE}/nightly/cu128"
assert mod._expected_torch_flavor_tag() == "cu128"
def test_every_pytorch_mirror_leaf_goes_through_the_guarded_helper():
"""A new direct concatenation would recreate #10516 on whichever path added it."""
source = (REPO_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
assert source.count('f"{_PYTORCH_WHL_BASE}/') == 1
helper = source.split("def _pytorch_whl_leaf_url", 1)[1].split("\ndef ", 1)[0]
assert 'f"{_PYTORCH_WHL_BASE}/{leaf}"' in helper
def test_an_explicit_family_is_honoured_when_torch_carries_no_tag(monkeypatch):
"""A mirror that rebuilds torch bare needs the explicit family; a None here is never corrected,
since a custom leaf is authoritative."""
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.example/whl")
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "current")
mod = _reload_install_python_stack()
assert mod._torch_accelerator_index_url("2.14.0") == "https://mirror.example/whl/current"
assert mod._torchcodec_index_url("2.14.0") == "https://mirror.example/whl/current"
assert mod._torch_accelerator_index_url("2.14.0+cu130") == (
"https://mirror.example/whl/current"
)
monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "xpu")
assert mod._torchcodec_index_url("2.14.0") == "https://mirror.example/whl/cpu"
def test_a_plain_mirror_is_still_joined_the_obvious_way(monkeypatch):
"""The join must not disturb the ordinary case, which is every host without a token."""
monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://mirror.example/whl")
mod = _reload_install_python_stack()
assert mod._torch_accelerator_index_url("2.13.0+cu130") == "https://mirror.example/whl/cu130"
monkeypatch.delenv("UNSLOTH_PYTORCH_MIRROR")
mod = _reload_install_python_stack()
assert mod._torch_accelerator_index_url("2.13.0+cu130") == (
"https://download.pytorch.org/whl/cu130"
)