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.

Import without Triton: define Unsloth's kernels against the zoo triton stub, visible to unsloth only (#15346)

Daniel Han7083076af3e3
diff --git a/tests/test_import_without_triton.py b/tests/test_import_without_triton.py
new file mode 100644
index 00000000000..d1f04e4bb68
--- /dev/null
+++ b/tests/test_import_without_triton.py
@@ -0,0 +1,71 @@
+# 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
+import sys
+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__
+
+ def _find_spec(cls, name, path = None, target = None):
+ if name == "triton" or name.startswith("triton."):
+ return None
+ return _find(cls, name, path, target)
+
+ importlib.machinery.PathFinder.find_spec = classmethod(_find_spec)
+ for _k in [k for k in sys.modules if k == "triton" or k.startswith("triton.")]:
+ del sys.modules[_k]
+""")
+
+_CHECK = textwrap.dedent("""
+ import builtins, importlib.util, sys
+ real_import = builtins.__import__
+ import unsloth # noqa: F401
+ import unsloth.kernels.cross_entropy_loss as ce
+ from unsloth_zoo.stubs import triton_stub
+ assert builtins.__import__ is real_import
+ assert importlib.util.find_spec("triton") is None
+ assert not [k for k in sys.modules if k == "triton" or k.startswith("triton.")]
+ assert ce.triton is triton_stub
+ holders = [n for n, m in list(sys.modules.items())
+ if m is not None and not n.startswith(("unsloth", "__main__", "__mp_main__"))
+ and any(v is triton_stub or type(v).__module__ == triton_stub.__name__ for v in list(vars(m).values()))]
+ assert not holders, holders
+ import unsloth_zoo.fused_losses.fused_linear as fl
+ assert not fl._HAS_TRITON
+ print("NO_TRITON_OK")
+""")
+
+
+def test_unsloth_imports_without_triton():
+ 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")
+ # UNSLOTH_ALLOW_CPU keeps the GPU import path (models, kernels) on a host without a GPU.
+ env = dict(os.environ, CUDA_VISIBLE_DEVICES = "", UNSLOTH_ALLOW_CPU = "1")
+ # That variable also installs zoo's global stub (download-only child), which this test must not see.
+ env.pop("UNSLOTH_ZOO_DISABLE_GPU_INIT", None)
+ out = subprocess.run(
+ [sys.executable, "-c", _NO_TRITON + _CHECK],
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 900,
+ )
+ assert out.returncode == 0 and "NO_TRITON_OK" in out.stdout, (
+ out.stdout[-2000:],
+ out.stderr[-4000:],
+ )
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index e31c3f88625..bb7c52afe15 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -623,9 +623,15 @@ try:
except Exception as _triton_import_exception:
triton = None
TRITON_IMPORT_ERROR = f"{type(_triton_import_exception).__name__}: {_triton_import_exception}"
+ # No Triton package at all (AMD Windows wheels), not an installed but broken one.
+ _TRITON_MISSING = (
+ isinstance(_triton_import_exception, ModuleNotFoundError)
+ and _triton_import_exception.name == "triton"
+ )
del _triton_import_exception
else:
TRITON_IMPORT_ERROR = None
+ _TRITON_MISSING = False
if TRITON_IMPORT_ERROR is not None:
if DEVICE_TYPE in ("cuda", "hip") and torch.cuda.is_available():
@@ -766,12 +772,68 @@ from .import_fixes import patch_bitsandbytes_optimizer_step_sync
patch_bitsandbytes_optimizer_step_sync()
del patch_bitsandbytes_optimizer_step_sync
-from .models import *
-from .models import __version__
-from .save import *
-from .chat_templates import *
-from .tokenizer_utils import *
-from .trainer import *
+
+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
+
+ real_import = builtins.__import__
+
+ def _import(
+ name,
+ globals = None,
+ locals = None,
+ fromlist = (),
+ level = 0,
+ ):
+ importer = (globals or {}).get("__name__") or ""
+ if (
+ level
+ or not (name == "triton" or name.startswith("triton."))
+ 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]
+
+ builtins.__import__ = _import
+
+ def remove():
+ if builtins.__import__ is _import:
+ builtins.__import__ = real_import
+
+ return remove
+
+
+_remove_triton_stub = _define_kernels_against_triton_stub() if _TRITON_MISSING else None
+try:
+ from .models import *
+ from .models import __version__
+ from .save import *
+ from .chat_templates import *
+ from .tokenizer_utils import *
+ from .trainer import *
+finally:
+ # Also on a failed import: the hook must never outlive `import unsloth`.
+ if _remove_triton_stub is not None:
+ _remove_triton_stub()
+del _define_kernels_against_triton_stub, _remove_triton_stub
# Export dataprep utilities for CLI and downstream users
from .dataprep.raw_text import RawTextDataLoader, TextPreprocessor
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index 96586d5661b..243d763f93f 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -218,7 +218,10 @@ try:
except:
# Old HF Hub versions <= 0.0.25.
from huggingface_hub.utils._token import get_token
-from triton import __version__ as triton_version
+try:
+ from triton import __version__ as triton_version
+except ImportError: # AMD Windows wheels ship no Triton
+ triton_version = None
# Not xformers is not None: HAS_XFORMERS is off when no kernel runs here, and then Mistral skips its sliding-window mask
BlockDiagonalCausalMask = xformers.attn_bias.BlockDiagonalCausalMask if HAS_XFORMERS else None
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 4072b3934db..51a10e99f9e 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -348,7 +348,11 @@ from unsloth_zoo.peft_utils import (
)
from transformers.models.llama.modeling_llama import logger
from transformers import __version__ as transformers_version
-from triton import __version__ as triton_version
+
+try:
+ from triton import __version__ as triton_version
+except ImportError: # AMD Windows wheels ship no Triton
+ triton_version = None
from unsloth_zoo.utils import _get_dtype
from unsloth_zoo.hf_utils import (
dtype_from_config,