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
Pin the accelerator index for torchao too, and let a starved index pin fall back (#10490)
Daniel Hanf3c339ce4c08
diff --git a/studio/backend/tests/test_torchao_select.py b/studio/backend/tests/test_torchao_select.pyindex 75466c2295e..c03dcf45e57 100644--- a/studio/backend/tests/test_torchao_select.py+++ b/studio/backend/tests/test_torchao_select.py@@ -51,10 +51,21 @@ def _load_module(monkeypatch):("2.10.0.dev20250804+cu130", "torchao==0.17.0"),("2.10.0.dev20250804+cu128", "torchao==0.16.0"),("2.10rc1", "torchao==0.16.0"),- # torch 2.11 (reachable via ROCm rocm7.2) and forward -> 0.17.0.+ # 2.11 -> 0.17.0, whose cpp is built for it.("2.11.0+cu130", "torchao==0.17.0"),("2.11.0", "torchao==0.17.0"),- ("2.12.0", "torchao==0.17.0"),+ ("2.11.1+cu126", "torchao==0.17.0"),+ # 2.12+ -> 0.18.0, whose release CI is pinned to 2.13. 0.17.0's upstream table stops+ # at 2.11, so leaving this range there ran it outside its declared window.+ ("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"),+ # The CUDA-13 branch belongs to 2.10 alone; it must not leak upward.+ ("2.12.0+cu126", "torchao==0.18.0"),+ ("2.12.0.dev20260801+cu132", "torchao==0.18.0"),# torch <=2.9 keeps today's pin (already a correct match for 2.9.0).("2.9.0+cu128", "torchao==0.14.0"),("2.9.1", "torchao==0.14.0"),@@ -87,6 +98,217 @@ def test_matching_torchao_pin_does_not_need_force_reinstall(monkeypatch):assert not mod._exact_distribution_spec_is_installed("torchao==0.16.0")+ "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):+ """torchao publishes a wheel per accelerator and PyPI's default is the CUDA-12 one, so+ an unpinned install puts a CUDA-12 cpp beside a CUDA-13 or ROCm torch. That is the+ `libcudart.so.12: cannot open shared object file` the 2.10 CUDA-13 row already dodges by+ picking a build whose cpp gets skipped instead."""+ 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)+++# torchao per leaf, from the live listings. Only leaves that do NOT cover every release this+# selector can ask for; everything absent serves its 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)),+}+++def test_the_index_pin_starves_only_where_the_retry_covers_it(monkeypatch):+ """A pin that could not be served would fail an install, because this step is fatal.++ Four cells cannot be served, and none of them is predictable from a rule: cu118 stops at+ torchao 0.11.0, rocm7.0 carries 0.16.0 alone, and cu129 has 0.14.1 where the 2.9 row asks+ for 0.14.0 exactly -- a hole in the MIDDLE of its range, which no floor could describe.+ All four resolve from the default index, which is where they came from before this step+ pinned anything, so the retry makes them identical to today rather than broken. Recording+ them here means a fifth cannot appear unnoticed.+ """+ 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 tops out at torchao 0.11.0, so every torch it serves wants more than it has.+ ("cu118", 5, "0.14.0"),+ ("cu118", 6, "0.14.0"),+ ("cu118", 7, "0.14.0"),+ # cu129 publishes 0.14.1, not 0.14.0, and stops at 0.17.0.+ ("cu129", 8, "0.14.0"),+ ("cu129", 9, "0.14.0"),+ ("cu129", 12, "0.18.0"),+ ("cu129", 13, "0.18.0"),+ # rocm7.0 publishes 0.16.0 alone, which is what its torch 2.10 row already wants.+ ("rocm7.0", 9, "0.14.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():+ """cu129 serves torch to 2.13 but stops at torchao 0.17.0, and a leaf added upstream+ after this ships can lag a release, so the pin must not be able to fail an install.+ Unlike torchcodec the retry stays FATAL if it also fails: torchao is not optional."""+ body = _torchao_installer_source()+ assert "index = _torch_accelerator_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")+++ "installed, spec, want_tag, expected",+ [+ # No index pinned: the wheel comes from the default index, which stamps no tag.+ ("0.18.0", "torchao==0.18.0", "<none>", False),+ # A tagged wheel on the unpinned path came from elsewhere, so it is replaced once,+ # then settles: what lands is bare.+ ("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: the release can be right while the BUILD is wrong. 0.18.0+cu126 satisfies+ # ==0.18.0, so pip fetches nothing and the wrong build stays.+ ("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 it is replaced: otherwise an untagged wheel+ # satisfies the pin and the mirror is never contacted.+ ("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 provenance tag has to come from the leaf the pin resolves to, not from the+ resident torch. With UNSLOTH_TORCH_INDEX_FAMILY=cu130 over a +cu128 venv the pin goes to+ cu130 while the old comparison asked for cu128, so an 0.18.0+cu128 wheel looked correct,+ pip found the requirement satisfied and the cu130 build was never fetched."""+ 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"))++ # An explicit URL is opaque, so nothing can prove where a wheel came from.+ monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/whl/cu130")+ assert mod._torch_index_tag("2.13.0+cu128") is None++ # And with no override at all the resident tag is still what is asked for.+ monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL")+ monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")+ assert mod._torch_index_tag("2.13.0+cu128") == "cu128"+++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+++def test_no_torchao_install_can_resolve_a_dependency():+ """Both call sites pass --no-deps, for the post-repair one: it runs right after step 13+ fixed the torch build. No torchao release declares a runtime torch dependency today, so+ this is hardening that must stay if one ever gains a pin."""+ 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():+ """Step 4 chooses torchao from the torch present BEFORE step 13's repairs, which move+ torch across families and releases. The explicit XPU pin is the sharp case: its spec is+ torch>=2.6,<2.11.0, so it necessarily lands below the 2.11 floor torchao 0.18.0 needs,+ leaving 0.18.0 beside torch 2.10. Only the Windows flavor repair reaches+ _resync_torch_coupled_packages, so on Linux nothing re-selected 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+ # The XPU repair really does land below the 0.18.0 floor.+ 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 requirementsdiff --git a/studio/install_python_stack.py b/studio/install_python_stack.pyindex 2ce5b24a68d..d27931e11f9 100644--- a/studio/install_python_stack.py+++ b/studio/install_python_stack.py@@ -301,20 +301,25 @@ _TORCH_FLAVOR_REPAIR_PKG_SPEC: tuple[str, str, str] = ("torchaudio>=2.4,<2.12.0",)-# torchao's cpp extensions are pinned to ONE torch release AND CUDA major. A torch-# mismatch just skips the cpp kernels (slow Python fallback); a CUDA mismatch fails-# to import ("libcudart.so.12: cannot open shared object file"). The torch pin is a-# range, so match torchao to the installed torch (table: pytorch/ao#2919):+# torchao's cpp is built for ONE torch release AND CUDA major. Either mismatch costs the+# kernels, never the import: torchao/__init__.py has caught the dlopen failure since 0.12 and+# import_fixes.py filters that warning. Match torchao to the installed torch (pytorch/ao#2919):# 2.9.x -> 0.14.0# 2.10.x, CUDA<=12 -> 0.16.0 (cpp built for 2.10, loads via the CUDA-12 wheel)# 2.10.x, CUDA>=13 -> 0.17.0 (cu130: 0.16.0's CUDA-12 cpp crashes on load; 0.17.0# targets torch 2.11 so its cpp is cleanly skipped, not crashed)-# 2.11.x -> 0.17.0 (reachable via CUDA or ROCm rocm7.2)+# 2.11.x -> 0.17.0 (cpp built for 2.11)+# 2.12.x and up -> 0.18.0 (dropped torch <2.11; release CI pinned to 2.13)# Unknown/older torch keeps the conservative default.+#+# The version alone is not enough: torchao ships per accelerator under /whl/<tag>, and PyPI's+# single default tracks whatever major PyTorch currently ships (13 as of 0.18.0), so it cannot+# be treated as a fixed fallback major. The caller pins the index to the resident torch._TORCHAO_DEFAULT_SPEC = "torchao==0.14.0"_TORCHAO_TORCH_210_SPEC = "torchao==0.16.0"_TORCHAO_TORCH_210_CUDA13_SPEC = "torchao==0.17.0"-_TORCHAO_TORCH_211_PLUS_SPEC = "torchao==0.17.0"+_TORCHAO_TORCH_211_SPEC = "torchao==0.17.0"+_TORCHAO_TORCH_212_PLUS_SPEC = "torchao==0.18.0"# torch 2.10 built against CUDA >= this major can't load 0.16.0's CUDA-12 cpp._TORCHAO_CUDA13_MIN_MAJOR = 13@@ -348,8 +353,10 @@ def _select_torchao_spec(torch_version: str | None) -> str:return _TORCHAO_DEFAULT_SPECif major != 2:return _TORCHAO_DEFAULT_SPEC- if minor >= 11:- return _TORCHAO_TORCH_211_PLUS_SPEC # newest known build; covers 2.11++ if minor >= 12:+ return _TORCHAO_TORCH_212_PLUS_SPEC # newest known build; covers 2.12++ if minor == 11:+ return _TORCHAO_TORCH_211_SPEC # 0.17.0's cpp is built for exactly this minorif minor == 10:# cu130+ can't load 0.16.0's CUDA-12 cpp; use 0.17.0 (cpp skipped, not crashed).cuda_major = _cuda_major_from_torch_version(str(torch_version))@@ -482,6 +489,10 @@ def _torchcodec_python_is_supported(# oldest venvs. They keep today's unpinned behavior._TORCHCODEC_MIN_ON_TORCH_INDEX = (0, 3, 0)+# torchcodec has no xpu build: the xpu leaf republishes cpu wheels, Linux x86_64 only, from+# 0.13 up, so xpu takes cpu. Unpinned is not an option -- PyPI's default is the CUDA build.+_TORCHCODEC_INDEX_TAGS = {"xpu": "cpu"}+def _cuda_major_for_npp(torch_version: "str | None", index_url: str) -> str:"""`"12"`, `"13"`, or `""` when this codec install needs no NPP runtime.@@ -502,39 +513,162 @@ def _cuda_major_for_npp(torch_version: "str | None", index_url: str) -> str:return match.group(1)[:2] if match else ""-def _torchcodec_index_url(torch_version: "str | None", spec: str = "") -> "str | None":- """The torchcodec index serving the resident torch's build, or None to stay unpinned.+# Any sign of the CUDA runtime, versioned or not: nvcudart_hybrid64.dll is the Windows cu130+# spelling and carries no major. Absent entirely from a cpu build, which is what makes "" safe.+_CUDA_RUNTIME_MARKER_RE = re.compile(+ rb"nvcuda\.dll|torch_cuda|nvcudart|libcudart|cudart64|libcuda\.so"+)+- torchcodec is published per accelerator exactly the way torch is: PyPI carries one- default flavor and the rest live at download.pytorch.org/whl/<tag>. Upstream's install- docs say to pass --index-url and "make sure to install the corresponding PyTorch version- as well", so a cu126 or cu128 venv that takes PyPI's default gets a codec built against a- different CUDA and libtorchcodec cannot dlopen. docker/Dockerfile already pins cu128 by- hand for this reason.+def _pytorch_whl_leaf_url(leaf: str) -> "str | None":+ """_PYTORCH_WHL_BASE plus an accelerator leaf, or None when it cannot be expressed.++ No URL shape pins a query-auth mirror -- pip joins the project name as text, so the token+ swallows either the leaf or the name (see _warn_query_index_unusable). Constructing one+ anyway is worse than declining: --index-url makes _install_env_for_cmd strip pip.conf and+ ~/.netrc, the only channel that can carry that credential.+ """+ if "?" in _PYTORCH_WHL_BASE or "#" in _PYTORCH_WHL_BASE:+ _warn_query_index_unusable(_PYTORCH_WHL_BASE)+ return None+ return f"{_PYTORCH_WHL_BASE}/{leaf}"+++def _torchcodec_distribution_for_probe():+ """The installed torchcodec distribution, or None when it cannot be read."""+ try:+ from importlib.metadata import PackageNotFoundError, distribution+ return distribution("torchcodec")+ except (PackageNotFoundError, ValueError, OSError):+ return None+++def _installed_torchcodec_cuda_major() -> "str | None":+ """The CUDA major the INSTALLED torchcodec links, "" when it links none, None when unknown.++ Only the unpinned fallback needs this: the default index carries whichever major PyTorch+ currently ships, not the resident torch's (PyPI's 0.16.0 links libcudart.so.13 while a+ +cu129 tag says 12), so it is read off the wheel rather than inferred.++ The three answers must stay distinct because "" SKIPS the NPP install. win_amd64 cu130+ names no major anywhere -- only nvcudart_hybrid64.dll -- so it is None, not "".+ """+ dist = _torchcodec_distribution_for_probe()+ if dist is None:+ return None+ files = list(getattr(dist, "files", None) or [])+ majors, saw_cuda, inspected = set(), False, False+ for entry in files:+ name = str(entry).lower()+ if not (name.endswith((".so", ".dll", ".pyd")) or ".so." in name):+ continue+ try:+ blob = Path(entry.locate()).read_bytes()+ except OSError:+ continue+ inspected = True+ majors |= {m.decode()[-2:] for m in re.findall(rb"libcudart\.so\.\d+", blob)}+ majors |= {m.decode()[9:11] for m in re.findall(rb"cudart64_\d+\.dll", blob)}+ saw_cuda = saw_cuda or bool(_CUDA_RUNTIME_MARKER_RE.search(blob))+ if not inspected:+ return None # nothing readable: say so rather than claim there is no CUDA+ if majors:+ return sorted(majors)[-1]+ # CUDA is clearly there but unversioned in the names, so the tag-derived answer stands.+ return None if saw_cuda else ""+++# Local tags a companion wheel is served under. xpu and rocmX.Y are here because those leaves+# really do carry companion builds; which a given package may use is that package's call.+_TORCH_ACCELERATOR_TAG_RE = re.compile(r"cpu|cu\d+|xpu|rocm\d+(\.\d+)?")+++def _torch_accelerator_index_url(+ torch_version: "str | None", substitutions: "dict[str, str] | None" = None+) -> "str | None":+ """The download.pytorch.org leaf serving the resident torch's build, or None.++ Companion wheels (torchcodec, torchao) are published per accelerator exactly the way+ torch is: PyPI carries one default flavor and the rest live under /whl/<tag>. The right+ version from the wrong index is a wheel whose cpp cannot dlopen against the resident+ CUDA or HIP runtime.Only an EXPLICIT local tag pins. An untagged torch is PyPI's own build, whose counterpart- is PyPI's default torchcodec -- already the right pairing. That is the opposite reading- from _torch_flavor_tag, which maps untagged to "cpu" for the Windows repair path; here an+ is PyPI's default wheel -- already the right pairing. That is the opposite reading from+ _torch_flavor_tag, which maps untagged to "cpu" for the Windows repair path; here anuntagged Linux torch is a CUDA build, so pinning cpu would install the wrong one.- rocm and xpu publish no torchcodec under that name, so they stay unpinned rather than- being sent to an index that cannot serve them."""if not torch_version:return None+ substitutions = substitutions or {}+ # Verbatim, and BEFORE the tag check: only download.pytorch.org stamps +cuNNN, so a+ # private mirror rebuilding torch ships it bare, and requiring a tag first sent exactly+ # that host to PyPI. Rewriting a leaf inside the URL would be a guess.+ url = os.environ.get("UNSLOTH_TORCH_INDEX_URL", "").strip()+ if url:+ return _trim_index_path_slashes(url)+ # Substitution still applies (FAMILY=xpu must not send torchcodec to a leaf with no codec+ # below 0.13). Before the tag check for the same reason as the URL, and because+ # _explicit_unknown_family_torch_index_url leaves such a torch alone: a None is final.+ family = os.environ.get("UNSLOTH_TORCH_INDEX_FAMILY", "").strip().strip("/")+ if family:+ return _pytorch_whl_leaf_url(substitutions.get(family.lower(), family))+ local = str(torch_version).partition("+")[2].strip().lower()+ if not _TORCH_ACCELERATOR_TAG_RE.fullmatch(local):+ return None+ return _pytorch_whl_leaf_url(substitutions.get(local, local))+++def _torchcodec_index_url(torch_version: "str | None", spec: str = "") -> "str | None":+ """The torchcodec index serving the resident torch's build, or None to stay unpinned.++ Upstream's install docs say to pass --index-url and "make sure to install the+ corresponding PyTorch version as well", so a cu126 or cu128 venv that takes PyPI's+ default gets a codec built against a different CUDA and libtorchcodec cannot dlopen.+ docker/Dockerfile already pins cu128 by hand for this reason.++ rocm is the one accelerator excluded: every rocm leaf answers 404/403 for torchcodec,+ so a pin there is a guaranteed wasted resolve. xpu is redirected to cpu, for the reason+ beside _TORCHCODEC_INDEX_TAGS. Where a pinned index turns out not to serve the selected+ window (cu129 has no 0.8 or 0.9), the caller's unpinned retry recovers; that is+ deliberate, because no local table of index CONTENTS stays true.+ """+ local = str(torch_version or "").partition("+")[2].strip().lower()+ if local.startswith("rocm"):+ return Noneif spec:_, ceiling = _torchcodec_spec_bounds(spec)if ceiling is not None and ceiling <= _TORCHCODEC_MIN_ON_TORCH_INDEX:return None # window sits entirely below what any torch index publishes- local = str(torch_version).partition("+")[2].strip().lower()- if local == "cpu" or re.fullmatch(r"cu\d+", local):- # An explicit pin wins, as it does for the torch repair helpers: synthesising the- # public URL from the local tag sent authenticated, corporate and air-gapped mirrors- # to download.pytorch.org, and the --index-url also makes _install_env_for_cmd drop- # the inherited index config, so the install fails outright there. _PYTORCH_WHL_BASE- # rather than a literal, since UNSLOTH_PYTORCH_MIRROR redirects every other index- # this module builds.- return _explicit_torch_index_url() or f"{_PYTORCH_WHL_BASE}/{local}"- return None+ return _torch_accelerator_index_url(torch_version, _TORCHCODEC_INDEX_TAGS)+++def _torch_index_tag(+ torch_version: "str | None", substitutions: "dict[str, str] | None" = None+) -> "str | None":+ """The local tag of the build the index pin will fetch, or None when unknowable.++ NOT always the resident torch's own tag: a FAMILY override names a leaf of its own, and+ a per-package substitution can redirect one (xpu takes the cpu codec). Provenance checks+ compare against this, so it has to be derived the same way the URL is, or a pin to one+ leaf gets validated against another leaf's tag and never fires.++ None means an explicit UNSLOTH_TORCH_INDEX_URL is in play. That URL is opaque -- it can+ be an accelerator-specific private mirror -- so nothing here can say which build it+ serves. Callers must treat that as "cannot prove the installed wheel came from there"+ and replace, not as "no tag required": an untagged wheel already satisfies the version,+ so pip would fetch nothing and the mirror would never be reached.+ """+ if os.environ.get("UNSLOTH_TORCH_INDEX_URL", "").strip():+ return None+ substitutions = substitutions or {}+ family = os.environ.get("UNSLOTH_TORCH_INDEX_FAMILY", "").strip().strip("/").lower()+ local = family or str(torch_version or "").partition("+")[2].strip().lower()+ return substitutions.get(local, local)+++def _torchcodec_index_tag(torch_version: "str | None") -> "str | None":+ return _torch_index_tag(torch_version, _TORCHCODEC_INDEX_TAGS)def _torchcodec_spec_bounds(spec: str) -> "tuple[tuple[int, ...], tuple[int, ...] | None]":@@ -728,6 +862,32 @@ def _exact_distribution_spec_is_installed(spec: str) -> bool:return installed is not None and installed == match.group(2)+def _pin_needs_reinstall(spec: str, want_tag: "str | None" = "") -> bool:+ """Whether a ``name==version`` pin has to be forced over what is already installed.++ Two reasons, and the second only exists once an index is pinned. The version can be+ wrong, which _exact_distribution_spec_is_installed already answers. Or the version can+ be RIGHT while the build is wrong: an accelerator index stamps its tag into the local+ version (``0.18.0+cu130``) and PyPI forbids one, so a wheel already inside the pin+ satisfies pip, nothing is fetched, and the wrong-accelerator build this pin exists to+ replace stays put.++ want_tag is the tag the pin will FETCH (_torch_index_tag), not the resident torch's,+ which a FAMILY override can differ from. "" is the unpinned case: the default index stamps+ no tag, so a tagged wheel there came from elsewhere and is replaced once, then settles.+ None is an opaque mirror, where provenance is unprovable, so it is replaced every time.+ """+ match = re.fullmatch(r"([A-Za-z0-9][A-Za-z0-9._-]*)==([^\s]+)", spec)+ if match is None:+ return False+ installed = _installed_distribution_version(match.group(1))+ if installed is None:+ return True # absent; kept True so the flag matches what this step passed before+ if installed.partition("+")[0] != match.group(2).partition("+")[0]:+ return True+ return installed.partition("+")[2].strip().lower() != want_tag++def _installed_torch_is_windows_rocm() -> bool:"""Return True when the target venv currently has a Windows ROCm torch build.@@ -4207,6 +4367,40 @@ def _resident_xformers_build_torch() -> "str | None":return recorded.strip() if isinstance(recorded, str) and recorded.strip() else None+def _install_torchao_for_torch(torch_version: "str | None") -> None:+ """Select the torchao matching torch_version and install it from its own index.++ Called twice: as step 4, and again after the Linux torch repair, which can move torch+ across families and releases underneath the first call.+ """+ spec = _select_torchao_spec(torch_version)+ # See _TORCHAO_DEFAULT_SPEC. rocm is included here, unlike torchcodec: the rocm leaves+ # really do publish torchao.+ index = _torch_accelerator_index_url(torch_version)+ # --no-deps skips nothing today (no torchao release declares a runtime torch dependency)+ # and guards the second caller, which runs right after the torch repair.+ args = ["--no-deps", "--no-cache-dir"]+ if _pin_needs_reinstall(spec, _torch_index_tag(torch_version) if index else ""):+ args.insert(0, "--force-reinstall")+ _note(+ f"torch {torch_version or 'unknown'} detected -- installing {spec}"+ # Redacted for display only; the installer below still gets the exact URL.+ + (f" from {_strip_index_url_credentials(index)}" if index else "")+ )+ if not index:+ pip_install("Installing dependency overrides", *args, spec)+ return+ if pip_install_try("Installing dependency overrides", *args, "--index-url", index, spec):+ return+ # A leaf can lack this release outright (cu129 stops at 0.17.0 while serving torch 2.13),+ # and the wrong build only costs the kernels, so retry unpinned -- still fatally.+ _note(+ f"{_strip_index_url_credentials(index)} did not serve {spec} "+ "-- retrying from the default index; its kernels may be skipped"+ )+ pip_install("Installing dependency overrides", *args, spec)++def _resync_torch_coupled_packages(label_before: str) -> bool:"""Re-settle the packages whose compiled extensions are tied to the torch build.@@ -4223,24 +4417,39 @@ def _resync_torch_coupled_packages(label_before: str) -> bool:if not _label_after or _label_after == label_before:return True_touched_torch = False- # Release OR CUDA major: cu124 to cu130 at one release still changes the build.+ # The whole local tag, not just the CUDA major: cpu to xpu moves no major at all (both+ # read None) yet still changes the build._release_moved = _label_after.split("+", 1)[0] != str(label_before).split("+", 1)[0]+ _family_moved = _label_after.partition("+")[2].strip().lower() != (+ str(label_before).partition("+")[2].strip().lower()+ )_cuda_moved = _cuda_major_from_torch_version(_label_after) != (_cuda_major_from_torch_version(str(label_before)))- if _release_moved or _cuda_moved:+ if _release_moved or _family_moved or _cuda_moved:try:_spec = _select_torchao_spec(_label_after)- if not _exact_distribution_spec_is_installed(_spec):+ # The same pin step 4 uses, or this reinstalls PyPI's build over it.+ # _pin_needs_reinstall, not an exact compare: ==0.18.0 never equals 0.18.0+cu130.+ _ao_index = _torch_accelerator_index_url(_label_after)+ _ao_args = ["--force-reinstall", "--no-deps", "--no-cache-dir"]+ if _pin_needs_reinstall(+ _spec, _torch_index_tag(_label_after) if _ao_index else ""+ ):_note(f"torch {_label_after} after repair -- reinstalling {_spec}")_touched_torch = True- if not pip_install_try(+ _ao_ok = pip_install_try("Re-matching torchao to the repaired torch",- "--force-reinstall",- "--no-deps",- "--no-cache-dir",+ *_ao_args,+ *(("--index-url", _ao_index) if _ao_index else ()),_spec,- ):+ )+ if not _ao_ok and _ao_index:+ # Same starved-leaf fallback as step 4; see the note there.+ _ao_ok = pip_install_try(+ "Re-matching torchao to the repaired torch", *_ao_args, _spec+ )+ if not _ao_ok:# Across a CUDA-major move the resident build is not merely slower:# _select_torchao_spec exists because a torchao compiled for CUDA 12# cannot load its cpp under cu130. Remove it, the way the xFormers arm@@ -7656,17 +7865,7 @@ def install_python_stack() -> int:_note("Windows ROCm -- skipping torchao (no working build; stubbed at runtime)")else:_progress("dependency overrides")- _torch_ver = _probe_installed_torch_version()- _torchao_spec = _select_torchao_spec(_torch_ver)- _note(f"torch {_torch_ver or 'unknown'} detected -- installing {_torchao_spec}")- _torchao_args = ["--no-cache-dir"]- if not _exact_distribution_spec_is_installed(_torchao_spec):- _torchao_args.insert(0, "--force-reinstall")- pip_install(- "Installing dependency overrides",- *_torchao_args,- _torchao_spec,- )+ _install_torchao_for_torch(_probe_installed_torch_version())# 5. Triton kernels (no-deps, from source). Skipped on Windows/macOS (no support)# and without git (the requirement is a git+https URL); a training speedup@@ -7781,6 +7980,7 @@ def install_python_stack() -> int:torch_flavor_tag = ""if not IS_WINDOWS and not IS_MACOS and not NO_TORCH:_progress(_torch_step_label("final"))+ _torch_before_repair = str(_probe_installed_torch_version() or "")_ensure_cuda_torch()_ensure_rocm_torch()_ensure_xpu_torch()@@ -7788,6 +7988,17 @@ def install_python_stack() -> int:# Last, after every torch migration: the swap keys off the installed +xpu label, so a# CPU pin over an XPU venv would leave XPU triton under a CPU torch._ensure_xpu_triton()+ # Step 4 chose torchao from the torch these repairs then moved. The XPU pin is the+ # sharp case: torch>=2.6,<2.11.0 lands below torchao 0.18.0's 2.11 floor. Only the+ # Windows repair reaches _resync_torch_coupled_packages, so on Linux nothing+ # re-selected it (#10493).+ _torch_after_repair = str(_probe_installed_torch_version() or "")+ if _torch_after_repair and _torch_after_repair != _torch_before_repair:+ _note(+ f"torch moved from {_torch_before_repair or 'unknown'} to "+ f"{_torch_after_repair} during the repair -- re-selecting torchao"+ )+ _install_torchao_for_torch(_torch_after_repair)# 13w. Windows torch flavor invariant, separate from step 13's Linux-shaped repair set# but in the same position: last, after the with-deps steps re-resolved torch.@@ -7848,8 +8059,12 @@ def install_python_stack() -> int:# from the version: the torch indexes carry a +cuNNN / +cpu local tag and PyPI# forbids one, so a local tag that is missing or different means another build._codec_have = _installed_distribution_version("torchcodec") or ""- _codec_want = str(_codec_torch_ver).partition("+")[2].strip().lower()- if _codec_have and _codec_have.partition("+")[2].strip().lower() != _codec_want:+ # The tag the PIN will fetch, not the resident torch's: an xpu torch is served+ # the cpu wheel, so comparing against "xpu" would force-reinstall every run.+ _codec_want = _torchcodec_index_tag(_codec_torch_ver)+ if _codec_have and (+ _codec_want is None or _codec_have.partition("+")[2].strip().lower() != _codec_want+ ):_codec_args += ("--force-reinstall",)_codec_rebuild = True_safe_print(@@ -7866,23 +8081,53 @@ def install_python_stack() -> int:# install inverts the rule the extras-no-deps filter above exists to enforce, and# the index can refuse for reasons no local table predicts -- a yanked release, an# offline mirror, a platform tag added or dropped upstream after this shipped.- if not pip_install_try(- "Installing torchcodec",- *_codec_args,- _codec_spec,- ):+ _codec_ok = pip_install_try("Installing torchcodec", *_codec_args, _codec_spec)+ _codec_fellback = False+ if not _codec_ok and _codec_index:+ # The leaf may not carry this window at all: cu129 serves torch 2.8-2.13 but+ # publishes no 0.8 or 0.9. Retry unpinned rather than table what each index+ # holds, which is what goes stale. _torchcodec_provenance_hint explains at+ # import if that lands another accelerator's build.+ _note(+ f"{_strip_index_url_credentials(_codec_index)} did not serve {_codec_spec} "+ "-- retrying from the default index"+ )+ # Drop only the pin: --force-reinstall must survive, or pip calls the requirement+ # satisfied and leaves the wrong-accelerator wheel in place.+ _codec_retry_args = [+ a+ for i, a in enumerate(_codec_args)+ if a != "--index-url" and _codec_args[i - 1] != "--index-url"+ ]+ # _codec_index stays set: PyPI's wheel is still a CUDA build on Linux, so the+ # NPP step below still applies.+ _codec_ok = pip_install_try("Installing torchcodec", *_codec_retry_args, _codec_spec)+ _codec_fellback = _codec_ok+ if not _codec_ok:_note(f"could not install {_codec_spec} -- audio decoding stays disabled, ""the rest of the install is unaffected")- elif _codec_index and _cuda_major_for_npp(_codec_torch_ver, _codec_index):+ elif _codec_index:# 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, disabling audio for a reason nothing here# would otherwise name. docker/Dockerfile installs nvidia-npp-cu12 beside the# same wheel for exactly this. cu13x wheels want nvidia-npp-cu13._npp_major = _cuda_major_for_npp(_codec_torch_ver, _codec_index)- if not pip_install_try(+ if _codec_fellback:+ # The pin is gone, so the tag no longer describes this wheel. Probe EVERY+ # fallback, including tags implying no CUDA: an xpu host takes the cpu leaf+ # and still lands PyPI's CUDA build, needing NPP its tag never mentioned.+ _npp_probed = _installed_torchcodec_cuda_major()+ if _npp_probed is not None and _npp_probed != _npp_major:+ _note(+ f"the unpinned torchcodec links CUDA {_npp_probed or 'nothing'} "+ f"rather than {'CUDA ' + _npp_major if _npp_major else 'nothing'}, "+ "which its torch tag implies -- matching NPP to the wheel"+ )+ _npp_major = _npp_probed+ if _npp_major and not pip_install_try("Installing torchcodec CUDA runtime (NPP)","--no-cache-dir",f"nvidia-npp-cu{_npp_major}",diff --git a/tests/python/test_torchcodec_torch_compat.py b/tests/python/test_torchcodec_torch_compat.pyindex 7e2df0cc5e3..d51d81d7ab0 100644--- a/tests/python/test_torchcodec_torch_compat.py+++ b/tests/python/test_torchcodec_torch_compat.py@@ -31,8 +31,7 @@ def _tomllib():@pytest.fixture(autouse = True)def _no_inherited_index_config(monkeypatch):- """Nearly every test here reads the index configuration, so a developer's own- UNSLOTH_TORCH_INDEX_URL must not be what decides which URL the suite asserts."""+ """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",@@ -179,6 +178,19 @@ def _load_install_python_stack():return install_python_stack+def _reload_install_python_stack():+ """A private instance: _PYTORCH_WHL_BASE is read from the environment at import, so the+ cached module answers with whatever was set on first 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)@@ -298,14 +310,17 @@ _UPSTREAM_TORCH_TO_TORCHCODEC_MINORS = {# What each download.pytorch.org index actually publishes, read off the live listings:-# the torch 2.x minors it serves, and the inclusive range of torchcodec minors.-# Note cu130 starts at codec 0.8, and no index carries 0.1 or 0.2 -- those are PyPI-only.+# the torch 2.x minors it serves and the torchcodec minors it carries. Explicit minors, not+# ranges: the inventory is not contiguous (cu129 skips 0.8, 0.9 and 0.12-0.14)._INDEX_INVENTORY = {- "cpu": {"torch": range(5, 15), "codec": (3, 16)},- "cu118": {"torch": range(5, 8), "codec": (3, 5)},- "cu126": {"torch": range(6, 15), "codec": (3, 16)},- "cu128": {"torch": range(7, 12), "codec": (3, 11)},- "cu130": {"torch": range(9, 15), "codec": (8, 16)},+ "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))},+ # xpu is not listed: an xpu torch is pinned to the cpu leaf, which is covered above.}@@ -320,49 +335,183 @@ def test_torchcodec_index_follows_the_resident_torch_build():assert ips._torchcodec_index_url("2.14.0+cu130") == base + "cu130"assert ips._torchcodec_index_url("2.11.0+cpu") == base + "cpu"+ # xpu is sent to cpu: no xpu codec build exists, and PyPI's default is the CUDA one.+ assert ips._torchcodec_index_url("2.14.0+xpu") == base + "cpu"+ assert ips._torchcodec_index_url("2.9.0+xpu") == base + "cpu"+# Untagged is PyPI's own torch, whose counterpart is PyPI's default torchcodec. Pinning# cpu here would be wrong: on Linux an untagged torch is a CUDA build.assert ips._torchcodec_index_url("2.11.0") is None- # No torchcodec is published under these, so unpinned beats an index that cannot serve.+ # Every rocm leaf answers 404/403 for torchcodec, so a pin there cannot ever serve.assert ips._torchcodec_index_url("2.9.0+rocm6.4") is None- assert ips._torchcodec_index_url("2.10.0+xpu") is None+ assert ips._torchcodec_index_url("2.11.0+rocm7.2") is Noneassert ips._torchcodec_index_url(None) is Noneassert ips._torchcodec_index_url("") is None-def test_pinning_the_index_never_starves_a_reachable_torch():- """A pin that removed audio from a supported host would trade one bug for another.-- Every torch build that pins must find its selected codec on that same index. This holds- because torch and torchcodec are cut together: cu128 stops at torch 2.11 and its- torchcodec stops at 0.11, the exact pair the matrix maps 2.11 to; cu130 starts at torch- 2.9 and its torchcodec starts at 0.8, the pair for 2.9.-- The one gap is deliberate and handled in the helper rather than here: no index carries- torchcodec 0.1 or 0.2, so torch 2.5 and 2.6 must not pin at all.- """+def _starved_index_cells():+ """Every (tag, torch minor) whose pinned index publishes nothing in the window."""from packaging.specifiers import SpecifierSetips = _load_install_python_stack()+ starved = []for tag, inv in _INDEX_INVENTORY.items():- low, high = inv["codec"]for minor in inv["torch"]:version = f"2.{minor}.0+{tag}"spec = ips._select_torchcodec_spec(version)- specifier = SpecifierSet(spec.split("torchcodec", 1)[1])- served = [f"0.{m}.0" for m in range(low, high + 1) if specifier.contains(f"0.{m}.0")]index = ips._torchcodec_index_url(version, spec)if index is None:- # Only the PyPI-only rows may decline to pin.- assert minor in (5, 6), f"torch 2.{minor}+{tag} unexpectedly refused to pin"continue- assert index.endswith("/" + tag)- assert served, (- f"torch 2.{minor} pins the {tag} index and selects {spec}, but that index "- f"publishes only torchcodec 0.{low}-0.{high}"+ 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():+ """A pin that removed audio from a supported host would trade one bug for another.++ Mostly the pin cannot starve, because torch and torchcodec are cut together: cu128 stops+ at torch 2.11 and its torchcodec stops at 0.11, the exact pair the matrix maps 2.11 to.+ But cu129 serves torch 2.8 to 2.13 while publishing no torchcodec 0.8 or 0.9, so torch+ 2.9 there selects a window that index has nothing in, and cu132 and xpu start above the+ lines the older torch minors select.++ The answer is not a table of index contents -- that is what goes stale, and cu132 did not+ exist when this file was written -- so the installer retries unpinned, which is what such+ a host got before any of this pinned anything. This test pins down which cells rely on+ that retry, so a new one cannot appear unnoticed, and the test below proves the retry is+ really there.+ """+ starved = {(tag, minor) for tag, minor, _ in _starved_index_cells()}+ # The one cell no floor could predict: cu129's gap is in the MIDDLE of its range.+ 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+ # The retry drops the pin and NOTHING else: --no-deps stops a re-resolve undoing the+ # repair two steps above, and --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 at all. The xpu leaf republishes the CPU wheels verbatim+ (`torchcodec-0.16.0+cpu-...`) and only for Linux x86_64, whereas the cpu leaf carries the+ same wheel for aarch64 and Windows too and goes back to 0.3 rather than starting at 0.13.+ So every Intel-GPU torch is served, not just the newest."""+ 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+ # The substitution is per tag, not a blanket fallback: cu126 still pins its own leaf.+ assert ips._torchcodec_index_url("2.9.0+cu126", ips._select_torchcodec_spec("2.9.0")) == (+ "https://download.pytorch.org/whl/cu126"+ )+ # torchao is unaffected: its xpu leaf really does carry +xpu builds.+ 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 names a leaf under our own base, so the xpu-to-cpu+ substitution has to apply to it as well. Without that, setting the family to xpu sent+ the codec to the xpu leaf, which publishes nothing below 0.13, and the retry then+ installed PyPI's CUDA build -- exactly the case the substitution exists to avoid.++ A full UNSLOTH_TORCH_INDEX_URL is different and is taken verbatim: its path belongs to+ whoever configured the mirror, and rewriting a leaf inside it would be a guess."""+ 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"+ # torchao has no substitution, so its own leaf is unchanged by the same override.+ assert ips._torch_accelerator_index_url("2.14.0+xpu") == base + "xpu"++ # A family with no substitution passes straight through.+ 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: reporting absent let+ # an untagged wheel compare equal and the mirror was never contacted.+ 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():+ """The fallback installs PyPI's torchao, which is the CUDA-12 build. That is harmless+ wherever its cpp is skipped or the host is CUDA 12, and every starved cell today is one+ of those. It would NOT be harmless on a CUDA-13 leaf whose torch matches the selected+ release, so this fails if such a cell ever appears."""+ ips = _load_install_python_stack()+ # torchao releases each CUDA-13 leaf carries, and the torch minors it serves, read off+ # the live listings. A leaf is only reachable for the torch it actually publishes.+ 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():+ """The step force-reinstalls when the installed codec's local tag says another index+ built it. That tag has to be the one the PIN fetches, not the resident torch's own: an+ xpu torch is served a `+cpu` wheel, so comparing against `xpu` never matches and every+ run would force-reinstall a codec that was already right."""+ 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+ # The old spelling read the torch tag straight off the version string.+ assert '_codec_want = str(_codec_torch_ver).partition("+")' not in step+ # An unknown tag has to force, not compare equal to an untagged wheel.+ assert "_codec_want is None" in step+++def test_an_opaque_mirror_replaces_a_codec_it_cannot_vouch_for(monkeypatch):+ """UNSLOTH_TORCH_INDEX_URL can be an accelerator-specific private mirror, and nothing+ here can tell which build it serves. Reporting that as "no tag required" let an+ installed untagged wheel -- PyPI's CUDA build -- compare equal and satisfy the version+ range, so pip fetched nothing and the mirror was never reached."""+ 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 torch2.5 / 2.6 would guarantee a skip on the oldest venvs instead of leaving them as they are."""@@ -830,8 +979,9 @@ def test_the_codec_index_honours_an_explicitly_pinned_torch_mirror(monkeypatch):monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")assert ips._torchcodec_index_url("2.11.0+cu128") == "https://download.pytorch.org/whl/cu126"- # The override does not make an untagged or rocm torch start pinning.- assert ips._torchcodec_index_url("2.11.0") is None+ # An explicit family DOES make an untagged torch pin: a private mirror ships torch bare,+ # and naming the family is how it says which leaf. rocm still never pins a codec.+ 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@@ -855,7 +1005,7 @@ def test_the_runtime_remedy_honours_a_configured_torch_index(monkeypatch):"UNSLOTH_TORCH_INDEX_URL", "https://user:[email protected]/pytorch/cu128/")hint = fixes._torchcodec_version_mismatch_hint()- assert '--index-url "$UNSLOTH_TORCH_INDEX_URL" ' in hint+ assert f'--index-url {fixes._shell_env_ref("UNSLOTH_TORCH_INDEX_URL")} ' in hintassert "secret" not in hintassert "mirror.corp.example" not in hintassert "download.pytorch.org" not in hint@@ -954,13 +1104,13 @@ def test_the_runtime_remedy_follows_a_configured_pytorch_mirror(monkeypatch):monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", "https://user:[email protected]/whl")hint = fixes._torchcodec_version_mismatch_hint()- assert '--index-url "$UNSLOTH_PYTORCH_MIRROR"/cu128' in hint+ assert f'--index-url {fixes._shell_env_ref("UNSLOTH_PYTORCH_MIRROR")}/cu128' in hintassert "secret" not in hintassert "download.pytorch.org" not in hint# The family names the leaf under the same mirror.monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")- assert '--index-url "$UNSLOTH_PYTORCH_MIRROR"/cu126' in (+ assert f'--index-url {fixes._shell_env_ref("UNSLOTH_PYTORCH_MIRROR")}/cu126' in (fixes._torchcodec_version_mismatch_hint() or "")@@ -1003,7 +1153,7 @@ def test_the_remedy_uses_the_shell_of_the_host_it_prints_on(monkeypatch):monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://user:[email protected]/cu128")monkeypatch.setattr(fixes.sys, "platform", "linux")- assert '--index-url "$UNSLOTH_TORCH_INDEX_URL"' in (+ assert f'--index-url {fixes._shell_env_ref("UNSLOTH_TORCH_INDEX_URL")}' in (fixes._torchcodec_version_mismatch_hint() or "")@@ -1128,3 +1278,139 @@ def test_the_provenance_hint_reads_a_codec_it_cannot_import(monkeypatch):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"+ # torchcodec keeps its own two refusals, which are about the WHEEL not existing rather+ # than about where to look: rocm publishes no torchcodec under any index.+ 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"+ # No torch at all still means no companion pin.+ assert mod._torch_accelerator_index_url(None) is None+ assert mod._torch_accelerator_index_url("") is None+ # And provenance stays unknowable through an opaque mirror, so the wheel is replaced.+ 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):+ """torchcodec 0.16.0 links libcudart.so.13 on PyPI and .12 on the cu126 leaf, so the NPP+ choice reads the wheel rather than 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 spells both the file and the major differently. Its natives are .dll/.pyd, so+ # an .so-only filter inspected nothing, found no major, and returned "" -- which SKIPS+ # the NPP install and leaves audio broken on a host with no system toolkit.+ assert _probe({"libtorchcodec_core7.dll": b"\x00cudart64_12.dll\x00"}) == "12"+ assert _probe({"libtorchcodec_pybind_ops.pyd": b"cudart64_13.dll"}) == "13"+ # The win_amd64 cu130 wheel names no major at all: it references nvcudart_hybrid64.dll.+ # CUDA is plainly there, so "" would be a lie; None keeps the tag-derived answer.+ assert _probe({"libtorchcodec_core7.dll": b"\x00nvcudart_hybrid64.dll\x00nvcuda.dll"}) is None+ # A cpu build links no CUDA runtime at all: "" means "needs no NPP", not "unknown".+ # Checked against the real 0.16.0 cpu wheels, x86_64 and win_amd64: neither carries any+ # CUDA reference.+ assert _probe({"libtorchcodec_core.so": b"nothing interesting here"}) == ""+ assert _probe({"libtorchcodec_core7.dll": b"nothing interesting here"}) == ""+ # Nothing native to read is "cannot tell", not "no CUDA": a stray text file mentioning a+ # major must neither be believed nor counted as an inspection.+ assert _probe({"version.txt": b"libcudart.so.12"}) is None+ # Absent entirely: None, which the caller reads as "keep the tag-derived answer".+ 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, and building a broken one is worse than+ declining: --index-url makes _install_env_for_cmd strip pip.conf and ~/.netrc, the only+ channel that can carry that credential."""+ 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()+ 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+ # The FAMILY override reaches the same base, so it declines the same way.+ monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu126")+ assert mod._torch_accelerator_index_url("2.13.0") is None, base+ monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")+ # An explicit full UNSLOTH_TORCH_INDEX_URL is still taken verbatim: that is the user+ # naming one exact index rather than a base this code appends a leaf to.+ 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_an_explicit_family_is_honoured_when_torch_carries_no_tag(monkeypatch):+ """As explicit as the full URL, and needed by the same host: a mirror that rebuilds torch+ bare. _explicit_unknown_family_torch_index_url treats a custom leaf as authoritative, so a+ None here is never corrected later."""+ 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"+ # A tagged torch is unaffected: the family still wins, as it did before.+ assert mod._torch_accelerator_index_url("2.14.0+cu130") == (+ "https://mirror.example/whl/current"+ )+ # And the per-package substitution still applies to the override.+ 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"+ )diff --git a/tests/studio/install/test_cuda_repair.py b/tests/studio/install/test_cuda_repair.pyindex a8454e742bf..aa868f2f9e6 100644--- a/tests/studio/install/test_cuda_repair.py+++ b/tests/studio/install/test_cuda_repair.py@@ -1593,10 +1593,19 @@ class TestThePackagesTiedToTheTorchReleaseAreResettled:with (patch.object(stack_mod, "_probe_installed_torch_version", return_value = after),+ # The resync asks _pin_needs_reinstall, which reads the installed version and+ # compares its local tag against the index it is about to pin. So "already+ # matching" means the exact wheel that pin would fetch, tag included -- an+ # untagged 0.16.0 beside a cu130 pin is precisely the case it must NOT skip.patch.object(stack_mod,- "_exact_distribution_spec_is_installed",- return_value = installed_spec,+ "_installed_distribution_version",+ side_effect = lambda name: (+ stack_mod._select_torchao_spec(after).split("==", 1)[1]+ + ("+" + after.partition("+")[2] if after.partition("+")[2] else "")+ if (installed_spec and name == "torchao")+ else None+ ),),patch.object(stack_mod,@@ -1634,19 +1643,33 @@ class TestThePackagesTiedToTheTorchReleaseAreResettled:assert calls["torchao"], "the CUDA major moved, so the pin has to be re-selected"assert any("torchao==0.17.0" in " ".join(c) for c in calls["torchao"])- def test_a_flavor_change_within_one_cuda_major_leaves_torchao_alone(self):+ def test_a_flavor_change_within_one_cuda_major_re_pins_torchao(self):+ """A no-op while every host took PyPI's one build; different wheels now that the+ install is pinned to the leaf matching torch."""calls = self._resync("2.10.0+cu124", "2.10.0+cu128")- assert calls["torchao"] == []+ assert calls["torchao"], "the leaf moved, so the pinned build has to be re-selected"+ assert any("cu128" in " ".join(c) for c in calls["torchao"]), calls["torchao"]++ def test_a_cpu_to_xpu_move_re_pins_torchao(self):+ """Neither side names a CUDA major, so None == None skipped the resync entirely."""+ calls = self._resync("2.10.0+cpu", "2.10.0+xpu")+ assert calls["torchao"], "cpu to xpu changes the build even at one release"+ assert any("/xpu" in " ".join(c) for c in calls["torchao"]), calls["torchao"]++ def test_a_build_that_kept_its_leaf_is_still_left_alone(self):+ """The widened test must not have become "always re-pin"."""+ assert self._resync("2.10.0+cu128", "2.10.0+cu128")["torchao"] == []+ assert self._resync("2.10.0", "2.10.0")["torchao"] == []def test_a_flavor_change_alone_still_rechecks_xformers(self):# xFormers links against the exact (torch, CUDA) pair.calls = self._resync("2.10.0+cu124", "2.10.0+cu128", resident_xformers = "2.10.0+cu124")- assert calls["torchao"] == [], "the release did not move; torchao is fine"assert calls["removed"] == ["xformers"]- assert calls["ok"] is True, "nothing here touched torch"+ assert calls["ok"] is False, "re-pinning torchao asks for a re-verify, as anywhere else"def test_the_torchao_reinstall_cannot_drag_torch_back(self):- # torchao depends on torch: resolving deps re-pulls the wheel just removed.+ # No torchao release declares a runtime torch dependency, but a reinstall right after+ # a repair is where one would undo it.calls = self._resync("2.11.0+cu124", "2.10.0+cu124")assert calls["torchao"], "the release moved, so torchao is re-pinned"assert all("--no-deps" in c for c in calls["torchao"])diff --git a/tests/studio/install/test_windows_torch_flavor_invariant.py b/tests/studio/install/test_windows_torch_flavor_invariant.pyindex 3f0b27a8a3a..7e064dc3dc2 100644--- a/tests/studio/install/test_windows_torch_flavor_invariant.py+++ b/tests/studio/install/test_windows_torch_flavor_invariant.py@@ -277,16 +277,26 @@ class TestStepThirteenWiring:"not IS_MACOS and (not NO_TORCH)","not IS_WINDOWS and (not IS_MACOS) and (not NO_TORCH)",]+ repairs = [+ "_ensure_cuda_torch",+ "_ensure_rocm_torch",+ "_ensure_xpu_torch",+ "_ensure_cpu_torch",+ "_ensure_xpu_triton",+ ]for guard in guards:- assert _calls_in(guard) == [- "_progress",- "_torch_step_label",- "_ensure_cuda_torch",- "_ensure_rocm_torch",- "_ensure_xpu_torch",- "_ensure_cpu_torch",- "_ensure_xpu_triton",- ]+ calls = _calls_in(guard)+ assert [c for c in calls if c in repairs] == repairs+ assert calls[:2] == ["_progress", "_torch_step_label"]+ # str() is the label coercion around the probe, not a step.+ step13 = [c for c in _calls_in(guards[1]) if c != "str"]+ # Step 13 also re-selects torchao when a repair moved the torch label, which both the+ # spec and the leaf are read from. Nothing else may join the set.+ assert step13 == (+ ["_progress", "_torch_step_label", "_probe_installed_torch_version"]+ + repairs + ["_probe_installed_torch_version", "_note", "_install_torchao_for_torch"]+ ), step13+ assert "_install_torchao_for_torch" not in _calls_in(guards[0])def test_the_invariant_is_wired_in_exactly_once(self):body = ast.unparse(_install_stack_ast())