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
"""`unsloth run --engine vllm|sglang`: the load payload, re-exec forwarding, and the
install-on-first-use consent."""
from __future__ import annotations
import inspect
import sys
import types
from pathlib import Path
import pytest
import typer
_REPO_ROOT = Path(__file__).resolve().parents[2]
if str(_REPO_ROOT) not in sys.path:
sys.path.insert(0, str(_REPO_ROOT))
from unsloth_cli.commands import studio as studio_mod
def test_engine_options_are_registered_on_run():
sig = inspect.signature(studio_mod.run)
assert set(sig.parameters["engine"].default.param_decls) == {"--engine"}
assert sig.parameters["engine"].default.default == "auto"
assert set(sig.parameters["engine_precision"].default.param_decls) == {"--engine-precision"}
def test_reexec_forwards_the_engine():
src = inspect.getsource(studio_mod.run)
assert 'args.extend(["--engine", engine, "--engine-precision", engine_precision])' in src
def _capture_payload(monkeypatch, **kwargs):
seen = {}
class _Resp:
def __enter__(self):
return self
def __exit__(self, *a):
return False
def read(self):
return b'{"status": "loaded", "model": "m"}'
def fake_urlopen(req, timeout = None):
import json
seen.update(json.loads(req.data))
return _Resp()
monkeypatch.setattr(studio_mod, "_direct_urlopen", fake_urlopen)
import unsloth_cli._inference as inf
monkeypatch.setattr(inf, "raise_for_deferred_error", lambda url, body: body)
monkeypatch.setattr(inf, "require_completed_padded_body", lambda url, body: body)
studio_mod._load_model_via_http(8888, "k", "m", None, 4096, False, **kwargs)
return seen
def test_default_load_payload_has_no_engine(monkeypatch):
payload = _capture_payload(monkeypatch)
assert "engine" not in payload and "engine_precision" not in payload
def test_engine_load_payload(monkeypatch):
payload = _capture_payload(monkeypatch, engine = "vllm", engine_precision = "fp8")
assert payload["engine"] == "vllm" and payload["engine_precision"] == "fp8"
class _FakeInstall:
def __init__(
self,
row,
finish = "success",
):
self.row = dict(row)
self.started = 0
self.finish = finish
def status(self, engine):
job = {"state": self.finish if self.started else "idle", "message": "done"}
return {**self.row, "job": job}
def support_reason(self, engine):
return self.row["unsupported_reason"]
def start_install(self, engine):
self.started += 1
return self.status(engine)
@pytest.fixture
def fake_install(monkeypatch):
def make(row, finish = "success"):
fake = _FakeInstall(row, finish)
core = types.ModuleType("core")
inference = types.ModuleType("core.inference")
inference.engine_install = fake
core.inference = inference
monkeypatch.setitem(sys.modules, "core", core)
monkeypatch.setitem(sys.modules, "core.inference", inference)
monkeypatch.setitem(sys.modules, "core.inference.engine_install", fake)
return fake
return make
_MISSING = {
"version": "0.30.0",
"installed": False,
"current": False,
"unsupported_reason": None,
"download_bytes": 1073741824,
}
def test_installed_engine_is_not_reinstalled(fake_install):
fake = fake_install({**_MISSING, "installed": True, "current": True})
studio_mod._ensure_engine_installed("vllm", yes = False, silent = True)
assert fake.started == 0
def test_restored_engine_is_loaded_as_is(fake_install):
fake = fake_install({**_MISSING, "installed": True, "current": False, "restored": True})
studio_mod._ensure_engine_installed("vllm", yes = True, silent = True)
assert fake.started == 0
def test_missing_engine_without_a_terminal_needs_yes(fake_install, monkeypatch):
fake = fake_install(_MISSING)
monkeypatch.setattr(sys.stdin, "isatty", lambda: False)
with pytest.raises(RuntimeError, match = "--yes"):
studio_mod._ensure_engine_installed("vllm", yes = False, silent = True)
assert fake.started == 0
def test_declined_prompt_installs_nothing(fake_install, monkeypatch):
fake = fake_install(_MISSING)
monkeypatch.setattr(sys.stdin, "isatty", lambda: True)
asked = []
monkeypatch.setattr(typer, "confirm", lambda text, default = False: asked.append(text) or False)
with pytest.raises(RuntimeError, match = "not installed"):
studio_mod._ensure_engine_installed("vllm", yes = False, silent = True)
assert fake.started == 0
assert asked == ["Install vllm 0.30.0 (about 1.0 GiB to download)?"]
def test_yes_installs_and_waits(fake_install):
fake = fake_install(_MISSING)
studio_mod._ensure_engine_installed("vllm", yes = True, silent = True)
assert fake.started == 1
def test_failed_install_is_an_error(fake_install):
fake_install(_MISSING, finish = "error")
with pytest.raises(RuntimeError, match = "did not finish"):
studio_mod._ensure_engine_installed("vllm", yes = True, silent = True)
def test_unsupported_host_is_refused_before_installing(fake_install):
fake = fake_install({**_MISSING, "unsupported_reason": "vLLM needs an NVIDIA GPU."})
with pytest.raises(RuntimeError, match = "NVIDIA"):
studio_mod._ensure_engine_installed("vllm", yes = True, silent = True)
assert fake.started == 0
def test_windows_asks_before_turning_on_wsl(fake_install, monkeypatch):
fake = fake_install({**_MISSING, "host": "wsl", "wsl": {"state": "missing", "distro": None}})
monkeypatch.setattr(sys.stdin, "isatty", lambda: True)
shown = []
monkeypatch.setattr(typer, "echo", lambda text = "", **k: shown.append(text))
monkeypatch.setattr(typer, "confirm", lambda text, default = False: False)
with pytest.raises(RuntimeError):
studio_mod._ensure_engine_installed("vllm", yes = False, silent = True)
assert fake.started == 0
assert any("administrator (UAC) prompt" in line and "WSL2" in line for line in shown)
@pytest.mark.parametrize(
("wsl", "expected"),
[
({"state": "restart_required"}, "Restart Windows"),
({"state": "ready", "distro": "UnslothStudio"}, "private WSL2 environment"),
],
)
def test_wsl_notice_follows_its_state(wsl, expected):
assert expected in studio_mod._engine_install_notice("vllm", {"host": "wsl", "wsl": wsl})
def test_linux_has_no_wsl_notice():
assert studio_mod._engine_install_notice("vllm", {"host": "local"}) is None
def test_parallelism_and_gpu_options_are_registered_on_run():
sig = inspect.signature(studio_mod.run)
assert set(sig.parameters["engine_parallelism"].default.param_decls) == {"--engine-parallelism"}
assert sig.parameters["engine_parallelism"].default.default == "tensor"
assert set(sig.parameters["gpus"].default.param_decls) == {"--gpus"}
assert sig.parameters["gpus"].default.default is None
def test_engine_parallelism_and_gpus_reach_the_load_payload(monkeypatch):
payload = _capture_payload(
monkeypatch, engine = "vllm", engine_parallelism = "data", gpu_ids = [0, 2]
)
assert payload["engine_parallelism"] == "data" and payload["gpu_ids"] == [0, 2]
def test_gpus_reach_a_gguf_load_payload(monkeypatch):
payload = _capture_payload(monkeypatch, gpu_ids = [1])
assert payload["gpu_ids"] == [1] and "engine_parallelism" not in payload
def test_default_tensor_parallelism_is_not_sent(monkeypatch):
payload = _capture_payload(monkeypatch, engine = "vllm")
assert "engine_parallelism" not in payload and "gpu_ids" not in payload
@pytest.mark.parametrize(
("value", "expected"),
[(None, None), ("", None), ("0", [0]), ("0,1, 3", [0, 1, 3]), ("2,", [2])],
)
def test_parse_gpu_ids(value, expected):
assert studio_mod._parse_gpu_ids(value) == expected
@pytest.mark.parametrize("value", ["a", "0,0", "-1", "0;1"])
def test_parse_gpu_ids_rejects_bad_values(value):
with pytest.raises(ValueError, match = "--gpus"):
studio_mod._parse_gpu_ids(value)