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.

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.sh
index e7eac3f2df0..6a90428f04a 100755
--- a/docker/build.sh
+++ b/docker/build.sh
@@ -93,9 +93,13 @@ DOCKER_BUILDKIT=1 docker build \
echo
echo "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.sh
index 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; then
say "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 0
diff --git a/docker/run.sh b/docker/run.sh
index 220928cbb06..3489419e890 100755
--- a/docker/run.sh
+++ b/docker/run.sh
@@ -103,6 +103,17 @@ if [[ ${#GPU_FLAG[@]} -gt 0 ]] && ! host_has_nvidia; then
done
fi
printf " 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
+ fi
fi
printf "\n" >&2
fi
diff --git a/docker/studio_launch.sh b/docker/studio_launch.sh
index 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 pipefail
export 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 0
export 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.py
index 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.py
index 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"] = image
env.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's
video/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 argv
assert "--device" in argv
assert "/dev/kfd" in argv and "/dev/dri" in argv
gids = [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, stderr
def test_the_group_lookup_is_guarded_on_getent_existing(self):
"""A host with no getent at all (busybox, some slim images) must skip the
diff --git a/tests/python/test_docker_nvidia_toolkit_install.py b/tests/python/test_docker_nvidia_toolkit_install.py
index 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.py
new file mode 100644
index 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:]