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
install-kernels: skip the torch import when a kernel's extension is absent, and probe torch only when a wheel is needed (#15896)
Daniel Hancd10deffe18e
diff --git a/studio/backend/tests/test_kernel_install_probe_count.py b/studio/backend/tests/test_kernel_install_probe_count.pynew file mode 100644index 00000000000..b8562c50cba--- /dev/null+++ b/studio/backend/tests/test_kernel_install_probe_count.py@@ -0,0 +1,107 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""`unsloth install-kernels` spends no torch import on a check whose answer is already known."""++from __future__ import annotations++import os+import subprocess+import sys+from pathlib import Path++import pytest++_BACKEND = Path(__file__).resolve().parent.parent+if str(_BACKEND) not in sys.path:+ sys.path.insert(0, str(_BACKEND))++from utils import kernel_install # noqa: E402++# Where each check's extension lives in a fake site: (relative path, source).+_PRESENT = {+ "xformers": [+ ("xformers/__init__.py", ""),+ ("xformers/_cpp_lib.py", "import torch\n\n\ndef _register_extensions():\n pass\n"),+ ],+ "flash_attn": [("flash_attn_2_cuda.py", "")],+ "causal_conv1d": [("causal_conv1d_cuda.py", "")],+ "mamba_ssm": [("selective_scan_cuda.py", "")],+}+++def _site(+ tmp_path,+ *,+ kernel = None,+ broken = False,+ torch_ok = True,+):+ """A PYTHONPATH with a fake torch that records its import, plus *kernel*'s extension."""+ site = tmp_path / "site"+ (site / "torch").mkdir(parents = True)+ marker = tmp_path / "torch_imported"+ (site / "torch" / "__init__.py").write_text(+ f"open({str(marker)!r}, 'a').write('x')\n"+ + ("" if torch_ok else "raise ImportError('no torch')\n")+ )+ files = _PRESENT.get(kernel, [])+ for i, (rel, source) in enumerate(files):+ path = site / rel+ path.parent.mkdir(parents = True, exist_ok = True)+ # The extension itself (last file) fails to load, after it imported torch.+ last = i == len(files) - 1+ path.write_text(+ source + ("raise ImportError('undefined symbol')\n" if broken and last else "")+ )+ env = dict(os.environ, PYTHONPATH = str(site))+ return env, marker+++def _run_check(name, env, tmp_path):+ return subprocess.run(+ # -S: only the fake site, so a real xformers / torch in this venv cannot answer.+ [sys.executable, "-S", "-c", kernel_install._load_check(name)],+ env = env,+ cwd = tmp_path,+ stdout = subprocess.DEVNULL,+ stderr = subprocess.DEVNULL,+ ).returncode++[email protected]("name", list(kernel_install.KERNELS))+def test_an_absent_extension_fails_without_importing_torch(tmp_path, name):+ env, marker = _site(tmp_path)+ assert _run_check(name, env, tmp_path) != 0+ assert not marker.exists()++[email protected]("name", list(kernel_install.KERNELS))+ "broken, torch_ok, loads",+ [(False, True, True), (True, True, False), (False, False, False)],+)+def test_a_present_extension_still_gets_the_full_check(tmp_path, name, broken, torch_ok, loads):+ env, marker = _site(tmp_path, kernel = name, broken = broken, torch_ok = torch_ok)+ assert (_run_check(name, env, tmp_path) == 0) is loads+ assert marker.exists()+++def test_main_probes_torch_only_when_a_kernel_needs_a_wheel(monkeypatch):+ probes = []++ def probe(**kwargs):+ probes.append(kwargs)+ return None++ monkeypatch.setattr(kernel_install, "probe_torch_wheel_env", probe)+ monkeypatch.setattr(kernel_install, "_installed_version", lambda distribution: "1.0")+ monkeypatch.setattr(kernel_install, "_loads", lambda check, run: True)+ assert kernel_install.main([]) == 0+ assert probes == []++ # One kernel without a working copy: probed once, and later kernels reuse the answer.+ monkeypatch.setattr(kernel_install, "_installed_version", lambda distribution: None)+ monkeypatch.setattr(kernel_install, "package_installs_offline_env", lambda: False)+ assert kernel_install.main([]) == 0+ assert probes == [{"timeout": 120, "include_windows": True}]diff --git a/studio/backend/utils/kernel_install.py b/studio/backend/utils/kernel_install.pyindex 8abfbe8b3c5..490dfd8eca4 100644--- a/studio/backend/utils/kernel_install.py+++ b/studio/backend/utils/kernel_install.py@@ -391,6 +391,28 @@ KERNELS = {"causal_conv1d": ("causal-conv1d", "import torch, causal_conv1d_cuda"),"mamba_ssm": ("mamba-ssm", "import torch, selective_scan_cuda"),}+_CHECKED_MODULE = {+ "xformers": "xformers",+ "flash_attn": "flash_attn_2_cuda",+ "causal_conv1d": "causal_conv1d_cuda",+ "mamba_ssm": "selective_scan_cuda",+}+++def _load_check(name: str) -> str:+ """KERNELS[name]'s check, exiting 1 before the ~2 s torch import when no path finds its module+ (torch adds no path or finder). A raising find_spec leaves it to the check."""+ return (+ "import importlib.util, sys\n"+ "try:\n"+ f" absent = importlib.util.find_spec({_CHECKED_MODULE[name]!r}) is None\n"+ "except Exception:\n"+ " absent = False\n"+ "if absent:\n"+ " sys.exit(1)\n"+ f"{KERNELS[name][1]}"+ )+_PINNED = {"causal_conv1d": CAUSAL_CONV1D, "mamba_ssm": MAMBA_SSM}_WITHOUT_GPU_ENV = "UNSLOTH_INSTALL_KERNELS_WITHOUT_GPU"@@ -551,7 +573,7 @@ def _uninstall(distribution: str, run: Callable[..., subprocess.CompletedProcessdef install_kernel(name: str,- env: dict[str, str] | None,+ env: dict[str, str] | None | Callable[[], dict[str, str] | None],*,dry_run: bool = False,run: Callable[..., subprocess.CompletedProcess] = subprocess.run,@@ -561,7 +583,8 @@ def install_kernel() -> int:# install_without_gpu: no visible GPU yet (an image build for the GPU it will run on) still# installs. Each kernel left uninstalled for this machine is appended to *skipped*.- distribution, check = KERNELS[name]+ distribution = KERNELS[name][0]+ check = _load_check(name)def skip(message: str) -> int:print(message)@@ -580,6 +603,9 @@ def install_kernel(f"Unsloth: not installing {name} while offline ""(UV_OFFLINE / HF_HUB_OFFLINE / TRANSFORMERS_OFFLINE).")+ # A callable env is probed only here, so a kernel that already loads costs no torch probe.+ if callable(env):+ env = env()url = resolve_wheel_url(name, env)if name in _GPU_GATED and url is not None:capability = _gpu_capability(run)@@ -686,7 +712,13 @@ def main(argv: list[str] | None = None) -> int:"yes","on",)- env = probe_torch_wheel_env(timeout = 120, include_windows = True)+ probed: list[dict[str, str] | None] = []++ def env() -> dict[str, str] | None:+ if not probed:+ probed.append(probe_torch_wheel_env(timeout = 120, include_windows = True))+ return probed[0]+status = 0skipped: list[str] = []for name in [name for name in KERNELS if not args.kernels or name in args.kernels]: