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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Setup installs flash-attn but not causal-conv1d or mamba-ssm: those (~550 MB) install when a
model that needs them is trained or loaded (core/training/worker.py, utils/ssm_runtime.py), and
`unsloth install-kernels` still provisions them ahead of time for offline images. After torch
moves, setup still removes an installed copy whose compiled extension no longer imports."""
from __future__ import annotations
import ast
import contextlib
import re
import subprocess
import sys
from pathlib import Path
import pytest
STUDIO_DIR = Path(__file__).resolve().parents[2] / "studio"
sys.path.insert(0, str(STUDIO_DIR))
sys.path.insert(0, str(STUDIO_DIR / "backend"))
import install_python_stack as ips # noqa: E402
SOURCE = (STUDIO_DIR / "install_python_stack.py").read_text(encoding = "utf-8")
TREE = ast.parse(SOURCE)
def _called_names() -> set[str]:
return {
node.func.id
for node in ast.walk(TREE)
if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
}
def test_setup_has_no_ssm_kernel_step():
assert not hasattr(ips, "_ensure_ssm_kernels")
assert "install_kernel" not in _called_names()
assert '_progress("mamba kernels")' not in SOURCE
assert "causal-conv1d + mamba-ssm" not in SOURCE
def test_flash_attn_and_the_stale_kernel_check_run_at_all_three_sites():
calls = [m.start() for m in re.finditer(r"\n\s+_ensure_flash_attn\(\)\n", SOURCE)]
assert len(calls) == 3
for start in calls:
following = SOURCE[start : start + 120]
assert "_remove_stale_ssm_kernels()" in following, following
assert "base_total += 1 # flash-attn, Linux and Windows" in SOURCE
class _Kernels:
"""Which SSM distributions are installed and how their extension import ends: True loads,
False raises ImportError, None hangs, an int is a raw exit code (negative = signal)."""
def __init__(
self,
installed: dict,
torch_imports = True,
):
self.installed = dict(installed)
self.torch_imports = torch_imports
self.probes: list[str] = []
self.removed: list[str] = []
def version(self, distribution):
return "1.0" if distribution in self.installed else None
def run(self, cmd, *args, **kwargs):
code = cmd[-1]
self.probes.append(code)
if code == "import torch":
if self.torch_imports is None:
raise subprocess.TimeoutExpired(cmd, 1)
if self.torch_imports:
return subprocess.CompletedProcess(cmd, 0, stderr = "")
return subprocess.CompletedProcess(
cmd, 1, stderr = "OSError: libtorch_cuda.so: cannot open shared object file"
)
assert "import torch" in code # the extension probe proves torch imports too
extension = "causal_conv1d_cuda" if "causal_conv1d_cuda" in code else "selective_scan_cuda"
distribution = "causal-conv1d" if extension == "causal_conv1d_cuda" else "mamba-ssm"
state = self.installed[distribution]
if state is None:
raise subprocess.TimeoutExpired(cmd, 1)
if state is True:
return subprocess.CompletedProcess(cmd, 0, stderr = "")
if state is False:
return subprocess.CompletedProcess(
cmd,
ips._SSM_EXTENSION_BROKEN_EXIT,
stderr = f"{extension}: ImportError: {extension}.so: undefined symbol: _ZN3c10",
)
return subprocess.CompletedProcess(cmd, state, stderr = "Killed")
def uninstall(self, distribution):
self.removed.append(distribution)
self.installed.pop(distribution, None)
return True
@contextlib.contextmanager
def _free_lock(name, **kwargs):
yield True
def _run_stale_check(monkeypatch, host: _Kernels, **flags):
monkeypatch.setattr(ips, "NO_TORCH", flags.get("no_torch", False))
monkeypatch.setattr(ips, "IS_MACOS", flags.get("macos", False))
monkeypatch.setattr(ips, "_installed_distribution_version", host.version)
monkeypatch.setattr(ips, "_uninstall_distribution", host.uninstall)
monkeypatch.setattr(ips, "_count_install_action", lambda: None)
monkeypatch.setattr(ips, "kernel_install_lock", flags.get("lock", _free_lock))
warnings = []
monkeypatch.setattr(ips, "_step", lambda label, value, color_fn = None: warnings.append(value))
monkeypatch.setattr(ips, "_note", lambda message, color_fn = None: warnings.append(message))
monkeypatch.setattr(ips.subprocess, "run", host.run)
installs = []
monkeypatch.setattr(ips, "install_prebuilt", lambda *a, **k: installs.append(a) or "installed")
ips._remove_stale_ssm_kernels()
assert installs == [] # never installs anything
return warnings
def test_stale_kernels_that_no_longer_import_are_removed(monkeypatch):
host = _Kernels({"causal-conv1d": False, "mamba-ssm": False})
warnings = _run_stale_check(monkeypatch, host)
assert host.removed == ["causal-conv1d", "mamba-ssm"]
assert len(warnings) == 2
# The probe's stderr tail says why.
assert "undefined symbol" in warnings[0] and "selective_scan_cuda" in warnings[1]
def test_kernels_that_still_import_are_kept(monkeypatch):
host = _Kernels({"causal-conv1d": True, "mamba-ssm": False})
_run_stale_check(monkeypatch, host)
assert host.removed == ["mamba-ssm"]
def test_absent_kernels_are_not_probed_or_installed(monkeypatch):
host = _Kernels({})
_run_stale_check(monkeypatch, host)
assert host.probes == [] and host.removed == []
def test_a_hung_probe_is_inconclusive_and_keeps_the_kernel(monkeypatch):
host = _Kernels({"causal-conv1d": None})
_run_stale_check(monkeypatch, host)
assert host.removed == []
def test_no_torch_or_macos_skips_the_check(monkeypatch):
for flags in ({"no_torch": True}, {"macos": True}):
host = _Kernels({"causal-conv1d": False})
_run_stale_check(monkeypatch, host, **flags)
assert host.probes == []
@pytest.mark.parametrize("torch_imports", [False, None])
def test_a_torch_that_does_not_import_keeps_every_kernel(monkeypatch, torch_imports):
# A torch that fails to import says nothing about the kernels, so none are removed.
host = _Kernels({"causal-conv1d": False, "mamba-ssm": False}, torch_imports = torch_imports)
warnings = _run_stale_check(monkeypatch, host)
assert host.removed == []
assert host.probes == ["import torch"]
if torch_imports is False:
assert "libtorch_cuda.so" in warnings[0]
@pytest.mark.parametrize("exit_code", [-9, -11, 1, 2])
def test_a_killed_or_unrelated_failure_is_inconclusive(monkeypatch, exit_code):
# A signal (OOM killer, segfault) or an exit that is not the extension's ImportError / OSError.
host = _Kernels({"causal-conv1d": exit_code, "mamba-ssm": exit_code})
warnings = _run_stale_check(monkeypatch, host)
assert host.removed == []
assert all("kept it" in message for message in warnings)
def test_the_probed_extensions_match_the_kernel_checks():
for name, extension in ips._SSM_KERNEL_EXTENSIONS.items():
assert ips.KERNELS[name][1] == f"import torch, {extension}"
def test_the_kernel_cli_still_provisions_both_ahead_of_time():
from utils import kernel_install
assert {"causal_conv1d", "mamba_ssm"} <= set(kernel_install.KERNELS)
assert callable(kernel_install.install_kernel)
def test_a_busy_install_lock_keeps_the_kernel(monkeypatch):
# A Studio load verifying a fresh install holds this lock: never remove it underneath that.
@contextlib.contextmanager
def _busy(name, **kwargs):
yield False
host = _Kernels({"causal-conv1d": False})
warnings = _run_stale_check(monkeypatch, host, lock = _busy)
assert host.removed == []
assert any("install lock is busy" in message for message in warnings)
def test_a_kernel_reinstalled_while_waiting_on_the_lock_is_kept(monkeypatch):
# Broken when first probed, but a Studio load / `unsloth install-kernels` held the lock and
# reinstalled it: the re-probe under the lock loads, so nothing is removed.
host = _Kernels({"causal-conv1d": False})
@contextlib.contextmanager
def _lock_after_reinstall(name, **kwargs):
host.installed["causal-conv1d"] = True
yield True
warnings = _run_stale_check(monkeypatch, host, lock = _lock_after_reinstall)
assert host.removed == []
assert any("now loads" in message and "kept it" in message for message in warnings)
extension_probes = [code for code in host.probes if code != "import torch"]
assert len(extension_probes) == 2 # probed again under the lock
def test_an_inconclusive_re_probe_under_the_lock_keeps_the_kernel(monkeypatch):
host = _Kernels({"causal-conv1d": False})
@contextlib.contextmanager
def _lock_then_hang(name, **kwargs):
host.installed["causal-conv1d"] = None
yield True
warnings = _run_stale_check(monkeypatch, host, lock = _lock_then_hang)
assert host.removed == []
assert any("kept it" in message for message in warnings)
def _real_probe(extension, path):
return subprocess.run(
[sys.executable, "-c", ips._ssm_extension_probe(extension)],
capture_output = True,
text = True,
timeout = 300,
env = {**__import__("os").environ, "PYTHONPATH": str(path)},
)
# Stand-ins for selective_scan_cuda / causal_conv1d_cuda: a CUDA build on the host cannot interfere.
_FAKE_SCAN, _FAKE_CONV = "unsloth_test_selective_scan_ext", "unsloth_test_causal_conv1d_ext"
def test_the_probe_passes_an_extension_free_mamba_ssm_only(monkeypatch, tmp_path):
pytest.importorskip("torch")
monkeypatch.setattr(ips, "_SSM_EXTENSION_OPTIONAL", {_FAKE_SCAN})
assert _real_probe(_FAKE_SCAN, tmp_path).returncode == 0
# causal_conv1d has no extension-free wheel: a missing causal_conv1d_cuda is still broken.
missing = _real_probe(_FAKE_CONV, tmp_path)
assert missing.returncode == ips._SSM_EXTENSION_BROKEN_EXIT, missing.stderr
# A build for another torch: the module is there but does not load.
(tmp_path / f"{_FAKE_SCAN}.py").write_text("raise ImportError('undefined symbol: _ZN3c10')\n")
broken = _real_probe(_FAKE_SCAN, tmp_path)
assert broken.returncode == ips._SSM_EXTENSION_BROKEN_EXIT, broken.stderr
assert _FAKE_SCAN in broken.stderr
def test_setup_keeps_the_extension_free_mamba_ssm(monkeypatch, tmp_path):
# Removing it on every update leaves an offline Mamba-2 load without mamba_ssm.
pytest.importorskip("torch")
monkeypatch.setattr(ips, "_SSM_KERNEL_EXTENSIONS", {"mamba_ssm": _FAKE_SCAN})
monkeypatch.setattr(ips, "_SSM_EXTENSION_OPTIONAL", {_FAKE_SCAN}, raising = False)
monkeypatch.setattr(ips, "NO_TORCH", False)
monkeypatch.setattr(ips, "IS_MACOS", False)
monkeypatch.setattr(
ips,
"_installed_distribution_version",
lambda d: "2.3.2.post1" if d == "mamba-ssm" else None,
)
removed = []
monkeypatch.setattr(ips, "_uninstall_distribution", lambda d: removed.append(d) or True)
monkeypatch.setattr(ips, "_count_install_action", lambda: None)
monkeypatch.setattr(ips, "kernel_install_lock", _free_lock)
messages = []
monkeypatch.setattr(ips, "_step", lambda label, value, color_fn = None: messages.append(value))
monkeypatch.setattr(ips, "_note", lambda message, color_fn = None: messages.append(message))
ips._remove_stale_ssm_kernels()
assert removed == [] and messages == []