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.

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.py
new file mode 100644
index 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.py
index 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.CompletedProcess
def 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 = 0
skipped: list[str] = []
for name in [name for name in KERNELS if not args.kernels or name in args.kernels]: