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 installer: cover the GPUs CUDA_VISIBLE_DEVICES hides when picking the llama.cpp CUDA bundle (#13924)

Daniel Hanb17be8bdad2b
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 462b030a2e0..399822f90ce 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -2000,13 +2000,66 @@ def _warn_uncovered_cuda_host(
log(message)
+def _mask_widened_sms(host: HostInfo) -> list[str] | None:
+ """Every physical SM when CUDA_VISIBLE_DEVICES hides a card with an SM the visible ones lack.
+
+ The mask is per process, the install tree is not: a bundle cut to the visible cards dies
+ with "no kernel image" on the hidden one once the mask is gone, and torch / setup.sh
+ already target every physical GPU. Coverage only widens; the mask still picks the card
+ at runtime. None when nothing is hidden or the physical caps are unknown, and when the
+ visible caps are unknown: the visible-only path's unknown-GPU safeguard then decides.
+ """
+ visible = normalize_compute_caps(host.compute_caps)
+ physical = normalize_compute_caps(host.physical_compute_caps)
+ if not visible or not physical or set(physical) <= set(visible):
+ return None
+ return normalize_compute_caps(physical + visible)
+
+
def linux_cuda_choice_from_release(
host: HostInfo,
release: PublishedReleaseBundle,
preferred_runtime_line: str | None = None,
selection_preamble: Iterable[str] = (),
+ host_sms: list[str] | None = None,
) -> LinuxCudaSelection | None:
- host_sms = normalize_compute_caps(host.compute_caps)
+ selection_preamble = list(selection_preamble)
+ # An explicit host_sms is the widened try, whose miss falls back rather than warns.
+ warn_uncovered = host_sms is None
+ if host_sms is None:
+ widened_sms = _mask_widened_sms(host)
+ if widened_sms is not None:
+ widened = linux_cuda_choice_from_release(
+ host,
+ release,
+ preferred_runtime_line,
+ selection_preamble
+ + [
+ "linux_cuda_selection: covering the GPUs CUDA_VISIBLE_DEVICES hides, "
+ f"physical_sms={','.join(widened_sms)}"
+ ],
+ host_sms = widened_sms,
+ )
+ if widened is not None:
+ # The visible-only picks stay as later attempts, should the wider one fail.
+ visible = linux_cuda_choice_from_release(
+ host,
+ release,
+ preferred_runtime_line,
+ selection_preamble,
+ host_sms = normalize_compute_caps(host.compute_caps),
+ )
+ names = {a.name for a in widened.attempts}
+ widened.attempts.extend(
+ a for a in (visible.attempts if visible else []) if a.name not in names
+ )
+ return widened
+ # No bundle covers every physical card: keep the visible-only choice.
+ selection_preamble.append(
+ "linux_cuda_selection: no bundle covers physical_sms="
+ f"{','.join(widened_sms)}; selecting for the visible GPUs"
+ )
+ host_sms = normalize_compute_caps(host.compute_caps)
detected_runtime_lines, runtime_dirs = detected_linux_runtime_lines()
driver_runtime_lines = compatible_linux_runtime_lines(host)
runtime_lines = [
@@ -2060,6 +2113,8 @@ def linux_cuda_choice_from_release(
selection_log.append(
"linux_cuda_selection: no Linux CUDA runtime line satisfied both runtime libraries and driver compatibility"
)
+ if not warn_uncovered:
+ return None
if driver_below_cuda_prebuilt_floor(host):
floor_message = cuda_driver_floor_message(host)
selection_log.append(f"linux_cuda_selection: {floor_message}")
@@ -2219,13 +2274,14 @@ def linux_cuda_choice_from_release(
add_attempt(artifact, url, "portable fallback for runtime line")
if not attempts:
- _warn_uncovered_cuda_host(
- host_sms,
- detected_runtime_lines,
- driver_runtime_lines,
- published_artifacts,
- host.is_arm64,
- )
+ if warn_uncovered:
+ _warn_uncovered_cuda_host(
+ host_sms,
+ detected_runtime_lines,
+ driver_runtime_lines,
+ published_artifacts,
+ host.is_arm64,
+ )
return None
selection_log.append(
@@ -3631,7 +3687,49 @@ def published_windows_cuda_attempts(
preferred_runtime_line: str | None,
selection_preamble: Iterable[str] = (),
arch: str | None = None,
+ host_sms: list[str] | None = None,
) -> list[AssetChoice]:
+ selection_preamble = list(selection_preamble)
+ # The widened try logs nothing a visible-only retry would repeat.
+ log_floor = host_sms is None
+ if host_sms is None:
+ # As linux_cuda_choice_from_release: cover the cards the mask hides when a bundle can.
+ widened_sms = _mask_widened_sms(host)
+ if widened_sms is not None:
+ widened = published_windows_cuda_attempts(
+ host,
+ release,
+ preferred_runtime_line,
+ selection_preamble
+ + [
+ "windows_cuda_selection: covering the GPUs CUDA_VISIBLE_DEVICES hides, "
+ f"physical_sms={','.join(widened_sms)}"
+ ],
+ arch = arch,
+ host_sms = widened_sms,
+ )
+ # Only bundles whose SM metadata proves they cover every card count as widening.
+ widened = [
+ a
+ for a in widened
+ if a.supported_sms and a.min_sm is not None and a.max_sm is not None
+ ]
+ if widened:
+ names = {a.name for a in widened}
+ visible = published_windows_cuda_attempts(
+ host,
+ release,
+ preferred_runtime_line,
+ selection_preamble,
+ arch = arch,
+ host_sms = normalize_compute_caps(host.compute_caps),
+ )
+ return widened + [a for a in visible if a.name not in names]
+ selection_preamble.append(
+ "windows_cuda_selection: no bundle covers physical_sms="
+ f"{','.join(widened_sms)}; selecting for the visible GPUs"
+ )
+ host_sms = normalize_compute_caps(host.compute_caps)
if arch is None:
arch = windows_cuda_arch_for_host(host)
install_kind = windows_cuda_install_kind_for_arch(arch)
@@ -3693,9 +3791,9 @@ def published_windows_cuda_attempts(
if driver_below_cuda_prebuilt_floor(host):
floor_message = cuda_driver_floor_message(host)
selection_log.append(f"windows_cuda_selection: {floor_message}")
- log(floor_message)
+ if log_floor:
+ log(floor_message)
- host_sms = normalize_compute_caps(host.compute_caps)
attempts: list[AssetChoice] = []
for runtime_line in ordered_lines:
if not runtime_line:
@@ -7480,6 +7578,12 @@ def host_profile(host: HostInfo) -> dict[str, Any]:
list(host.driver_cuda_version) if host.driver_cuda_version else None
),
"compute_caps": _sorted_labels(host.compute_caps),
+ # Only when a mask hides another SM (the selectors then widen), so other hosts keep their profile.
+ **(
+ {"physical_compute_caps": _sorted_labels(host.physical_compute_caps)}
+ if _mask_widened_sms(host) is not None
+ else {}
+ ),
"has_rocm": bool(host.has_rocm),
# Upstream ROCm assets go by the runtime's major.minor, which the GPU fields do not carry.
"rocm_runtime": _rocm_runtime_for_profile(host),
diff --git a/tests/studio/install/test_llama_cuda_covers_masked_gpus.py b/tests/studio/install/test_llama_cuda_covers_masked_gpus.py
new file mode 100644
index 00000000000..74092c83279
--- /dev/null
+++ b/tests/studio/install/test_llama_cuda_covers_masked_gpus.py
@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+"""A CUDA_VISIBLE_DEVICES mask that hides a card of another SM must not narrow the llama.cpp
+CUDA bundle to the visible cards: the install outlives the mask. Torch and setup.sh already
+target every physical GPU. When no bundle covers them all, the visible-only choice stands."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+MODULE_NAME = "studio_install_llama_prebuilt"
+if MODULE_NAME in sys.modules:
+ m = sys.modules[MODULE_NAME]
+else:
+ SPEC = importlib.util.spec_from_file_location(MODULE_NAME, MODULE_PATH)
+ assert SPEC is not None and SPEC.loader is not None
+ m = importlib.util.module_from_spec(SPEC)
+ sys.modules[MODULE_NAME] = m
+ SPEC.loader.exec_module(m)
+
+
+def host(
+ system,
+ caps,
+ physical,
+ visible = "1",
+ driver = (12, 8),
+):
+ return m.HostInfo(
+ system = system,
+ machine = "AMD64" if system == "Windows" else "x86_64",
+ is_windows = system == "Windows",
+ is_linux = system == "Linux",
+ is_macos = False,
+ is_x86_64 = True,
+ is_arm64 = False,
+ nvidia_smi = "nvidia-smi",
+ driver_cuda_version = driver,
+ compute_caps = list(caps),
+ physical_compute_caps = list(physical),
+ visible_cuda_devices = visible,
+ has_physical_nvidia = True,
+ has_usable_nvidia = True,
+ )
+
+
+def artifact(
+ name,
+ kind,
+ line,
+ profile,
+ sms,
+ coverage = "targeted",
+ rank = 100,
+):
+ caps = [str(s) for s in sms]
+ return m.PublishedLlamaArtifact(
+ asset_name = name,
+ install_kind = kind,
+ runtime_line = line,
+ coverage_class = coverage,
+ supported_sms = caps,
+ min_sm = int(caps[0]),
+ max_sm = int(caps[-1]),
+ bundle_profile = profile,
+ rank = rank,
+ )
+
+
+def release(artifacts):
+ return m.PublishedReleaseBundle(
+ repo = "unslothai/llama.cpp",
+ release_tag = "v1.0",
+ upstream_tag = "b8508",
+ assets = {a.asset_name: f"https://example.com/{a.asset_name}" for a in artifacts},
+ artifacts = list(artifacts),
+ )
+
+
+LINUX_NEWER = artifact(
+ "app-b8508-linux-x64-cuda12-newer.tar.gz", "linux-cuda", "cuda12", "cuda12-newer", [86, 89, 90]
+)
+LINUX_WIDE = artifact(
+ "app-b8508-linux-x64-cuda12-wide.tar.gz",
+ "linux-cuda",
+ "cuda12",
+ "cuda12-wide",
+ [61, 70, 75, 80, 86, 89, 90],
+ rank = 200,
+)
+WIN_NEWER = artifact(
+ "llama-app-win-cuda12-newer-x64.zip", "windows-cuda", "cuda12", "cuda12-newer", [86, 89, 90]
+)
+WIN_WIDE = artifact(
+ "llama-app-win-cuda12-wide-x64.zip",
+ "windows-cuda",
+ "cuda12",
+ "cuda12-wide",
+ [61, 70, 75, 80, 86, 89, 90],
+ rank = 200,
+)
+
+
[email protected](autouse = True)
+def _isolated(monkeypatch):
+ monkeypatch.setattr(m, "_UNCOVERED_CUDA_HOST_WARNINGS", set())
+ monkeypatch.setattr(
+ m, "detected_linux_runtime_lines", lambda: (["cuda12"], {"cuda12": ["/usr/lib"]})
+ )
+ monkeypatch.setattr(m, "detected_windows_runtime_lines", lambda: (["cuda12"], {}))
+
+
+# GTX 1080 (sm_61) + RTX 4090 (sm_89), CUDA_VISIBLE_DEVICES=1 leaves only the 4090 visible.
+MASKED_LINUX = host("Linux", ["89"], ["61", "89"])
+MASKED_WINDOWS = host("Windows", ["89"], ["61", "89"])
+
+
+class TestLinux:
+ def test_the_bundle_covers_the_card_the_mask_hides(self):
+ selection = m.linux_cuda_choice_from_release(
+ MASKED_LINUX, release([LINUX_NEWER, LINUX_WIDE])
+ )
+ assert selection is not None
+ # The visible-only pick stays as the fallback attempt.
+ assert [a.bundle_profile for a in selection.attempts] == ["cuda12-wide", "cuda12-newer"]
+ assert any("physical_sms=61,89" in line for line in selection.selection_log)
+
+ def test_no_bundle_for_every_card_keeps_the_visible_choice_without_a_warning(self, monkeypatch):
+ warnings = []
+ monkeypatch.setattr(m, "log", warnings.append)
+ selection = m.linux_cuda_choice_from_release(MASKED_LINUX, release([LINUX_NEWER]))
+ assert selection is not None
+ assert [a.bundle_profile for a in selection.attempts] == ["cuda12-newer"]
+ assert any("selecting for the visible GPUs" in line for line in selection.selection_log)
+ assert not any("no published CUDA bundle covers" in w for w in warnings)
+
+ def test_the_published_attempts_path_takes_the_wide_bundle(self, monkeypatch):
+ monkeypatch.setattr(
+ m,
+ "detect_torch_cuda_runtime_preference",
+ lambda *a, **k: m.CudaRuntimePreference(None, []),
+ )
+ attempts = m._linux_published_attempts(MASKED_LINUX, release([LINUX_NEWER, LINUX_WIDE]))
+ assert [a.bundle_profile for a in attempts] == ["cuda12-wide", "cuda12-newer"]
+
+
+class TestWindows:
+ def test_the_bundle_covers_the_card_the_mask_hides(self):
+ attempts = m.published_windows_cuda_attempts(
+ MASKED_WINDOWS, release([WIN_NEWER, WIN_WIDE]), None
+ )
+ assert [a.bundle_profile for a in attempts] == ["cuda12-wide", "cuda12-newer"]
+
+ def test_no_bundle_for_every_card_keeps_the_visible_choice(self):
+ attempts = m.published_windows_cuda_attempts(MASKED_WINDOWS, release([WIN_NEWER]), None)
+ assert [a.bundle_profile for a in attempts] == ["cuda12-newer"]
+ assert any("selecting for the visible GPUs" in line for line in attempts[0].selection_log)
+
+ def test_unknown_coverage_is_not_a_widening(self):
+ # A bundle without SM metadata cannot prove it covers the hidden card, so the visible pick stays.
+ unknown = m.PublishedLlamaArtifact(
+ asset_name = "llama-app-win-cuda12-unknown-x64.zip",
+ install_kind = "windows-cuda",
+ runtime_line = "cuda12",
+ coverage_class = "targeted",
+ supported_sms = [],
+ min_sm = None,
+ max_sm = None,
+ bundle_profile = "cuda12-unknown",
+ rank = 50,
+ )
+ attempts = m.published_windows_cuda_attempts(
+ MASKED_WINDOWS, release([WIN_NEWER, unknown]), None
+ )
+ assert "cuda12-newer" in [a.bundle_profile for a in attempts]
+
+
+class TestKeptInstallProfile:
+ def test_a_masked_mixed_host_records_its_physical_caps(self):
+ assert m.host_profile(MASKED_LINUX)["physical_compute_caps"] == ["61", "89"]
+
+ @pytest.mark.parametrize("physical", [["89"], []])
+ def test_other_hosts_keep_their_profile_keys(self, physical):
+ assert "physical_compute_caps" not in m.host_profile(host("Linux", ["89"], physical))
+
+
[email protected]("system", ["Linux", "Windows"])
+def test_unknown_visible_caps_keep_the_unknown_gpu_safeguard(system):
+ # An empty or unresolvable mask hides which card runs: no widening, main's safeguard decides.
+ assert m._mask_widened_sms(host(system, [], ["61", "89"], visible = "")) is None