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.

No-Triton import: hand the triton stub to unsloth importers without publishing it (#15576)

Daniel Han74bc04a72e83
diff --git a/tests/test_import_without_triton.py b/tests/test_import_without_triton.py
index d1f04e4bb68..c285961569e 100644
--- a/tests/test_import_without_triton.py
+++ b/tests/test_import_without_triton.py
@@ -1,7 +1,5 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-"""AMD Windows wheels ship no Triton: `import unsloth` must still work. Unsloth's own kernel modules see unsloth_zoo's
-triton stub while they are defined; no other module may see it afterwards."""
import os
import subprocess
@@ -10,7 +8,6 @@ import textwrap
import pytest
-# Triton made unfindable for the child, as on a host where the package is not installed.
_NO_TRITON = textwrap.dedent("""
import importlib.machinery, sys
_find = importlib.machinery.PathFinder.find_spec.__func__
@@ -69,3 +66,101 @@ def test_unsloth_imports_without_triton():
out.stdout[-2000:],
out.stderr[-4000:],
)
+
+
+_CONCURRENT = textwrap.dedent("""
+ import ast, builtins, importlib.util, os, sys, textwrap, threading
+ from unsloth_zoo.stubs import triton_stub
+
+ path = os.path.join(importlib.util.find_spec("unsloth").submodule_search_locations[0], "_gpu_init.py")
+ tree = ast.parse(open(path, encoding = "utf-8").read())
+ node = next(n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name == "_define_kernels_against_triton_stub")
+ ns = {"sys": sys}
+ exec(compile(ast.Module(body = [node], type_ignores = []), path, "exec"), ns)
+
+ real_import = builtins.__import__
+ checkpoint, release = threading.Event(), threading.Event()
+
+ def paused_import(name, globals = None, locals = None, fromlist = (), level = 0):
+ if name.split(".")[0] == "triton" and (globals or {}).get("__name__", "").startswith("unsloth."):
+ checkpoint.set()
+ assert release.wait(30)
+ return real_import(name, globals, locals, fromlist, level)
+
+ builtins.__import__ = paused_import
+ meta_path = list(sys.meta_path)
+ remove = ns["_define_kernels_against_triton_stub"]()
+ kernel = {"__name__": "unsloth.kernels.example"}
+
+ def define_kernels():
+ try:
+ exec("import triton", kernel)
+ finally:
+ checkpoint.set()
+
+ worker = threading.Thread(target = define_kernels)
+ worker.start()
+ assert checkpoint.wait(30)
+ outsider = {"__name__": "some_library"}
+ try:
+ exec("import triton", outsider)
+ except ModuleNotFoundError:
+ pass
+ leaked = [k for k in sys.modules if k == "triton" or k.startswith("triton.")]
+ finders = [f for f in sys.meta_path if f not in meta_path]
+ release.set()
+ worker.join(30)
+ assert outsider.get("triton") is None, "another thread received the triton stub"
+ assert not leaked and not finders, (leaked, finders)
+ assert kernel["triton"] is triton_stub
+
+ # Every import form an unsloth.* module uses, handed the stub without publishing it.
+ forms = '''
+ import triton
+ import triton.language as tl
+ import triton.language
+ from triton import jit, cdiv
+ from triton.language import constexpr
+ from triton.language.extra import libdevice
+ import triton.runtime.jit as rjit
+ import triton.experimental.deep.module as deep
+ from triton.experimental.deep import module as deep2
+ '''
+ mod = {"__name__": "unsloth.kernels.forms"}
+ exec(textwrap.dedent(forms), mod)
+ assert mod["triton"] is triton_stub and mod["tl"] is triton_stub.language
+ assert mod["jit"] is triton_stub.jit and mod["cdiv"] is triton_stub.cdiv
+ assert mod["constexpr"] is triton_stub._ConstExpr
+ assert mod["rjit"] is triton_stub.runtime.jit
+ assert mod["deep"].__name__ == "triton.experimental.deep.module" and mod["deep2"] is mod["deep"]
+ assert repr(mod["libdevice"]).startswith("<triton_stub")
+ assert not [k for k in sys.modules if k == "triton" or k.startswith("triton.")]
+ assert sys.meta_path == meta_path
+ remove()
+ assert builtins.__import__ is paused_import
+ print("NO_TRITON_CONCURRENT_OK")
+""")
+
+
+def test_triton_stub_never_reaches_other_importers():
+ try:
+ import unsloth_zoo.stubs.triton_stub # noqa: F401
+ except ImportError:
+ pytest.skip("unsloth_zoo has no triton stub")
+ import unsloth_zoo
+
+ if getattr(unsloth_zoo, "DEVICE_TYPE", None) == "mlx":
+ pytest.skip("Apple Silicon / MLX stubs Triton for every importer by design")
+ env = dict(os.environ, CUDA_VISIBLE_DEVICES = "", UNSLOTH_ALLOW_CPU = "1")
+ env.pop("UNSLOTH_ZOO_DISABLE_GPU_INIT", None)
+ out = subprocess.run(
+ [sys.executable, "-c", _NO_TRITON + _CONCURRENT],
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 900,
+ )
+ assert out.returncode == 0 and "NO_TRITON_CONCURRENT_OK" in out.stdout, (
+ out.stdout[-2000:],
+ out.stderr[-4000:],
+ )
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index d9b60fe21e2..4d22588c5de 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -787,16 +787,28 @@ del patch_bitsandbytes_optimizer_step_sync
def _define_kernels_against_triton_stub():
- """Unsloth's kernel modules define @triton.jit kernels at import. With no Triton package, a triton import made
- by an unsloth.* module resolves to unsloth_zoo's triton stub (calling a kernel raises); every other importer
- still sees no Triton, so no library mistakes the stub for a real one. Returns the undo callable."""
try:
from unsloth_zoo.stubs import triton_stub
except ImportError:
return None
import builtins
+ import threading
+ import types
real_import = builtins.__import__
+ lock = threading.Lock()
+
+ def _stub_module(name):
+ # Unknown attributes of a stub module are no-ops, not submodules, so create missing ones explicitly.
+ module = triton_stub
+ with lock:
+ for i, part in enumerate(name.split(".")[1:], start = 2):
+ child = vars(module).get(part)
+ if not isinstance(child, types.ModuleType):
+ child = triton_stub._make_module(".".join(name.split(".")[:i]))
+ setattr(module, part, child)
+ module = child
+ return module
def _import(
name,
@@ -812,18 +824,8 @@ def _define_kernels_against_triton_stub():
or importer.split(".")[0] != "unsloth"
):
return real_import(name, globals, locals, fromlist, level)
- meta_path, modules = list(sys.meta_path), set(sys.modules)
- triton_stub.inject_into_sys_modules()
- try:
- return real_import(name, globals, locals, fromlist, level)
- finally:
- sys.meta_path[:] = meta_path
- for key in [
- k
- for k in sys.modules
- if (k == "triton" or k.startswith("triton.")) and k not in modules
- ]:
- del sys.modules[key]
+ module = _stub_module(name)
+ return module if fromlist else triton_stub
builtins.__import__ = _import