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
Diagnose torch and triton version skew at import time (#11023)
Daniel Hanb07e4666760f
diff --git a/pyproject.toml b/pyproject.tomlindex 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.pynew file mode 100644index 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 commanddiff --git a/unsloth/__init__.py b/unsloth/__init__.pyindex 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.pyindex 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_detectiondel disable_broken_causal_conv1ddel disable_broken_vllmdel fix_message_factory_issue+del patch_torch_missing_attribute_errordel fix_torch_check_is_sizedel fix_torchao_torch_symbol_skewdel propagate_torchao_fix_to_subprocessesdel check_fbgemm_gpu_versiondel check_transformers_dependency_versions+del check_triton_py_ssize_t_cleandel torchvision_compatibility_checkdel fix_diffusers_warningsdel fix_huggingface_hubdiff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.pyindex 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 defineddef fix_openenv_no_vllm():spec = importlib.util.find_spec("trl")diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.pyindex 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 inspectfor 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")