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: add flash-attn and install every kernel by default (#12744)
Daniel Han33f100b40417
diff --git a/studio/backend/tests/test_kernel_install.py b/studio/backend/tests/test_kernel_install.pyindex 5edee61d5a9..4e01ddaf572 100644--- a/studio/backend/tests/test_kernel_install.py+++ b/studio/backend/tests/test_kernel_install.py@@ -105,12 +105,19 @@ def test_causal_conv1d_has_no_wheel_off_linux_cuda(env):class _Runner:- def __init__(self, loads):+ def __init__(+ self,+ loads,+ capability = "9 0",+ ):self.loads = list(loads)+ self.capability = capabilityself.calls = []def __call__(self, cmd, **kwargs):self.calls.append(cmd)+ if cmd[1] == "-c" and "get_device_capability" in cmd[2]:+ return SimpleNamespace(returncode = 0, stdout = self.capability)if cmd[1] == "-c":return SimpleNamespace(returncode = 0 if self.loads.pop(0) else 1, stdout = "")return SimpleNamespace(returncode = 0, stdout = "")@@ -306,3 +313,86 @@ def test_console_entry_drops_an_unwritable_ssl_keylog_file(tmp_path):)assert result.returncode == 0, result.stderrassert "ignoring SSLKEYLOGFILE" in result.stdout + result.stderr+++ "env, expected",+ [+ (+ _env("2.11.0+cu130", "13.0"),+ "https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.1/"+ "flash_attn-2.8.1+cu13torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl",+ ),+ (+ _env("2.13.0+cu130", "13.0"),+ "https://github.com/unslothai/unsloth/releases/download/prebuilt-wheels-cu13/"+ "flash_attn-2.8.4+cu13torch2.13cxx11abiTRUE-cp313-cp313-linux_x86_64.whl",+ ),+ (_env("2.11.0+cu130", "13.0", platform_tag = "win_amd64"), None),+ (_env("2.11.0+cpu", ""), None),+ ],+)+def test_flash_attn_resolution(env, expected):+ assert kernel_install.resolve_wheel_url("flash_attn", env) == expected++[email protected]("capability", ["7 5", "None"])+def test_flash_attn_is_skipped_below_sm80(capability, capsys):+ run = _Runner([], capability = capability)+ assert (+ kernel_install.install_kernel("flash_attn", _COLAB, run = run, exists = lambda url: True) == 0+ )+ assert run.installer_calls == []+ assert "skipping flash_attn" in capsys.readouterr().out+++def test_flash_attn_installs_on_sm80_and_newer(uv):+ uv(False)+ run = _Runner([False, True], capability = "8 0")+ assert (+ kernel_install.install_kernel("flash_attn", _COLAB, run = run, exists = lambda url: True) == 0+ )+ assert run.installer_calls[0][-1].endswith(+ "flash_attn-2.8.1+cu13torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"+ )+++ "argv, expected",+ [+ ([], ["xformers", "flash_attn", "causal_conv1d", "mamba_ssm"]),+ (["mamba_ssm", "causal_conv1d", "mamba_ssm"], ["causal_conv1d", "mamba_ssm"]),+ ],+)+def test_main_installs_all_by_default_in_dependency_order(monkeypatch, argv, expected):+ order = []+ monkeypatch.setattr(kernel_install, "probe_torch_wheel_env", lambda **kwargs: _COLAB)+ monkeypatch.setattr(+ kernel_install, "install_kernel", lambda name, env, dry_run = False: order.append(name) or 0+ )+ assert kernel_install.main(argv) == 0+ assert order == expected+++def test_flash_attn_without_a_wheel_never_probes_the_gpu():+ run = _Runner([])+ assert kernel_install.install_kernel("flash_attn", None, run = run, exists = lambda url: True) == 0+ assert run.calls == []+++def test_capability_probe_timeout_counts_as_no_gpu():+ def run(cmd, **kwargs):+ raise subprocess.TimeoutExpired(cmd, kwargs.get("timeout"))++ assert kernel_install._gpu_capability(run) is None+++def test_capability_probe_takes_the_best_visible_gpu():+ seen = {}++ def run(cmd, **kwargs):+ seen["check"], seen["timeout"] = cmd[2], kwargs.get("timeout")+ return SimpleNamespace(returncode = 0, stdout = "9 0\n")++ assert kernel_install._gpu_capability(run) == (9, 0)+ assert "max(torch.cuda.get_device_capability(i)" in seen["check"] and seen["timeout"]diff --git a/studio/backend/utils/kernel_install.py b/studio/backend/utils/kernel_install.pyindex eabf2475889..a713326816c 100644--- a/studio/backend/utils/kernel_install.py+++ b/studio/backend/utils/kernel_install.py@@ -1,7 +1,7 @@# 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 xformers causal_conv1d`: prebuilt kernel wheels matched to the resident torch.+"""`unsloth install-kernels [names]`: prebuilt kernel wheels matched to the resident torch, all by default.Wheel-only by design: no wheel for this torch / CUDA / Python means nothing is installed and themodel keeps its torch fallback, never a source build. Installs use --no-deps so torch is never touched.@@ -23,6 +23,7 @@ from utils.wheel_utils import (MAMBA_SSM_RELEASE_BASE_URL,MAMBA_SSM_RELEASE_TAG,direct_wheel_url,+ flash_attn_wheel_url,install_wheel,probe_torch_wheel_env,redact_url_credentials,@@ -32,11 +33,13 @@ from utils.wheel_utils import (# name -> (pip distribution, check that loads the compiled extension). The package imports are no# proof: `import causal_conv1d` never loads it, and `import mamba_ssm` fails on einops under --no-deps.+# Install order: mamba_ssm's fast path imports causal_conv1d.KERNELS = {"xformers": ("xformers","from xformers._cpp_lib import _register_extensions; _register_extensions()",),+ "flash_attn": ("flash-attn", "import torch, flash_attn_2_cuda"),"causal_conv1d": ("causal-conv1d", "import torch, causal_conv1d_cuda"),"mamba_ssm": ("mamba-ssm", "import torch, selective_scan_cuda"),}@@ -56,9 +59,11 @@ def resolve_wheel_url(name: str, env: dict[str, str] | None) -> str | None:return Noneif name == "xformers":return xformers_wheel_url(env)- # causal-conv1d and mamba-ssm publish Linux wheels only.+ # flash-attn, causal-conv1d and mamba-ssm publish Linux wheels only.if not str(env.get("platform_tag") or "").startswith("linux"):return None+ if name == "flash_attn":+ return flash_attn_wheel_url(env)package_version, release_tag, release_base_url = _RELEASES[name]return direct_wheel_url(filename_prefix = name,@@ -69,6 +74,31 @@ def resolve_wheel_url(name: str, env: dict[str, str] | None) -> str | None:)+def _gpu_capability(run: Callable[..., subprocess.CompletedProcess]) -> tuple[int, int] | None:+ """The best compute capability across the visible GPUs, or None."""+ check = (+ "import torch; n = torch.cuda.device_count() if torch.cuda.is_available() else 0; "+ "print(*max(torch.cuda.get_device_capability(i) for i in range(n))) if n else None"+ )+ try:+ result = run(+ [sys.executable, "-c", check],+ stdout = subprocess.PIPE,+ stderr = subprocess.DEVNULL,+ text = True,+ encoding = "utf-8",+ errors = "replace",+ timeout = 120,+ )+ except subprocess.TimeoutExpired:+ return None+ try:+ major, minor = (int(part) for part in result.stdout.split())+ except ValueError:+ return None+ return major, minor++def _loads(check: str, run: Callable[..., subprocess.CompletedProcess]) -> bool:result = run([sys.executable, "-c", check], stdout = subprocess.DEVNULL, stderr = subprocess.DEVNULL@@ -100,6 +130,17 @@ def install_kernel() -> int:distribution, check = KERNELS[name]url = resolve_wheel_url(name, env)+ if name == "flash_attn" and url is not None:+ # FlashAttention 2 needs Ampere or newer, and Unsloth only enables it there.+ capability = _gpu_capability(run)+ if capability is None or capability < (8, 0):+ gpu = (+ "no CUDA GPU is visible"+ if capability is None+ else "the best GPU is sm%d%d" % capability+ )+ print(f"Unsloth: skipping flash_attn, which needs sm80 or newer ({gpu}).")+ return 0torch_desc = f"torch {env.get('torch_version')}" if env else "this environment"# Only a 404 proves nothing is published; an unreachable check falls through to the install.if url is None or exists(url) is False:@@ -146,14 +187,19 @@ def main(argv: list[str] | None = None) -> int:prog = "unsloth install-kernels",description = "Install prebuilt kernel wheels matching the installed torch. Never builds from source or changes torch.",)- parser.add_argument("kernels", nargs = "+", choices = sorted(KERNELS))+ parser.add_argument(+ "kernels",+ nargs = "*",+ choices = list(KERNELS),+ help = "kernels to install (default: all, each skipped when no wheel matches)",+ )parser.add_argument("--dry-run", action = "store_true", help = "print the resolved wheel URL and install nothing")args = parser.parse_args(argv)env = probe_torch_wheel_env(timeout = 120, include_windows = True)status = 0- for name in dict.fromkeys(args.kernels):+ for name in [name for name in KERNELS if not args.kernels or name in args.kernels]:status = max(status, install_kernel(name, env, dry_run = args.dry_run))return statusdiff --git a/unsloth_cli/__init__.py b/unsloth_cli/__init__.pyindex 449fe438232..809e82f3482 100644--- a/unsloth_cli/__init__.py+++ b/unsloth_cli/__init__.py@@ -267,7 +267,7 @@ if not _windows_studio_mutation_entry:"ignore_unknown_options": True,"help_option_names": [],},- help = "Install prebuilt xformers / causal_conv1d / mamba_ssm wheels matching the installed torch.",+ help = "Install prebuilt xformers / flash-attn / causal_conv1d / mamba_ssm wheels matching the installed torch (all by default).",)def install_kernels(ctx: typer.Context):# Listed for `unsloth --help`; the console script dispatches before typer is imported.