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
unsloth: explain the real fix when nvidia-smi sees a GPU torch cannot use (#9281)
vivek varikuti6e5147f9d3fa
diff --git a/tests/test_nvidia_smi_torch_mismatch_hint.py b/tests/test_nvidia_smi_torch_mismatch_hint.pynew file mode 100644index 00000000000..28007df02c7--- /dev/null+++ b/tests/test_nvidia_smi_torch_mismatch_hint.py@@ -0,0 +1,199 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++from __future__ import annotations++import ast+import os+import re+import subprocess+import sys+from pathlib import Path++import pytest++_GPU_INIT = Path(__file__).resolve().parents[1] / "unsloth" / "_gpu_init.py"+_HELPER = "_reraise_device_type_error_with_gpu_hint"++# Messages copied from unsloth_zoo/device_type.py.+_ROCM_HINT = "Unsloth detected signs of an AMD ROCm GPU, but your current PyTorch build has no usable HIP accelerator."+_NO_ACCELERATOR = "Unsloth cannot find any torch accelerator? You need a GPU."+_VENDOR_LIST = "Unsloth currently only works on NVIDIA, AMD and Intel GPUs."++[email protected](scope = "module")+def helper():+ """The shipped function, without importing unsloth (it `del`s the name at import)."""+ tree = ast.parse(_GPU_INIT.read_text(encoding = "utf-8"))+ names = (_HELPER, "_nvidia_smi_gpu_name")+ wanted = [n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name in names]+ assert _HELPER in [n.name for n in wanted]+ namespace = {"subprocess": subprocess, "os": os, "sys": sys}+ exec(compile(ast.Module(body = wanted, type_ignores = []), str(_GPU_INIT), "exec"), namespace)+ return namespace[_HELPER]+++def _smi(+ monkeypatch,+ *,+ returncode = 0,+ stdout = "NVIDIA GB10\n",+ raises = None,+):+ calls = []++ def fake_run(argv, **kwargs):+ calls.append(argv)+ if raises is not None:+ raise raises+ return subprocess.CompletedProcess(argv, returncode, stdout = stdout, stderr = "")++ monkeypatch.setattr(subprocess, "run", fake_run)+ monkeypatch.delenv("CUDA_VISIBLE_DEVICES", raising = False)+ return calls+++def _raise_through_handler(helper, original):+ """Call the helper the way _gpu_init does: from inside `except NotImplementedError`."""+ try:+ raise original+ except NotImplementedError as caught:+ helper(caught)+++def test_every_raise_site_is_wrapped():+ tree = ast.parse(_GPU_INIT.read_text(encoding = "utf-8"))+ handlers = [+ n+ for n in ast.walk(tree)+ if isinstance(n, ast.ExceptHandler)+ and isinstance(n.type, ast.Name)+ and n.type.id == "NotImplementedError"+ and any(+ isinstance(c, ast.Call) and getattr(c.func, "id", None) == _HELPER for c in ast.walk(n)+ )+ ]+ assert len(handlers) == 2, [h.lineno for h in handlers]++ deletes = [n for n in ast.walk(tree) if isinstance(n, ast.Delete)]+ freed = [+ n.lineno+ for n in deletes+ if any(isinstance(t, ast.Name) and t.id == _HELPER for t in ast.walk(n))+ ]+ assert len(freed) == 1+ assert freed[0] > max(h.lineno for h in handlers)++[email protected]("message", [_NO_ACCELERATOR, _VENDOR_LIST])+def test_generic_failure_gets_the_reinstall_hint(helper, monkeypatch, message):+ original = NotImplementedError(message)+ _smi(monkeypatch)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(original)++ assert "NVIDIA GB10" in str(excinfo.value)+ assert "torch.cuda.is_available() is False" in str(excinfo.value)+ assert excinfo.value.__cause__ is original+++def test_hint_diagnoses_and_links_rather_than_printing_a_command(helper, monkeypatch):+ _smi(monkeypatch)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(NotImplementedError(_NO_ACCELERATOR))++ message = str(excinfo.value)+ assert "https://github.com/unslothai/unsloth#-install" in message+ assert sys.executable in message+ assert not re.search(+ r"pip install|--index-url|download\.pytorch\.org|--torch-backend|torch[<>=]", message+ )+++def test_rocm_advice_passes_through_without_probing(helper, monkeypatch):+ original = NotImplementedError(_ROCM_HINT)+ calls = _smi(monkeypatch)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(original)++ assert excinfo.value is original+ assert calls == []++[email protected]("mask", ["", "-1", " ", " -1 "])+def test_deliberately_hidden_gpu_is_not_a_broken_build(helper, monkeypatch, mask):+ original = NotImplementedError(_NO_ACCELERATOR)+ calls = _smi(monkeypatch)+ monkeypatch.setenv("CUDA_VISIBLE_DEVICES", mask)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(original)++ assert excinfo.value is original+ assert calls == []++[email protected]("mask", ["0", "0,1", "1", "GPU-fake-uuid"])+def test_a_partial_mask_keeps_the_hint_but_names_itself(helper, monkeypatch, mask):+ _smi(monkeypatch)+ monkeypatch.setenv("CUDA_VISIBLE_DEVICES", mask)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(NotImplementedError(_NO_ACCELERATOR))++ assert "NVIDIA GB10" in str(excinfo.value)+ assert f"CUDA_VISIBLE_DEVICES={mask!r}" in str(excinfo.value)+++def test_no_mask_note_when_the_variable_is_unset(helper, monkeypatch):+ _smi(monkeypatch)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(NotImplementedError(_NO_ACCELERATOR))++ assert "CUDA_VISIBLE_DEVICES" not in str(excinfo.value)+++def test_undecodable_probe_output_does_not_escape_the_handler(helper, monkeypatch):+ """The probe decodes with errors="replace", so bad bytes cannot raise UnicodeDecodeError."""+ seen = {}++ def fake_run(argv, **kwargs):+ seen.update(kwargs)+ stdout = b"NVIDIA GB\xc5\x31\n".decode("utf-8", kwargs.get("errors", "strict"))+ return subprocess.CompletedProcess(argv, 0, stdout = stdout, stderr = "")++ monkeypatch.setattr(subprocess, "run", fake_run)+ monkeypatch.delenv("CUDA_VISIBLE_DEVICES", raising = False)++ with pytest.raises(NotImplementedError) as excinfo:+ helper(NotImplementedError(_NO_ACCELERATOR))++ assert seen["errors"] == "replace"+ assert "NVIDIA GB" in str(excinfo.value)+++ "kwargs",+ [+ {"raises": FileNotFoundError(2, "No such file or directory", "nvidia-smi")},+ {"raises": subprocess.TimeoutExpired("nvidia-smi", 5)},+ {"returncode": 9},+ {"stdout": " \n"},+ ],+ ids = ["missing", "timeout", "nonzero_exit", "empty_stdout"],+)+def test_probe_failures_return_the_original_error(helper, monkeypatch, kwargs):+ original = NotImplementedError(_NO_ACCELERATOR)+ _smi(monkeypatch, **kwargs)++ with pytest.raises(NotImplementedError) as excinfo:+ _raise_through_handler(helper, original)++ assert excinfo.value is original+ assert excinfo.value.__cause__ is None+ # Do not show the probe failure before the original error.+ assert excinfo.value.__context__ is Nonediff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.pyindex 7c47068ca85..9a48f080c8a 100644--- a/unsloth/_gpu_init.py+++ b/unsloth/_gpu_init.py@@ -172,6 +172,47 @@ del _nvd, _cgroup_pinnedfrom importlib.metadata import version as importlib_versionfrom importlib.metadata import PackageNotFoundError++def _nvidia_smi_gpu_name():+ try:+ smi = subprocess.run(+ ["nvidia-smi", "--query-gpu=name", "--format=csv,noheader"],+ capture_output = True,+ text = True,+ # A UnicodeDecodeError here would replace the original error.+ errors = "replace",+ timeout = 5,+ )+ except (OSError, subprocess.SubprocessError):+ return None+ if smi.returncode != 0 or not smi.stdout.strip():+ return None+ return smi.stdout.strip().splitlines()[0].strip()+++def _reraise_device_type_error_with_gpu_hint(exception):+ mask = os.environ.get("CUDA_VISIBLE_DEVICES")+ # Zoo's generic error lists AMD, so only "ROCm" identifies its ROCm advice.+ # An empty or "-1" mask hides every GPU on purpose.+ if "ROCm" in str(exception) or (mask is not None and "".join(mask.split()) in ("", "-1")):+ raise exception+ gpu_name = _nvidia_smi_gpu_name()+ if gpu_name is None:+ raise exception+ try:+ import torch as _torch+ torch_build = _torch.__version__ # local tag names the build: +cpu, +cu128, +rocm6.4, +xpu+ except Exception:+ torch_build = "unknown"+ mask_note = "" if mask is None else f", CUDA_VISIBLE_DEVICES={mask!r}"+ raise NotImplementedError(+ f"Unsloth: nvidia-smi sees {gpu_name} but torch.cuda.is_available() is False "+ f"(torch {torch_build}{mask_note}). PyTorch likely does not match this "+ f"machine; reinstall it for {sys.executable} per "+ f"https://github.com/unslothai/unsloth#-install"+ ) from exception++# Try importing PyTorch and check versiontry:unsloth_zoo_version = importlib_version("unsloth_zoo")@@ -185,6 +226,8 @@ except PackageNotFoundError:raise ImportError(f"Unsloth: Please install unsloth_zoo via `pip install unsloth_zoo` then retry!")+except NotImplementedError as device_type_error:+ _reraise_device_type_error_with_gpu_hint(device_type_error)except:raisedel PackageNotFoundError, importlib_version@@ -247,12 +290,18 @@ from unsloth_zoo.device_type import (DEVICE_COUNT,ALLOW_PREQUANTIZED_MODELS,)-from .device_type import (- arch_lacks_bf16,- arch_lacks_buffer_ops,- apply_gfx101x_triton_workaround,- hip_visible_archs,-)++# UNSLOTH_ZOO_DISABLE_GPU_INIT makes zoo answer "cpu", so unsloth's own check raises instead.+try:+ from .device_type import (+ arch_lacks_bf16,+ arch_lacks_buffer_ops,+ apply_gfx101x_triton_workaround,+ hip_visible_archs,+ )+except NotImplementedError as device_type_error:+ _reraise_device_type_error_with_gpu_hint(device_type_error)+del _reraise_device_type_error_with_gpu_hint, _nvidia_smi_gpu_namefrom .import_fixes import (fix_transformers5_bare_annotation_configs,