Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Diagnose torch and triton version skew at import time (#11023)

Daniel Hanb07e4666760f
diff --git a/pyproject.toml b/pyproject.toml
index c59e38c9a86..93c78833e9e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -184,6 +184,15 @@ studio = [
]
triton = [
+ # Not raised past 3.0.0 on purpose. torch pins triton exactly, and the oldest
+ # torch supported here, 2.6.0, requires `triton==3.2.0`, so any floor above
+ # that makes torch 2.6.0 unresolvable rather than safe, and a marker cannot
+ # be written against another distribution's version. The two triton defects
+ # that were reported through us are handled where the version is actually
+ # known: the sm_75 cut cross entropy miscompile in triton 3.3.0 and 3.3.1
+ # (#2491) by the gate in unsloth_zoo/loss_utils.py, and the missing
+ # PY_SSIZE_T_CLEAN in a repackaged driver shim (#2760) by
+ # check_triton_py_ssize_t_clean() in unsloth/import_fixes.py.
"triton>=3.0.0 ; ('linux' in sys_platform)",
# triton-windows has win_arm64 wheels from 3.8.0.post28, so a floor works here, not a marker.
"triton-windows ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
diff --git a/tests/test_import_time_floors.py b/tests/test_import_time_floors.py
new file mode 100644
index 00000000000..677c51543f8
--- /dev/null
+++ b/tests/test_import_time_floors.py
@@ -0,0 +1,1196 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+"""Version skew that used to surface deep in a forward pass, named at import.
+
+Three reports, one shape: pip installs a combination it has no specifier to
+reject, and the user sees an error from the wrong layer.
+
+#8933: transformers 5.10 beside a torch without `torch.float8_e8m0fnu`, so
+`import unsloth` ended on a bare `AttributeError: module 'torch' has no
+attribute 'float8_e8m0fnu'`.
+
+#2760: a repackaged triton whose CUDA driver shim includes Python.h without
+defining PY_SSIZE_T_CLEAN, so the first kernel launch raised `SystemError:
+PY_SSIZE_T_CLEAN macro must be defined for '#' formats`.
+
+#3130: one temporary patch raised a SyntaxError and took `import unsloth` down
+with it, because the caller tolerated only ValueError and TypeError.
+"""
+
+import ast
+import pathlib
+import re
+import sys
+import textwrap
+import types
+
+import pytest
+
+from unsloth import import_fixes
+
+
+_UNSLOTH = pathlib.Path(import_fixes.__file__).resolve().parent
+
+
+# ---------------------------------------------------------------- #8933
+
+
+def _access_from(module_name, attribute):
+ """Read `torch.<attribute>` from a frame that belongs to `module_name`.
+
+ The fix keys off the module the ACCESS was made from, so the frame has to be
+ real; a call through a helper defined in this file would be attributed to
+ the test.
+ """
+ import torch
+
+ module = types.ModuleType(module_name)
+ module.__dict__["torch"] = torch
+ code = compile(f"value = torch.{attribute}\n", f"<{module_name}>", "exec")
+ exec(code, module.__dict__)
+ return module.__dict__["value"]
+
+
+def patched_torch(monkeypatch):
+ """torch with the diagnosis installed and one attribute known to be absent."""
+ import torch
+
+ original = torch.__dict__.get("__getattr__")
+ assert original is not None, "torch has no module-level __getattr__ to wrap"
+ assert import_fixes.patch_torch_missing_attribute_error() is True
+ monkeypatch.setitem(import_fixes._TORCH_ATTRIBUTE_FLOORS, "unsloth_probe_dtype", "2.7.0")
+ try:
+ yield torch
+ finally:
+ # Restore whatever was there, so an idempotence check in another test
+ # still measures a first install.
+ installed = torch.__dict__.get("__getattr__")
+ if getattr(installed, "__unsloth_patched__", False):
+ torch.__getattr__ = installed.__unsloth_original__
+
+
+def test_a_dependency_reaching_for_a_missing_dtype_gets_the_upgrade(patched_torch):
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ # The original wording stays first, so anything already matching on it, and
+ # anyone searching the web for it, still finds what they expect.
+ assert message.startswith("module 'torch' has no attribute 'unsloth_probe_dtype'")
+ assert "transformers==" in message
+ assert patched_torch.__version__ in message
+ assert "first appears in torch 2.7.0" in message
+ assert 'pip install --upgrade "torch>=2.7.0"' in message
+ # Still an AttributeError, so no caller's except clause changes meaning.
+ assert isinstance(raised.value, AttributeError)
+
+
+def test_an_unknown_attribute_is_diagnosed_without_prescribing_a_direction(patched_torch):
+ """The table names the release; it is not the gate. A dtype added after this release
+ must still be diagnosed, but an absent attribute is not evidence that torch is the
+ older half: an older dependency reaching for a RETIRED torch API lands here too, and
+ telling that user to upgrade torch is the opposite remedy. So the no-floor branch
+ names both directions and prescribes neither."""
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_future_dtype")
+
+ message = str(raised.value)
+ assert "first appears in torch" not in message
+ assert "so this torch is the older half" not in message
+ assert "either newer than this torch or removed by it" in message
+ # Both remedies are offered, neither as the answer.
+ assert 'pip install --upgrade "torch"' in message
+ assert "install a transformers that matches this torch" in message
+
+
+def test_a_known_floor_still_prescribes_the_upgrade(patched_torch):
+ """NEGATIVE CONTROL: a floor IS evidence of the direction, so that branch must keep
+ saying which half is out of step rather than being softened with it."""
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ assert "first appears in torch 2.7.0, so this torch is the older half" in message
+ assert "either newer than this torch or removed by it" not in message
+ assert 'pip install --upgrade "torch>=2.7.0"' in message
+
+
+ "requester",
+ ["__main__", "my_training_script", "torch._inductor.analysis.device_info"],
+)
+def test_user_and_torch_frames_are_left_exactly_as_torch_wrote_them(patched_torch, requester):
+ """A typo in user code, or torch asking itself, is not a version report."""
+ with pytest.raises(AttributeError) as raised:
+ _access_from(requester, "unsloth_probe_dtype")
+
+ assert not isinstance(raised.value, import_fixes.UnslothTorchTooOldError)
+ assert str(raised.value) == "module 'torch' has no attribute 'unsloth_probe_dtype'"
+
+
+ "torch_version, family",
+ [
+ ("2.7.0+rocm6.3", "ROCm"),
+ ("2.7.0+xpu", "XPU"),
+ ("2.7.0+cpu", "CPU"),
+ ("2.6.0+cu124", "CUDA"),
+ ],
+)
+def test_the_upgrade_names_the_accelerator_it_found(
+ patched_torch, monkeypatch, torch_version, family
+):
+ """pip's --index-url defaults to pypi.org, which ships one build per release: the
+ default CUDA one. So an unqualified upgrade silently moves a ROCm or XPU user off
+ their accelerator, and the message has to say so. It must NOT paste the installed
+ tag into --index-url: each index carries only the releases built for it, and the
+ reported torch 2.6.0+cu124 case would then get a command with no candidate at all
+ (download.pytorch.org/whl/cu124 stops at torch 2.6.0; 2.7 shipped on cu126/cu128)."""
+ monkeypatch.setattr(patched_torch, "__version__", torch_version)
+
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ assert 'pip install --upgrade "torch>=2.7.0"' in message
+ assert "--index-url" in message
+ assert (
+ f"--index-url https://download.pytorch.org/whl/{torch_version.split('+')[1]}" not in message
+ )
+ assert f"This torch is a {torch_version.split('+')[1]} build" in message
+ assert f"pick the {family} index" in message
+ assert "https://pytorch.org/get-started/locally/" in message
+
+
+ "torch_version",
+ ["2.10.0+rocm7.2.0.lw.gitb6ee5fde", "2.10.0+rocm7.2.0.gitba5c1517"],
+)
+def test_a_vendor_rocm_torch_is_sent_back_to_its_own_source(
+ patched_torch, monkeypatch, torch_version
+):
+ """unsloth's own AMD extras install torch-2.10.0+rocm7.2.0.lw.gitb6ee5fde straight from
+ repo.radeon.com. That tag is no index name, so there is no --index-url that would keep
+ the accelerator, and an unqualified upgrade would put the default CUDA build over a
+ working Radeon one. Naming the source is the only advice that holds."""
+ monkeypatch.setattr(patched_torch, "__version__", torch_version)
+
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ assert f"This torch is a {torch_version.split('+')[1]} build" in message
+ assert "no public index carries" in message
+ assert "repo.radeon.com" in message
+ assert "--index-url" not in message
+
+
+def test_an_unrecognisable_local_tag_gets_no_accelerator_note(patched_torch, monkeypatch):
+ """NEGATIVE CONTROL: a local tag naming no known family says nothing about the
+ accelerator, so inventing a source for it would be worse than silence."""
+ monkeypatch.setattr(patched_torch, "__version__", "2.10.0+localbuild1")
+
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ assert "This torch is a" not in message
+ assert "no public index carries" not in message
+ assert "repo.radeon.com" not in message
+
+
+def test_a_conda_torch_is_pointed_at_conda_not_pip(patched_torch, monkeypatch, tmp_path):
+ """conda writes no local tag, so a conda torch reads like a PyPI one by version alone.
+ `pip install --upgrade torch` there overlays the conda-managed files with a PyPI wheel
+ and can change the backend with them, so the remedy has to name conda instead."""
+ conda_meta = tmp_path / "conda-meta"
+ conda_meta.mkdir()
+ (conda_meta / "pytorch-2.7.0-py3.12_cuda12.4_cudnn9_0.json").write_text("{}", encoding = "utf-8")
+ monkeypatch.setattr(import_fixes.sys, "prefix", str(tmp_path))
+ monkeypatch.setattr(patched_torch, "__version__", "2.7.0")
+
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ assert "conda installed this torch" in message
+ assert "conda update pytorch" in message
+ assert "--index-url" not in message
+
+
[email protected]("torch_version", ["2.7.0", "2.9.0.dev20250101", "2.7.0+fbcode"])
+def test_a_pypi_torch_gets_no_accelerator_note(patched_torch, monkeypatch, torch_version):
+ """NEGATIVE CONTROL: no recognised backend tag means PyPI is already the right
+ place, so the plain command stands alone with nothing extra to read."""
+ monkeypatch.setattr(patched_torch, "__version__", torch_version)
+
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ message = str(raised.value)
+ assert 'pip install --upgrade "torch>=2.7.0"' in message
+ assert "--index-url" not in message
+ assert "get-started" not in message
+
+
+def test_an_unattributable_access_keeps_torchs_own_error(patched_torch, monkeypatch):
+ """sys._getframe is CPython-only and raises an audit event, so a hardened
+ interpreter can refuse it. hasattr() swallows only AttributeError, so rethrowing
+ the frame-lookup failure would break an ordinary feature probe."""
+
+ def _refuse(_depth):
+ raise RuntimeError("frame inspection is not allowed here")
+
+ monkeypatch.setattr(sys, "_getframe", _refuse)
+
+ with pytest.raises(AttributeError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+
+ assert not isinstance(raised.value, import_fixes.UnslothTorchTooOldError)
+ assert str(raised.value) == "module 'torch' has no attribute 'unsloth_probe_dtype'"
+ assert hasattr(patched_torch, "__version__")
+ assert getattr(patched_torch, "unsloth_probe_dtype", "fallback") == "fallback"
+
+
+def test_hasattr_and_getattr_default_are_unaffected(patched_torch):
+ """The error subclasses AttributeError precisely so these keep working;
+ transformers 5.17 guards this very dtype with hasattr."""
+ assert not hasattr(patched_torch, "unsloth_probe_dtype")
+ assert getattr(patched_torch, "unsloth_probe_dtype", "fallback") == "fallback"
+
+
+def test_a_failed_probe_does_not_re_read_the_installed_metadata(patched_torch, monkeypatch):
+ """A missing attribute is not always fatal, so the wrapper has to stay cheap.
+
+ `hasattr(torch, name)` and `getattr(torch, name, default)` are how these same
+ libraries feature-probe, and both reach the wrapper. Resolving a distribution
+ version walks sys.path and costs about 850 microseconds on a normal install,
+ which is a thousand times a failed lookup, so it is asked once per package and
+ remembered. Counted rather than timed: a timing threshold on a shared runner is
+ a flake.
+ """
+ calls = []
+
+ def counting_version(package):
+ calls.append(package)
+ return "9.9.9"
+
+ import_fixes._installed_version.cache_clear()
+ monkeypatch.setattr(import_fixes, "importlib_version", counting_version)
+ try:
+ for _ in range(25):
+ assert not hasattr(patched_torch, "unsloth_probe_dtype")
+ # transformers is not in the frames above (hasattr here is attributed to
+ # this test module), so drive the diagnosing path explicitly too.
+ for _ in range(25):
+ with pytest.raises(import_fixes.UnslothTorchTooOldError):
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+ # The message also names the companion packages that have to move with torch, and
+ # each of those is a lookup too. What must hold is ONE lookup per package across 50
+ # failed accesses, not one lookup in total.
+ assert "transformers" in calls
+ assert set(calls) <= {"transformers", "torchvision", "torchaudio"}, calls
+ assert len(calls) == len(set(calls)), (
+ f"the installed version was resolved more than once for some package: {calls}. "
+ f"It cannot change inside a process and this path runs on every failed "
+ f"attribute lookup"
+ )
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_an_unresolvable_package_still_reports_a_version_word(patched_torch, monkeypatch):
+ """The word unknown rather than a traceback, and cached like any other answer."""
+
+ def always_raises(package):
+ raise RuntimeError("no metadata here")
+
+ import_fixes._installed_version.cache_clear()
+ monkeypatch.setattr(import_fixes, "importlib_version", always_raises)
+ try:
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+ assert "transformers==unknown" in str(raised.value)
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_installing_twice_wraps_once(patched_torch):
+ first = patched_torch.__dict__["__getattr__"]
+ assert import_fixes.patch_torch_missing_attribute_error() is True
+ second = patched_torch.__dict__["__getattr__"]
+ assert first is second
+ assert not getattr(first.__unsloth_original__, "__unsloth_patched__", False)
+
+
+def test_a_torch_without_a_module_getattr_is_left_alone(monkeypatch):
+ """The wrapper has one prerequisite, so say what happens without it: nothing,
+ and it says so rather than raising."""
+ monkeypatch.setitem(sys.modules, "torch", types.ModuleType("torch"))
+ assert import_fixes.patch_torch_missing_attribute_error() is False
+
+
+def test_the_diagnosis_is_installed_before_anything_imports_transformers():
+ """Ordering is the whole fix: installed after `import unsloth_zoo`, it would
+ arrive after the import that fails."""
+ source = (_UNSLOTH / "_gpu_init.py").read_text(encoding = "utf-8")
+ install = source.find("patch_torch_missing_attribute_error()")
+ # The statement, not the several comments that name it.
+ zoo = re.search(r"^ {4}import unsloth_zoo$", source, re.M)
+ assert install != -1, (
+ "DRIFT DETECTED: patch_torch_missing_attribute_error is defined but never "
+ "called in _gpu_init.py, so real imports never install it."
+ )
+ assert zoo is not None, "the `import unsloth_zoo` statement moved"
+ assert install < zoo.start(), (
+ "DRIFT DETECTED: patch_torch_missing_attribute_error is called after "
+ "`import unsloth_zoo`, which is what imports transformers and raises."
+ )
+ assert "del patch_torch_missing_attribute_error" in source
+
+
+def test_the_rocm_id_table_is_configured_before_torch_is_imported():
+ """`patch_torch_missing_attribute_error` imports torch, so it has to come after the
+ ROCm table. `configure_amdgpu_asic_id_table_path` sets AMDGPU_ASIC_ID_TABLE_PATH, which
+ is how ROCm resolves AMD device names, and a torch that has already brought up libdrm
+ would not see the discovered table."""
+ source = (_UNSLOTH / "_gpu_init.py").read_text(encoding = "utf-8")
+ table = source.find("configure_amdgpu_asic_id_table_path()")
+ install = source.find("patch_torch_missing_attribute_error()")
+ assert table != -1 and install != -1
+ assert table < install, (
+ "DRIFT DETECTED: the torch diagnosis, which imports torch, is installed before "
+ "the ROCm ASIC id table path is configured."
+ )
+
+
+def test_a_conda_triton_is_repaired_through_conda(monkeypatch, tmp_path):
+ """conda-forge publishes `triton`, and a pip --force-reinstall over a conda-managed one
+ overlays conda's files with a wheel, leaving two managers owning the same paths."""
+ conda_meta = tmp_path / "conda-meta"
+ conda_meta.mkdir()
+ (conda_meta / "triton-3.2.0-py312_0.json").write_text("{}", encoding = "utf-8")
+ monkeypatch.setattr(import_fixes.sys, "prefix", str(tmp_path))
+
+ spec, _driver = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton"]})
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "3.2.0" if name == "triton" else _raise_missing(name),
+ )
+
+ logger = _CollectingLogger()
+ monkeypatch.setattr(import_fixes, "logger", logger)
+ import_fixes.check_triton_py_ssize_t_clean()
+
+ message = logger.warnings[0]
+ assert "conda installed this Triton" in message
+ assert "conda install --force-reinstall triton=3.2.0" in message
+ assert "pip install" not in message
+
+
+def test_a_pip_triton_in_a_conda_prefix_still_gets_pip(monkeypatch, tmp_path):
+ """NEGATIVE CONTROL: the conda-meta entry has to name this distribution at this
+ version, or a conda prefix alone would redirect every pip-installed Triton."""
+ conda_meta = tmp_path / "conda-meta"
+ conda_meta.mkdir()
+ (conda_meta / "pytorch-2.7.0-py312_0.json").write_text("{}", encoding = "utf-8")
+ monkeypatch.setattr(import_fixes.sys, "prefix", str(tmp_path))
+
+ spec, _driver = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton"]})
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "3.2.0" if name == "triton" else _raise_missing(name),
+ )
+
+ logger = _CollectingLogger()
+ monkeypatch.setattr(import_fixes, "logger", logger)
+ import_fixes.check_triton_py_ssize_t_clean()
+
+ message = logger.warnings[0]
+ assert "conda installed this Triton" not in message
+ assert '--force-reinstall --no-cache-dir "triton==3.2.0"' in message
+
+
+# ---------------------------------------------------------------- #2760
+
+
+_UNGUARDED_SHIM = textwrap.dedent(
+ """
+ #include "cuda.h"
+ #include <Python.h>
+
+ static PyObject *loadBinary(PyObject *self, PyObject *args) {
+ const char *name;
+ const char *data;
+ Py_ssize_t data_size;
+ int shared;
+ int device;
+ if (!PyArg_ParseTuple(args, "ss#ii", &name, &data, &data_size, &shared,
+ &device)) {
+ return NULL;
+ }
+ return NULL;
+ }
+ """
+)
+
+
+def _fake_triton(
+ tmp_path,
+ source,
+ backend = "nvidia",
+):
+ driver = tmp_path / "triton" / "backends" / backend / "driver.c"
+ driver.parent.mkdir(parents = True)
+ driver.write_text(source, encoding = "utf-8")
+ spec = types.SimpleNamespace(
+ submodule_search_locations = [str(tmp_path / "triton")],
+ )
+ return spec, driver
+
+
+def test_a_shim_without_the_macro_is_named(monkeypatch, tmp_path):
+ spec, driver = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ offenders = import_fixes._triton_driver_shims_missing_py_ssize_t_clean()
+ assert offenders == [("nvidia", str(driver))]
+
+
+def test_a_shim_with_the_macro_is_not_named(monkeypatch, tmp_path):
+ fixed = "#define PY_SSIZE_T_CLEAN\n" + _UNGUARDED_SHIM
+ spec, _ = _fake_triton(tmp_path, fixed)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ assert import_fixes._triton_driver_shims_missing_py_ssize_t_clean() == []
+
+
+def test_a_shim_with_no_hash_format_is_not_named(monkeypatch, tmp_path):
+ """Only a '#' in a PyArg_Parse format needs the macro, so a shim without one
+ is not a finding no matter what it includes."""
+ spec, _ = _fake_triton(tmp_path, _UNGUARDED_SHIM.replace('"ss#ii"', '"sslii"'))
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ assert import_fixes._triton_driver_shims_missing_py_ssize_t_clean() == []
+
+
+ "comment",
+ [
+ '/* legacy: PyArg_ParseTuple(args, "ss#ii", &name, &data, &size, &shared); */',
+ '// legacy: PyArg_ParseTuple(args, "ss#ii", &name, &data, &size, &shared);',
+ ],
+ ids = ["block", "line"],
+)
+def test_a_hash_format_only_in_a_comment_is_not_a_finding(monkeypatch, tmp_path, comment):
+ """A repackaged shim can keep the old call around as a comment. The compiler never
+ sees it, so the active parser is the one without a '#' and the first kernel launch
+ does not fail. Naming it would promise a failure that cannot happen and recommend a
+ force reinstall for nothing."""
+ source = comment + "\n" + _UNGUARDED_SHIM.replace('"ss#ii"', '"sslii"')
+ spec, _ = _fake_triton(tmp_path, source)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ assert import_fixes._triton_driver_shims_missing_py_ssize_t_clean() == []
+
+
+def test_a_live_hash_format_beside_a_comment_is_still_a_finding(monkeypatch, tmp_path):
+ """NEGATIVE CONTROL: masking comments must not mask the call itself, and a `//`
+ inside a string literal must not blank the rest of the file."""
+ source = (
+ "/* the parser below still uses a length format */\n"
+ 'static const char *kDoc = "see //triton/backends for /* details */";\n' + _UNGUARDED_SHIM
+ )
+ spec, driver = _fake_triton(tmp_path, source)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ assert import_fixes._triton_driver_shims_missing_py_ssize_t_clean() == [
+ ("nvidia", str(driver)),
+ ]
+
+
+def test_a_hash_format_only_inside_a_string_literal_is_not_a_finding(monkeypatch, tmp_path):
+ """A documentation string quoting an example call is not a call. The format has to be
+ readable, so literals are kept, but the CALL has to be located in code."""
+ source = (
+ "static const char *kUsage =\n"
+ ' "example: PyArg_ParseTuple(args, \\"ss#ii\\", &name, &data, &size, &shared)";\n'
+ + _UNGUARDED_SHIM.replace('"ss#ii"', '"sslii"')
+ )
+ spec, _ = _fake_triton(tmp_path, source)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ assert import_fixes._triton_driver_shims_missing_py_ssize_t_clean() == []
+
+
+def test_a_vendor_tagged_triton_is_sent_back_to_its_own_source(monkeypatch, tmp_path):
+ """The AMD extras install triton==3.6.0+rocm7.2.0.gitba5c1517 from a repo.radeon.com
+ URL under the plain `triton` name. No public index publishes that version, so a pinned
+ pip command resolves to nothing and the advice has to name the source instead."""
+ spec, _driver = _fake_triton(tmp_path, _UNGUARDED_SHIM, backend = "amd")
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton"]})
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "3.6.0+rocm7.2.0.gitba5c1517" if name == "triton" else _raise_missing(name),
+ )
+
+ logger = _CollectingLogger()
+ monkeypatch.setattr(import_fixes, "logger", logger)
+ import_fixes.check_triton_py_ssize_t_clean()
+
+ assert len(logger.warnings) == 1, logger.warnings
+ message = logger.warnings[0]
+ assert "+rocm7.2.0.gitba5c1517 tag marks a vendor build" in message
+ assert "repo.radeon.com" in message
+
+
+def test_a_public_triton_still_gets_the_plain_reinstall_line(monkeypatch, tmp_path):
+ """NEGATIVE CONTROL: a version PyPI does publish keeps the command as the advice."""
+ spec, _driver = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton"]})
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "3.6.0" if name == "triton" else _raise_missing(name),
+ )
+
+ logger = _CollectingLogger()
+ monkeypatch.setattr(import_fixes, "logger", logger)
+ import_fixes.check_triton_py_ssize_t_clean()
+
+ message = logger.warnings[0]
+ assert "vendor build" not in message
+ assert '--force-reinstall --no-cache-dir "triton==3.6.0"' in message
+
+
+def test_python_313_and_later_do_not_pay_for_the_probe(monkeypatch, tmp_path):
+ """CPython stopped requiring the macro in 3.13, so the shim is fine there and
+ the file is never read."""
+ spec, _ = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 13, 1))
+
+ def refuse(name):
+ raise AssertionError("the probe read the filesystem on Python 3.13")
+
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", refuse)
+ assert import_fixes._triton_driver_shims_missing_py_ssize_t_clean() == []
+
+
+def test_the_installed_triton_is_not_flagged():
+ """Drift detector, not a unit test: every triton on PyPI from 3.0.0 to 3.8.0
+ defines the macro, and this must stay a silent check for real installs."""
+ pytest.importorskip("triton")
+ if sys.version_info >= (3, 13):
+ pytest.skip("the probe is inert on Python 3.13 and later")
+ offenders = import_fixes._triton_driver_shims_missing_py_ssize_t_clean()
+ assert (
+ offenders == []
+ ), f"the installed triton would fail at the first kernel launch: {offenders}"
+
+
+ "prefix,suffix,named",
+ [
+ ("#define PY_SSIZE_T_CLEAN\n", "", False),
+ ("# define PY_SSIZE_T_CLEAN 1\n", "", False),
+ ("/* PY_SSIZE_T_CLEAN is not needed here */\n", "", True),
+ ("#define PY_SSIZE_T_CLEAN\n#undef PY_SSIZE_T_CLEAN\n", "", True),
+ ("", "#define PY_SSIZE_T_CLEAN\n", True),
+ ('const char *why = "PY_SSIZE_T_CLEAN";\n', "", True),
+ # The compiler strips comments before the preprocessor sees a directive, so a
+ # define that exists only inside one is not a definition at all.
+ ("/*\n#define PY_SSIZE_T_CLEAN\n*/\n", "", True),
+ ("/* x */ /*\n# define PY_SSIZE_T_CLEAN 1\n*/\n", "", True),
+ ("//#define PY_SSIZE_T_CLEAN\n", "", True),
+ # A real define followed by an UNDEF hidden in a comment is still defined, which
+ # is the control for blanking too much.
+ ("#define PY_SSIZE_T_CLEAN\n/*\n#undef PY_SSIZE_T_CLEAN\n*/\n", "", False),
+ # A comment between the define and the include changes nothing.
+ ("#define PY_SSIZE_T_CLEAN\n/* now include it */\n", "", False),
+ ],
+)
+def test_the_macro_only_counts_when_it_is_in_effect(monkeypatch, tmp_path, prefix, suffix, named):
+ """CPython requires the define BEFORE Python.h. A comment, an `#undef`, a string
+ literal and a define placed after the include all leave the '#' formats unsafe, so
+ the substring test that accepted them suppressed the warning on a shim that still
+ dies at the first kernel launch."""
+ spec, driver = _fake_triton(tmp_path, prefix + _UNGUARDED_SHIM + suffix)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ offenders = import_fixes._triton_driver_shims_missing_py_ssize_t_clean()
+ assert offenders == ([("nvidia", str(driver))] if named else [])
+
+
+def test_the_reinstall_command_names_the_distribution_that_owns_triton(monkeypatch, tmp_path):
+ """triton-windows, pytorch-triton-rocm and pytorch-triton-xpu all provide the
+ `triton` import name, so `importlib.metadata.version("triton")` raises on them (the
+ "unknown" version) and `pip install --force-reinstall triton` installs a CUDA build
+ over a platform one instead of repairing it."""
+ spec, _driver = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton-windows"]})
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "3.3.1.post19" if name == "triton-windows" else _raise_missing(name),
+ )
+
+ logger = _CollectingLogger()
+ monkeypatch.setattr(import_fixes, "logger", logger)
+ import_fixes.check_triton_py_ssize_t_clean()
+
+ assert len(logger.warnings) == 1, logger.warnings
+ message = logger.warnings[0]
+ assert "triton-windows==3.3.1.post19" in message
+ assert '--force-reinstall --no-cache-dir "triton-windows==3.3.1.post19"' in message
+ assert "unknown" not in message
+
+
+def _raise_missing(name):
+ from importlib.metadata import PackageNotFoundError
+ raise PackageNotFoundError(name)
+
+
+def test_the_plain_triton_distribution_is_still_named(monkeypatch, tmp_path):
+ """The control: on an ordinary CUDA install nothing about the message changes."""
+ spec, _driver = _fake_triton(tmp_path, _UNGUARDED_SHIM)
+ monkeypatch.setattr(sys, "version_info", (3, 12, 3))
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: spec)
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton"]})
+ monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "3.3.0")
+
+ logger = _CollectingLogger()
+ monkeypatch.setattr(import_fixes, "logger", logger)
+ import_fixes.check_triton_py_ssize_t_clean()
+
+ assert "triton==3.3.0" in logger.warnings[0]
+ assert '--force-reinstall --no-cache-dir "triton==3.3.0"\n' in logger.warnings[0]
+
+
+ "distribution, triton_version, torch_version, expected",
+ [
+ # The ordinary CUDA install: PyPI carries this wheel, so only the pin is added.
+ (
+ "triton",
+ "3.2.0",
+ "2.6.0+cu124",
+ 'pip install --force-reinstall --no-cache-dir "triton==3.2.0"',
+ ),
+ # Windows builds also come from PyPI, and are not a pytorch-triton-* provider.
+ (
+ "triton-windows",
+ "3.3.1.post19",
+ "2.7.1+cu126",
+ 'pip install --force-reinstall --no-cache-dir "triton-windows==3.3.1.post19"',
+ ),
+ # ROCm and XPU Triton exist only on download.pytorch.org, under torch's own tag.
+ (
+ "pytorch-triton-rocm",
+ "3.3.0",
+ "2.7.0+rocm6.3",
+ "pip install --force-reinstall --no-cache-dir"
+ ' --index-url https://download.pytorch.org/whl/rocm6.3 "pytorch-triton-rocm==3.3.0"',
+ ),
+ (
+ "pytorch-triton-xpu",
+ "3.3.0",
+ "2.7.0+xpu",
+ "pip install --force-reinstall --no-cache-dir"
+ ' --index-url https://download.pytorch.org/whl/xpu "pytorch-triton-xpu==3.3.0"',
+ ),
+ # NEGATIVE CONTROL: no version to pin, so the command stays bare rather than
+ # inventing a pin that would resolve to no wheel at all.
+ ("triton", "unknown", "2.6.0+cu124", "pip install --force-reinstall --no-cache-dir triton"),
+ ],
+)
+def test_the_reinstall_command_pins_the_installed_triton(
+ monkeypatch, distribution, triton_version, torch_version, expected
+):
+ """An unpinned --force-reinstall resolves the NEWEST provider release, but torch pins
+ Triton exactly (torch 2.6.0 requires triton==3.2.0), so the bare command can replace a
+ broken shim with a working-but-ABI-incompatible Triton."""
+ torch_module = types.ModuleType("torch")
+ torch_module.__version__ = torch_version
+ monkeypatch.setitem(sys.modules, "torch", torch_module)
+
+ assert import_fixes._triton_reinstall_command(distribution, triton_version) == expected
+
+
+def test_the_triton_probe_is_wired_into_gpu_init():
+ source = (_UNSLOTH / "_gpu_init.py").read_text(encoding = "utf-8")
+ assert "check_triton_py_ssize_t_clean()" in source, (
+ "DRIFT DETECTED: check_triton_py_ssize_t_clean is defined but never called "
+ "in _gpu_init.py."
+ )
+ assert "del check_triton_py_ssize_t_clean" in source
+
+
+# ---------------------------------------------------------------- #3130
+
+
+class _CollectingLogger:
+ def __init__(self):
+ self.warnings = []
+
+ def warning(self, message):
+ self.warnings.append(message)
+
+
+def _isolated_run_temporary_patches(patches, logger):
+ """`_run_temporary_patches` alone, with its two module globals supplied.
+
+ Loading it out of the file rather than importing unsloth.models._utils keeps
+ this a test of the control flow and not of a full model-stack import.
+ """
+ path = _UNSLOTH / "models" / "_utils.py"
+ source = path.read_text(encoding = "utf-8")
+ tree = ast.parse(source)
+ for node in tree.body:
+ if isinstance(node, ast.FunctionDef) and node.name == "_run_temporary_patches":
+ segment = ast.get_source_segment(source, node)
+ break
+ else:
+ raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")
+
+ namespace = {"TEMPORARY_PATCHES": patches, "logger": logger}
+ exec(compile(segment, str(path), "exec"), namespace)
+ return namespace["_run_temporary_patches"]
+
+
+def test_a_patch_that_raises_is_skipped_not_fatal():
+ called = []
+
+ def raises_syntax_error():
+ # What patch_merge_quantization_configs did: exec'd
+ # `from transformers.quantizers.auto import ()`.
+ raise SyntaxError("invalid syntax")
+
+ def later_patch():
+ called.append("later_patch")
+
+ logger = _CollectingLogger()
+ run = _isolated_run_temporary_patches([raises_syntax_error, later_patch], logger)
+
+ run("init")
+
+ assert called == ["later_patch"], "a raising patch stopped the ones after it"
+ assert len(logger.warnings) == 1
+ assert "raises_syntax_error" in logger.warnings[0]
+ assert "SyntaxError" in logger.warnings[0]
+
+
+def test_a_patch_is_called_once_and_gets_its_phase():
+ calls = []
+
+ def takes_phase(phase):
+ calls.append(("takes_phase", phase))
+
+ def takes_nothing():
+ calls.append(("takes_nothing", None))
+
+ def raises_value_error(phase):
+ calls.append(("raises_value_error", phase))
+ raise ValueError("a patch may legitimately raise this")
+
+ logger = _CollectingLogger()
+ run = _isolated_run_temporary_patches([takes_phase, takes_nothing, raises_value_error], logger)
+
+ run("pre_compile")
+
+ # The ValueError one used to be retried without its argument, because the
+ # signature probe and the call shared an except clause.
+ assert calls == [
+ ("takes_phase", "pre_compile"),
+ ("takes_nothing", None),
+ ("raises_value_error", "pre_compile"),
+ ]
+ assert len(logger.warnings) == 1
+
+
+def test_a_callable_with_no_readable_signature_is_still_called():
+ logger = _CollectingLogger()
+ # inspect.signature raises ValueError for some builtins, which is the case the
+ # original except clause existed for.
+ run = _isolated_run_temporary_patches([print], logger)
+ run("init")
+ assert logger.warnings == []
+
+
+ "installed, version",
+ [
+ ("pytorch-triton-rocm", "3.3.0"),
+ # download.pytorch.org renamed both accelerator providers. pytorch-triton-rocm
+ # stops at 3.5.1 and triton-rocm carries 3.7 onwards, the same split the XPU
+ # provider has, so a current ROCm host is only found under the new name.
+ ("triton-rocm", "3.8.0"),
+ ("triton-xpu", "3.7.1"),
+ ],
+)
+def test_the_provider_lookup_still_works_without_packages_distributions(
+ monkeypatch, installed, version
+):
+ """`importlib.metadata.packages_distributions` is Python 3.10+, and pyproject still
+ admits 3.9. There the import raises, the mapping comes back empty, and the message
+ used to report `triton==unknown` and recommend the CUDA `triton` over the platform
+ build, which is the exact substitution this helper exists to prevent."""
+ import importlib.metadata as metadata
+
+ def _absent():
+ raise ImportError("no packages_distributions on this interpreter")
+
+ monkeypatch.setattr(metadata, "packages_distributions", _absent, raising = False)
+ monkeypatch.setitem(sys.modules, "importlib_metadata", None)
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: version if name == installed else _raise_missing(name),
+ )
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution() == (installed, version)
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_the_provider_fallback_reports_unknown_when_nothing_is_installed(monkeypatch):
+ """NEGATIVE CONTROL: the fallback asks each provider whether it is installed, so a
+ host with none of them must not pick one anyway."""
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {}, raising = False)
+ monkeypatch.setitem(sys.modules, "importlib_metadata", None)
+ monkeypatch.setattr(import_fixes, "importlib_version", _raise_missing)
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution() == ("triton", "unknown")
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_the_mlx_branch_installs_the_torch_diagnosis():
+ """_gpu_init.py is the only other installation site and the MLX branch never reaches
+ it, so an Apple Silicon host with the old-torch/new-transformers pair would get the
+ bare AttributeError this PR exists to replace. The branch already mirrors three other
+ _gpu_init fixes for exactly this reason."""
+ source = (_UNSLOTH / "__init__.py").read_text(encoding = "utf-8")
+ mlx_branch = source[source.index("if _IS_MLX:") : source.index("import unsloth_zoo")]
+ assert "patch_torch_missing_attribute_error" in mlx_branch, (
+ "DRIFT DETECTED: the MLX branch no longer installs the torch-too-old diagnosis, "
+ "so it is installed only on the GPU path."
+ )
+
+
+def _fake_distribution(files_by_name):
+ """importlib.metadata.distribution, answering from `{name: [paths]}`."""
+
+ class _Entry:
+ def __init__(self, path):
+ self._path = path
+
+ def locate(self):
+ return self._path
+
+ class _Dist:
+ def __init__(self, paths):
+ self.files = [_Entry(p) for p in paths]
+
+ def _distribution(name):
+ if name not in files_by_name:
+ from importlib.metadata import PackageNotFoundError
+ raise PackageNotFoundError(name)
+ return _Dist(files_by_name[name])
+
+ return _distribution
+
+
+ "order", [["triton", "pytorch-triton-xpu"], ["pytorch-triton-xpu", "triton"]]
+)
+def test_the_provider_that_ships_the_offending_file_is_the_one_named(monkeypatch, tmp_path, order):
+ """Providers coexist: install_python_stack.py's _ensure_xpu_triton documents generic
+ triton beside pytorch-triton-xpu on the same paths, and packages_distributions reports
+ both without saying which one wrote the file. Taking the first entry can name the CUDA
+ provider for an XPU install and hand the user a command that replaces the Triton that
+ works -- the substitution this helper exists to avoid. The answer must not depend on
+ the order the mapping happens to return."""
+ driver = tmp_path / "backends" / "intel" / "driver.c"
+ driver.parent.mkdir(parents = True)
+ driver.write_text("x", encoding = "utf-8")
+
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": list(order)})
+ monkeypatch.setattr(
+ metadata,
+ "distribution",
+ _fake_distribution(
+ {
+ "triton": [str(tmp_path / "backends" / "nvidia" / "driver.c")],
+ "pytorch-triton-xpu": [str(driver)],
+ }
+ ),
+ )
+ monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "3.3.0")
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution(str(driver))[0] == "pytorch-triton-xpu"
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+ "order",
+ [("triton", "triton-xpu"), ("triton-xpu", "triton")],
+ ids = ["generic-first", "accelerator-first"],
+)
+def test_a_file_claimed_by_two_providers_is_settled_by_torchs_backend(monkeypatch, tmp_path, order):
+ """Coexisting providers RECORD the same paths, so both claim the offending file and the
+ first entry is nothing but ordering. The harmful answer is always the one that installs
+ a CUDA build over an accelerator one, so an XPU torch settles it for the XPU provider."""
+ driver = tmp_path / "backends" / "intel" / "driver.c"
+ driver.parent.mkdir(parents = True)
+ driver.write_text("x", encoding = "utf-8")
+
+ import importlib.metadata as metadata
+
+ torch_module = types.ModuleType("torch")
+ torch_module.__version__ = "2.10.0+xpu"
+ monkeypatch.setitem(sys.modules, "torch", torch_module)
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": list(order)})
+ monkeypatch.setattr(
+ metadata,
+ "distribution",
+ # Both RECORDs list the same file, which is the coexistence case.
+ _fake_distribution({"triton": [str(driver)], "triton-xpu": [str(driver)]}),
+ )
+ monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "3.7.1")
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution(str(driver))[0] == "triton-xpu"
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+ "order",
+ [("pytorch-triton-xpu", "triton-xpu"), ("triton-xpu", "pytorch-triton-xpu")],
+ ids = ["stale-first", "current-first"],
+)
+def test_a_rename_leftover_is_settled_by_what_torch_requires(monkeypatch, tmp_path, order):
+ """Both spellings name the backend, so the family rule cannot separate them.
+
+ An upgrade to a torch that installs `triton-xpu` leaves `pytorch-triton-xpu`'s
+ dist-info behind, both RECORDs claim the driver, and recommending the stale one would
+ install it over the provider this torch actually requires. torch declares that name
+ itself, which is the only record that settles it.
+ """
+ driver = tmp_path / "backends" / "intel" / "driver.c"
+ driver.parent.mkdir(parents = True)
+ driver.write_text("x", encoding = "utf-8")
+
+ import importlib.metadata as metadata
+
+ torch_module = types.ModuleType("torch")
+ torch_module.__version__ = "2.10.0+xpu"
+ monkeypatch.setitem(sys.modules, "torch", torch_module)
+ monkeypatch.setattr(
+ metadata,
+ "requires",
+ lambda name: ['triton-xpu==3.7.1; platform_system == "Linux"'] if name == "torch" else [],
+ )
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": list(order)})
+ monkeypatch.setattr(
+ metadata,
+ "distribution",
+ _fake_distribution({name: [str(driver)] for name in order}),
+ )
+ monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "3.7.1")
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution(str(driver))[0] == "triton-xpu"
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_the_declared_requirement_is_read_by_distribution_name(monkeypatch):
+ """The names are compared PEP 503 normalised, so an underscore spelling in torch's
+ own metadata still matches the dist-info name, and a non-Triton requirement is not
+ collected."""
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(
+ metadata,
+ "requires",
+ lambda name: [
+ "filelock",
+ 'pytorch_triton_xpu==3.7.1; platform_system == "Linux"',
+ "sympy>=1.13.3",
+ ],
+ )
+ assert import_fixes._torch_required_triton_distributions() == frozenset({"pytorch-triton-xpu"})
+
+
+def test_two_claimants_a_cuda_torch_cannot_separate_name_the_generic_one(monkeypatch, tmp_path):
+ """NEGATIVE CONTROL: with no accelerator in torch's tag there is no accelerator to
+ preserve, so the generic provider is the answer rather than whichever came first."""
+ driver = tmp_path / "backends" / "nvidia" / "driver.c"
+ driver.parent.mkdir(parents = True)
+ driver.write_text("x", encoding = "utf-8")
+
+ import importlib.metadata as metadata
+
+ torch_module = types.ModuleType("torch")
+ torch_module.__version__ = "2.10.0+cu128"
+ monkeypatch.setitem(sys.modules, "torch", torch_module)
+ monkeypatch.setattr(
+ metadata, "packages_distributions", lambda: {"triton": ["triton-windows", "triton"]}
+ )
+ monkeypatch.setattr(
+ metadata,
+ "distribution",
+ _fake_distribution({"triton": [str(driver)], "triton-windows": [str(driver)]}),
+ )
+ monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "3.7.1")
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution(str(driver))[0] == "triton"
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_an_unownable_path_falls_back_to_the_previous_answer(monkeypatch, tmp_path):
+ """NEGATIVE CONTROL: metadata that names no owner, or no path at all, must leave the
+ ordering-based answer exactly as it was rather than reporting nothing."""
+ import importlib.metadata as metadata
+
+ monkeypatch.setattr(metadata, "packages_distributions", lambda: {"triton": ["triton-windows"]})
+ monkeypatch.setattr(metadata, "distribution", _fake_distribution({}))
+ monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "3.3.1.post19")
+ import_fixes._installed_version.cache_clear()
+ try:
+ assert import_fixes._triton_distribution(None)[0] == "triton-windows"
+ assert import_fixes._triton_distribution(str(tmp_path / "nope.c"))[0] == "triton-windows"
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_the_upgrade_moves_the_companions_that_pin_torch_exactly(patched_torch, monkeypatch):
+ """`pip install --upgrade` upgrades the packages it is given and nothing else.
+
+ Every torchvision wheel requires an exact `torch==X.Y.Z`, so naming torch alone moves
+ torch and leaves the torchvision built against the old one: the "operator
+ torchvision::nms does not exist" mismatch that `_torchvision_repair_command` in this
+ same file exists to repair, created by following the remedy.
+ """
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "9.9.9" if name in ("transformers", "torchvision") else _raise_missing(name),
+ )
+ import_fixes._installed_version.cache_clear()
+ try:
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+ message = str(raised.value)
+ assert 'pip install --upgrade "torch>=2.7.0" "torchvision"' in message
+ # NEGATIVE CONTROL: torchaudio is not installed in this case, so it is not named.
+ assert "torchaudio" not in message
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+def test_a_bare_torch_install_gets_the_plain_upgrade(patched_torch, monkeypatch):
+ """NEGATIVE CONTROL: nothing that pins torch is installed, so nothing extra is named."""
+ monkeypatch.setattr(
+ import_fixes,
+ "importlib_version",
+ lambda name: "9.9.9" if name == "transformers" else _raise_missing(name),
+ )
+ import_fixes._installed_version.cache_clear()
+ try:
+ with pytest.raises(import_fixes.UnslothTorchTooOldError) as raised:
+ _access_from("transformers.integrations.finegrained_fp8", "unsloth_probe_dtype")
+ assert 'pip install --upgrade "torch>=2.7.0"\n' in str(raised.value)
+ finally:
+ import_fixes._installed_version.cache_clear()
+
+
+ "distribution, torch_version, expect_index",
+ [
+ # torch 2.10 renamed pytorch-triton-xpu to triton-xpu, and pyproject pins the new
+ # name straight from download.pytorch.org, where the old prefix no longer matches.
+ ("triton-xpu", "2.10.0+xpu", True),
+ ("pytorch-triton-xpu", "2.7.0+xpu", True),
+ ("pytorch-triton-rocm", "2.7.0+rocm6.3", True),
+ ("triton-rocm", "2.10.0+rocm6.4", True),
+ # NEGATIVE CONTROLS: PyPI serves these, so no index is added.
+ ("triton", "2.6.0+cu124", False),
+ ("triton-windows", "2.7.1+cu126", False),
+ ],
+)
+def test_every_torch_index_triton_provider_gets_the_accelerator_index(
+ monkeypatch, distribution, torch_version, expect_index
+):
+ torch_module = types.ModuleType("torch")
+ torch_module.__version__ = torch_version
+ monkeypatch.setitem(sys.modules, "torch", torch_module)
+
+ command = import_fixes._triton_reinstall_command(distribution, "3.6.0")
+ assert ("--index-url https://download.pytorch.org/whl/" in command) is expect_index
+ assert f'"{distribution}==3.6.0"' in command
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 36c28e1615b..f88b4d93a3c 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -153,6 +153,18 @@ def _is_mlx_available():
_IS_MLX = _is_mlx_available()
if _IS_MLX:
+ # Same reason again, and first because it is what turns the bare AttributeError into a
+ # diagnosis: this branch imports transformers below, so an Apple Silicon host carrying the
+ # old-torch/new-transformers pair hits #8933 here exactly as a CUDA host does, and
+ # _gpu_init.py, the only other installation site, is never reached on this path. The
+ # triton shim check is deliberately NOT mirrored: it is a CUDA/ROCm/XPU driver shim and
+ # there is no triton on this platform to inspect.
+ try:
+ from .import_fixes import patch_torch_missing_attribute_error as _patch_torch_attr
+ _patch_torch_attr()
+ del _patch_torch_attr
+ except Exception:
+ pass
# _gpu_init does this on the GPU path and the MLX path never reaches it, so torchao 0.18 + torch <
# 2.10 dies on `ScalingType`.
try:
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 18cc7926cad..04428973fdb 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -22,6 +22,8 @@ already_imported = [mod for mod in critical_modules if mod in sys.modules]
from .import_fixes import (
fix_message_factory_issue,
+ patch_torch_missing_attribute_error,
+ check_triton_py_ssize_t_clean,
fix_torch_check_is_size,
fix_torchao_torch_symbol_skew,
propagate_torchao_fix_to_subprocesses,
@@ -62,8 +64,16 @@ try:
except Exception:
pass
-# Configure libdrm ids table path early so ROCm can resolve AMD GPU names.
+# Configure libdrm ids table path early so ROCm can resolve AMD GPU names. Stdlib only,
+# and it must stay ahead of the first `import torch` in this file: it sets
+# AMDGPU_ASIC_ID_TABLE_PATH, and a torch that has already brought up libdrm would not see
+# the discovered table.
configure_amdgpu_asic_id_table_path()
+# Ahead of every fix below and of `import unsloth_zoo`, because those are what
+# import transformers, and a transformers newer than this torch raises its bare
+# AttributeError at the first one of them to reach it (#8933). It imports torch, which is
+# why the ROCm table above comes first.
+patch_torch_missing_attribute_error()
# Must precede `import unsloth_zoo` below, which imports bnb on ROCm.
fix_bitsandbytes_rocm_arch_detection()
disable_broken_causal_conv1d()
@@ -76,6 +86,8 @@ fix_torchao_torch_symbol_skew()
propagate_torchao_fix_to_subprocesses()
# Warn, do not raise: this only adds the correct remedy just before transformers prints its misleading one.
check_transformers_dependency_versions()
+# Same reason: nothing has failed yet, and a run that launches no Triton kernel never will.
+check_triton_py_ssize_t_clean()
check_fbgemm_gpu_version()
torchvision_compatibility_check()
# Ahead of `import unsloth_zoo` below, deliberately not down with the other import fixes: unsloth_zoo's
@@ -91,11 +103,13 @@ del fix_bitsandbytes_rocm_arch_detection
del disable_broken_causal_conv1d
del disable_broken_vllm
del fix_message_factory_issue
+del patch_torch_missing_attribute_error
del fix_torch_check_is_size
del fix_torchao_torch_symbol_skew
del propagate_torchao_fix_to_subprocesses
del check_fbgemm_gpu_version
del check_transformers_dependency_versions
+del check_triton_py_ssize_t_clean
del torchvision_compatibility_check
del fix_diffusers_warnings
del fix_huggingface_hub
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index ca741249663..5f56c6b5500 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -1903,6 +1903,12 @@ def _is_broken_torchvision_error(error) -> bool:
# unqualified pin swaps a working wheel for PyPI's and raises the very
# "operator torchvision::nms does not exist" it was handed out to clear.
_TORCH_BACKEND_INDEX = re.compile(r"cpu|xpu|cu\d+|rocm\d+(?:\.\d+)*", re.IGNORECASE)
+# The same families, matched as a PREFIX. A vendor build carries more than the family in its
+# local tag: this repo's AMD extras install torch-2.10.0+rocm7.2.0.lw.gitb6ee5fde and
+# triton-3.6.0+rocm7.2.0.gitba5c1517 straight from repo.radeon.com, and neither tag is an
+# index name. Those are not PyPI builds, so advice that treats them as PyPI ones would swap a
+# working Radeon wheel for the default CUDA build.
+_TORCH_BACKEND_FAMILY = re.compile(r"(cpu|xpu|cu\d+|rocm[\d.]*)", re.IGNORECASE)
# conda keeps the backend in the build string (py3.12_cuda12.4_cudnn9_0) and leaves the version
# plain, so a conda torch looks like a PyPI one by version alone; its
# conda-meta/<name>-<version>-<build>.json tells them apart.
@@ -1915,16 +1921,16 @@ def _torch_local_tag(torch_version_raw):
return torch_version_raw.split("+", 1)[1]
-def _torch_is_conda_managed(torch_version_raw):
- """Did conda install this torch, rather than pip?"""
+def _is_conda_managed(names, version_raw):
+ """Did conda install one of `names` at this version, rather than pip?"""
conda_meta = os.path.join(sys.prefix, "conda-meta")
- # A conda version never carries the +tag, but strip it so a pip torch inside a conda prefix is
+ # A conda version never carries the +tag, but strip it so a pip install inside a conda prefix is
# still matched on its release numbers.
- version = (torch_version_raw or "").split("+", 1)[0]
+ version = (version_raw or "").split("+", 1)[0]
if not version or not os.path.isdir(conda_meta):
return False
# Pinned to this exact version, so an unrelated pytorch-lightning-*.json cannot answer for torch.
- prefixes = tuple(f"{name}-{version}-" for name in _CONDA_TORCH_PACKAGES)
+ prefixes = tuple(f"{name}-{version}-" for name in names)
try:
entries = os.listdir(conda_meta)
except OSError:
@@ -1932,6 +1938,11 @@ def _torch_is_conda_managed(torch_version_raw):
return any(e.endswith(".json") and e.startswith(prefixes) for e in entries)
+def _torch_is_conda_managed(torch_version_raw):
+ """Did conda install this torch, rather than pip?"""
+ return _is_conda_managed(_CONDA_TORCH_PACKAGES, torch_version_raw)
+
+
def _has_no_matching_public_wheel(torch_version_raw):
try:
# .is_prerelease, not a substring list: 2.11.0a1 and 2.11.0b2 are prereleases no a0/b0 match would catch.
@@ -1947,6 +1958,89 @@ def _has_no_matching_public_wheel(torch_version_raw):
return not _TORCH_BACKEND_INDEX.fullmatch(local)
+def _torch_wheel_index(torch_version_raw):
+ """The ` --index-url ...` fragment that keeps an install on torch's own accelerator family.
+
+ pip's `--index-url` defaults to https://pypi.org/simple, which carries exactly one build
+ per release: the default CUDA one. A ROCm or XPU or CPU torch records its family in the
+ local version tag (2.9.0+rocm6.4, 2.9.0+xpu, 2.9.0+cpu) and every one of those builds is
+ published only under https://download.pytorch.org/whl/<tag>, so an unqualified command
+ handed to such a user swaps their working torch for an incompatible default build. An
+ absent or non-family tag means PyPI, where the unqualified command is already right.
+ """
+ local = _torch_local_tag(torch_version_raw)
+ if local and _TORCH_BACKEND_INDEX.fullmatch(local):
+ return f" --index-url https://download.pytorch.org/whl/{local.lower()}"
+ return ""
+
+
+def _torch_companion_specs():
+ """The packages that must move WITH torch, as a `"pkg" ` prefix for the upgrade command.
+
+ `pip install --upgrade` upgrades the packages it is given and nothing else, so naming
+ only torch moves torch and leaves the companion that was built against the old one. Every
+ torchvision wheel requires an exact `torch==X.Y.Z`, which is why `_torchvision_repair_command`
+ above pins the pair; a torch upgrade on its own is how the mismatch it repairs gets created
+ in the first place ("operator torchvision::nms does not exist"). Only packages that are
+ actually installed are named, so an install without torchvision gets the plain command.
+ """
+ return "".join(
+ f' "{name}"'
+ for name in ("torchvision", "torchaudio")
+ if _installed_version(name) != "unknown"
+ )
+
+
+def _torch_accelerator_note(torch_version_raw):
+ """The sentence that keeps an UPGRADE on the right accelerator, without naming an index.
+
+ A repair reinstalls the release that is already here, so the installed torch's own index
+ is guaranteed to carry it and `_torch_wheel_index` can hand over a ready command. An
+ upgrade moves to a release that index may never have had: each
+ download.pytorch.org/whl/<backend> holds only what was built for that backend, and the
+ CUDA families retire (cu124's newest torch is 2.6.0, while torch 2.7 shipped on cu126 and
+ cu128), so pinning the installed tag would hand the reported torch 2.6.0+cu124 user a
+ command with no candidate at all. Naming the family and the selector is the part that is
+ true for every release.
+ """
+ local = _torch_local_tag(torch_version_raw)
+ if not local:
+ # conda never writes a local tag, so an untagged version alone reads like a PyPI
+ # install. `pip install --upgrade torch` into a conda environment overlays the
+ # conda-managed files with a PyPI wheel, and the backend it lands on is whatever
+ # PyPI ships by default rather than the one the channel built.
+ if _torch_is_conda_managed(torch_version_raw):
+ return (
+ " conda installed this torch, so upgrade it the same way "
+ "(`conda update pytorch` on the channel it came from). `pip install "
+ "--upgrade` would overlay the conda files with a PyPI wheel and can "
+ "change the backend with them."
+ )
+ return ""
+ if not _TORCH_BACKEND_INDEX.fullmatch(local):
+ vendor = _TORCH_BACKEND_FAMILY.match(local)
+ if vendor is None:
+ return ""
+ # A tag that names a family but is not an index name is a vendor build, which is
+ # what this repo's own AMD extras install. PyPI has no such version, and neither
+ # does download.pytorch.org, so the only advice that keeps the accelerator is to
+ # go back to the source the wheel came from.
+ return (
+ f" That takes the default build from PyPI. This torch is a {local} build, "
+ f"which no public index carries, so upgrade it from wherever it came from "
+ f"(the ROCm builds unsloth's AMD extras install come from repo.radeon.com). "
+ f"An unqualified pip upgrade replaces it with the default build."
+ )
+ family = local.rstrip("0123456789.").lower()
+ family = {"cu": "CUDA", "rocm": "ROCm", "xpu": "XPU", "cpu": "CPU"}.get(family, local)
+ return (
+ f" That takes the default build from PyPI. This torch is a {local} build, and each "
+ f"https://download.pytorch.org/whl/ index carries only the releases built for it, so "
+ f"pick the {family} index for the release you are moving to at "
+ f"https://pytorch.org/get-started/locally/ and pass it as --index-url."
+ )
+
+
def _torchvision_repair_advice(required = None, torch_version_raw = None):
"""The one sentence telling the user how to repair a broken torchvision."""
if _has_no_matching_public_wheel(torch_version_raw):
@@ -1977,10 +2071,7 @@ def _torchvision_repair_command(required = None, torch_version_raw = None):
spec = f"torchvision=={required[0]}.{required[1]}.{required[2]}"
else:
spec = f"torchvision=={required[0]}.{required[1]}.*"
- local = _torch_local_tag(torch_version_raw)
- index = ""
- if local and _TORCH_BACKEND_INDEX.fullmatch(local):
- index = f" --index-url https://download.pytorch.org/whl/{local.lower()}"
+ index = _torch_wheel_index(torch_version_raw)
return f'pip install --force-reinstall --no-deps --no-cache-dir{index} "{spec}"'
@@ -2252,6 +2343,599 @@ def check_transformers_dependency_versions():
logger.warning("\n".join(lines))
+# torch releases that first provide a given attribute, used only to name the
+# upgrade in the message below. Measured against the wheels rather than guessed:
+# torch 2.6.0 has neither MX dtype and 2.8.0 has both, and both landed in 2.7.0
+# (pytorch/pytorch#146427 and #146578). An attribute that is not in here still
+# gets the diagnosis, just without a release to name, which is the point: the
+# table is a convenience and never the mechanism.
+_TORCH_ATTRIBUTE_FLOORS = {
+ "float8_e8m0fnu": "2.7.0",
+ "float4_e2m1fn_x2": "2.7.0",
+}
+
+# Packages unsloth imports and cannot add a missing torch attribute to. The same
+# AttributeError raised from user code is a typo, so it is left exactly as torch
+# wrote it.
+_TORCH_ATTRIBUTE_DEPENDENTS = frozenset(
+ (
+ "accelerate",
+ "bitsandbytes",
+ "cut_cross_entropy",
+ "diffusers",
+ "peft",
+ "torchao",
+ "torchaudio",
+ "torchvision",
+ "transformers",
+ "trl",
+ "unsloth_zoo",
+ "vllm",
+ "xformers",
+ )
+)
+
+
+class UnslothTorchTooOldError(AttributeError):
+ """The installed torch is older than a library unsloth imports needs.
+
+ An AttributeError subclass on purpose: it replaces one torch itself raised,
+ so `hasattr(torch, name)` and `getattr(torch, name, default)` keep behaving
+ exactly as they did. Only an unguarded access changes, and only by carrying
+ the diagnosis instead of four words.
+ """
+
+
[email protected]_cache(maxsize = None)
+def _installed_version(package):
+ """The installed version of `package`, or "unknown", asked at most once.
+
+ Cached because this sits on a path the interpreter takes for EVERY attribute
+ access on torch that normal lookup missed, and a missing attribute is not
+ always fatal: `hasattr(torch, name)` and `getattr(torch, name, default)` are
+ how these same libraries feature-probe, and both come through here. Measured
+ on this workspace, `importlib.metadata.version` costs about 850 microseconds
+ per call because it walks sys.path, so an uncached lookup turned a failed
+ probe from roughly 0.8 microseconds into roughly 850, a thousandfold, for a
+ string that cannot change inside one process. With the cache the wrapper is
+ back to the cost of building the message.
+ """
+ try:
+ return importlib_version(package)
+ except Exception:
+ return "unknown"
+
+
+def _torch_too_old_message(attribute, package, exception):
+ # torch.__version__ rather than the metadata version, because it carries the
+ # build (2.6.0+cu124) and that is what the user reads in every other message.
+ torch_version = getattr(sys.modules.get("torch"), "__version__", None)
+ if not torch_version:
+ torch_version = _installed_version("torch")
+ package_version = _installed_version(package)
+
+ floor = _TORCH_ATTRIBUTE_FLOORS.get(attribute)
+ requirement = f'"torch>={floor}"' if floor else '"torch"'
+
+ lines = [
+ str(exception),
+ "",
+ f"Unsloth: {package}=={package_version} uses torch.{attribute}, and the "
+ f"installed torch=={torch_version} does not have it, so this environment pairs "
+ f"a {package} with a torch that cannot serve it.",
+ ]
+ if floor is not None:
+ # A known floor is evidence of the direction: the attribute was ADDED in that
+ # release, so the torch here is the older half and upgrading it is the remedy.
+ lines += [
+ f"torch.{attribute} first appears in torch {floor}, so this torch is the "
+ f"older half.",
+ "",
+ f"Upgrade torch, which leaves {package} where it is:",
+ f" pip install --upgrade {requirement}{_torch_companion_specs()}",
+ ]
+ else:
+ # No floor is no evidence of direction. The attribute may be newer than this
+ # torch, and it may equally have been REMOVED by it, which an older dependency
+ # reaching for a retired API hits; prescribing an upgrade there is the opposite
+ # remedy. So state both directions and prescribe neither.
+ lines += [
+ "",
+ f"torch.{attribute} is not in this release's table of added attributes, so "
+ f"it is either newer than this torch or removed by it. Check which release "
+ f"of torch has torch.{attribute} at "
+ f"https://pytorch.org/docs/stable/torch.html and move whichever half is out "
+ f"of step: upgrade torch when the attribute is newer,",
+ f" pip install --upgrade {requirement}{_torch_companion_specs()}",
+ f"or install a {package} that matches this torch when the attribute is gone.",
+ ]
+ accelerator = _torch_accelerator_note(torch_version)
+ if accelerator:
+ lines.append(accelerator)
+ lines += [
+ "",
+ f"Installing a {package} that matches this torch works too. Pip allowed the "
+ f"pair because {package} declares a lower torch floor than its own modules "
+ f"actually touch, so there was nothing for the resolver to reject.",
+ ]
+ return "\n".join(lines)
+
+
+def patch_torch_missing_attribute_error():
+ """Name the torch upgrade when a dependency reaches for a dtype torch lacks.
+
+ The reported failure was a Studio training run whose transformers (5.10) was
+ newer than its torch: `import unsloth` died inside unsloth_zoo's temporary
+ patches, importing transformers.processing_utils, on a module-scope
+ `_UE8M0_SF_DTYPE = torch.float8_e8m0fnu` in
+ transformers/integrations/finegrained_fp8.py, as a bare
+
+ AttributeError: module 'torch' has no attribute 'float8_e8m0fnu'
+
+ with no mention of a version and nothing for the user to act on. Both
+ pyprojects still permit the pair, and pip cannot be made to reject it:
+ transformers declares `torch>=2.2` through `torch>=2.5` depending on the
+ release, well below what its own modules touch, so there is no floor for the
+ resolver to enforce. A static transformers-to-torch table here would be no
+ better, because it would have to be wrong somewhere: torch 2.6.0 with
+ transformers 4.57.6 is a supported combination that works.
+
+ So probe the behaviour, at the only place that knows the answer. torch
+ answers a missing attribute through a module-level __getattr__, which the
+ interpreter calls only after normal lookup has already failed, so wrapping
+ that one function costs nothing on every successful attribute access and
+ turns the one failing access into a diagnosis. Idempotent, and the original
+ stays reachable as `__unsloth_original__`.
+ """
+ try:
+ import torch
+ except Exception:
+ # A missing or broken torch has its own, clearer error further down
+ # _gpu_init.py; there is nothing to wrap here.
+ return False
+
+ original = torch.__dict__.get("__getattr__")
+ if original is None:
+ # No module-level __getattr__ to wrap, so torch raises its AttributeError
+ # from the interpreter itself and there is nothing to improve.
+ return False
+ if getattr(original, "__unsloth_patched__", False):
+ return True
+
+ @functools.wraps(original)
+ def __getattr__(name):
+ try:
+ return original(name)
+ except AttributeError as exception:
+ try:
+ # The frame that made the access, and only that one. Walking
+ # further up would blame transformers for a typo in a callback
+ # transformers happened to call.
+ requester = sys._getframe(1).f_globals.get("__name__") or ""
+ except Exception:
+ # sys._getframe is CPython-only and raises an audit event, so a
+ # hardened interpreter can refuse it. A bare `raise` here would
+ # rethrow THAT exception instead of torch's AttributeError, and
+ # `hasattr(torch, name)` only swallows AttributeError, so an
+ # ordinary feature probe would start propagating a RuntimeError.
+ # Unattributable is not fatal: leave it to torch's own error.
+ requester = ""
+ package = requester.split(".", 1)[0]
+ if package not in _TORCH_ATTRIBUTE_DEPENDENTS:
+ raise
+ raise UnslothTorchTooOldError(
+ _torch_too_old_message(name, package, exception)
+ ) from exception
+
+ __getattr__.__unsloth_patched__ = True
+ __getattr__.__unsloth_original__ = original
+ torch.__getattr__ = __getattr__
+ return True
+
+
+# The '#' argument formats in triton's CUDA driver shim need this macro, and
+# CPython stopped requiring it in 3.13.
+_PY_SSIZE_T_CLEAN = "PY_SSIZE_T_CLEAN"
+
+# `#define` / `#undef PY_SSIZE_T_CLEAN` as their own directives, anchored to the start of
+# a line so a mention inside a comment or a string literal is neither.
+_PY_SSIZE_T_CLEAN_DIRECTIVE = re.compile(
+ r"^[ \t]*#[ \t]*(define|undef)[ \t]+" + _PY_SSIZE_T_CLEAN + r"\b",
+ re.M,
+)
+_PYTHON_H_INCLUDE = re.compile(r"^[ \t]*#[ \t]*include[ \t]*[<\"][^>\"]*Python\.h[>\"]", re.M)
+
+
+_C_COMMENT_OR_STRING = re.compile(
+ r"/\*.*?\*/|//[^\n]*|\"(?:\\.|[^\"\\\n])*\"|'(?:\\.|[^'\\\n])*'",
+ re.S,
+)
+
+
+def _blank_c_spans(source: str, keep_strings: bool = False) -> str:
+ """`source` with comment spans blanked, offsets and lines intact, and string literals
+ blanked too unless `keep_strings`.
+
+ The compiler removes comments before the preprocessor ever sees a directive, so a
+ `#define PY_SSIZE_T_CLEAN` that only appears inside a `/* ... */` is not a definition
+ at all, and treating it as one silences the warning on a shim that still dies at the
+ first kernel launch. Blanked rather than deleted so every span keeps its length: the
+ scan below compares directive positions against the `#include <Python.h>` position,
+ and deleting text would move one relative to the other. Newlines are kept for the same
+ reason, since both patterns are line-anchored.
+
+ `keep_strings` is for the caller that has to read inside a literal: the PyArg_Parse
+ scan decides on the format string itself, so blanking literals would make every shim
+ look clean. String spans are still matched either way, since that is what stops a
+ `//` or a `/*` inside a literal from blanking the rest of the file.
+ """
+
+ def blank(match):
+ text = match.group(0)
+ if keep_strings and not text.startswith(("/*", "//")):
+ return text
+ return "".join("\n" if character == "\n" else " " for character in text)
+
+ return _C_COMMENT_OR_STRING.sub(blank, source)
+
+
+_PYARG_CALL = re.compile(r"PyArg_Parse\w*\(")
+_HASH_FORMAT = re.compile(r"\"[^\"]*#")
+
+
+def _parses_a_hash_format(source: str) -> bool:
+ """Does a call the compiler still sees parse a '#' format?
+
+ Two masked copies of the same offsets, because the two halves of the question need
+ opposite things. The CALL has to be real code, so it is located in the copy with both
+ comments and string literals blanked: a documentation string quoting an example
+ `PyArg_ParseTuple(args, "ss#ii", ...)` is not a call, and a commented-out one is not
+ either. The FORMAT then has to be readable, so the argument list is read from the copy
+ that blanks comments only. Blanking preserves length, so one offset serves both.
+ """
+ code_only = _blank_c_spans(source)
+ with_literals = _blank_c_spans(source, keep_strings = True)
+ for call in _PYARG_CALL.finditer(code_only):
+ end = with_literals.find(";", call.end())
+ if end == -1:
+ end = len(with_literals)
+ if _HASH_FORMAT.search(with_literals, call.end(), end):
+ return True
+ return False
+
+
+def _defines_py_ssize_t_clean_before_python_h(source: str) -> bool:
+ """Is the macro in effect where CPython needs it: defined, and still defined, at the
+ point Python.h is included.
+
+ The requirement is positional, not textual. CPython documents
+ `#define PY_SSIZE_T_CLEAN` immediately before `#include <Python.h>`; a definition
+ that lands after the include, one that is undefined again before it, and a bare
+ mention in a comment or a string literal all leave the '#' formats unsafe exactly as
+ if the macro were absent. The `token in source` test this replaces called all four of
+ those fixed, so the warning stayed silent on a shim that still dies at the first
+ kernel launch.
+
+ The LAST directive before the include is the one that decides, which is what makes
+ the `#define` / `#undef` pair read correctly rather than just the presence of either.
+ """
+ source = _blank_c_spans(source)
+ include = _PYTHON_H_INCLUDE.search(source)
+ if include is None:
+ return False
+ state = False
+ for directive in _PY_SSIZE_T_CLEAN_DIRECTIVE.finditer(source):
+ if directive.start() >= include.start():
+ break
+ state = directive.group(1) == "define"
+ return state
+
+
+# Every distribution this repository knows of that provides the `triton` import name. Only a
+# fallback for interpreters without `packages_distributions`; the mapping is asked for first
+# wherever it exists, so a provider added upstream is still found on 3.10 and later.
+# Providers published only on download.pytorch.org, so a reinstall of one needs torch's own
+# accelerator index rather than PyPI. `pytorch-triton*` is matched by prefix; these are the
+# renamed spellings that prefix no longer covers.
+_TORCH_INDEX_TRITON_PROVIDERS = ("triton-xpu", "triton-rocm")
+
+_TRITON_PROVIDERS = (
+ "triton",
+ "triton-windows",
+ "pytorch-triton",
+ "pytorch-triton-rocm",
+ "pytorch-triton-xpu",
+ # The renamed spellings. Both accelerator providers were renamed on
+ # download.pytorch.org: `pytorch-triton-rocm` stops at 3.5.1 and `triton-rocm` carries
+ # 3.7 onwards, the same split `pytorch-triton-xpu` and `triton-xpu` have. Missing here,
+ # a current ROCm or XPU shim reads as `triton==unknown` on the probing fallback, and
+ # the repair command then installs generic CUDA `triton` over the installed provider.
+ "triton-xpu",
+ "triton-rocm",
+)
+
+
+def _canonical_distribution(name):
+ """PEP 503 normalised, so `pytorch_triton_xpu` and `pytorch-triton-xpu` are one name."""
+ return re.sub(r"[-_.]+", "-", str(name)).lower()
+
+
+def _torch_required_triton_distributions():
+ """The Triton distributions the INSTALLED torch declares it needs, normalised.
+
+ torch pins its Triton by name as well as version (`triton~=3.8.0`,
+ `pytorch-triton-xpu==...`), so when a rename leaves the old dist-info in place beside
+ the new one this is the only record that says which of the two belongs to this torch.
+ Empty when torch declares none, or when its metadata cannot be read at all.
+ """
+ try:
+ from importlib.metadata import requires as _requires
+ declared = _requires("torch") or ()
+ except Exception:
+ return frozenset()
+ found = set()
+ for requirement in declared:
+ name = re.split(r"[\s;\[<>=!~(]", str(requirement).strip(), maxsplit = 1)[0]
+ if "triton" in name.lower():
+ found.add(_canonical_distribution(name))
+ return frozenset(found)
+
+
+def _distribution_owning_path(names, path):
+ """The distribution among `names` whose installed file list contains `path`, or None.
+
+ Providers can coexist: `studio/install_python_stack.py::_ensure_xpu_triton` documents
+ generic `triton` beside `pytorch-triton-xpu` on the same paths, and
+ `packages_distributions()` then reports both without saying which one last wrote the
+ file. Taking the first entry can name the CUDA provider for an XPU install and hand the
+ user a command that replaces their working Triton, which is the substitution this whole
+ helper exists to avoid. The offending `driver.c` is a concrete path, so ask which
+ distribution actually ships it.
+ """
+ if not path:
+ return None
+ try:
+ from importlib.metadata import distribution as _distribution
+ target = Path(path).resolve()
+ except Exception:
+ return None
+ claimants = []
+ for name in names:
+ try:
+ files = _distribution(name).files or ()
+ except Exception:
+ continue
+ for entry in files:
+ try:
+ if Path(entry.locate()).resolve() == target:
+ claimants.append(name)
+ break
+ except Exception:
+ continue
+ if len(claimants) == 1:
+ return claimants[0]
+ if not claimants:
+ return None
+ # Coexisting providers can both RECORD the same file, and then the first entry is
+ # nothing but ordering. Three tiebreaks, most authoritative first.
+ #
+ # 1. The distribution torch itself requires. A renamed provider leaves the old
+ # dist-info behind (`pytorch-triton-xpu` beside `triton-xpu` after an upgrade), so
+ # both claim the file and both name the backend; only torch says which one belongs
+ # to the torch that is installed.
+ required = _torch_required_triton_distributions()
+ named = [name for name in claimants if _canonical_distribution(name) in required]
+ if len(named) == 1:
+ return named[0]
+ # 2. Failing that, torch's backend family, because the harmful answer is always the one
+ # that installs a CUDA build over an accelerator one.
+ local = _torch_local_tag(getattr(sys.modules.get("torch"), "__version__", None)).lower()
+ for family in ("xpu", "rocm"):
+ if family in local:
+ matches = [name for name in claimants if family in name.lower()]
+ return matches[0] if len(matches) == 1 else None
+ # 3. And with no accelerator to preserve, the generic provider.
+ generic = [name for name in claimants if name.lower() == "triton"]
+ return generic[0] if len(generic) == 1 else None
+
+
+def _triton_distribution(offending_path = None):
+ """Which distribution owns the imported ``triton`` package, and its version.
+
+ The `triton` PyPI distribution is only one of the providers this repository supports.
+ Windows installs `triton-windows`, ROCm installs `pytorch-triton-rocm`, Intel XPU
+ installs `pytorch-triton-xpu`, and all of them land on the same `triton` import name.
+ Asking `importlib.metadata.version("triton")` on any of those raises
+ PackageNotFoundError, which is how the version used to be reported as "unknown", and
+ telling that user to `pip install --force-reinstall triton` either finds no wheel for
+ their platform or overwrites their platform build with a CUDA one.
+
+ `packages_distributions()` maps top-level import name to the distributions providing
+ it, which is the only mapping that answers this without guessing from the platform.
+ Falls back to the import name so the message still reads sensibly if the metadata is
+ missing entirely (an unpacked or vendored tree).
+ """
+ names = []
+ try:
+ from importlib.metadata import packages_distributions
+ names = list(packages_distributions().get("triton") or [])
+ except Exception:
+ names = []
+ if not names:
+ # `packages_distributions` is Python 3.10+, and pyproject still admits 3.9, where
+ # the import above raises and leaves this empty -- reporting `triton==unknown` and
+ # recommending the CUDA `triton` over the platform build, which is the exact
+ # failure this helper exists to avoid. The backport answers the same question when
+ # it is installed; when it is not, ask each provider directly, which needs no
+ # mapping at all: a provider that is not installed has no version to report.
+ try:
+ from importlib_metadata import packages_distributions as _backport
+ names = list(_backport().get("triton") or [])
+ except Exception:
+ names = []
+ if not names:
+ names = [name for name in _TRITON_PROVIDERS if _installed_version(name) != "unknown"]
+ # The distribution that actually ships the offending file wins over ordering, when the
+ # file is known and the metadata answers.
+ owner = _distribution_owning_path(names, offending_path)
+ if owner is not None:
+ names = [owner] + [name for name in names if name != owner]
+ # Prefer a provider that can actually report a version; a stale empty dist-info
+ # otherwise wins over the real one purely on ordering.
+ for name in names:
+ try:
+ return name, importlib_version(name)
+ except Exception:
+ continue
+ try:
+ return "triton", importlib_version("triton")
+ except Exception:
+ return (names[0] if names else "triton"), "unknown"
+
+
+def _triton_reinstall_command(distribution, triton_version):
+ """The pip command that repairs a broken Triton shim without changing which Triton is installed.
+
+ Pinned to the installed version, because torch pins Triton exactly (torch 2.6.0 requires
+ `triton==3.2.0`) and pip's `--force-reinstall` is documented only as "Reinstall all packages
+ even if they are already up-to-date" -- it still resolves the newest release, so the bare
+ command trades a broken-but-matching Triton for a working one torch cannot load. The
+ pytorch-triton-* providers are published only on download.pytorch.org, so those also need
+ torch's own accelerator index. An "unknown" version (vendored or stripped metadata) has no
+ pin to give, and an invented one would resolve to nothing at all, so that case stays bare.
+ """
+ index = ""
+ # `triton-xpu` as well as `pytorch-triton-*`: torch 2.10 renamed the XPU provider and
+ # pyproject pins the new name straight from download.pytorch.org (studio/setup.ps1
+ # records the rename too). Matching only the old spelling asked PyPI for `triton-xpu`,
+ # where that pinned wheel is not published at all.
+ if distribution.startswith("pytorch-triton") or distribution in _TORCH_INDEX_TRITON_PROVIDERS:
+ torch_version_raw = getattr(sys.modules.get("torch"), "__version__", None)
+ index = _torch_wheel_index(torch_version_raw)
+ if not triton_version or triton_version == "unknown":
+ spec = distribution
+ else:
+ spec = f'"{distribution}=={triton_version}"'
+ return f"pip install --force-reinstall --no-cache-dir{index} {spec}"
+
+
+def _triton_repair_advice(distribution, triton_version):
+ """How to repair this Triton, as one line, or two when no index can serve it.
+
+ A pip command only helps when some index publishes the pinned version. The AMD extras
+ install `triton==3.6.0+rocm7.2.0.gitba5c1517` from a repo.radeon.com URL under the
+ plain `triton` name, and neither PyPI nor download.pytorch.org has that version at
+ all, so a pinned command there resolves to nothing. Name the source instead, the same
+ way the torchvision advice does for a torch with no public wheel.
+ """
+ command = _triton_reinstall_command(distribution, triton_version)
+ if _is_conda_managed((distribution,), triton_version):
+ # conda-forge publishes `triton`, and a pip --force-reinstall over a conda-managed
+ # one overlays conda's own files with a wheel, leaving two package managers owning
+ # the same paths. Same reasoning, and same remedy shape, as the conda branch of the
+ # torch upgrade advice.
+ return (
+ f"conda installed this Triton, so repair it the same way "
+ f"(`conda install --force-reinstall {distribution}={triton_version}` on the "
+ f"channel it came from). A pip reinstall would overlay the conda files with a "
+ f"wheel and can change the backend with them."
+ )
+ local = (triton_version or "").split("+", 1)[1] if "+" in (triton_version or "") else ""
+ if local and "--index-url" not in command:
+ return (
+ f"Reinstall the Triton your torch pins from wherever this one came from: the "
+ f"+{local} tag marks a vendor build that no public index publishes (unsloth's "
+ f"AMD extras take theirs from repo.radeon.com), so a pinned pip command "
+ f"resolves to nothing:\n {command}"
+ )
+ return f"Reinstall the Triton your torch pins:\n {command}"
+
+
+def _triton_driver_shims_missing_py_ssize_t_clean():
+ """Installed triton backend driver shims that cannot parse their own
+ arguments on this interpreter, as [(backend, path), ...].
+
+ Static, because the failure is a property of the C source triton compiles at
+ run time: `loadBinary` parses with the format "ss#ii" into a Py_ssize_t, and
+ CPython below 3.13 raises SystemError for a '#' format unless the extension
+ was compiled with PY_SSIZE_T_CLEAN defined before Python.h.
+ """
+ if sys.version_info >= (3, 13):
+ return []
+ try:
+ spec = importlib.util.find_spec("triton")
+ except Exception:
+ return []
+ if spec is None or not spec.submodule_search_locations:
+ return []
+
+ offenders = []
+ for location in spec.submodule_search_locations:
+ backends = Path(location) / "backends"
+ if not backends.is_dir():
+ continue
+ for driver in sorted(backends.glob("*/driver.c")):
+ try:
+ source = driver.read_text(encoding = "utf-8", errors = "replace")
+ except Exception:
+ continue
+ if "Python.h" not in source:
+ continue
+ if _defines_py_ssize_t_clean_before_python_h(source):
+ continue
+ if not _parses_a_hash_format(source):
+ continue
+ offenders.append((driver.parent.name, str(driver)))
+ return offenders
+
+
+def check_triton_py_ssize_t_clean():
+ """Warn when triton's driver shim will fail at the first kernel launch.
+
+ unsloth #2760: training died at the first Triton kernel with
+
+ SystemError: PY_SSIZE_T_CLEAN macro must be defined for '#' formats
+
+ raised from `driver.active.utils.load_binary`, on Python 3.12. Measured
+ against the wheels, every triton on PyPI from 3.0.0 to 3.8.0 defines the
+ macro in `backends/<backend>/driver.c`, so raising the `triton>=3.0.0` floor
+ in pyproject.toml would not have prevented this and cannot: torch pins triton
+ exactly (torch 2.6.0 requires `triton==3.2.0`), so any floor above what the
+ oldest supported torch carries makes that torch unresolvable rather than
+ safe. What is actually broken in these reports is a rebuilt or repackaged
+ triton whose shim lost the macro, which no dependency specifier can describe,
+ so name it here instead. Warns rather than raises: nothing has failed yet,
+ and a process that launches no Triton kernel never will.
+ """
+ if os.environ.get("UNSLOTH_SKIP_TRITON_SHIM_CHECK", "0").lower() in ("1", "true"):
+ return
+ try:
+ offenders = _triton_driver_shims_missing_py_ssize_t_clean()
+ except Exception:
+ return
+ if not offenders:
+ return
+
+ distribution, triton_version = _triton_distribution(offenders[0][1] if offenders else None)
+ python_version = ".".join(str(part) for part in sys.version_info[:3])
+ reinstall = _triton_repair_advice(distribution, triton_version)
+
+ logger.warning(
+ f"Unsloth: {distribution}=={triton_version} ships a "
+ f"{', '.join(backend for backend, _ in offenders)} driver shim that includes "
+ f"Python.h without defining {_PY_SSIZE_T_CLEAN}, and Python {python_version} "
+ f"requires that macro for the '#' argument formats the shim uses. The first "
+ f"Triton kernel launch in this process will fail with\n"
+ f" SystemError: {_PY_SSIZE_T_CLEAN} macro must be defined for '#' formats\n"
+ f"Every published Triton build defines it, so this is a rebuilt or repackaged one. "
+ f"{reinstall}\n"
+ f"Python 3.13 and later do not need the macro, so moving to a newer Python "
+ f"also clears it. Affected file(s): "
+ f"{', '.join(path for _, path in offenders)}. Set "
+ f"UNSLOTH_SKIP_TRITON_SHIM_CHECK=1 to silence this."
+ )
+
+
# Fix TRL OpenEnv 0.26 NameError: name 'SamplingParams' is not defined
def fix_openenv_no_vllm():
spec = importlib.util.find_spec("trl")
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 65e7a6b894c..1484ec5429a 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -914,14 +914,31 @@ def resolve_encoder_attention_implementation(
def _run_temporary_patches(phase):
import inspect
for temporary_patch in TEMPORARY_PATCHES:
+ # Two separate questions, kept separate. inspect.signature raises
+ # ValueError or TypeError for a callable whose signature it cannot read,
+ # which only tells us we cannot see a `phase` parameter; catching those
+ # around the CALL as well re-ran a patch that had already half applied,
+ # and let every other exception out of an optional patch step and
+ # straight through `import unsloth` (#3130 ended the import
+ # on a SyntaxError from one of them). A temporary patch is an
+ # optimisation that reports its own failures through raise_error, so a
+ # patch that raises anyway is logged, not fatal.
try:
- sig = inspect.signature(temporary_patch)
- if "phase" in sig.parameters:
+ accepts_phase = "phase" in inspect.signature(temporary_patch).parameters
+ except (ValueError, TypeError):
+ accepts_phase = False
+ try:
+ if accepts_phase:
temporary_patch(phase = phase)
else:
temporary_patch()
- except (ValueError, TypeError):
- temporary_patch()
+ except Exception as exception:
+ logger.warning(
+ f"Unsloth: temporary patch "
+ f"{getattr(temporary_patch, '__name__', temporary_patch)} failed in "
+ f"phase {phase} and was skipped. "
+ f"({type(exception).__name__}: {exception})"
+ )
_run_temporary_patches("init")