Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Docker: stop JupyterLab from silently taking Studio's port, and correct three host-script messages (#10828)
oobaboogaa092906c98a1
diff --git a/docker/build.sh b/docker/build.shindex e7eac3f2df0..6a90428f04a 100755--- a/docker/build.sh+++ b/docker/build.sh@@ -93,9 +93,13 @@ DOCKER_BUILDKIT=1 docker build \echoecho "Built ${IMAGE_NAME}:${TAG}"echo-echo "Smoke test on this host (B200, sm_100):"+# name the GPU only from a successful query: a failing nvidia-smi prints its error on stdout+HOST_GPU=""+if HOST_GPU_QUERY="$(nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null)"; then+ HOST_GPU="$(printf '%s\n' "$HOST_GPU_QUERY" | head -1)"+fi+echo "Smoke test on this host${HOST_GPU:+ (${HOST_GPU})}:"echo " docker run --rm --gpus all ${IMAGE_NAME}:${TAG} python /workspace/smoke_test.py"echo-echo "Smoke test on an RTX 5090 host (sm_120):"+echo "On another host, the same command after:"echo " docker pull ${IMAGE_NAME}:${TAG} # or load .tar"-echo " docker run --rm --gpus all ${IMAGE_NAME}:${TAG} python /workspace/smoke_test.py"diff --git a/docker/install_nvidia_toolkit.sh b/docker/install_nvidia_toolkit.shindex b76a0774b70..0d006afa96f 100755--- a/docker/install_nvidia_toolkit.sh+++ b/docker/install_nvidia_toolkit.sh@@ -24,14 +24,61 @@ command -v docker >/dev/null 2>&1 \# Measured on `docker info` with a 50ms pause mid-output: status 141, the Docker Desktop guard skipped,# and the script elevating to install on the one daemon it exists to leave alone.+# Mac and Windows shells never need the toolkit (no NVIDIA GPU on a Mac; Docker Desktop's+# WSL 2 backend brings its own), so answer before the endpoint check, which sent colima and+# Rancher Desktop users off to configure a socket. Only a remote Linux daemon gets the+# remote answer; DOCKER_CONTEXT over DOCKER_HOST over the selected context, as below.+host_os="$(uname -s)"+case "$host_os" in+ Darwin|MINGW*|MSYS*|CYGWIN*)+ if [[ -n "${DOCKER_CONTEXT:-}" || -z "${DOCKER_HOST:-}" ]]; then+ host_endpoint="$(docker context inspect --format '{{.Endpoints.docker.Host}}' 2>/dev/null)" \+ || fail "cannot inspect the Docker context '${DOCKER_CONTEXT:-current}' (it may exist only in the invoking user's Docker config); refusing to guess which daemon it drives." 2+ else+ host_endpoint="$DOCKER_HOST"+ fi+ # loopback tcp is this machine too (Docker Desktop's "expose daemon on tcp://localhost:2375")+ case "$host_endpoint" in+ ""|unix://*|npipe://*) ;;+ tcp://localhost|tcp://localhost:*|tcp://127.*|tcp://\[::1\]*|localhost:*|127.*) ;;+ *) fail "the Docker CLI on this machine talks to a remote daemon (${host_endpoint}); run this script on that host, it configures the local Docker only." 2 ;;+ esac+ if [[ "$host_os" == Darwin ]]; then+ say "macOS: no NVIDIA GPU can be attached on a Mac, so there is nothing to install."+ say "The image runs CPU-only there: drop --gpus and set UNSLOTH_ALLOW_CPU=1."+ exit 0+ fi+ # GPU support is the WSL 2 backend only (docs.docker.com/desktop/features/gpu/); Hyper-V's+ # LinuxKit VM has none. The kernel string tells them apart: *-microsoft-standard-WSL2 vs *-linuxkit.+ desktop_info="$(docker info --format '{{.OperatingSystem}}|{{.KernelVersion}}' 2>/dev/null)" \+ || fail "Docker Desktop is not running, or the Docker CLI cannot reach it. Start Docker Desktop,+ wait until it reports running, then run this again." 2+ desktop_os_name="${desktop_info%%|*}"+ desktop_os="$(printf '%s' "$desktop_os_name" | tr '[:upper:]' '[:lower:]')"+ desktop_kernel="${desktop_info#*|}"+ kernel_lc="$(printf '%s' "$desktop_kernel" | tr '[:upper:]' '[:lower:]')"+ case "$desktop_os" in+ *"docker desktop"*)+ case "$kernel_lc" in+ *microsoft*|*wsl*)+ say "Windows: Docker Desktop with the WSL 2 backend brings its own GPU support, nothing to install here."+ say "Keep a current NVIDIA Windows driver installed (from nvidia.com), then: docker run --gpus all ..."+ say "Only a WSL 2 distro running its own Docker Engine needs this script; run it inside that distro."+ exit 0 ;;+ esac+ fail "Docker Desktop is running on the Hyper-V backend (kernel ${desktop_kernel}), which has no+ GPU support. Switch it to WSL 2 (Settings > General > Use the WSL 2 based engine), keep a+ current NVIDIA Windows driver installed (from nvidia.com), then: docker run --gpus all ..." 2 ;;+ esac+ say "Windows: this Docker CLI drives ${desktop_os_name:-a daemon}, not Docker Desktop, and a Windows shell cannot configure it."+ say "Only a WSL 2 distro running its own Docker Engine needs this script; run it inside that distro."+ exit 0 ;;+esac+# Docker Desktop ships its own GPU integration; installing here would configure a daemon it does not use. Checked before elevating.docker_info="$(docker info 2>/dev/null || true)"if grep -qi 'Operating System: Docker Desktop' <<<"$docker_info"; then- if [[ "$(uname -s)" == Darwin ]]; then- say "Docker Desktop on macOS: no NVIDIA GPU can be attached on a Mac, so there is nothing to install."- say "The image runs CPU-only there: drop --gpus and set UNSLOTH_ALLOW_CPU=1."- exit 0- elif grep -qi microsoft "$PROC_VERSION" 2>/dev/null; then+ if grep -qi microsoft "$PROC_VERSION" 2>/dev/null; thensay "Docker Desktop with the WSL 2 backend: GPU support comes with it, nothing to install here."say "Keep a current NVIDIA Windows driver installed (from nvidia.com; wsl --update updates WSL itself, not the driver)."exit 0diff --git a/docker/run.sh b/docker/run.shindex 220928cbb06..3489419e890 100755--- a/docker/run.sh+++ b/docker/run.sh@@ -103,6 +103,17 @@ if [[ ${#GPU_FLAG[@]} -gt 0 ]] && ! host_has_nvidia; thendonefiprintf " AMD devices found: passing /dev/kfd and /dev/dri through.\n" >&2+ # published images only (untagged is :latest); a custom image may carry a HIP or Vulkan build+ if [[ "$IMAGE" == unsloth/unsloth || "$IMAGE" == unsloth/unsloth:* ]]; then+ printf " Nothing in the image uses them yet: torch is cu128 and the bundled\n" >&2+ printf " llama.cpp has no HIP or Vulkan backend, so this container runs on the CPU.\n" >&2+ if [[ "$IMAGE" == unsloth/unsloth:core* ]]; then+ printf " :core refuses a CPU-only start unless UNSLOTH_ALLOW_CPU=1 is set (:latest allows it).\n" >&2+ fi+ else+ printf " The published unsloth/unsloth images cannot use them (cu128 torch, no HIP\n" >&2+ printf " or Vulkan llama.cpp); whether %s does is up to that image.\n" "$IMAGE" >&2+ fifiprintf "\n" >&2fidiff --git a/docker/studio_launch.sh b/docker/studio_launch.shindex ab9c4ed9c3a..fd0989f18c1 100644--- a/docker/studio_launch.sh+++ b/docker/studio_launch.sh@@ -16,9 +16,23 @@# PUBLIC_KEY/SSH_KEY OpenSSH public key for root login; sshd stays disabled# when neither is set (nothing to authenticate with --# password login is never enabled for root)+# UNSLOTH_STUDIO_LAUNCH_CHECK_ONLY=1 exit 0 right after the settings checks, before+# anything is written (tests only)set -euo pipefailexport JUPYTER_PORT="${JUPYTER_PORT:-8888}"+# Studio is fixed at 8000 (studio_run.sh); JupyterLab starts first and wins the bind, so+# Studio silently falls back to an unpublished 8001. Compared as traitlets does, via int():+# whitespace, leading zeros, a leading + and underscores ("08000", " 8000", "8_000") all bind 8000.+jupyter_port_digits="${JUPYTER_PORT//[[:space:]_]/}"+jupyter_port_digits="${jupyter_port_digits#+}"+if [[ "$jupyter_port_digits" =~ ^[0-9]+$ ]] && (( 10#$jupyter_port_digits == 8000 )); then+ printf "\033[1;31mERROR:\033[0m JUPYTER_PORT=8000 is Unsloth Studio's port inside the container.\n" >&2+ printf " Leave JupyterLab on 8888 and map the host side instead: -p 9000:8888\n" >&2+ exit 1+fi+# tests run this on the host; everything past here writes /etc/profile.d, /root/.jupyter, /workspace+[[ "${UNSLOTH_STUDIO_LAUNCH_CHECK_ONLY:-0}" == 1 ]] && exit 0export UNSLOTH_STUDIO_HOME="${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}"export UNSLOTH_JUPYTER_CLOUDFLARE="${UNSLOTH_JUPYTER_CLOUDFLARE:-0}"diff --git a/tests/python/test_docker_build_ref_resolution.py b/tests/python/test_docker_build_ref_resolution.pyindex a768fe33dfe..f649ca2709d 100644--- a/tests/python/test_docker_build_ref_resolution.py+++ b/tests/python/test_docker_build_ref_resolution.py@@ -39,10 +39,13 @@ def _run(tmp_path: Path,git_body: str,env_extra: dict[str, str] | None = None,+ stubs: dict[str, str] | None = None,):bin_dir = tmp_path / "bin"bin_dir.mkdir()args_file = tmp_path / "docker-args.txt"+ for name, body in (stubs or {}).items():+ _stub(bin_dir / name, body)_stub(bin_dir / "git", git_body)_stub(bin_dir / "docker", f'printf "%s\\n" "$@" > {args_file}\n')# no network: the llama.cpp tag lookup must not reach github from a unit test@@ -95,6 +98,33 @@ def test_the_default_main_refs_are_frozen_to_commits(tmp_path):assert _build_arg(argv, "UNSLOTH_NOTEBOOKS_REF") == NB_SHA+def test_the_smoke_test_message_names_the_build_hosts_own_gpu(tmp_path):+ """It named a B200 on every host, including the ones that have no NVIDIA GPU."""+ proc, _argv = _run(+ tmp_path, LS_REMOTE_STUB, stubs = {"nvidia-smi": 'echo "NVIDIA GeForce RTX 3090"\n'}+ )+ assert "RTX 3090" in proc.stdout, proc.stdout+ assert "B200" not in proc.stdout and "sm_100" not in proc.stdout+++def test_the_smoke_test_message_claims_no_gpu_when_there_is_none(tmp_path):+ proc, _argv = _run(tmp_path, LS_REMOTE_STUB, stubs = {"nvidia-smi": "exit 9\n"})+ assert "Smoke test on this host:" in proc.stdout, proc.stdout+++def test_a_failing_gpu_query_is_not_shown_as_a_gpu_name(tmp_path):+ """nvidia-smi prints its failure text on stdout; only a successful query names a GPU."""+ proc, _argv = _run(+ tmp_path,+ LS_REMOTE_STUB,+ stubs = {+ "nvidia-smi": 'echo "NVIDIA-SMI has failed because it could not communicate"; exit 9\n'+ },+ )+ assert "Smoke test on this host:" in proc.stdout, proc.stdout+ assert "has failed" not in proc.stdout++def test_an_explicit_tag_is_frozen_too(tmp_path):_proc, argv = _run(tmp_path, LS_REMOTE_STUB, {"UNSLOTH_REF": "v2026.5.6", "UNSLOTH_ZOO_REF": "v2026.5.4"}diff --git a/tests/python/test_docker_cpu_fallback.py b/tests/python/test_docker_cpu_fallback.pyindex e0cfbe3f081..033ec46d681 100644--- a/tests/python/test_docker_cpu_fallback.py+++ b/tests/python/test_docker_cpu_fallback.py@@ -46,6 +46,7 @@ def _invoke_run_sh(nvidia,amd,groups = "both",+ image = None,extra_env = None,):"""Run docker/run.sh with a recording `docker` stub and a staged /dev tree.@@ -108,6 +109,9 @@ def _invoke_run_sh("UNSLOTH_STUDIO_VOLUME",):env.pop(leak, None)+ env.pop("UNSLOTH_IMAGE", None)+ if image:+ env["UNSLOTH_IMAGE"] = imageenv.update(extra_env or {})# absolute: the "absent" case strips /usr/bin from PATH, so `bash` itself would@@ -135,12 +139,32 @@ class TestRunShDegradesWithoutNvidia:def test_amd_host_gets_the_render_nodes_with_numeric_gids(self, tmp_path):"""--group-add by NAME resolves inside the container, where the host'svideo/render groups do not exist, so the gids must be numeric."""- argv, _ = _invoke_run_sh(tmp_path, nvidia = False, amd = True)+ argv, stderr = _invoke_run_sh(tmp_path, nvidia = False, amd = True)assert "--gpus" not in argvassert "--device" in argvassert "/dev/kfd" in argv and "/dev/dri" in argvgids = [argv[i + 1] for i, a in enumerate(argv) if a == "--group-add"]assert all(g.isdigit() for g in gids), f"non-numeric --group-add: {gids}"+ # the devices go through, but no part of the image can drive them: torch is+ # cu128 and the bundled llama.cpp has neither a HIP nor a Vulkan backend+ assert "HIP" in stderr and "runs on the CPU" in stderr, (+ "an AMD host must be told the container still runs on the CPU:\n" + stderr+ )++ def test_the_untagged_published_name_is_recognised(self, tmp_path):+ """`unsloth/unsloth` is :latest to Docker, so the AMD notice has to treat it as a+ published image rather than as somebody else's."""+ _, stderr = _invoke_run_sh(tmp_path, nvidia = False, amd = True, image = "unsloth/unsloth")+ assert "runs on the CPU" in stderr, stderr+ assert "up to that image" not in stderr, stderr++ def test_the_cpu_only_claim_is_scoped_to_the_published_images(self, tmp_path):+ """A custom image may carry a HIP or Vulkan build; run.sh cannot know, so it+ must not claim the container runs on the CPU."""+ argv, stderr = _invoke_run_sh(tmp_path, nvidia = False, amd = True, image = "myorg/custom:rocm")+ assert "/dev/kfd" in argv+ assert "runs on the CPU" not in stderr, stderr+ assert "myorg/custom:rocm" in stderr and "unsloth/unsloth" in stderr, stderrdef test_the_group_lookup_is_guarded_on_getent_existing(self):"""A host with no getent at all (busybox, some slim images) must skip thediff --git a/tests/python/test_docker_nvidia_toolkit_install.py b/tests/python/test_docker_nvidia_toolkit_install.pyindex d35f7d3a39c..565625e0be8 100644--- a/tests/python/test_docker_nvidia_toolkit_install.py+++ b/tests/python/test_docker_nvidia_toolkit_install.py@@ -88,6 +88,9 @@ def _setup(rootless: bool | str = False,chunked: bool = False,gpus: int = 1,+ desktop_os: str = "Docker Desktop",+ desktop_kernel: str = "5.15.167.4-microsoft-standard-WSL2",+ desktop_info_fails: bool = False,) -> tuple[Path, Path, dict]:bindir = tmp_path / "bin"bindir.mkdir()@@ -127,6 +130,11 @@ def _setup(rec+ 'if [ "$1" = context ]; then case "${DOCKER_CONTEXT:-}" in remote*) echo "tcp://gpu-box:2376" ;; missing*) echo "context not found" >&2; exit 1 ;; *) echo "unix:///var/run/docker.sock" ;; esac; exit 0; fi\n'+ 'if [ "$1" = info ]; then\n'+ + (+ ' case "$3" in *OperatingSystem*) echo "cannot connect to the Docker daemon" >&2; exit 1 ;; esac\n'+ if desktop_info_fails+ else f' case "$3" in *OperatingSystem*) echo "{desktop_os}|{desktop_kernel}"; exit 0 ;; esac\n'+ )+ (' echo " Operating System: Docker Desktop"\n' if desktop else "")# A real daemon does not hand `docker info` over in one write. Pausing here puts the# rest of the output after the point where a `grep -q` consumer has already matched.@@ -545,6 +553,167 @@ def test_docker_desktop_on_macos_says_cpu_only(tmp_path: Path):assert "GPU support comes with it" not in res.stdout+def test_macos_says_cpu_only_whatever_runs_the_daemon(tmp_path: Path):+ """colima and Rancher Desktop keep their socket outside /var/run, which took a Mac+ to the endpoint check: it told the user to configure that daemon by hand, for a+ toolkit no Mac can use."""+ _, _, env = _setup(tmp_path, driver = False, uid = 1000)+ _stub(tmp_path / "bin" / "uname", 'if [ "$1" = -s ]; then echo Darwin; else echo arm64; fi\n')+ res = _run(env, extra_env = {"DOCKER_HOST": "unix:///Users/u/.colima/default/docker.sock"})+ assert res.returncode == 0, res.stdout + res.stderr+ assert "no NVIDIA GPU" in res.stdout and "UNSLOTH_ALLOW_CPU=1" in res.stdout+ assert "by hand" not in res.stderr, res.stderr+++def test_a_mac_driving_a_remote_daemon_is_sent_to_that_host(tmp_path: Path):+ """The one Mac the toolkit concerns: a CLI pointed at a Linux box over tcp:// or+ ssh://. "Nothing to install" there is wrong; the box needs it."""+ _, _, env = _setup(tmp_path, driver = False, uid = 1000)+ _stub(tmp_path / "bin" / "uname", 'if [ "$1" = -s ]; then echo Darwin; else echo arm64; fi\n')+ res = _run(env, extra_env = {"DOCKER_HOST": "tcp://gpu-box:2376"})+ assert res.returncode == 2, res.stdout + res.stderr+ assert "remote daemon (tcp://gpu-box:2376)" in res.stderr+ assert "nothing to install" not in res.stdout+ # DOCKER_CONTEXT wins over DOCKER_HOST, as in the endpoint check further down+ res = _run(+ env,+ extra_env = {"DOCKER_HOST": "unix:///var/run/docker.sock", "DOCKER_CONTEXT": "remote-gpu"},+ )+ assert res.returncode == 2, res.stdout + res.stderr+ assert "remote daemon (tcp://gpu-box:2376)" in res.stderr+ # a bare host:port is tcp to Docker, so it is remote here too+ res = _run(env, extra_env = {"DOCKER_HOST": "gpu-box:2376"})+ assert res.returncode == 2, res.stdout + res.stderr+ assert "remote daemon (gpu-box:2376)" in res.stderr+++ "endpoint", ["tcp://localhost:2375", "tcp://127.0.0.1:2375", "tcp://[::1]:2375", "localhost:2375"]+)+def test_a_loopback_tcp_endpoint_is_this_machine(tmp_path: Path, endpoint: str):+ """Docker Desktop can expose its daemon on tcp://localhost:2375, and a socket can be+ proxied through localhost; both are the local daemon, not a box to run this on."""+ _, _, env = _setup(tmp_path, driver = False, uid = 1000)+ _stub(tmp_path / "bin" / "uname", 'if [ "$1" = -s ]; then echo Darwin; else echo arm64; fi\n')+ res = _run(env, extra_env = {"DOCKER_HOST": endpoint})+ assert res.returncode == 0, res.stdout + res.stderr+ assert "remote daemon" not in res.stderr+ assert "nothing to install" in res.stdout+++ "kernel", ["MINGW64_NT-10.0-22631", "MSYS_NT-10.0-22631", "CYGWIN_NT-10.0"]+)+def test_a_windows_shell_is_sent_to_docker_desktops_wsl2_backend(tmp_path: Path, kernel: str):+ """Git Bash / MSYS2 / Cygwin drive Docker Desktop, whose WSL 2 backend has the GPU+ support built in. The Linux path read Desktop as "Docker Desktop for Linux" (exit 2)+ and, with a plain daemon, tried apt on Windows."""+ _, log, env = _setup(tmp_path, desktop = True, driver = False)+ _stub(+ tmp_path / "bin" / "uname", f'if [ "$1" = -s ]; then echo {kernel}; else echo x86_64; fi\n'+ )+ res = _run(env)+ assert res.returncode == 0, res.stdout + res.stderr+ assert "WSL 2 backend" in res.stdout+ assert "Docker Desktop for Linux" not in res.stderr+ assert not any(c.startswith(("apt-get", "dnf", "nvidia-ctk", "systemctl")) for c in _calls(log))++[email protected]("kernel", ["MINGW64_NT-10.0-22631", "MSYS_NT-10.0"])+def test_a_windows_shell_driving_a_remote_daemon_is_sent_to_that_host(tmp_path: Path, kernel: str):+ """Same rule as on a Mac: DOCKER_HOST or a context pointing at a Linux box means that+ box may need the toolkit, so the Desktop shortcut must not answer for it."""+ _, log, env = _setup(tmp_path, desktop = True, driver = False)+ _stub(+ tmp_path / "bin" / "uname", f'if [ "$1" = -s ]; then echo {kernel}; else echo x86_64; fi\n'+ )+ res = _run(env, extra_env = {"DOCKER_HOST": "tcp://gpu-box:2376"})+ assert res.returncode == 2, res.stdout + res.stderr+ assert "remote daemon (tcp://gpu-box:2376)" in res.stderr+ assert "WSL 2 backend" not in res.stdout+ res = _run(env, extra_env = {"DOCKER_CONTEXT": "remote-gpu"})+ assert res.returncode == 2, res.stdout + res.stderr+ assert "remote daemon (tcp://gpu-box:2376)" in res.stderr+ res = _run(env, extra_env = {"DOCKER_CONTEXT": "missing-in-root-config"})+ assert res.returncode == 2+ assert "cannot inspect the Docker context" in res.stderr+ assert not any(c.startswith(("apt-get", "dnf", "nvidia-ctk", "systemctl")) for c in _calls(log))+++def test_a_windows_shell_on_the_hyper_v_backend_is_told_to_switch(tmp_path: Path):+ """Docker Desktop's GPU support is the WSL 2 backend only; the Hyper-V backend runs a+ LinuxKit VM no GPU reaches, so "nothing to install" there leaves --gpus failing at the+ daemon. The backends are told apart by the kernel `docker info` reports."""+ _, log, env = _setup(tmp_path, desktop = True, driver = False, desktop_kernel = "6.6.87.2-linuxkit")+ _stub(+ tmp_path / "bin" / "uname",+ 'if [ "$1" = -s ]; then echo MINGW64_NT-10.0-22631; else echo x86_64; fi\n',+ )+ res = _run(env)+ assert res.returncode == 2, res.stdout + res.stderr+ assert "Use the WSL 2 based engine" in res.stderr+ assert "6.6.87.2-linuxkit" in res.stderr+ assert "nothing to install" not in res.stdout+ assert not any(c.startswith(("apt-get", "dnf", "nvidia-ctk", "systemctl")) for c in _calls(log))+++def test_a_windows_shell_that_cannot_reach_docker_desktop_says_so(tmp_path: Path):+ """With Desktop stopped the backend is unknowable, so neither answer can be given."""+ _, log, env = _setup(tmp_path, driver = False, desktop_info_fails = True)+ _stub(+ tmp_path / "bin" / "uname",+ 'if [ "$1" = -s ]; then echo MINGW64_NT-10.0-22631; else echo x86_64; fi\n',+ )+ res = _run(env)+ assert res.returncode == 2, res.stdout + res.stderr+ assert "Docker Desktop is not running" in res.stderr+ assert "WSL 2 backend" not in res.stdout+ assert not any(c.startswith(("apt-get", "dnf", "nvidia-ctk", "systemctl")) for c in _calls(log))+++def test_a_windows_shell_on_a_non_desktop_daemon_is_sent_into_the_distro(tmp_path: Path):+ """A Docker Engine inside a WSL distro, reached through its pipe or socket, and Rancher+ Desktop both answer `docker info` with something other than Docker Desktop. Neither can+ be configured from a Windows shell, and neither is an error."""+ _, log, env = _setup(+ tmp_path,+ driver = False,+ desktop_os = "Ubuntu 24.04.1 LTS",+ desktop_kernel = "5.15.167.4-microsoft-standard-WSL2",+ )+ _stub(+ tmp_path / "bin" / "uname",+ 'if [ "$1" = -s ]; then echo MINGW64_NT-10.0-22631; else echo x86_64; fi\n',+ )+ res = _run(env)+ assert res.returncode == 0, res.stdout + res.stderr+ assert "run it inside that distro" in res.stdout+ assert "Ubuntu 24.04.1 LTS" in res.stdout+ assert not any(c.startswith(("apt-get", "dnf", "nvidia-ctk", "systemctl")) for c in _calls(log))+++def test_a_mac_never_asks_the_daemon_which_backend_it_is(tmp_path: Path):+ """No Mac takes an NVIDIA GPU whatever the daemon is, so the backend probe added for+ Windows must not make macOS depend on a reachable daemon."""+ _, log, env = _setup(tmp_path, driver = False, desktop_info_fails = True)+ _stub(tmp_path / "bin" / "uname", 'if [ "$1" = -s ]; then echo Darwin; else echo arm64; fi\n')+ res = _run(env)+ assert res.returncode == 0, res.stdout + res.stderr+ assert "no NVIDIA GPU" in res.stdout and "UNSLOTH_ALLOW_CPU=1" in res.stdout+ assert not any(c.startswith("docker info") for c in _calls(log))+++def test_a_mac_with_an_uninspectable_context_gets_the_error_not_nothing_to_install(tmp_path: Path):+ """Same rule as the endpoint check further down: a context lookup failure is an+ error, not a local daemon."""+ _, _, env = _setup(tmp_path, driver = False, uid = 1000)+ _stub(tmp_path / "bin" / "uname", 'if [ "$1" = -s ]; then echo Darwin; else echo arm64; fi\n')+ res = _run(env, extra_env = {"DOCKER_CONTEXT": "missing-in-root-config"})+ assert res.returncode == 2, res.stdout + res.stderr+ assert "cannot inspect the Docker context 'missing-in-root-config'" in res.stderr+ assert "nothing to install" not in res.stdout++def test_the_old_driver_message_names_the_host_platform_even_without_verification(tmp_path: Path):_, _, env = _setup(tmp_path, driver_version = "550.54.15")_stub(tmp_path / "bin" / "uname", 'if [ "$1" = -s ]; then echo Linux; else echo aarch64; fi\n')diff --git a/tests/python/test_docker_studio_launch_port_guard.py b/tests/python/test_docker_studio_launch_port_guard.pynew file mode 100644index 00000000000..e3afb154c24--- /dev/null+++ b/tests/python/test_docker_studio_launch_port_guard.py@@ -0,0 +1,83 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0++"""JupyterLab must not be started on Studio's port.++Studio's port is fixed at 8000 (`studio_run.sh`), so with `JUPYTER_PORT=8000`+JupyterLab wins the bind and Studio falls back to an unpublished 8001. Both report+RUNNING and the summary still points at 8000, where Jupyter answers 404.+"""++from __future__ import annotations++import os+import shutil+import subprocess+from pathlib import Path++import pytest++REPO_ROOT = Path(__file__).resolve().parents[2]+LAUNCH = REPO_ROOT / "docker" / "studio_launch.sh"++pytestmark = pytest.mark.skipif(shutil.which("bash") is None, reason = "needs bash")+++def _run(port: str) -> subprocess.CompletedProcess:+ # check-only: past the settings checks the launcher writes /etc/profile.d,+ # /root/.jupyter and /workspace, which on a root test host it really would+ env = dict(os.environ, JUPYTER_PORT = port, UNSLOTH_STUDIO_LAUNCH_CHECK_ONLY = "1")+ return subprocess.run(+ ["bash", str(LAUNCH)], capture_output = True, text = True, env = env, timeout = 120+ )+++def test_jupyter_on_studios_port_is_refused_with_a_remedy():+ res = _run("8000")+ assert res.returncode != 0, "the container started with Studio unreachable"+ assert "JUPYTER_PORT=8000" in res.stderr, res.stderr+ assert "-p 9000:8888" in res.stderr, "the remedy must be printed:\n" + res.stderr++[email protected]("spelling", ["08000", " 8000", "8000 ", "+8000", "8_000"])+def test_other_spellings_of_8000_are_refused_too(spelling: str):+ """Jupyter's port is a traitlets Integer, read with int(): whitespace, leading zeros,+ a leading + and digit-group underscores all give 8000 as well."""+ res = _run(spelling)+ assert res.returncode != 0, spelling+ assert "JUPYTER_PORT=8000" in res.stderr, res.stderr++[email protected]("port", ["8899", "8001", "8000.0", "0x1f40", "8000/tcp", "-8000"])+def test_other_ports_and_values_jupyter_rejects_itself_pass_the_guard(port: str):+ """Only what int() reads as 8000 is ours to refuse; "8000.0" or "0x1f40" fail in+ Jupyter with its own message."""+ res = _run(port)+ assert res.returncode == 0, res.stderr+ assert "JUPYTER_PORT=8000" not in res.stderr, res.stderr+++ getattr(os, "geteuid", lambda: -1)() == 0,+ reason = "as root the launcher would write to /etc and /root",+)+def test_check_only_set_to_zero_does_not_stop_the_launcher():+ """`=0` must mean off: the launcher goes on past the guard. On a non-root test host+ the next step, writing /etc/profile.d, fails, which is the proof that it went on."""+ env = dict(os.environ, JUPYTER_PORT = "8899", UNSLOTH_STUDIO_LAUNCH_CHECK_ONLY = "0")+ res = subprocess.run(+ ["bash", str(LAUNCH)], capture_output = True, text = True, env = env, timeout = 120+ )+ assert res.returncode != 0, "check-only=0 exited 0 before touching anything"+ assert "/etc/profile.d/unsloth_env.sh" in res.stderr, res.stderr+++def test_the_check_only_exit_comes_after_the_guard():+ """The guard is the point; check-only must not skip it, and nothing before the+ check-only exit may touch the host."""+ body = LAUNCH.read_text(encoding = "utf-8")+ guard = body.index("jupyter_port_digits == 8000")+ check = body.index("UNSLOTH_STUDIO_LAUNCH_CHECK_ONLY:-")+ assert guard < check+ assert "> /etc/profile.d/unsloth_env.sh" not in body[:check]+ assert "> /etc/profile.d/unsloth_env.sh" in body[check:]