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.

Studio: run vLLM and SGLang on Windows inside a private WSL2 distro (#12024)

Daniel Han619cd71ec226
diff --git a/studio/backend/core/inference/engine_adapters.py b/studio/backend/core/inference/engine_adapters.py
index b7623460561..ccf4f118449 100644
--- a/studio/backend/core/inference/engine_adapters.py
+++ b/studio/backend/core/inference/engine_adapters.py
@@ -7,6 +7,8 @@ from __future__ import annotations
from dataclasses import dataclass
import subprocess
+
+from utils.subprocess_compat import windows_hidden_subprocess_kwargs
import json
from pathlib import Path
@@ -292,17 +294,20 @@ def gpu_memory_fraction(
engine does not budget. An unreadable
device is an actionable failure, never permission to fall back to a larger engine default.
"""
+ from utils.hardware.nvidia import _nvidia_smi_executable
from utils.vram_budget_settings import get_vram_budget_fraction
+
try:
result = subprocess.run(
[
- "nvidia-smi",
+ _nvidia_smi_executable(),
"--id",
",".join(str(gpu_id) for gpu_id in gpu_ids),
"--query-gpu=memory.total,memory.free",
"--format=csv,noheader,nounits",
],
capture_output = True,
+ **windows_hidden_subprocess_kwargs(),
text = True,
encoding = "utf-8",
errors = "replace",
diff --git a/studio/backend/core/inference/engine_install.py b/studio/backend/core/inference/engine_install.py
index 2179470d95f..fe9070cba85 100644
--- a/studio/backend/core/inference/engine_install.py
+++ b/studio/backend/core/inference/engine_install.py
@@ -22,6 +22,8 @@ import platform
import re
import shutil
import subprocess
+
+from utils.subprocess_compat import windows_hidden_subprocess_kwargs
import sys
import sysconfig
import tempfile
@@ -127,7 +129,12 @@ def engine_root() -> Path:
def _release(engine: str) -> dict:
"""The release built on Studio's own torch, so the engine can share it; otherwise the newest,
which then gets an isolated environment of its own."""
+ from . import wsl_host
+
releases = PROFILES[engine]["releases"]
+ if wsl_host.active():
+ # The WSL guest has no Studio torch to share, so it always gets the newest.
+ return releases[0]
torch = _studio_packages().get("torch")
for release in releases:
if _same_build(torch, release["torch"], PROFILES[engine]["cuda"]):
@@ -249,14 +256,21 @@ def _compat(engine: str) -> dict[str, list[str]]:
def download_bytes(engine: str) -> int | None:
"""Wheel bytes an install of the selected release downloads: the lock minus what Studio provides."""
+ from . import wsl_host
+
sizes = _compat_file(engine).get("sizes")
if not sizes:
return None
- provided = install_plan(engine)["provided"]
+ wsl = wsl_host.active()
+ # A WSL engine is always a complete environment, plus the distro and uv on first setup.
+ provided = {} if wsl else install_plan(engine)["provided"]
omit = set(profile(engine).get("omit", ()))
- return sum(
+ total = sum(
size or 0 for name, size in sizes.items() if name not in provided and name not in omit
)
+ if wsl and not wsl_host.summary().get("distro"):
+ total += wsl_host.ROOTFS["size"] + wsl_host.UV["size"]
+ return total
# Not engine dependencies, so absent from the compat file: the configs Studio's adapters build
@@ -420,6 +434,8 @@ def link_cuda_home(env: Path, shared: bool) -> None:
def cuda_environment(info: dict) -> dict[str, str]:
"""CUDA_HOME for the engine's JIT compiles; CPATH is its merged include tree for other compilers."""
+ if info.get("host") == "wsl":
+ return dict(info.get("cuda_environment") or {})
env = Path(info["path"])
if not (env / "cuda" / "bin" / "nvcc").exists():
return {}
@@ -497,14 +513,16 @@ def _cached_rows(gpu_id):
def _probe_rows(gpu_id):
rows = None
try:
+ from utils.hardware.nvidia import _nvidia_smi_executable
result = subprocess.run(
[
- "nvidia-smi",
+ _nvidia_smi_executable(),
"--query-gpu=driver_version,compute_cap",
"--format=csv,noheader",
*(["--id", str(gpu_id)] if gpu_id is not None else []),
],
capture_output = True,
+ **windows_hidden_subprocess_kwargs(),
text = True,
encoding = "utf-8",
errors = "replace",
@@ -548,11 +566,19 @@ def support_reason(
*,
wait: bool = True,
) -> str | None:
- if platform.system() != "Linux" or platform.machine() != "x86_64":
- return "Managed engines currently require Linux x86_64."
- glibc = profile(engine).get("glibc", (2, 34))
- if tuple(int(x) for x in (platform.libc_ver()[1] or "0.0").split(".")[:2]) < glibc:
- return f"{engine} requires glibc {glibc[0]}.{glibc[1]} or newer."
+ from . import wsl_host
+
+ if wsl_host.active():
+ # WSL itself is not a prerequisite: installing the engine sets it up.
+ reason = wsl_host.support_reason()
+ if reason:
+ return reason
+ elif platform.system() != "Linux" or platform.machine() != "x86_64":
+ return "Managed engines currently require Linux x86_64 or Windows x64."
+ else:
+ glibc = profile(engine).get("glibc", (2, 34))
+ if tuple(int(x) for x in (platform.libc_ver()[1] or "0.0").split(".")[:2]) < glibc:
+ return f"{engine} requires glibc {glibc[0]}.{glibc[1]} or newer."
rows = _driver_rows(gpu_id, wait = wait)
if rows is _PENDING:
return "Checking for a supported NVIDIA GPU."
@@ -586,7 +612,7 @@ def engine_lease(
):
"""``wait=0`` for status probes: real takers retry so a probe's instant hold never fails them."""
profile(engine)
- import fcntl
+ lock, unlock = _file_lock()
root = engine_root()
root.mkdir(parents = True, exist_ok = True)
@@ -594,7 +620,7 @@ def engine_lease(
deadline = time.monotonic() + wait
while True:
try:
- fcntl.flock(handle, (fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH) | fcntl.LOCK_NB)
+ lock(handle, exclusive)
break
except BlockingIOError:
if time.monotonic() >= deadline:
@@ -605,7 +631,59 @@ def engine_lease(
try:
yield
finally:
- fcntl.flock(handle, fcntl.LOCK_UN)
+ unlock(handle)
+
+
+def _file_lock():
+ """(lock, unlock) raising BlockingIOError when held: flock, or LockFileEx on Windows, which
+ also has shared and exclusive modes (msvcrt.locking is exclusive only)."""
+ if os.name != "nt":
+ import fcntl
+ return (
+ lambda handle, exclusive: fcntl.flock(
+ handle, (fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH) | fcntl.LOCK_NB
+ ),
+ lambda handle: fcntl.flock(handle, fcntl.LOCK_UN),
+ )
+ import ctypes
+ import msvcrt
+ from ctypes import wintypes
+
+ class Overlapped(ctypes.Structure):
+ _fields_ = [
+ ("Internal", ctypes.c_void_p),
+ ("InternalHigh", ctypes.c_void_p),
+ ("Offset", wintypes.DWORD),
+ ("OffsetHigh", wintypes.DWORD),
+ ("hEvent", wintypes.HANDLE),
+ ]
+
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error = True)
+
+ def lock(handle, exclusive):
+ flags = 0x1 | (
+ 0x2 if exclusive else 0
+ ) # LOCKFILE_FAIL_IMMEDIATELY | LOCKFILE_EXCLUSIVE_LOCK
+ if not kernel32.LockFileEx(
+ wintypes.HANDLE(msvcrt.get_osfhandle(handle.fileno())),
+ flags,
+ 0,
+ 1,
+ 0,
+ ctypes.byref(Overlapped()),
+ ):
+ raise BlockingIOError(ctypes.get_last_error(), "lock held")
+
+ def unlock(handle):
+ kernel32.UnlockFileEx(
+ wintypes.HANDLE(msvcrt.get_osfhandle(handle.fileno())),
+ 0,
+ 1,
+ 0,
+ ctypes.byref(Overlapped()),
+ )
+
+ return lock, unlock
def installed(engine: str) -> dict | None:
@@ -622,6 +700,10 @@ def installed(engine: str) -> dict | None:
or Path(directory).name != directory
):
return None
+ if info.get("host") == "wsl":
+ # Lives in the distro; checking it would boot WSL on every status poll, so the load checks.
+ from .wsl_host import GUEST_ROOT
+ return {**info, "path": f"{GUEST_ROOT}/engines/{engine}/{directory}"}
path = root / directory
if path.is_symlink() or not (path / "bin" / "python").is_file():
return None
@@ -677,9 +759,15 @@ def status(engine: str) -> dict:
else _safe_download_bytes(engine),
"additional_disk_bytes": None,
"job": job,
+ **_host_status(),
}
+def _host_status() -> dict:
+ from . import wsl_host
+ return {"host": "wsl", "wsl": wsl_host.summary()} if wsl_host.active() else {"host": "local"}
+
+
def _safe_download_bytes(engine: str) -> int | None:
try:
return download_bytes(engine)
@@ -698,6 +786,18 @@ def _update(engine: str, **values) -> None:
_atomic_json(root / f"{engine}.job.json", _jobs[engine])
+def driver_library_path(env: dict[str, str]) -> str | None:
+ """The LD_LIBRARY_PATH entries that hold the NVIDIA driver. Hosts such as Colab keep libcuda
+ outside the loader cache and reach it only this way; every other entry is dropped, so a CUDA
+ runtime Studio's environment points at never shadows the engine's own."""
+ entries = [
+ entry
+ for entry in env.get("LD_LIBRARY_PATH", "").split(os.pathsep)
+ if entry and os.path.isabs(entry) and (Path(entry) / "libcuda.so.1").exists()
+ ]
+ return os.pathsep.join(entries) or None
+
+
def install_environment() -> dict[str, str]:
# Do not inherit Studio's resolver overrides, Python overlays or credentials.
env = {
@@ -733,6 +833,9 @@ def install_environment() -> dict[str, str]:
env["UV_CACHE_DIR"] = (
os.environ.get("UV_CACHE_DIR") or recorded_cache or str(cache_root() / "uv")
)
+ # The install checks import the engine, whose device detection needs the driver.
+ if driver := driver_library_path(dict(os.environ)):
+ env["LD_LIBRARY_PATH"] = driver
env["PYTHONNOUSERSITE"] = "1"
env["UV_NO_CONFIG"] = "1"
env["UV_CONCURRENT_DOWNLOADS"] = "4"
@@ -761,7 +864,12 @@ def package_link_mode(destination: Path) -> str:
return "copy"
-def _run(engine: str, argv: list[str], cancel: threading.Event) -> None:
+def _run(
+ engine: str,
+ argv: list[str],
+ cancel: threading.Event,
+ env: dict | None = None,
+) -> None:
from utils.process_lifetime import (
adopt_pid,
child_popen_kwargs,
@@ -777,13 +885,15 @@ def _run(engine: str, argv: list[str], cancel: threading.Event) -> None:
proc = spawn_on_lifetime_thread(
lambda: subprocess.Popen(
argv,
- env = install_environment(),
+ env = install_environment() if env is None else env,
stdout = subprocess.PIPE,
stderr = subprocess.STDOUT,
text = True,
encoding = "utf-8",
errors = "replace",
start_new_session = True,
+ # A windowed Studio has no console; wsl.exe would otherwise open one.
+ creationflags = 0x08000000 if sys.platform == "win32" else 0,
**child_popen_kwargs(),
)
)
@@ -860,6 +970,11 @@ def _install(
reason = support_reason(engine)
if reason:
raise RuntimeError(reason)
+ from . import wsl_host
+
+ if wsl_host.active():
+ _install_wsl(engine, cancel)
+ return
uv = shutil.which("uv")
if uv is None:
raise RuntimeError("uv is unavailable. Repair the Studio installation and retry.")
@@ -982,8 +1097,16 @@ def _install(
_record_manifest(engine)
_update(engine, state = "success", phase = "ready", message = "Engine installed")
except Exception as exc:
+ from .wsl_host import Waiting
_update(
- engine, state = "cancelled" if cancel.is_set() else "error", phase = None, message = str(exc)
+ engine,
+ state = "waiting"
+ if isinstance(exc, Waiting)
+ else "cancelled"
+ if cancel.is_set()
+ else "error",
+ phase = None,
+ message = str(exc),
)
finally:
if destination is not None:
@@ -992,6 +1115,173 @@ def _install(
lease.__exit__(None, None, None)
+# Runs in the engine's interpreter inside WSL: the non-shared half of link_cuda_home and
+# managed_engine._deep_gemm_unloadable, whose paths Windows cannot inspect.
+_GUEST_FINALIZE = r"""
+import json, sys
+from pathlib import Path
+
+env = Path(sys.argv[1])
+site = next(env.glob("lib/python3.*/site-packages"))
+tree = site / "nvidia" / "cu13"
+home = env / "cuda"
+(home / "lib64").mkdir(parents = True, exist_ok = True)
+for name in ("bin", "nvvm", "include"):
+ if (tree / name).exists() and not (home / name).is_symlink():
+ (home / name).symlink_to(tree / name)
+cudart = tree / "lib" / "libcudart.so.13"
+if cudart.exists() and not (home / "lib64" / "libcudart.so").is_symlink():
+ (home / "lib64" / "libcudart.so").symlink_to(cudart)
+vendored = site / "vllm" / "third_party" / "deep_gemm"
+tag = "cpython-3" + site.parent.name.removeprefix("python3.")
+print(json.dumps({
+ "cuda_environment": {"CUDA_HOME": str(home), "CPATH": str(tree / "include")}
+ if (home / "bin" / "nvcc").exists() else {},
+ "deep_gemm_unloadable": not (site / "deep_gemm").is_dir() and vendored.is_dir()
+ and not any(vendored.glob(f"_C.{tag}-*.so")) and not any(vendored.glob("_C.abi3*.so")),
+}))
+"""
+_PROXIES = ("HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "https_proxy", "http_proxy", "no_proxy")
+
+
+def _install_wsl(engine: str, cancel: threading.Event) -> None:
+ """The same hash-pinned lock and checks as on Linux, run inside Studio's WSL distro. Always
+ isolated: Studio's Windows packages cannot serve a Linux interpreter."""
+ from . import wsl_host
+
+ guest_root = wsl_host.GUEST_ROOT
+ _update(engine, phase = "preparing_wsl", message = "Setting up the Unsloth WSL environment")
+ wsl_host.prepare(lambda text: _update(engine, activity = text), cancel)
+ if cancel.is_set():
+ raise RuntimeError("Installation cancelled.")
+ root = engine_root() / engine
+ root.mkdir(parents = True, exist_ok = True)
+ digest = profile_digest(engine)
+ directory = "env-" + uuid.uuid4().hex
+ base = f"{guest_root}/engines/{engine}"
+ destination = f"{base}/{directory}"
+ python = f"{destination}/bin/python"
+ uv = f"{guest_root}/bin/uv"
+ env = {
+ "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+ "PYTHONNOUSERSITE": "1",
+ "UV_CACHE_DIR": f"{guest_root}/uv-cache",
+ "UV_PYTHON_INSTALL_DIR": f"{guest_root}/python",
+ "UV_NO_CONFIG": "1",
+ "UV_CONCURRENT_DOWNLOADS": "4",
+ "UV_HTTP_RETRIES": "5",
+ # Cache and environments share the distro's ext4 disk.
+ "UV_LINK_MODE": "hardlink",
+ }
+ secrets = {key: os.environ[key] for key in _PROXIES if os.environ.get(key)}
+
+ def guest_run(argv):
+ command, windows_env = wsl_host.guest_command(argv, env = env, secrets = secrets)
+ _run(engine, command, cancel, env = windows_env)
+
+ try:
+ _update(engine, phase = "creating", message = "Preparing an isolated Python environment")
+ guest_run([uv, "venv", "--python", "{}.{}".format(*PYTHON), destination])
+ _update(engine, phase = "installing", message = "Downloading and installing engine packages")
+ lock = wsl_host.to_guest_path(requirements(engine))
+ guest_run(
+ [
+ uv,
+ "pip",
+ "sync",
+ "--python",
+ python,
+ "--require-hashes",
+ "--only-binary",
+ ":all:",
+ "--index-url",
+ "https://pypi.org/simple",
+ lock,
+ ]
+ )
+ _update(engine, phase = "checking", message = "Checking the installed engine")
+ from .engine_adapters import ADAPTERS
+
+ torch_version = _pins(engine)["torch"][0]
+ scripts = {
+ "check.py": _CHECK,
+ "finalize.py": _GUEST_FINALIZE,
+ "smoke.py": f"import {profile(engine)['module']}; import torch; import bitsandbytes; import torchao\n"
+ f"assert torch.__version__.split('+')[0] == {torch_version!r}\n"
+ "assert torch.version.cuda == '13.0'\n",
+ }
+ for name, source in scripts.items():
+ wsl_host.put(f"{destination}/{name}", source)
+ guest_run(
+ [
+ python,
+ "-I",
+ f"{destination}/check.py",
+ lock,
+ ",".join(profile(engine).get("omit", ())),
+ profile(engine)["cuda"],
+ "{}",
+ ]
+ )
+ guest_run([python, "-I", f"{destination}/smoke.py"])
+ guest_run([python, "-I", "-m", ADAPTERS[engine].module, "--help"])
+ facts = json.loads(
+ wsl_host.guest([python, "-I", f"{destination}/finalize.py", destination])
+ .strip()
+ .splitlines()[-1]
+ )
+ if (engine_root() / f"{engine}.cancel").exists():
+ cancel.set()
+ if cancel.is_set():
+ raise RuntimeError("Installation cancelled.")
+ if profile_digest(engine) != digest:
+ raise RuntimeError(
+ "Studio's engine profile changed during installation. Retry to use the updated profile."
+ )
+ prior = installed(engine)
+ _atomic_json(
+ root / "active.json",
+ {
+ "directory": directory,
+ "version": profile(engine)["version"],
+ "profile_digest": digest,
+ "shared": False,
+ "python": "{}.{}".format(*PYTHON),
+ "provided": {},
+ "host": "wsl",
+ "distro": wsl_host.distro_name(),
+ **facts,
+ "previous_directory": prior["directory"] if prior else None,
+ "previous": {
+ k: v
+ for k, v in prior.items()
+ if k not in ("path", "previous", "previous_directory")
+ }
+ if prior
+ else None,
+ },
+ )
+ # Committed: from here a failed cleanup must never delete the environment just activated.
+ destination = None
+ keep = [directory, *([prior["directory"]] if prior else [])]
+ try:
+ wsl_host.guest(
+ ["find", base, "-mindepth", "1", "-maxdepth", "1", "-name", "env-*"]
+ + [arg for name in keep for arg in ("!", "-name", name)]
+ + ["-exec", "rm", "-rf", "{}", "+"]
+ )
+ except (OSError, RuntimeError, subprocess.TimeoutExpired):
+ pass
+ finally:
+ if destination is not None:
+ try:
+ wsl_host.guest(["rm", "-rf", destination])
+ except (OSError, RuntimeError, subprocess.TimeoutExpired):
+ pass
+ _record_manifest(engine)
+ _update(engine, state = "success", phase = "ready", message = "Engine installed")
+
+
def start_install(engine: str) -> dict:
profile(engine)
with _lock:
@@ -1034,6 +1324,26 @@ def remove(engine: str) -> dict:
root = engine_root() / engine
if root.is_symlink():
raise RuntimeError("Engine directory must not be a symbolic link.")
+ from . import wsl_host
+
+ if (
+ wsl_host.active()
+ and not wsl_host.distro_ready()
+ and wsl_host.wsl_exe() is not None
+ and wsl_host.distro_name() in wsl_host.registered_distros()
+ ):
+ # Forgetting the engine now would strand its files inside the distro.
+ raise RuntimeError("WSL is not responding, so the engine cannot be removed. Try again.")
+ if wsl_host.active() and wsl_host.distro_ready():
+ # The compile caches live beside the environments, not under them.
+ wsl_host.guest(
+ [
+ "rm",
+ "-rf",
+ f"{wsl_host.GUEST_ROOT}/engines/{engine}",
+ f"{wsl_host.GUEST_ROOT}/cache/{engine}",
+ ]
+ )
shutil.rmtree(root, ignore_errors = False) if root.exists() else None
with _lock:
_jobs.pop(engine, None)
@@ -1043,6 +1353,29 @@ def remove(engine: str) -> dict:
return status(engine)
+def remove_wsl_environment() -> list[dict]:
+ """Unregister the private distro. Every engine lives in it, so all must be idle."""
+ from contextlib import ExitStack
+ from . import wsl_host
+
+ if not wsl_host.active():
+ raise RuntimeError("Studio only creates a WSL environment on Windows.")
+ with ExitStack() as stack:
+ for engine in PROFILES:
+ stack.enter_context(engine_lease(engine, exclusive = True))
+ wsl_host.unregister()
+ for engine in PROFILES:
+ root = engine_root() / engine
+ if root.exists() and not root.is_symlink():
+ shutil.rmtree(root)
+ (engine_root() / f"{engine}.job.json").unlink(missing_ok = True)
+ with _lock:
+ _jobs.pop(engine, None)
+ for engine in PROFILES:
+ _record_manifest(engine)
+ return [status(engine) for engine in PROFILES]
+
+
def rollback(engine: str) -> dict:
with engine_lease(engine, exclusive = True):
info = installed(engine)
@@ -1056,7 +1389,18 @@ def rollback(engine: str) -> dict:
raise RuntimeError("No previous engine installation is available.")
root = engine_root() / engine
path = root / directory
- if path.is_symlink() or not (path / "bin" / "python").is_file():
+ if previous.get("host") == "wsl":
+ from . import wsl_host
+ try:
+ wsl_host.guest(
+ ["test", "-f", f"{wsl_host.GUEST_ROOT}/engines/{engine}/{directory}/bin/python"]
+ )
+ present = True
+ except (OSError, RuntimeError, subprocess.TimeoutExpired):
+ present = False
+ else:
+ present = not path.is_symlink() and (path / "bin" / "python").is_file()
+ if not present:
raise RuntimeError(
"The previous engine installation is unavailable. Repair the engine instead."
)
diff --git a/studio/backend/core/inference/managed_engine.py b/studio/backend/core/inference/managed_engine.py
index fc641fc3a1a..657211e8cf6 100644
--- a/studio/backend/core/inference/managed_engine.py
+++ b/studio/backend/core/inference/managed_engine.py
@@ -11,6 +11,9 @@ import os
import secrets
import socket
import subprocess
+
+from utils.subprocess_compat import windows_hidden_subprocess_kwargs
+import sys
import threading
import time
from collections import deque
@@ -21,6 +24,7 @@ import httpx
from utils.hardware.hardware import resolve_requested_gpu_ids
from .engine_install import (
+ driver_library_path,
engine_lease,
installed,
profile,
@@ -40,6 +44,13 @@ from .engine_adapters import (
)
+def _offline(env) -> bool:
+ return any(
+ str(env.get(key, "")).strip().lower() in {"1", "true", "yes", "on"}
+ for key in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE")
+ )
+
+
def validate_load(engine: str, request) -> list[int]:
"""Returns the physical GPU ids to launch on, all inside the GPUs Studio may use."""
profile(engine)
@@ -177,15 +188,17 @@ def validate_model(
}
if precision == "fp8":
# Eager TorchAO FP8 on Ampere: Triton cannot compile its casts, SGLang online FP8 is invalid.
+ from utils.hardware.nvidia import _nvidia_smi_executable
result = subprocess.run(
[
- "nvidia-smi",
+ _nvidia_smi_executable(),
"--id",
",".join(str(i) for i in (gpu_ids or [0])),
"--query-gpu=compute_cap",
"--format=csv,noheader,nounits",
],
capture_output = True,
+ **windows_hidden_subprocess_kwargs(),
text = True,
encoding = "utf-8",
errors = "replace",
@@ -234,6 +247,26 @@ STARTUP_STALL_S = 900
STARTUP_LIMIT_S = 4 * 3600
+def _token_file_token(env) -> str | None:
+ """The `hf auth login` token a local engine would read from its inherited HF_HOME; the WSL
+ guest gets its own HF_HOME, so the token has to cross over. Anonymous loads keep none."""
+ if (env.get("HF_HUB_DISABLE_IMPLICIT_TOKEN") or "").upper() in ("1", "ON", "YES", "TRUE"):
+ return None
+ home = env.get("HF_HOME") or os.path.join(
+ env.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache"), "huggingface"
+ )
+ path = env.get("HF_TOKEN_PATH") or os.path.join(
+ os.path.expandvars(os.path.expanduser(home)), "token"
+ )
+ try:
+ token = (
+ Path(os.path.expandvars(os.path.expanduser(path))).read_text(encoding = "utf-8").strip()
+ )
+ except (OSError, UnicodeDecodeError):
+ return None
+ return token or None
+
+
class ManagedEngine:
def __init__(self, engine: str):
self.engine = engine
@@ -249,6 +282,7 @@ class ManagedEngine:
self._tail = deque(maxlen = 200)
self._last_output = time.monotonic()
self.base_url = ""
+ self._guest_environment = None
# A URL-safe token can start with '-', which CLI parsers read as an option.
self.key = "studio-" + secrets.token_urlsafe(32)
@@ -298,86 +332,95 @@ class ManagedEngine:
raise RuntimeError("Could not allocate an inference server port.")
self.base_url = f"http://127.0.0.1:{port}"
self.model, self.context = model, context or 4096
- child_env = {
- k: v
- for k, v in env.items()
- if not k.startswith(("PYTHON", "UV_", "PIP_", "SGLANG_", "VLLM_"))
- }
- from utils.native_path_leases import child_env_without_native_path_secret
-
- child_env = child_env_without_native_path_secret(child_env)
- child_env.pop("VIRTUAL_ENV", None)
- child_env.pop("LD_PRELOAD", None)
- child_env.pop("LD_LIBRARY_PATH", None)
- child_env["PATH"] = os.pathsep.join(
- [
- info["path"] + "/bin",
- *([info["studio_prefix"] + "/bin"] if info.get("shared") else []),
- child_env.get("PATH", os.defpath),
- ]
- )
- child_env["CUDA_VISIBLE_DEVICES"] = ",".join(str(i) for i in (gpu_ids or [0]))
- child_env["PYTHONNOUSERSITE"] = "1"
- from .engine_install import engine_root
-
- # Compiler caches are keyed per launch config: reuse across dtype/GPU changes breaks.
- policy = Path(__file__).with_name("engine_adapters.py").read_bytes()
- policy += Path(__file__).with_name(f"{self.engine}_server.py").read_bytes()
- cache_key = hashlib.sha256(
- policy
- + json.dumps(
- [info.get("profile_digest"), model, self.context, gpu_ids, options],
- sort_keys = True,
- ).encode()
- ).hexdigest()[:16]
- cache = engine_root() / self.engine / "cache" / cache_key
- child_env["VLLM_CACHE_ROOT"] = str(cache)
- child_env["TORCHINDUCTOR_CACHE_DIR"] = str(cache / "inductor")
- child_env["TRITON_CACHE_DIR"] = str(cache / "triton")
- # FlashInfer's JIT build files name this env's sources; a shared ~/.cache outlives a replaced env.
- child_env["FLASHINFER_WORKSPACE_BASE"] = info["path"]
- from .engine_install import cuda_environment
-
- child_env.pop("CUDA_PATH", None)
- child_env.update(cuda_environment(info))
- memory_fraction = gpu_memory_fraction(
- gpu_ids or [0], memory_reserve_mib(self.engine, options), RESERVE_SHARE
- )
- child_env.update(self.adapter.environment(len(gpu_ids or [0])))
- child_env.update(self.adapter.key_environment(self.key))
- if self.engine == "vllm" and _deep_gemm_unloadable(info["path"]):
- child_env["VLLM_USE_DEEP_GEMM"] = "0"
+ stdin = None
+ if info.get("host") == "wsl":
+ command, child_env = self._wsl_command(
+ info, env, gpu_ids, options, trust_remote_code, model, model_path, port
+ )
+ # The guest runner ends the engine when this pipe closes (stop, or Studio dying).
+ stdin = subprocess.PIPE
+ self._guest_environment = info["path"]
+ else:
+ child_env = {
+ k: v
+ for k, v in env.items()
+ if not k.startswith(("PYTHON", "UV_", "PIP_", "SGLANG_", "VLLM_"))
+ }
+ from utils.native_path_leases import child_env_without_native_path_secret
+
+ child_env = child_env_without_native_path_secret(child_env)
+ child_env.pop("VIRTUAL_ENV", None)
+ child_env.pop("LD_PRELOAD", None)
+ child_env.pop("LD_LIBRARY_PATH", None)
+ if driver := driver_library_path(env):
+ child_env["LD_LIBRARY_PATH"] = driver
+ child_env["PATH"] = os.pathsep.join(
+ [
+ info["path"] + "/bin",
+ *([info["studio_prefix"] + "/bin"] if info.get("shared") else []),
+ child_env.get("PATH", os.defpath),
+ ]
+ )
+ child_env["CUDA_VISIBLE_DEVICES"] = ",".join(str(i) for i in (gpu_ids or [0]))
+ child_env["PYTHONNOUSERSITE"] = "1"
+ from .engine_install import engine_root
+
+ cache = (
+ engine_root()
+ / self.engine
+ / "cache"
+ / self._cache_key(info, model, gpu_ids, options)
+ )
+ child_env["VLLM_CACHE_ROOT"] = str(cache)
+ child_env["TORCHINDUCTOR_CACHE_DIR"] = str(cache / "inductor")
+ child_env["TRITON_CACHE_DIR"] = str(cache / "triton")
+ # FlashInfer's JIT build files name this env's sources; a shared ~/.cache outlives a replaced env.
+ child_env["FLASHINFER_WORKSPACE_BASE"] = info["path"]
+ from .engine_install import cuda_environment
+
+ child_env.pop("CUDA_PATH", None)
+ child_env.update(cuda_environment(info))
+ memory_fraction = gpu_memory_fraction(
+ gpu_ids or [0], memory_reserve_mib(self.engine, options), RESERVE_SHARE
+ )
+ child_env.update(self.adapter.environment(len(gpu_ids or [0])))
+ child_env.update(self.adapter.key_environment(self.key))
+ if self.engine == "vllm" and _deep_gemm_unloadable(info["path"]):
+ child_env["VLLM_USE_DEEP_GEMM"] = "0"
+ command = self.adapter.command(
+ info["path"] + "/bin/python",
+ model_path or model,
+ port,
+ self.key,
+ self.context,
+ memory_fraction,
+ len(gpu_ids or [0]),
+ **(
+ {
+ "options": {**options, "engine_version": info.get("version")},
+ "trust_remote_code": trust_remote_code,
+ }
+ if options
+ else {}
+ ),
+ **(
+ {"served_model_name": model}
+ if model_path and model_path != model
+ else {}
+ ),
+ )
self.process = spawn_on_lifetime_thread(
lambda: subprocess.Popen(
- self.adapter.command(
- info["path"] + "/bin/python",
- model_path or model,
- port,
- self.key,
- self.context,
- memory_fraction,
- len(gpu_ids or [0]),
- **(
- {
- "options": {**options, "engine_version": info.get("version")},
- "trust_remote_code": trust_remote_code,
- }
- if options
- else {}
- ),
- **(
- {"served_model_name": model}
- if model_path and model_path != model
- else {}
- ),
- ),
+ command,
env = child_env,
+ stdin = stdin,
stdout = subprocess.PIPE,
stderr = subprocess.STDOUT,
text = True,
encoding = "utf-8",
errors = "replace",
start_new_session = True,
+ creationflags = 0x08000000 if sys.platform == "win32" else 0,
**child_popen_kwargs(),
)
)
@@ -419,6 +462,100 @@ class ManagedEngine:
self.stop()
raise
+ def _cache_key(self, info, model, gpu_ids, options) -> str:
+ # Compiler caches are keyed per launch config: reuse across dtype/GPU changes breaks.
+ policy = Path(__file__).with_name("engine_adapters.py").read_bytes()
+ policy += Path(__file__).with_name(f"{self.engine}_server.py").read_bytes()
+ return hashlib.sha256(
+ policy
+ + json.dumps(
+ [info.get("profile_digest"), model, self.context, gpu_ids, options],
+ sort_keys = True,
+ ).encode()
+ ).hexdigest()[:16]
+
+ def _wsl_command(
+ self, info, env, gpu_ids, options, trust_remote_code, model, model_path, port
+ ) -> tuple[list[str], dict]:
+ """The engine inside Studio's WSL distro: only the variables it needs cross over, since
+ Studio's Windows paths mean nothing there; the token crosses through WSLENV, not argv."""
+ from . import wsl_host
+ from hub.utils.hf_tokens import _HF_TOKEN_ENV_KEYS
+
+ guest_root = wsl_host.GUEST_ROOT
+ environment = info["path"]
+ wsl_host.guest(["test", "-x", environment + "/bin/python"], timeout = 300)
+ cache = f"{guest_root}/cache/{self.engine}/{self._cache_key(info, model, gpu_ids, options)}"
+ guest_env = {
+ "PATH": environment
+ + "/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/wsl/lib",
+ "CUDA_DEVICE_ORDER": "PCI_BUS_ID",
+ "CUDA_VISIBLE_DEVICES": ",".join(
+ str(i) for i in wsl_host.guest_gpu_indices(list(gpu_ids or [0]))
+ ),
+ "PYTHONNOUSERSITE": "1",
+ # Weights download inside the distro's own disk; /mnt/c reads are far slower.
+ "HF_HOME": f"{guest_root}/hf",
+ "VLLM_CACHE_ROOT": cache,
+ "TORCHINDUCTOR_CACHE_DIR": cache + "/inductor",
+ "TRITON_CACHE_DIR": cache + "/triton",
+ "FLASHINFER_WORKSPACE_BASE": environment,
+ **({"HF_ENDPOINT": env["HF_ENDPOINT"]} if env.get("HF_ENDPOINT") else {}),
+ # Cache-only mode must hold in the guest too.
+ **({"HF_HUB_OFFLINE": "1"} if _offline(env) else {}),
+ }
+ from .engine_install import cuda_environment
+
+ guest_env.update(cuda_environment(info))
+ guest_env.update(self.adapter.environment(len(gpu_ids or [0])))
+ if self.engine == "vllm" and info.get("deep_gemm_unloadable"):
+ guest_env["VLLM_USE_DEEP_GEMM"] = "0"
+ target = wsl_host.to_guest_path(model_path) if model_path else model
+ command = self.adapter.command(
+ environment + "/bin/python",
+ target,
+ port,
+ self.key,
+ self.context,
+ gpu_memory_fraction(
+ gpu_ids or [0], memory_reserve_mib(self.engine, options), RESERVE_SHARE
+ ),
+ len(gpu_ids or [0]),
+ **(
+ {
+ "options": {**options, "engine_version": info.get("version")},
+ "trust_remote_code": trust_remote_code,
+ }
+ if options
+ else {}
+ ),
+ **({"served_model_name": model} if model_path and model_path != model else {}),
+ )
+ # The engine launchers are Studio source files; the guest reads them through /mnt.
+ server = str(Path(__file__).with_name(f"{self.engine}_server.py"))
+ command = [wsl_host.to_guest_path(arg) if arg == server else arg for arg in command]
+ secrets = {
+ key: env[key]
+ for key in (*_HF_TOKEN_ENV_KEYS, "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY")
+ if env.get(key)
+ }
+ if not any(key in secrets for key in _HF_TOKEN_ENV_KEYS):
+ token = _token_file_token(env)
+ if token:
+ secrets["HF_TOKEN"] = token
+ # The engine key goes through WSLENV like the tokens: guest_env lands on /usr/bin/env's argv.
+ secrets.update(self.adapter.key_environment(self.key))
+ return wsl_host.guest_command(
+ [
+ f"{guest_root}/bin/run-engine",
+ "/usr/bin/env",
+ *[f"{k}={v}" for k, v in guest_env.items()],
+ *command,
+ ],
+ secrets = secrets,
+ withhold = tuple(key.upper() for key in _HF_TOKEN_ENV_KEYS if key not in secrets),
+ )
+
@property
def headers(self):
return {"Authorization": "Bearer " + self.key}
@@ -443,11 +580,25 @@ class ManagedEngine:
self._cancel.set()
with self._lock:
if self.process is not None:
- terminate_pid(self.process.pid, timeout = 5, owner_verified = True)
+ graceful = False
+ if self.process.stdin is not None:
+ # WSL: closing the pipe makes the guest runner stop the engine's process group.
+ try:
+ self.process.stdin.close()
+ self.process.wait(timeout = 15)
+ graceful = True
+ except (OSError, subprocess.TimeoutExpired):
+ pass
+ if not graceful:
+ terminate_pid(self.process.pid, timeout = 5, owner_verified = True)
try:
self.process.wait(timeout = 5)
except subprocess.TimeoutExpired:
return False
+ if self._guest_environment and not graceful:
+ from .wsl_host import kill_environment
+ kill_environment(self._guest_environment)
+ self._guest_environment = None
forget_pid(self.process.pid)
if self._reader:
self._reader.join(timeout = 2)
diff --git a/studio/backend/core/inference/wsl_host.py b/studio/backend/core/inference/wsl_host.py
new file mode 100644
index 00000000000..dbebbe49782
--- /dev/null
+++ b/studio/backend/core/inference/wsl_host.py
@@ -0,0 +1,558 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Managed engines on native Windows run inside a private WSL2 distro that Studio owns.
+
+Studio stays a Windows process: it enables WSL (one UAC prompt), imports a pinned Ubuntu rootfs
+as its own distro, and drives everything through ``wsl.exe`` argv lists. The engine's HTTP
+server is reached through WSL2's localhost forwarding. The user's own distros are never touched.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+
+import sys
+import threading
+import time
+from pathlib import Path, PureWindowsPath
+
+# Pinned: a dated release, not "current", so the bytes never move under the hash.
+ROOTFS = {
+ "url": "https://cloud-images.ubuntu.com/wsl/releases/24.04/20240423/ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz",
+ "sha256": "8251e27ffff381a4af5f41dcb94d867de3e0d9774a9241908ab34555d99315ea",
+ "size": 356739129,
+}
+UV = {
+ "url": "https://github.com/astral-sh/uv/releases/download/0.12.19/uv-x86_64-unknown-linux-gnu.tar.gz",
+ "sha256": "23bf5552d220e0842b65c862097b2ebaeba0064b74eda5e565e77fd25969d8c8",
+ "size": 19831732,
+}
+_PREPARE_LOCK = threading.Lock()
+MIN_BUILD = 19044 # Windows 10 21H2: first build with CUDA in WSL2.
+GUEST_ROOT = "/opt/unsloth"
+_CREATE_NO_WINDOW = 0x08000000
+
+# systemd off: nothing else runs, so the distro starts in about a second and idles cleanly.
+WSL_CONF = """[boot]
+systemd=false
+[interop]
+appendWindowsPath=false
+[automount]
+root=/mnt/
+"""
+
+# Runs the engine in its own process group. The engine exits when Studio closes the stdin
+# pipe, which happens on stop and when Studio itself dies, so vLLM never outlives its owner.
+# A non-interactive sh gives background jobs /dev/null as stdin, hence the fd 3 duplicate.
+RUNNER = """#!/bin/sh
+exec 3<&0
+setsid "$@" </dev/null &
+child=$!
+trap 'kill -TERM -$child 2>/dev/null' TERM INT HUP
+(cat <&3 >/dev/null; kill -TERM -$child 2>/dev/null; sleep 10; kill -KILL -$child 2>/dev/null) &
+watcher=$!
+exec 3<&-
+wait $child
+status=$?
+kill $watcher 2>/dev/null
+# Workers the engine forked outlive a crashed leader and would hold GPU memory.
+if kill -0 -$child 2>/dev/null; then
+ kill -TERM -$child 2>/dev/null; sleep 5; kill -KILL -$child 2>/dev/null
+fi
+exit $status
+"""
+
+# Windows messages and HRESULTs `wsl --import` / `--status` print for hosts that cannot run WSL2.
+_BLOCKERS = (
+ (
+ # learn.microsoft.com/windows/wsl/troubleshooting lists both codes under BIOS virtualization.
+ ("0x80370102", "0x80070003", "HCS_E_HYPERV_NOT_INSTALLED"),
+ "Turn on virtualization (Intel VT-x or AMD-V) in the BIOS/UEFI settings and make sure the "
+ "Virtual Machine Platform Windows feature is on, then click Install again.",
+ ),
+ (
+ ("0x800701bc",),
+ "WSL needs a kernel update. Run 'wsl --update' in a terminal, then click Install again.",
+ ),
+ (
+ ("Group Policy", "blocked by policy", "0x80070005"),
+ "WSL is blocked on this computer by an administrator policy.",
+ ),
+)
+
+
+class Waiting(Exception):
+ """A step only the user can finish: a UAC prompt or a Windows restart."""
+
+
+def active() -> bool:
+ return sys.platform == "win32"
+
+
+def host_dir() -> Path:
+ from .engine_install import engine_root
+ return engine_root() / "wsl"
+
+
+def distro_name() -> str:
+ from utils.paths.storage_roots import studio_root
+
+ # One distro per Studio home, so two installs never drive the same guest.
+ return "Unsloth-Engines-" + hashlib.sha256(str(studio_root()).encode()).hexdigest()[:8]
+
+
+def wsl_exe() -> str | None:
+ system = Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32" / "wsl.exe"
+ return str(system) if system.is_file() else shutil.which("wsl.exe")
+
+
+def native_machine() -> str:
+ """The OS architecture, not the interpreter's: an x64 Python under ARM64 emulation reports AMD64."""
+ try:
+ import ctypes
+
+ process, native = ctypes.c_ushort(), ctypes.c_ushort()
+ kernel32 = ctypes.windll.kernel32
+ if kernel32.IsWow64Process2(
+ kernel32.GetCurrentProcess(), ctypes.byref(process), ctypes.byref(native)
+ ):
+ return {0x8664: "x86_64", 0xAA64: "arm64", 0x14C: "x86"}.get(native.value, "unknown")
+ except (AttributeError, OSError):
+ pass
+ arch = os.environ.get("PROCESSOR_ARCHITEW6432") or os.environ.get("PROCESSOR_ARCHITECTURE", "")
+ return {"AMD64": "x86_64", "ARM64": "arm64"}.get(arch.upper(), arch.lower())
+
+
+def windows_build() -> int:
+ try:
+ return sys.getwindowsversion().build
+ except AttributeError:
+ return 0
+
+
+def support_reason() -> str | None:
+ if native_machine() != "x86_64":
+ return "Managed engines on Windows need an x64 PC; the engine packages are x86_64 only."
+ if windows_build() < MIN_BUILD:
+ return "Managed engines need Windows 10 21H2 (build 19044) or newer for GPU access in WSL."
+ return None
+
+
+def boot_id() -> int:
+ """Minute the machine booted; unchanged across Studio restarts, new after a Windows restart."""
+ try:
+ import ctypes
+
+ tick = ctypes.windll.kernel32.GetTickCount64
+ tick.restype = ctypes.c_ulonglong
+ return int(time.time() - tick() / 1000) // 60
+ except (AttributeError, OSError):
+ return 0
+
+
+def decode(raw: bytes) -> str:
+ """wsl.exe writes its own messages as UTF-16LE; guest programs write UTF-8."""
+ # Localized messages can open with a non-ASCII character, so no single byte identifies
+ # UTF-16; UTF-8 text never carries NULs and CJK UTF-16 is almost never valid UTF-8.
+ if raw[:2] == b"\xff\xfe" or b"\x00" in raw:
+ return raw.decode("utf-16-le", errors = "replace").lstrip("\ufeff")
+ try:
+ return raw.decode("utf-8")
+ except UnicodeDecodeError:
+ if len(raw) % 2 == 0:
+ return raw.decode("utf-16-le", errors = "replace")
+ return raw.decode("utf-8", errors = "replace")
+
+
+def run(
+ args: list[str],
+ *,
+ timeout: float = 120,
+ input: bytes | None = None,
+ env = None,
+):
+ exe = wsl_exe()
+ if exe is None:
+ raise RuntimeError("WSL is not installed.")
+ result = subprocess.run(
+ [exe, *args],
+ input = input,
+ capture_output = True,
+ timeout = timeout,
+ env = env,
+ creationflags = _CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+ )
+ return result.returncode, decode(result.stdout + result.stderr)
+
+
+def blocker(output: str) -> str | None:
+ for needles, message in _BLOCKERS:
+ if any(needle.lower() in output.lower() for needle in needles):
+ return message
+ return None
+
+
+def _state_file() -> Path:
+ return host_dir() / "state.json"
+
+
+def read_state() -> dict:
+ try:
+ return json.loads(_state_file().read_text(encoding = "utf-8"))
+ except (OSError, ValueError):
+ return {}
+
+
+def write_state(**values) -> None:
+ from .engine_install import _atomic_json
+ host_dir().mkdir(parents = True, exist_ok = True)
+ _atomic_json(_state_file(), {**read_state(), **values})
+
+
+def wsl_state() -> str:
+ """ready | missing | restart_required | blocked: <message>. Never elevates or boots a distro."""
+ if wsl_exe() is None:
+ return "missing"
+ code, output = run(["--status"], timeout = 60)
+ if code == 0:
+ write_state(state = "ready")
+ return "ready"
+ state = read_state()
+ if state.get("state") == "restart_required":
+ if state.get("boot") == boot_id():
+ return "restart_required"
+ # Restarted and WSL still does not start: something the user must fix.
+ return "blocked: " + (blocker(output) or output.strip()[-300:] or "WSL did not start.")
+ return "missing"
+
+
+def enable_wsl() -> str:
+ """Install WSL with one UAC prompt. Only this fixed argv is ever elevated; the distro import
+ runs unelevated, since an elevating admin account would register it under its own profile."""
+ import ctypes
+ from ctypes import wintypes
+
+ class ShellExecuteInfo(ctypes.Structure):
+ _fields_ = [
+ ("cbSize", wintypes.DWORD),
+ ("fMask", ctypes.c_ulong),
+ ("hwnd", wintypes.HWND),
+ ("lpVerb", wintypes.LPCWSTR),
+ ("lpFile", wintypes.LPCWSTR),
+ ("lpParameters", wintypes.LPCWSTR),
+ ("lpDirectory", wintypes.LPCWSTR),
+ ("nShow", ctypes.c_int),
+ ("hInstApp", wintypes.HINSTANCE),
+ ("lpIDList", ctypes.c_void_p),
+ ("lpClass", wintypes.LPCWSTR),
+ ("hkeyClass", wintypes.HKEY),
+ ("dwHotKey", wintypes.DWORD),
+ ("hIcon", wintypes.HANDLE),
+ ("hProcess", wintypes.HANDLE),
+ ]
+
+ info = ShellExecuteInfo()
+ info.cbSize = ctypes.sizeof(info)
+ info.fMask = 0x00000040 # SEE_MASK_NOCLOSEPROCESS
+ info.lpVerb = "runas"
+ info.lpFile = str(Path(os.environ.get("SystemRoot", r"C:\Windows")) / "System32" / "wsl.exe")
+ info.lpParameters = "--install --no-distribution"
+ info.nShow = 0
+ if not ctypes.windll.shell32.ShellExecuteExW(ctypes.byref(info)):
+ if ctypes.GetLastError() == 1223: # ERROR_CANCELLED
+ raise Waiting(
+ "Windows asked for permission to install WSL and it was declined. Click Install to ask again."
+ )
+ raise RuntimeError("Windows could not start the WSL installer.")
+ kernel32 = ctypes.windll.kernel32
+ kernel32.WaitForSingleObject(info.hProcess, 30 * 60 * 1000)
+ code = wintypes.DWORD()
+ kernel32.GetExitCodeProcess(info.hProcess, ctypes.byref(code))
+ kernel32.CloseHandle(info.hProcess)
+ state = wsl_state()
+ if state == "ready":
+ return state
+ write_state(state = "restart_required", boot = boot_id(), installer_exit = code.value)
+ raise Waiting("Restart Windows to finish installing WSL, then click Install again.")
+
+
+def to_guest_path(path: str | os.PathLike) -> str:
+ """C:\\Users\\a -> /mnt/c/Users/a under the automount root this distro is configured with."""
+ windows = PureWindowsPath(path)
+ if not re.fullmatch(r"[A-Za-z]:", windows.drive):
+ raise ValueError(f"Engines inside WSL can only read local drive paths, not {path}")
+ rest = "/".join(windows.parts[1:])
+ return f"/mnt/{windows.drive[0].lower()}/{rest}".rstrip("/")
+
+
+def guest_command(
+ argv: list[str],
+ *,
+ env: dict[str, str] | None = None,
+ secrets: dict[str, str] | None = None,
+ withhold: tuple[str, ...] = (),
+) -> tuple[list[str], dict[str, str]]:
+ """wsl.exe argv plus the Windows env for it. Secrets cross through WSLENV, never argv, so they
+ stay out of the Windows process list."""
+ exe = wsl_exe()
+ if exe is None:
+ raise RuntimeError("WSL is not installed.")
+ secrets = secrets or {}
+ # `withhold` keys the caller chose not to send (an anonymous load) must not ride in on the
+ # user's own WSLENV either.
+ windows_env = {key: value for key, value in os.environ.items() if key.upper() not in withhold}
+ windows_env.update(secrets)
+ shared = [item for item in windows_env.get("WSLENV", "").split(":") if item]
+ shared = [
+ item
+ for item in shared
+ if item.split("/")[0] not in secrets and item.split("/")[0].upper() not in withhold
+ ]
+ windows_env["WSLENV"] = ":".join([*shared, *(f"{key}/u" for key in secrets)])
+ command = [exe, "-d", distro_name(), "-u", "root", "--cd", "/root", "--", "/usr/bin/env"]
+ command += [f"{key}={value}" for key, value in (env or {}).items()]
+ return command + list(argv), windows_env
+
+
+def guest(
+ argv: list[str],
+ *,
+ env: dict[str, str] | None = None,
+ timeout: float = 600,
+ input: bytes | None = None,
+) -> str:
+ command, windows_env = guest_command(argv, env = env)
+ code, output = run(command[1:], timeout = timeout, input = input, env = windows_env)
+ if code:
+ raise RuntimeError(output.strip()[-2000:] or f"{argv[0]} failed in WSL.")
+ return output
+
+
+def put(
+ path: str,
+ text: str,
+ mode: str = "644",
+) -> None:
+ """Write a guest file through stdin: multi-line argv does not survive Windows quoting intact."""
+ guest(["sh", "-c", f'cat > "$0" && chmod {mode} "$0"', path], input = text.encode())
+
+
+def distro_ready() -> bool:
+ try:
+ command, windows_env = guest_command(["test", "-f", f"{GUEST_ROOT}/owner.json"])
+ code, _ = run(command[1:], timeout = 120, env = windows_env)
+ except (OSError, RuntimeError, subprocess.TimeoutExpired):
+ return False
+ return code == 0
+
+
+def download(
+ spec: dict,
+ name: str,
+ progress = None,
+ cancel = None,
+) -> Path:
+ """Fetch a pinned artifact once; a partial or tampered file never survives the hash check."""
+ import httpx
+
+ folder = host_dir() / "downloads"
+ folder.mkdir(parents = True, exist_ok = True)
+ target = folder / f"{spec['sha256'][:16]}-{name}"
+ if target.is_file() and _sha256(target) == spec["sha256"]:
+ return target
+ partial = target.with_suffix(target.suffix + ".part")
+ digest = hashlib.sha256()
+ done = 0
+ with httpx.stream("GET", spec["url"], follow_redirects = True, timeout = 60) as response:
+ response.raise_for_status()
+ with partial.open("wb") as handle:
+ for chunk in response.iter_bytes(1 << 20):
+ if cancel is not None and cancel.is_set():
+ break
+ handle.write(chunk)
+ digest.update(chunk)
+ done += len(chunk)
+ if progress:
+ progress(f"Downloading {name}: {done >> 20} / {spec['size'] >> 20} MiB")
+ if cancel is not None and cancel.is_set():
+ partial.unlink(missing_ok = True)
+ raise RuntimeError("Installation cancelled.")
+ if digest.hexdigest() != spec["sha256"]:
+ partial.unlink(missing_ok = True)
+ raise RuntimeError(f"{name} did not match its pinned checksum. Retry the installation.")
+ os.replace(partial, target)
+ return target
+
+
+def _sha256(path: Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as handle:
+ for chunk in iter(lambda: handle.read(1 << 20), b""):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def ensure_distro(progress = None, cancel = None) -> None:
+ """Idempotent: import the private distro, configure it, and install uv inside it."""
+ from utils.paths.storage_roots import studio_root
+
+ if not distro_ready():
+ rootfs = download(ROOTFS, "ubuntu-24.04-wsl.rootfs.tar.gz", progress, cancel)
+ if progress:
+ progress("Creating the Unsloth WSL environment")
+ # A half-imported distro from an interrupted run would make --import fail.
+ code, output = run(["--unregister", distro_name()], timeout = 300)
+ # Its VHD lives in the target: never delete it under a distro that is still registered.
+ if code and distro_name() in registered_distros():
+ raise RuntimeError("Could not reset the WSL environment. " + output.strip()[-500:])
+ target = host_dir() / "distro"
+ # An import interrupted before registration leaves its VHD behind and --import refuses it.
+ shutil.rmtree(target, ignore_errors = True)
+ target.mkdir(parents = True, exist_ok = True)
+ code, output = run(
+ ["--import", distro_name(), str(target), str(rootfs), "--version", "2"], timeout = 1800
+ )
+ if code:
+ raise RuntimeError(
+ blocker(output) or "Could not create the WSL environment. " + output.strip()[-500:]
+ )
+ put("/etc/wsl.conf", WSL_CONF)
+ run(["--terminate", distro_name()], timeout = 120)
+ # The GPU paravirtualization library comes from the Windows driver, not the distro.
+ try:
+ guest(["test", "-e", "/usr/lib/wsl/lib/libcuda.so"])
+ except RuntimeError:
+ raise RuntimeError(
+ "WSL cannot see the NVIDIA GPU. Update the NVIDIA Windows driver, then click Install again."
+ ) from None
+ owner = json.dumps({"studio_home": str(studio_root()), "distro": distro_name()})
+ guest(["mkdir", "-p", f"{GUEST_ROOT}/bin"])
+ put(f"{GUEST_ROOT}/owner.json", owner)
+ put(f"{GUEST_ROOT}/bin/run-engine", RUNNER, "755")
+ try:
+ guest(["test", "-x", f"{GUEST_ROOT}/bin/uv"])
+ except RuntimeError:
+ archive = download(UV, "uv-x86_64-unknown-linux-gnu.tar.gz", progress, cancel)
+ guest(
+ [
+ "tar",
+ "-xzf",
+ to_guest_path(archive),
+ "-C",
+ f"{GUEST_ROOT}/bin",
+ "--strip-components=1",
+ ]
+ )
+ write_state(state = "ready", distro = distro_name())
+
+
+def prepare(progress = None, cancel = None) -> None:
+ """Everything before the engine's own packages. Raises ``Waiting`` for a user step."""
+ # vLLM and SGLang installs share one download, one elevation prompt and one distro import.
+ with _PREPARE_LOCK:
+ _prepare(progress, cancel)
+
+
+def _prepare(progress, cancel) -> None:
+ state = wsl_state()
+ if state.startswith("blocked"):
+ raise RuntimeError(state.partition(": ")[2])
+ if state == "restart_required":
+ raise Waiting("Restart Windows to finish installing WSL, then click Install again.")
+ if state == "missing":
+ if progress:
+ progress("Approve the Windows prompt to install WSL")
+ enable_wsl()
+ ensure_distro(progress, cancel)
+
+
+def _uuid_table(output: str) -> dict[int, str]:
+ uuids = {}
+ for line in output.splitlines():
+ index, _, uuid = (part.strip() for part in line.partition(","))
+ if index.isdigit() and uuid.startswith("GPU-"):
+ uuids[int(index)] = uuid
+ return uuids
+
+
+def gpu_uuids(gpu_ids: list[int]) -> list[str]:
+ result = subprocess.run(
+ [_nvidia_smi(), "--query-gpu=index,uuid", "--format=csv,noheader"],
+ capture_output = True,
+ text = True,
+ encoding = "utf-8",
+ errors = "replace",
+ timeout = 60,
+ creationflags = _CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+ )
+ uuids = _uuid_table(result.stdout)
+ missing = [gpu_id for gpu_id in gpu_ids if gpu_id not in uuids]
+ if result.returncode or missing:
+ raise RuntimeError("Could not identify the selected GPUs for WSL. Check the NVIDIA driver.")
+ return [uuids[gpu_id] for gpu_id in gpu_ids]
+
+
+def guest_gpu_indices(gpu_ids: list[int]) -> list[int]:
+ """Windows and WSL may number the same GPUs differently, so match by UUID. vLLM parses
+ CUDA_VISIBLE_DEVICES as integers, so the result is guest indices, used with
+ CUDA_DEVICE_ORDER=PCI_BUS_ID so CUDA ordinals equal nvidia-smi's."""
+ wanted = gpu_uuids(gpu_ids)
+ table = _uuid_table(
+ guest(
+ [
+ "sh",
+ "-c",
+ 'PATH="$PATH:/usr/lib/wsl/lib" nvidia-smi --query-gpu=index,uuid --format=csv,noheader',
+ ],
+ timeout = 120,
+ )
+ )
+ by_uuid = {uuid: index for index, uuid in table.items()}
+ if any(uuid not in by_uuid for uuid in wanted):
+ raise RuntimeError("WSL cannot see the selected GPU. Update the NVIDIA Windows driver.")
+ return [by_uuid[uuid] for uuid in wanted]
+
+
+def kill_environment(environment: str) -> None:
+ """Last resort after the runner: end any process still running from this engine environment."""
+ try:
+ guest(["pkill", "-KILL", "-f", f"^{environment}/bin/python"], timeout = 60)
+ except (OSError, RuntimeError, subprocess.TimeoutExpired):
+ pass
+
+
+def unregister() -> None:
+ """Deletes the private distro and everything in it; never touches the user's own distros."""
+ if distro_ready():
+ owner = json.loads(guest(["cat", f"{GUEST_ROOT}/owner.json"]))
+ if owner.get("distro") != distro_name():
+ raise RuntimeError("The WSL environment belongs to another Studio installation.")
+ code, output = run(["--unregister", distro_name()], timeout = 300)
+ if code and distro_name() in registered_distros():
+ raise RuntimeError("Could not remove the WSL environment. " + output.strip()[-500:])
+ shutil.rmtree(host_dir() / "distro", ignore_errors = True)
+ write_state(state = "removed")
+
+
+def registered_distros() -> set[str]:
+ code, output = run(["--list", "--quiet"], timeout = 120)
+ if code:
+ raise RuntimeError("Could not list WSL distributions. " + output.strip()[-500:])
+ return {line.strip() for line in output.splitlines() if line.strip()}
+
+
+def _nvidia_smi() -> str:
+ from utils.hardware.nvidia import _nvidia_smi_executable
+ return _nvidia_smi_executable()
+
+
+def summary() -> dict:
+ """Status-poll view from the state file only: no wsl.exe call, so polling never boots WSL."""
+ state = read_state()
+ return {"state": state.get("state"), "distro": state.get("distro")}
diff --git a/studio/backend/routes/engines.py b/studio/backend/routes/engines.py
index 5308533c17c..a1d61b82d4c 100644
--- a/studio/backend/routes/engines.py
+++ b/studio/backend/routes/engines.py
@@ -66,3 +66,13 @@ async def rollback(engine: Engine):
return await asyncio.to_thread(engine_install.rollback, engine)
except RuntimeError as exc:
raise HTTPException(status_code = 409, detail = str(exc)) from exc
+
+
[email protected]("/wsl/environment", dependencies = [Depends(policy.require_owner)])
+async def remove_wsl_environment():
+ """Windows only: delete Studio's private WSL distro with every engine inside it."""
+ try:
+ await asyncio.to_thread(_reap_crashed_engine)
+ return await asyncio.to_thread(engine_install.remove_wsl_environment)
+ except (RuntimeError, OSError) as exc:
+ raise HTTPException(status_code = 409, detail = str(exc)) from exc
diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index 2cf84153e36..6e27ffa6cc1 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -175,8 +175,10 @@ def _reset_gpu_query_cache():
# Only when already imported: importing utils.hardware would change import-order tests.
def _reset():
gpu_query = sys.modules.get("utils.hardware.gpu_query")
- if gpu_query is not None:
- gpu_query.reset()
+ # A background probe thread may still be importing it; a half-built module has no cache yet.
+ reset = getattr(gpu_query, "reset", None)
+ if reset is not None:
+ reset()
hw = sys.modules.get("utils.hardware.hardware")
if hw is not None and hasattr(hw, "_last_good_visible_info"):
with hw._last_good_visible_lock:
diff --git a/studio/backend/tests/fake_wsl.py b/studio/backend/tests/fake_wsl.py
new file mode 100644
index 00000000000..2889b6e7de5
--- /dev/null
+++ b/studio/backend/tests/fake_wsl.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""A stand-in for wsl.exe on Linux CI: guest commands run on this host, every call is logged.
+
+FAKE_WSL_LOG names a JSON-lines log; FAKE_WSL_STATUS is the ``--status`` exit code,
+FAKE_WSL_UNREGISTER the ``--unregister`` one, FAKE_WSL_DISTROS the ``--list`` names (comma-separated).
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+
+def main(argv):
+ with open(os.environ["FAKE_WSL_LOG"], "a", encoding = "utf-8") as log:
+ log.write(
+ json.dumps(
+ {
+ "argv": argv,
+ "wslenv": os.environ.get("WSLENV", ""),
+ "shared": {
+ key.split("/")[0]: os.environ.get(key.split("/")[0])
+ for key in os.environ.get("WSLENV", "").split(":")
+ if key
+ },
+ }
+ )
+ + "\n"
+ )
+ if argv[:1] == ["--status"]:
+ return int(os.environ.get("FAKE_WSL_STATUS", "0"))
+ if argv[:1] == ["--list"]:
+ print(os.environ.get("FAKE_WSL_DISTROS", "").replace(",", "\n"))
+ return 0
+ if argv[:1] == ["--unregister"]:
+ return int(os.environ.get("FAKE_WSL_UNREGISTER", "0"))
+ if argv[:1] in (["--import"], ["--terminate"]):
+ return 0
+ if "--" not in argv:
+ return 2
+ command = argv[argv.index("--") + 1 :]
+ return subprocess.call(command)
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/studio/backend/tests/test_managed_engines.py b/studio/backend/tests/test_managed_engines.py
index d9a4280d868..9df73f5f9f2 100644
--- a/studio/backend/tests/test_managed_engines.py
+++ b/studio/backend/tests/test_managed_engines.py
@@ -9,6 +9,8 @@ import sys
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
+import os
+
import pytest
from core.inference import engine_install as install
@@ -39,8 +41,8 @@ def isolated(monkeypatch, tmp_path):
_LOCAL_ENGINE_HOST = pytest.mark.skipif(
sys.platform != "linux", reason = "local engine host is Linux only"
)
-# Engine leases and copy-on-write clones use fcntl, which Windows does not have.
-_POSIX_ENGINE_LOCKS = pytest.mark.skipif(sys.platform == "win32", reason = "engine locks use fcntl")
+# fcntl only: the copy-on-write clone probe, and a test that holds a lease with fcntl directly.
+_POSIX_ENGINE_LOCKS = pytest.mark.skipif(sys.platform == "win32", reason = "uses fcntl")
def active(
@@ -285,6 +287,7 @@ def test_engine_cuda_home_is_the_locked_pip_nvcc(tmp_path, monkeypatch):
assert sorted(os.listdir(home / "include")) == ["crt", "cuda_runtime.h"]
+@_LOCAL_ENGINE_HOST
@pytest.mark.parametrize("engine", ["vllm", "sglang"])
def test_glibc_floor_matches_the_lock_platform(engine, monkeypatch):
# Both locks resolve for x86_64-manylinux_2_34 (see the lock headers).
@@ -405,6 +408,7 @@ def test_no_lock_downloads_the_cuda12_cutlass_libraries(monkeypatch):
("sglang", "2.10.0+cu128", "0.5.20"),
],
)
+@_LOCAL_ENGINE_HOST
def test_release_follows_studio_torch(monkeypatch, engine, studio_torch, version):
monkeypatch.setattr(
install, "_studio_packages", lambda: {"torch": studio_torch} if studio_torch else {}
@@ -416,6 +420,7 @@ def test_release_follows_studio_torch(monkeypatch, engine, studio_torch, version
assert install._pins(engine)["torch"][0] == chosen["torch"]
+@_LOCAL_ENGINE_HOST
@pytest.mark.parametrize("engine", ["vllm", "sglang"])
def test_every_release_lock_is_current(monkeypatch, engine):
for release in install.PROFILES[engine]["releases"]:
@@ -425,6 +430,7 @@ def test_every_release_lock_is_current(monkeypatch, engine):
assert install._pins(engine)[engine][0] == release["version"]
+@_LOCAL_ENGINE_HOST
@pytest.mark.parametrize("engine", ["vllm", "sglang"])
def test_download_size_leaves_out_what_studio_shares(isolated, monkeypatch, engine):
full = install.download_bytes(engine)
@@ -558,7 +564,6 @@ def test_explicit_rollback_allows_old_profile_until_replaced(isolated, monkeypat
assert install.status(engine)["restored"] is False
-@_POSIX_ENGINE_LOCKS
def test_runtime_lease_blocks_removal(isolated):
marker = active(isolated)
with install.engine_lease("vllm"):
@@ -570,7 +575,6 @@ def test_runtime_lease_blocks_removal(isolated):
assert not marker.exists()
-@_POSIX_ENGINE_LOCKS
def test_removal_keeps_shared_models_and_cache(isolated):
active(isolated)
shared = isolated / "shared-model.safetensors"
@@ -607,6 +611,27 @@ def test_installer_does_not_inherit_base_python_or_secrets(monkeypatch):
assert env["UV_LINK_MODE"] == "copy"
+def test_only_driver_directories_survive_the_library_path(tmp_path):
+ driver, runtime = tmp_path / "lib64-nvidia", tmp_path / "cuda" / "lib64"
+ for folder, library in ((driver, "libcuda.so.1"), (runtime, "libcudart.so.13")):
+ folder.mkdir(parents = True)
+ (folder / library).write_bytes(b"")
+ joined = os.pathsep.join([str(runtime), "", "lib64-nvidia", str(driver)])
+ assert install.driver_library_path({"LD_LIBRARY_PATH": joined}) == str(driver)
+ assert install.driver_library_path({"LD_LIBRARY_PATH": str(runtime)}) is None
+ assert install.driver_library_path({}) is None
+
+
+def test_installer_keeps_the_driver_its_checks_import(monkeypatch, tmp_path):
+ driver = tmp_path / "lib64-nvidia"
+ driver.mkdir()
+ (driver / "libcuda.so.1").write_bytes(b"")
+ monkeypatch.setenv("LD_LIBRARY_PATH", os.pathsep.join(["/opt/cuda-12/lib64", str(driver)]))
+ assert install.install_environment()["LD_LIBRARY_PATH"] == str(driver)
+ monkeypatch.setenv("LD_LIBRARY_PATH", "/opt/cuda-12/lib64")
+ assert "LD_LIBRARY_PATH" not in install.install_environment()
+
+
def test_installer_reuses_recorded_cache(monkeypatch, tmp_path):
from utils.paths import storage_roots
@@ -778,7 +803,6 @@ def test_install_routes_require_owner(isolated, monkeypatch):
assert called == []
-@_POSIX_ENGINE_LOCKS
def test_engine_routes_reap_a_crashed_engine_before_reporting(isolated, monkeypatch):
from fastapi import FastAPI
from fastapi.testclient import TestClient
@@ -961,7 +985,6 @@ def test_validate_rejects_engine_settings_before_the_picker_unloads(monkeypatch,
assert "already quantized" in raised.value.detail
-@_POSIX_ENGINE_LOCKS
def test_busy_install_does_not_overwrite_another_job(isolated):
job = {"state": "running", "phase": "installing", "message": "Downloading"}
(isolated / "vllm.job.json").write_text(json.dumps(job))
@@ -971,7 +994,6 @@ def test_busy_install_does_not_overwrite_another_job(isolated):
assert install.status("vllm")["job"] == job
-@_POSIX_ENGINE_LOCKS
def test_another_instance_can_request_install_cancellation(isolated):
(isolated / "vllm.job.json").write_text(json.dumps({"state": "running"}))
with install.engine_lease("vllm", exclusive = True):
@@ -979,7 +1001,6 @@ def test_another_instance_can_request_install_cancellation(isolated):
assert (isolated / "vllm.cancel").exists()
-@_POSIX_ENGINE_LOCKS
def test_rollback_rejects_traversal(isolated):
marker = active(isolated)
info = json.loads(marker.read_text())
@@ -1162,14 +1183,15 @@ def test_memory_reserve_grows_with_the_card(monkeypatch):
def test_engine_start_reserves_a_share_of_the_card():
import inspect
from core.inference import managed_engine
- assert "memory_reserve_mib(self.engine, options), RESERVE_SHARE" in inspect.getsource(
- managed_engine
- )
+
+ # The local and the WSL launch both keep the share free.
+ source = inspect.getsource(managed_engine)
+ assert source.count("memory_reserve_mib(self.engine, options), RESERVE_SHARE") == 2
@_LOCAL_ENGINE_HOST
@pytest.mark.parametrize("gpu_ids", [[1], [1, 0]])
-def test_server_outlives_short_lived_start_thread(isolated, monkeypatch, gpu_ids):
+def test_server_outlives_short_lived_start_thread(isolated, monkeypatch, gpu_ids, tmp_path):
import os
import sys
import time
@@ -1188,7 +1210,7 @@ def test_server_outlives_short_lived_start_thread(isolated, monkeypatch, gpu_ids
"class Handler(BaseHTTPRequestHandler):\n"
" def do_GET(self):\n"
" self.send_response(200); self.end_headers()\n"
- " self.wfile.write('|'.join(os.environ[k] for k in ('CUDA_VISIBLE_DEVICES', 'TRITON_CACHE_DIR', 'FLASHINFER_WORKSPACE_BASE')).encode())\n"
+ " self.wfile.write('|'.join(os.environ.get(k, '') for k in ('CUDA_VISIBLE_DEVICES', 'TRITON_CACHE_DIR', 'FLASHINFER_WORKSPACE_BASE', 'LD_LIBRARY_PATH')).encode())\n"
" def log_message(self, *args): pass\n"
f"HTTPServer(('127.0.0.1', {port}), Handler).serve_forever()\n"
)
@@ -1201,6 +1223,11 @@ def test_server_outlives_short_lived_start_thread(isolated, monkeypatch, gpu_ids
key_environment = lambda _: {},
)
errors = []
+ # Colab reaches libcuda only through LD_LIBRARY_PATH; a CUDA runtime there must not follow.
+ driver, runtime = tmp_path / "lib64-nvidia", tmp_path / "cuda-12" / "lib64"
+ for folder, library in ((driver, "libcuda.so.1"), (runtime, "libcudart.so.12")):
+ folder.mkdir(parents = True)
+ (folder / library).write_bytes(b"")
def start():
try:
@@ -1209,7 +1236,10 @@ def test_server_outlives_short_lived_start_thread(isolated, monkeypatch, gpu_ids
2048,
gpu_ids,
dict(
- os.environ, TRITON_CACHE_DIR = "/shared-cache", FLASHINFER_WORKSPACE_BASE = "/home"
+ os.environ,
+ TRITON_CACHE_DIR = "/shared-cache",
+ FLASHINFER_WORKSPACE_BASE = "/home",
+ LD_LIBRARY_PATH = os.pathsep.join(map(str, (runtime, driver))),
),
)
except Exception as exc:
@@ -1224,9 +1254,10 @@ def test_server_outlives_short_lived_start_thread(isolated, monkeypatch, gpu_ids
assert engine.alive()
import httpx
- visible, cache_path, flashinfer_base = httpx.get(
+ visible, cache_path, flashinfer_base, library_path = httpx.get(
engine.base_url, trust_env = False
).text.split("|")
+ assert library_path == str(driver)
assert flashinfer_base == install.installed("vllm")["path"]
assert visible == ",".join(map(str, gpu_ids))
assert Path(cache_path).parent.parent == isolated / "vllm" / "cache"
@@ -2245,6 +2276,27 @@ def test_an_audio_model_that_also_reads_images_is_refused_as_audio():
assert "detected as an audio model" in refused.value.detail
+@_LOCAL_ENGINE_HOST
[email protected]("engine", ["vllm", "sglang"])
+def test_wsl_installs_the_newest_release_and_prices_the_distro(isolated, monkeypatch, engine):
+ from core.inference import wsl_host
+
+ studio_with_engine_torch(monkeypatch, engine)
+ monkeypatch.setattr(install, "_studio_packages", lambda: {"torch": "2.11.0+cu130"})
+ local = install.profile(engine)["version"]
+ monkeypatch.setattr(wsl_host, "active", lambda: True)
+ newest = install.PROFILES[engine]["releases"][0]
+ assert install.profile(engine)["version"] == newest["version"] != local
+ sizes = install._compat_file(engine)["sizes"]
+ omit = set(install.profile(engine)["omit"])
+ complete = sum(size or 0 for name, size in sizes.items() if name not in omit)
+ extra = wsl_host.ROOTFS["size"] + wsl_host.UV["size"]
+ monkeypatch.setattr(wsl_host, "summary", lambda: {"state": None, "distro": None})
+ assert install.download_bytes(engine) == complete + extra
+ monkeypatch.setattr(wsl_host, "summary", lambda: {"state": "ready", "distro": "UnslothStudio"})
+ assert install.download_bytes(engine) == complete
+
+
@pytest.mark.parametrize("version", ["0.5.20", "0.5.18"])
def test_sglang_without_torchao_refuses_int8_and_int4(version):
from core.inference.engine_adapters import ADAPTERS
diff --git a/studio/backend/tests/test_wsl_host.py b/studio/backend/tests/test_wsl_host.py
new file mode 100644
index 00000000000..5c542b71c4f
--- /dev/null
+++ b/studio/backend/tests/test_wsl_host.py
@@ -0,0 +1,561 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""The Windows engine host, driven through a fake wsl.exe; the guest runner runs for real."""
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+import types
+from pathlib import Path
+
+import pytest
+
+from core.inference import engine_install as install
+from core.inference import managed_engine
+from core.inference import wsl_host
+
+FAKE = Path(__file__).with_name("fake_wsl.py")
+
+
+def wsl(tmp_path, monkeypatch):
+ """Windows host with a fake wsl.exe; guest paths live under tmp_path."""
+ if sys.platform == "win32":
+ pytest.skip("the fake wsl.exe is a POSIX shell script")
+ log = tmp_path / "wsl.log"
+ log.touch()
+ exe = tmp_path / "wsl.exe"
+ exe.write_text(f'#!/bin/sh\nexec {sys.executable} {FAKE} "$@"\n')
+ exe.chmod(0o755)
+ monkeypatch.setenv("FAKE_WSL_LOG", str(log))
+ monkeypatch.setattr(wsl_host, "active", lambda: True)
+ monkeypatch.setattr(wsl_host, "wsl_exe", lambda: str(exe))
+ monkeypatch.setattr(wsl_host, "GUEST_ROOT", str(tmp_path / "guest"))
+ monkeypatch.setattr(wsl_host, "distro_name", lambda: "Unsloth-Engines-test")
+ monkeypatch.setattr(install, "engine_root", lambda: tmp_path / "engines")
+ monkeypatch.setattr(wsl_host, "boot_id", lambda: 1000)
+ monkeypatch.setattr(install, "_jobs", {})
+
+ def calls():
+ return [json.loads(line) for line in log.read_text().splitlines()]
+
+ return calls
+
+
+def test_to_guest_path():
+ assert wsl_host.to_guest_path(r"C:\Users\A B\model") == "/mnt/c/Users/A B/model"
+ assert wsl_host.to_guest_path("D:\\") == "/mnt/d"
+ with pytest.raises(ValueError):
+ wsl_host.to_guest_path(r"\\server\share\model")
+
+
+def test_decode_reads_wsl_utf16_and_guest_utf8():
+ assert wsl_host.decode("Default Version: 2".encode("utf-16-le")) == "Default Version: 2"
+ assert wsl_host.decode("\ufeffok".encode("utf-16-le")) == "ok"
+ assert wsl_host.decode("naïve".encode()) == "naïve"
+
+
+def test_blocker_names_virtualization_fix():
+ message = wsl_host.blocker("Error code: Wsl/Service/CreateInstance/CreateVm/0x80370102")
+ assert "virtualization" in message
+ assert wsl_host.blocker("some other failure") is None
+
+
+def test_wsl_state_across_a_restart(wsl, monkeypatch):
+ monkeypatch.setenv("FAKE_WSL_STATUS", "1")
+ assert wsl_host.wsl_state() == "missing"
+ wsl_host.write_state(state = "restart_required", boot = 1000)
+ # A Studio restart in the same Windows boot is not the restart WSL needs.
+ assert wsl_host.wsl_state() == "restart_required"
+ monkeypatch.setattr(wsl_host, "boot_id", lambda: 2000)
+ assert wsl_host.wsl_state().startswith("blocked: ")
+ monkeypatch.setenv("FAKE_WSL_STATUS", "0")
+ assert wsl_host.wsl_state() == "ready"
+ assert wsl_host.read_state()["state"] == "ready"
+
+
+def test_missing_wsl_is_not_unsupported(wsl, monkeypatch):
+ monkeypatch.setattr(wsl_host, "native_machine", lambda: "x86_64")
+ monkeypatch.setattr(wsl_host, "windows_build", lambda: 26100)
+ monkeypatch.setattr(install, "_driver_rows", lambda gpu_id, wait = True: [["580.10", "9.0"]])
+ assert install.support_reason("vllm") is None
+ monkeypatch.setattr(wsl_host, "native_machine", lambda: "arm64")
+ assert "x64" in install.support_reason("vllm")
+ monkeypatch.setattr(wsl_host, "native_machine", lambda: "x86_64")
+ monkeypatch.setattr(wsl_host, "windows_build", lambda: 19041)
+ assert "19044" in install.support_reason("vllm")
+
+
+def test_restart_leaves_a_waiting_job_not_an_interrupted_one(wsl, monkeypatch):
+ monkeypatch.setattr(install, "support_reason", lambda *a, **k: None)
+ monkeypatch.setattr(install, "_record_manifest", lambda engine: None)
+
+ def prepare(progress = None, cancel = None):
+ raise wsl_host.Waiting(
+ "Restart Windows to finish installing WSL, then click Install again."
+ )
+
+ monkeypatch.setattr(wsl_host, "prepare", prepare)
+ install.start_install("vllm")
+ deadline = time.monotonic() + 30
+ # status() reads the job file, written just after the in-memory state.
+ while install.status("vllm")["job"]["state"] == "running" and time.monotonic() < deadline:
+ time.sleep(0.05)
+ job = install.status("vllm")["job"]
+ assert job["state"] == "waiting"
+ assert "Restart Windows" in job["message"]
+ assert install.status("vllm")["host"] == "wsl"
+
+
+def test_secrets_cross_through_wslenv_not_argv(wsl, monkeypatch):
+ monkeypatch.setenv("WSLENV", "USERPROFILE/p")
+ command, env = wsl_host.guest_command(
+ ["python", "-V"], env = {"CUDA_VISIBLE_DEVICES": "GPU-1"}, secrets = {"HF_TOKEN": "hf_secret"}
+ )
+ assert "hf_secret" not in " ".join(command)
+ assert command[1:8] == ["-d", "Unsloth-Engines-test", "-u", "root", "--cd", "/root", "--"]
+ assert "CUDA_VISIBLE_DEVICES=GPU-1" in command
+ assert env["HF_TOKEN"] == "hf_secret"
+ assert env["WSLENV"] == "USERPROFILE/p:HF_TOKEN/u"
+ subprocess.run(command, env = env, check = True, capture_output = True)
+ assert wsl()[-1]["shared"]["HF_TOKEN"] == "hf_secret"
+
+
+def test_an_anonymous_load_withholds_a_token_the_user_shares_through_wslenv(wsl, monkeypatch):
+ monkeypatch.setenv("WSLENV", "USERPROFILE/p:HF_TOKEN/u")
+ monkeypatch.setenv("HF_TOKEN", "hf_ambient")
+ command, env = wsl_host.guest_command(["python", "-V"], withhold = ("HF_TOKEN",))
+ assert "HF_TOKEN" not in env
+ assert env["WSLENV"] == "USERPROFILE/p"
+
+
+def test_cancel_stops_a_download_and_leaves_no_partial(tmp_path, monkeypatch):
+ import contextlib
+ import threading
+
+ cancel = threading.Event()
+ monkeypatch.setattr(wsl_host, "host_dir", lambda: tmp_path)
+
+ class Response:
+ def raise_for_status(self):
+ pass
+
+ def iter_bytes(self, size):
+ for _ in range(1000):
+ cancel.set()
+ yield b"x" * 16
+
+ monkeypatch.setitem(
+ sys.modules,
+ "httpx",
+ types.SimpleNamespace(stream = lambda *a, **k: contextlib.nullcontext(Response())),
+ )
+ spec = {"url": "https://example.invalid/r", "sha256": "0" * 64, "size": 16000}
+ with pytest.raises(RuntimeError, match = "cancelled"):
+ wsl_host.download(spec, "rootfs.tar.gz", cancel = cancel)
+ assert list((tmp_path / "downloads").iterdir()) == []
+
+
+def test_localized_utf16_messages_decode_and_still_name_the_blocker():
+ message = "请启用虚拟机平台 Windows 功能并确保在 BIOS 中启用虚拟化。错误代码: Wsl/0x80370102"
+ assert wsl_host.decode(message.encode("utf-16-le")) == message
+ assert "BIOS" in wsl_host.blocker(wsl_host.decode(message.encode("utf-16-le")))
+ assert wsl_host.decode("请启用虚拟化".encode("utf-16-le")) == "请启用虚拟化"
+
+
+def test_concurrent_installs_prepare_the_distro_one_at_a_time(monkeypatch):
+ import threading
+
+ inside, peak = [0], [0]
+
+ def ensure_distro(progress = None, cancel = None):
+ inside[0] += 1
+ peak[0] = max(peak[0], inside[0])
+ time.sleep(0.3)
+ inside[0] -= 1
+
+ monkeypatch.setattr(wsl_host, "wsl_state", lambda: "ready")
+ monkeypatch.setattr(wsl_host, "ensure_distro", ensure_distro)
+ threads = [threading.Thread(target = wsl_host.prepare) for _ in range(2)]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join()
+ assert peak[0] == 1
+
+
+def test_gpus_are_selected_by_uuid(monkeypatch):
+ rows = "0, GPU-aaaa\n1, GPU-bbbb\n"
+ monkeypatch.setattr(
+ wsl_host.subprocess,
+ "run",
+ lambda *a, **k: subprocess.CompletedProcess(a, 0, stdout = rows, stderr = ""),
+ )
+ assert wsl_host.gpu_uuids([1, 0]) == ["GPU-bbbb", "GPU-aaaa"]
+ with pytest.raises(RuntimeError):
+ wsl_host.gpu_uuids([2])
+ # The guest enumerates the same two cards the other way round.
+ monkeypatch.setattr(wsl_host, "guest", lambda *a, **k: "0, GPU-bbbb\n1, GPU-aaaa\n")
+ assert wsl_host.guest_gpu_indices([0, 1]) == [1, 0]
+
+
+def test_installed_wsl_record_never_boots_the_distro(wsl, tmp_path):
+ root = tmp_path / "engines" / "vllm"
+ root.mkdir(parents = True)
+ (root / "active.json").write_text(
+ json.dumps({"directory": "env-abc", "host": "wsl", "profile_digest": "x"})
+ )
+ info = install.installed("vllm")
+ assert info["path"] == f"{wsl_host.GUEST_ROOT}/engines/vllm/env-abc"
+ assert wsl() == []
+ (root / "active.json").write_text(json.dumps({"directory": "../x", "host": "wsl"}))
+ assert install.installed("vllm") is None
+
+
+# The runner is the WSL guest's bash script (setsid, Linux process groups); it never runs elsewhere.
+_GUEST_RUNNER = pytest.mark.skipif(sys.platform != "linux", reason = "WSL guest runner is Linux only")
+
+
+def _runner(tmp_path) -> Path:
+ runner = tmp_path / "run-engine"
+ runner.write_text(wsl_host.RUNNER)
+ runner.chmod(0o755)
+ return runner
+
+
+def _gone(pid: int, seconds: float) -> bool:
+ deadline = time.monotonic() + seconds
+ while time.monotonic() < deadline:
+ try:
+ os.kill(pid, 0)
+ except ProcessLookupError:
+ return True
+ time.sleep(0.1)
+ return False
+
+
+@_GUEST_RUNNER
+def test_runner_stops_the_engine_group_when_studio_closes_the_pipe(tmp_path):
+ pids = tmp_path / "pids"
+ engine = f"import os, subprocess, time; child = subprocess.Popen(['sleep', '300']); open({str(pids)!r}, 'w').write(f'{{os.getpid()}} {{child.pid}}'); time.sleep(300)"
+ proc = subprocess.Popen(
+ [str(_runner(tmp_path)), sys.executable, "-c", engine], stdin = subprocess.PIPE
+ )
+ for _ in range(100):
+ if pids.exists() and pids.read_text():
+ break
+ time.sleep(0.05)
+ engine_pid, grandchild = map(int, pids.read_text().split())
+ proc.stdin.close()
+ assert proc.wait(timeout = 15) != 0
+ # The engine and what it spawned both go: the whole process group is signalled.
+ assert _gone(engine_pid, 5) and _gone(grandchild, 5)
+
+
+@_GUEST_RUNNER
+def test_runner_survives_idle_and_reports_the_engine_exit_code(tmp_path):
+ proc = subprocess.Popen(
+ [
+ str(_runner(tmp_path)),
+ sys.executable,
+ "-c",
+ "import time, sys; time.sleep(1); sys.exit(7)",
+ ],
+ stdin = subprocess.PIPE,
+ )
+ assert proc.wait(timeout = 15) == 7
+
+
+@_GUEST_RUNNER
+def test_runner_reaps_workers_left_behind_when_the_engine_exits(tmp_path):
+ pids = tmp_path / "pids"
+ engine = f"import subprocess, sys; child = subprocess.Popen(['sleep', '300']); open({str(pids)!r}, 'w').write(str(child.pid)); sys.exit(3)"
+ proc = subprocess.Popen(
+ [str(_runner(tmp_path)), sys.executable, "-c", engine], stdin = subprocess.PIPE
+ )
+ assert proc.wait(timeout = 20) == 3
+ assert _gone(int(pids.read_text()), 5)
+
+
+@_GUEST_RUNNER
+def test_runner_stops_the_engine_when_studio_is_killed(tmp_path):
+ """Studio dying closes its end of the pipe too, so vLLM never outlives its owner."""
+ pids = tmp_path / "pids"
+ owner = subprocess.Popen(
+ [
+ sys.executable,
+ "-c",
+ "import subprocess, sys, time; p = subprocess.Popen(sys.argv[1:], stdin = subprocess.PIPE); time.sleep(300)",
+ str(_runner(tmp_path)),
+ sys.executable,
+ "-c",
+ f"import os, time; open({str(pids)!r}, 'w').write(str(os.getpid())); time.sleep(300)",
+ ],
+ start_new_session = True,
+ )
+ for _ in range(100):
+ if pids.exists() and pids.read_text():
+ break
+ time.sleep(0.05)
+ engine_pid = int(pids.read_text())
+ os.kill(owner.pid, signal.SIGKILL)
+ owner.wait()
+ assert _gone(engine_pid, 15)
+
+
+def test_wsl_launch_command(wsl, monkeypatch):
+ # Windows GPU 1 and 3 are guest GPUs 0 and 2.
+ monkeypatch.setattr(wsl_host, "guest_gpu_indices", lambda ids: [{1: 0, 3: 2}[i] for i in ids])
+ monkeypatch.setattr(managed_engine, "gpu_memory_fraction", lambda *_: 0.5)
+ monkeypatch.setattr(wsl_host, "to_guest_path", lambda path: "/mnt/c/" + Path(path).name)
+ guest = Path(wsl_host.GUEST_ROOT) / "engines" / "vllm" / "env-abc" / "bin"
+ guest.mkdir(parents = True)
+ (guest / "python").write_text("", encoding = "utf-8")
+ (guest / "python").chmod(0o755)
+ engine = managed_engine.ManagedEngine("vllm")
+ engine.context = 2048
+ info = {
+ "path": str(guest.parent),
+ "host": "wsl",
+ "profile_digest": "d",
+ "deep_gemm_unloadable": True,
+ "cuda_environment": {"CUDA_HOME": "/env/cuda", "CPATH": "/env/include"},
+ }
+ command, env = engine._wsl_command(
+ info,
+ {"HF_TOKEN": "hf_secret", "HF_HUB_CACHE": r"C:\Users\a\.cache", "PATH": r"C:\Windows"},
+ [1, 3],
+ None,
+ False,
+ "unsloth/Qwen3-0.6B",
+ None,
+ 8123,
+ )
+ joined = " ".join(command)
+ assert command[command.index("--") + 2].endswith("/bin/run-engine")
+ assert "CUDA_VISIBLE_DEVICES=0,2" in command and "CUDA_DEVICE_ORDER=PCI_BUS_ID" in command
+ assert "VLLM_USE_DEEP_GEMM=0" in command and "CUDA_HOME=/env/cuda" in command
+ assert f"HF_HOME={wsl_host.GUEST_ROOT}/hf" in command
+ # Windows paths and secrets never reach the guest command line.
+ assert "hf_secret" not in joined and "C:\\" not in joined
+ assert env["HF_TOKEN"] == "hf_secret" and "HF_TOKEN/u" in env["WSLENV"]
+ assert "unsloth/Qwen3-0.6B" in command and "--port" in command
+ # The engine key rides WSLENV too: on the guest command line any local user could read it.
+ assert engine.key not in joined
+ assert env["VLLM_API_KEY"] == engine.key and "VLLM_API_KEY/u" in env["WSLENV"]
+ # vLLM's route-guarding launcher is a Studio source file the guest reads through /mnt.
+ assert "/mnt/c/vllm_server.py" in command
+
+
+def test_a_logged_in_token_file_reaches_the_guest(wsl, monkeypatch, tmp_path):
+ monkeypatch.setattr(wsl_host, "guest_gpu_indices", lambda ids: [0])
+ monkeypatch.setattr(managed_engine, "gpu_memory_fraction", lambda *_: 0.5)
+ monkeypatch.setattr(wsl_host, "to_guest_path", lambda path: "/mnt/c/" + Path(path).name)
+ guest = Path(wsl_host.GUEST_ROOT) / "engines" / "vllm" / "env-abc" / "bin"
+ guest.mkdir(parents = True)
+ (guest / "python").write_text("", encoding = "utf-8")
+ (guest / "python").chmod(0o755)
+ (tmp_path / "token").write_text("hf_from_login\n", encoding = "utf-8")
+ engine = managed_engine.ManagedEngine("vllm")
+ engine.context = 2048
+ info = {"path": str(guest.parent), "host": "wsl"}
+ # `hf auth login` stores the token under the host HF_HOME, which the guest does not share.
+ command, env = engine._wsl_command(
+ info, {"HF_HOME": str(tmp_path)}, [0], None, False, "m", None, 8123
+ )
+ assert env["HF_TOKEN"] == "hf_from_login" and "HF_TOKEN/u" in env["WSLENV"]
+ assert "hf_from_login" not in " ".join(command)
+ # An explicit token wins, and an anonymous load sends none.
+ _, env = engine._wsl_command(
+ info,
+ {"HF_HOME": str(tmp_path), "HF_TOKEN": "hf_explicit"},
+ [0],
+ None,
+ False,
+ "m",
+ None,
+ 8123,
+ )
+ assert env["HF_TOKEN"] == "hf_explicit"
+ _, env = engine._wsl_command(
+ info,
+ {"HF_HOME": str(tmp_path), "HF_HUB_DISABLE_IMPLICIT_TOKEN": "1"},
+ [0],
+ None,
+ False,
+ "m",
+ None,
+ 8123,
+ )
+ assert "HF_TOKEN" not in env or env["HF_TOKEN"] != "hf_from_login"
+
+
+def test_offline_mode_reaches_the_guest(wsl, monkeypatch):
+ monkeypatch.setattr(wsl_host, "guest_gpu_indices", lambda ids: [0])
+ monkeypatch.setattr(managed_engine, "gpu_memory_fraction", lambda *_: 0.5)
+ monkeypatch.setattr(wsl_host, "to_guest_path", lambda path: "/mnt/c/" + Path(path).name)
+ guest = Path(wsl_host.GUEST_ROOT) / "engines" / "vllm" / "env-abc" / "bin"
+ guest.mkdir(parents = True)
+ (guest / "python").write_text("", encoding = "utf-8")
+ (guest / "python").chmod(0o755)
+ engine = managed_engine.ManagedEngine("vllm")
+ engine.context = 2048
+ info = {"path": str(guest.parent), "host": "wsl"}
+ command, _ = engine._wsl_command(info, {}, [0], None, False, "m", None, 8123)
+ assert "HF_HUB_OFFLINE=1" not in command
+ command, _ = engine._wsl_command(
+ info, {"TRANSFORMERS_OFFLINE": "1"}, [0], None, False, "m", None, 8123
+ )
+ assert "HF_HUB_OFFLINE=1" in command
+
+
+def test_a_failed_unregister_keeps_the_distro_recorded(wsl, monkeypatch):
+ monkeypatch.setattr(wsl_host, "distro_ready", lambda: False)
+ monkeypatch.setattr(wsl_host, "host_dir", lambda: Path(wsl_host.GUEST_ROOT).parent / "host")
+ monkeypatch.setenv("FAKE_WSL_UNREGISTER", "1")
+ monkeypatch.setenv("FAKE_WSL_DISTROS", "Ubuntu,Unsloth-Engines-test")
+ with pytest.raises(RuntimeError, match = "Could not remove"):
+ wsl_host.unregister()
+ assert wsl_host.read_state().get("state") != "removed"
+ # Already gone: a failing exit code is not an error.
+ monkeypatch.setenv("FAKE_WSL_DISTROS", "Ubuntu")
+ wsl_host.unregister()
+ assert wsl_host.read_state()["state"] == "removed"
+
+
+def test_an_orphaned_import_directory_is_cleared_before_importing(wsl, monkeypatch, tmp_path):
+ host = tmp_path / "host"
+ (host / "distro").mkdir(parents = True)
+ (host / "distro" / "ext4.vhdx").write_text("half an import")
+ monkeypatch.setattr(wsl_host, "host_dir", lambda: host)
+ monkeypatch.setattr(wsl_host, "distro_ready", lambda: False)
+ monkeypatch.setattr(wsl_host, "download", lambda *a, **k: tmp_path / "rootfs.tar.gz")
+ seen = []
+ real_run = wsl_host.run
+
+ def run(args, **kwargs):
+ if args[:1] == ["--import"]:
+ seen.append(sorted(p.name for p in (host / "distro").iterdir()))
+ raise KeyboardInterrupt
+ return real_run(args, **kwargs)
+
+ monkeypatch.setattr(wsl_host, "run", run)
+ with pytest.raises(KeyboardInterrupt):
+ wsl_host.ensure_distro()
+ assert seen == [[]]
+
+
+def test_host_probes_find_nvidia_smi_off_path(monkeypatch):
+ import utils.hardware.nvidia as nvidia
+
+ monkeypatch.setattr(nvidia, "_nvidia_smi_executable", lambda: r"C:\NVSMI\nvidia-smi.exe")
+ argv = []
+
+ def fake_run(args, *a, **k):
+ argv.append(args[0])
+ return subprocess.CompletedProcess(args, 0, stdout = "0, GPU-aaaa\n", stderr = "")
+
+ monkeypatch.setattr(wsl_host.subprocess, "run", fake_run)
+ wsl_host.gpu_uuids([0])
+ monkeypatch.setattr(install.subprocess, "run", fake_run)
+ install._probe_rows(0)
+ from core.inference import engine_adapters
+
+ monkeypatch.setattr(engine_adapters.subprocess, "run", fake_run)
+ try:
+ engine_adapters.gpu_memory_fraction([0], 1024)
+ except Exception:
+ pass
+ assert argv == [r"C:\NVSMI\nvidia-smi.exe"] * 3
+
+
+def test_removing_a_wsl_engine_also_drops_its_compile_cache(wsl):
+ guest = Path(wsl_host.GUEST_ROOT)
+ guest.mkdir(parents = True)
+ (guest / "owner.json").write_text("{}", encoding = "utf-8")
+ for folder in ("engines/vllm/env-abc", "cache/vllm/k", "engines/sglang", "cache/sglang/k"):
+ (guest / folder).mkdir(parents = True)
+ install.remove("vllm")
+ assert not (guest / "engines" / "vllm").exists() and not (guest / "cache" / "vllm").exists()
+ assert (guest / "engines" / "sglang").exists() and (guest / "cache" / "sglang").exists()
+
+
+def test_sglang_launcher_is_read_through_mnt(wsl, monkeypatch):
+ monkeypatch.setattr(wsl_host, "guest_gpu_indices", lambda ids: [0])
+ monkeypatch.setattr(managed_engine, "gpu_memory_fraction", lambda *_: 0.5)
+ monkeypatch.setattr(wsl_host, "to_guest_path", lambda path: "/mnt/c/" + Path(path).name)
+ guest = Path(wsl_host.GUEST_ROOT) / "engines" / "sglang" / "env-abc" / "bin"
+ guest.mkdir(parents = True)
+ (guest / "python").write_text("", encoding = "utf-8")
+ (guest / "python").chmod(0o755)
+ engine = managed_engine.ManagedEngine("sglang")
+ engine.context = 2048
+ command, env = engine._wsl_command(
+ {"path": str(guest.parent), "host": "wsl"}, {}, [0], None, False, "m", None, 8123
+ )
+ assert "/mnt/c/sglang_server.py" in command
+ assert engine.key not in " ".join(command)
+ assert env["UNSLOTH_ENGINE_API_KEY"] == engine.key
+ assert "UNSLOTH_ENGINE_API_KEY/u" in env["WSLENV"]
+ assert str(Path(managed_engine.__file__).with_name("sglang_server.py")) not in command
+
+
+def test_linux_launch_is_unchanged_without_wsl(monkeypatch):
+ assert wsl_host.active() is (sys.platform == "win32")
+ if sys.platform == "win32":
+ assert install._host_status()["host"] == "wsl"
+ else:
+ assert install._host_status() == {"host": "local"}
+
+
+def test_a_failed_reset_never_deletes_the_disk_of_a_registered_distro(wsl, monkeypatch, tmp_path):
+ host = tmp_path / "host"
+ (host / "distro").mkdir(parents = True)
+ (host / "distro" / "ext4.vhdx").write_text("a live distro's disk")
+ monkeypatch.setattr(wsl_host, "host_dir", lambda: host)
+ monkeypatch.setattr(wsl_host, "distro_ready", lambda: False) # e.g. the probe timed out
+ monkeypatch.setattr(wsl_host, "download", lambda *a, **k: tmp_path / "rootfs.tar.gz")
+ monkeypatch.setenv("FAKE_WSL_UNREGISTER", "1")
+ monkeypatch.setenv("FAKE_WSL_DISTROS", "Unsloth-Engines-test")
+ with pytest.raises(RuntimeError, match = "Could not reset"):
+ wsl_host.ensure_distro()
+ assert (host / "distro" / "ext4.vhdx").exists()
+
+
+def test_removal_waits_for_an_unresponsive_but_registered_distro(wsl, monkeypatch):
+ root = install.engine_root() / "vllm"
+ root.mkdir(parents = True)
+ (root / "active.json").write_text("{}")
+ monkeypatch.setattr(wsl_host, "distro_ready", lambda: False)
+ monkeypatch.setenv("FAKE_WSL_DISTROS", "Unsloth-Engines-test")
+ with pytest.raises(RuntimeError, match = "not responding"):
+ install.remove("vllm")
+ assert (root / "active.json").exists()
+ monkeypatch.setenv("FAKE_WSL_DISTROS", "Ubuntu")
+ install.remove("vllm")
+ assert not root.exists()
+
+
+def test_host_gpu_probes_hide_their_console_window(monkeypatch):
+ from core.inference import engine_adapters
+
+ seen = []
+
+ def fake_run(args, *a, **k):
+ seen.append(k.get("creationflags"))
+ return subprocess.CompletedProcess(args, 0, stdout = "0, GPU-aaaa\n", stderr = "")
+
+ hidden = lambda: {"creationflags": 0x08000000} # noqa: E731
+ for module in (install, engine_adapters):
+ monkeypatch.setattr(module, "windows_hidden_subprocess_kwargs", hidden)
+ monkeypatch.setattr(module.subprocess, "run", fake_run)
+ install._probe_rows(0)
+ try:
+ engine_adapters.gpu_memory_fraction([0], 1024)
+ except Exception:
+ pass
+ assert seen == [0x08000000] * 2
diff --git a/studio/frontend/src/features/model-picker/api/engines.ts b/studio/frontend/src/features/model-picker/api/engines.ts
index 5793048311e..dbe2b2f753b 100644
--- a/studio/frontend/src/features/model-picker/api/engines.ts
+++ b/studio/frontend/src/features/model-picker/api/engines.ts
@@ -15,6 +15,10 @@ export interface EngineStatus {
restored?: boolean;
can_rollback: boolean;
unsupported_reason: string | null;
+ /** "wsl": on Windows the engine runs inside Studio's own WSL2 distro. */
+ host?: "local" | "wsl";
+ /** WSL2 state from Studio's own record; distro is set once its Ubuntu has been imported. */
+ wsl?: { state: string | null; distro: string | null };
// Wheel bytes the offered install or update downloads; null when unknown or nothing is on offer.
download_bytes?: number | null;
job: {
@@ -46,6 +50,16 @@ export function precisionAfterEngineSwitch<P extends string>(
: precision;
}
+/** What the install prompt tells a Windows user about WSL2, or null when the engine runs locally. */
+export function wslNoticeKey(
+ engine: EngineStatus,
+): "managedEngines.wslSetup" | "managedEngines.wslReady" | "managedEngines.wslRestart" | null {
+ if (engine.host !== "wsl") return null;
+ if (engine.wsl?.state === "restart_required") return "managedEngines.wslRestart";
+ if (engine.wsl?.state === "ready" && engine.wsl?.distro) return "managedEngines.wslReady";
+ return "managedEngines.wslSetup";
+}
+
/** SGLang 0.5.18 dropped --torchao-config, its only load-time INT8 / 4-bit conversion. */
export function convertsToInteger(engine: EngineStatus | undefined): boolean {
if (engine?.engine !== "sglang") return true;
diff --git a/studio/frontend/src/features/model-picker/components/inference-engines.tsx b/studio/frontend/src/features/model-picker/components/inference-engines.tsx
index b8c745783da..fc0eebe11f4 100644
--- a/studio/frontend/src/features/model-picker/components/inference-engines.tsx
+++ b/studio/frontend/src/features/model-picker/components/inference-engines.tsx
@@ -24,6 +24,7 @@ import {
convertsToInteger,
precisionAfterEngineSwitch,
isEngineReady,
+ wslNoticeKey,
} from "../api/engines";
import { useEngines } from "../hooks/use-engines";
@@ -42,7 +43,11 @@ function EngineInstall({
const isOwner = useIsAccountOwner();
const useAfterInstall = useRef(false);
useEffect(() => {
- if (engine.job.state === "error" || engine.job.state === "cancelled") {
+ if (
+ engine.job.state === "error" ||
+ engine.job.state === "cancelled" ||
+ engine.job.state === "waiting"
+ ) {
useAfterInstall.current = false;
}
if (
@@ -175,6 +180,9 @@ function EngineInstall({
version: engine.version,
})}
</p>
+ {wslNoticeKey(engine) && (
+ <p>{t(wslNoticeKey(engine)!, { engine: names[engine.engine] })}</p>
+ )}
<p>{t("managedEngines.background")}</p>
<div className="flex gap-2">
<Button
@@ -208,6 +216,9 @@ function EngineInstall({
{engine.job.state === "cancelled" && (
<output>{t("managedEngines.cancelled")}</output>
)}
+ {engine.job.state === "waiting" && (
+ <output className="whitespace-pre-wrap">{engine.job.message}</output>
+ )}
</div>
);
}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 9d348ba2216..c77ae21c1fa 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -34,6 +34,9 @@ export const en = {
installAndLoad: "Install and load",
confirm: "Install {engine} {version}? This optional download can use several gigabytes. Exact additional download and disk usage are unavailable. Compatible cached packages and model files are reused.",
confirmSized: "Install {engine} {version}? This optional download is about {size}. Packages Studio already has, including PyTorch when the versions match, are reused rather than downloaded again.",
+ wslSetup: "On Windows, {engine} runs inside WSL2 (Windows Subsystem for Linux). Studio will turn on WSL2 and set up its own private Ubuntu environment for engines; your existing Linux distributions are not touched. Windows will show one administrator (UAC) prompt, and may ask you to restart before the installation can finish. Nothing changes until you click Install.",
+ wslReady: "On Windows, {engine} runs inside Studio's private WSL2 environment.",
+ wslRestart: "Restart Windows to finish turning on WSL2, then click Install again.",
background: "Installation runs in the background. Removing the engine keeps your downloaded models.",
failed: "Engine installation failed. Retry or use the default engine.",
details: "Technical details",
diff --git a/studio/frontend/tests/managed-engine-readiness.test.ts b/studio/frontend/tests/managed-engine-readiness.test.ts
index 37a4e02fdb1..d06beee8399 100644
--- a/studio/frontend/tests/managed-engine-readiness.test.ts
+++ b/studio/frontend/tests/managed-engine-readiness.test.ts
@@ -7,8 +7,12 @@ import type { EngineStatus } from "../src/features/model-picker/api/engines.ts";
import { registerStoreStubResolver } from "./helpers/kit.ts";
registerStoreStubResolver();
-const { isEngineReady, convertsToInteger, precisionAfterEngineSwitch } =
- await import("../src/features/model-picker/api/engines.ts");
+const {
+ isEngineReady,
+ wslNoticeKey,
+ convertsToInteger,
+ precisionAfterEngineSwitch,
+} = await import("../src/features/model-picker/api/engines.ts");
const installed: EngineStatus = {
engine: "vllm",
@@ -56,6 +60,39 @@ test("failed or cancelled repairs leave the restored installation loadable", ()
}
});
+test("Windows users are told about WSL2, the UAC prompt and a restart before installing", () => {
+ assert.equal(wslNoticeKey(installed), null);
+ assert.equal(wslNoticeKey({ ...installed, host: "local" }), null);
+ assert.equal(
+ wslNoticeKey({ ...installed, host: "wsl" }),
+ "managedEngines.wslSetup",
+ );
+ assert.equal(
+ wslNoticeKey({
+ ...installed,
+ host: "wsl",
+ wsl: { state: "ready", distro: null },
+ }),
+ "managedEngines.wslSetup",
+ );
+ assert.equal(
+ wslNoticeKey({
+ ...installed,
+ host: "wsl",
+ wsl: { state: "restart_required", distro: null },
+ }),
+ "managedEngines.wslRestart",
+ );
+ assert.equal(
+ wslNoticeKey({
+ ...installed,
+ host: "wsl",
+ wsl: { state: "ready", distro: "UnslothStudio" },
+ }),
+ "managedEngines.wslReady",
+ );
+});
+
test("SGLang 0.5.18 and newer offer no load-time INT8 or 4-bit conversion", () => {
assert.equal(convertsToInteger(installed), true);
const sglang = { ...installed, engine: "sglang" as const };
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index d2f32b76079..7f8561858ec 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -1760,6 +1760,8 @@ def _ensure_engine_installed(engine: str, yes: bool, silent: bool) -> None:
if not typer.confirm(f"{question}?", default = False):
raise RuntimeError(f"{engine} was not installed, so the model was not loaded.")
elif not silent:
+ if notice:
+ typer.echo(notice)
typer.echo(f"{question}: --yes given, installing.")
engine_install.start_install(engine)
last = None
@@ -1777,7 +1779,21 @@ def _ensure_engine_installed(engine: str, yes: bool, silent: bool) -> None:
def _engine_install_notice(engine: str, row: dict) -> Optional[str]:
- return None
+ """The Windows consent text Settings shows before the same install (managedEngines.wsl*)."""
+ if row.get("host") != "wsl":
+ return None
+ wsl = row.get("wsl") or {}
+ if wsl.get("state") == "restart_required":
+ return "Restart Windows to finish turning on WSL2, then run this command again."
+ if wsl.get("state") == "ready" and wsl.get("distro"):
+ return f"On Windows, {engine} runs inside Studio's private WSL2 environment."
+ return (
+ f"On Windows, {engine} runs inside WSL2 (Windows Subsystem for Linux). Studio will turn "
+ "on WSL2 and set up its own private Ubuntu environment for engines; your existing Linux "
+ "distributions are not touched. Windows will show one administrator (UAC) prompt, and "
+ "may ask you to restart before the installation can finish. Nothing changes unless you "
+ "answer yes."
+ )
def _format_context_length_line(load_result: dict) -> Optional[str]:
diff --git a/unsloth_cli/tests/test_studio_run_engine_flag.py b/unsloth_cli/tests/test_studio_run_engine_flag.py
index 0667bed0665..976c52cabbd 100644
--- a/unsloth_cli/tests/test_studio_run_engine_flag.py
+++ b/unsloth_cli/tests/test_studio_run_engine_flag.py
@@ -165,3 +165,30 @@ def test_unsupported_host_is_refused_before_installing(fake_install):
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)
+
+
+ ("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