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
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.pynew file mode 100644index 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.pyindex 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 = NoneTRITON_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_exceptionelse:TRITON_IMPORT_ERROR = None+ _TRITON_MISSING = Falseif 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_syncpatch_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 usersfrom .dataprep.raw_text import RawTextDataLoader, TextPreprocessordiff --git a/unsloth/models/llama.py b/unsloth/models/llama.pyindex 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 maskBlockDiagonalCausalMask = xformers.attn_bias.BlockDiagonalCausalMask if HAS_XFORMERS else Nonediff --git a/unsloth/models/vision.py b/unsloth/models/vision.pyindex 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 loggerfrom 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 = Nonefrom unsloth_zoo.utils import _get_dtypefrom unsloth_zoo.hf_utils import (dtype_from_config,