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.

Key triton < 3.4 driver module cache by Python version (#13409)

Daniel Han0651282e2071
diff --git a/tests/test_triton_module_cache_key.py b/tests/test_triton_module_cache_key.py
new file mode 100644
index 00000000000..f7fd94778d5
--- /dev/null
+++ b/tests/test_triton_module_cache_key.py
@@ -0,0 +1,93 @@
+# 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/>.
+"""#2760: triton < 3.4 reused a driver module another Python version compiled."""
+
+import importlib.util
+import sys
+import sysconfig
+import textwrap
+import types
+
+from unsloth import import_fixes
+
+
+_TRITON_33_DRIVER = textwrap.dedent(
+ """
+ seen = []
+
+ def compile_module_from_src(src, name):
+ seen.append((src, name))
+ return name
+
+ class CudaDriver:
+ def __init__(self):
+ self.utils = compile_module_from_src("driver.c source", "cuda_utils")
+ """
+)
+
+_TRITON_34_DRIVER = textwrap.dedent(
+ """
+ from keyed_build import compile_module_from_src
+
+ class CudaDriver:
+ def __init__(self):
+ self.utils = compile_module_from_src("driver.c source", "cuda_utils")
+ """
+)
+
+
+def _install_backend(monkeypatch, tmp_path, source):
+ # Load the way triton.backends does: spec_from_file_location, never in sys.modules.
+ path = tmp_path / "driver.py"
+ path.write_text(source, encoding = "utf-8")
+ spec = importlib.util.spec_from_file_location("nvidia", path)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ registry = types.ModuleType("triton.backends")
+ registry.backends = {"nvidia": types.SimpleNamespace(driver = module.CudaDriver)}
+ monkeypatch.setitem(sys.modules, "triton.backends", registry)
+ monkeypatch.setattr(import_fixes.importlib.util, "find_spec", lambda name: object())
+ return module
+
+
+def test_triton_33_driver_modules_are_keyed_by_python(monkeypatch, tmp_path):
+ module = _install_backend(monkeypatch, tmp_path, _TRITON_33_DRIVER)
+ import_fixes.fix_triton_module_cache_python_key()
+ import_fixes.fix_triton_module_cache_python_key()
+
+ assert module.CudaDriver().utils == "cuda_utils"
+ ((src, name),) = module.seen
+ assert name == "cuda_utils"
+ assert src.startswith("driver.c source")
+ assert sysconfig.get_config_var("EXT_SUFFIX") in src
+ assert src.count("unsloth:") == 1
+ assert not getattr(module.compile_module_from_src.__wrapped__, "__unsloth_patched__", False)
+
+
+def test_triton_34_keyed_build_is_left_alone(monkeypatch, tmp_path):
+ keyed = types.ModuleType("keyed_build")
+
+ def compile_module_from_src(src, name):
+ return src
+
+ compile_module_from_src.__module__ = "keyed_build"
+ keyed.compile_module_from_src = compile_module_from_src
+ monkeypatch.setitem(sys.modules, "keyed_build", keyed)
+ module = _install_backend(monkeypatch, tmp_path, _TRITON_34_DRIVER)
+
+ import_fixes.fix_triton_module_cache_python_key()
+ assert module.compile_module_from_src is compile_module_from_src
+ assert module.CudaDriver().utils == "driver.c source"
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 220967ee5ce..37537bbcafa 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -24,6 +24,7 @@ from .import_fixes import (
fix_message_factory_issue,
patch_torch_missing_attribute_error,
check_triton_py_ssize_t_clean,
+ fix_triton_module_cache_python_key,
check_transformers_prequantized_vlm_quant_state,
fix_torch_check_is_size,
fix_torchao_torch_symbol_skew,
@@ -100,6 +101,8 @@ propagate_torchao_fix_to_subprocesses()
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()
+# Before triton's driver first compiles and caches cuda_utils (#2760).
+fix_triton_module_cache_python_key()
check_fbgemm_gpu_version()
torchvision_compatibility_check()
# Ahead of `import unsloth_zoo` below, deliberately not down with the other import fixes: unsloth_zoo's
@@ -122,6 +125,7 @@ del propagate_torchao_fix_to_subprocesses
del check_fbgemm_gpu_version
del check_transformers_dependency_versions
del check_triton_py_ssize_t_clean
+del fix_triton_module_cache_python_key
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 2fe18c166fa..62be4fb7ed9 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -6580,9 +6580,10 @@ def check_triton_py_ssize_t_clean():
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,
+ safe. The reported failures come from a stale cached shim built by Python
+ 3.13 (fixed by `fix_triton_module_cache_python_key`); this names the rarer
+ rebuilt or repackaged triton whose shim lost the macro, which no dependency
+ specifier can describe. 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"):
@@ -6614,6 +6615,44 @@ def check_triton_py_ssize_t_clean():
)
+def fix_triton_module_cache_python_key():
+ """#2760: triton 3.2 / 3.3 cache `cuda_utils.so` and launchers by C source hash alone, so
+ Python 3.12 reuses a 3.13 build and the first launch raises `SystemError: PY_SSIZE_T_CLEAN
+ macro must be defined for '#' formats`. Tag the source with EXT_SUFFIX, as triton 3.4 keys it.
+ """
+ try:
+ if importlib.util.find_spec("triton") is None:
+ return
+ from triton.backends import backends
+ except Exception:
+ return
+ tag = f"\n/* unsloth: {sysconfig.get_config_var('EXT_SUFFIX') or sys.implementation.cache_tag} */\n"
+ for backend in backends.values():
+ # Backend drivers load outside sys.modules: patch the defining module via its globals.
+ namespace = getattr(getattr(backend.driver, "__init__", None), "__globals__", None)
+ if not isinstance(namespace, dict):
+ continue
+ original = namespace.get("compile_module_from_src")
+ # 3.4+ imports the EXT_SUFFIX-keyed one from triton.runtime.build.
+ if not callable(original) or getattr(original, "__unsloth_patched__", False):
+ continue
+ if getattr(original, "__module__", None) != namespace.get("__name__"):
+ continue
+
+ def compile_module_from_src(
+ src,
+ name,
+ *args,
+ _original = original,
+ **kwargs,
+ ):
+ return _original(src + tag, name, *args, **kwargs)
+
+ functools.update_wrapper(compile_module_from_src, original)
+ compile_module_from_src.__unsloth_patched__ = True
+ namespace["compile_module_from_src"] = compile_module_from_src
+
+
def _transformers_rescopes_submodule_prefix_renamings():
"""True when this build scopes a nested submodule's conversions to where it lives.