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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""detect_hardware() records why a host is chat-only; Apple Silicon without MLX gives mlx_unavailable."""
from __future__ import annotations
import sys
import types
from pathlib import Path
import pytest
_BACKEND = Path(__file__).resolve().parent.parent
if str(_BACKEND) not in sys.path:
sys.path.insert(0, str(_BACKEND))
import utils.hardware.hardware as hw # noqa: E402
@pytest.fixture(autouse = True)
def _no_torch(monkeypatch):
# Force the non-CUDA/XPU path regardless of the test host's real GPUs.
monkeypatch.setattr(hw, "_has_torch", lambda: False)
# no_torch reads the venv's install manifest, so pin it to keep tests venv-independent.
monkeypatch.setattr(hw, "_installed_without_torch", lambda: False)
monkeypatch.setattr(hw, "_NO_TORCH_SETTLED_EPOCH", None)
monkeypatch.setattr(hw, "_CHAT_ONLY_HINT", None)
# detect_hardware sets these globals directly; restore them so they do not leak.
saved = (hw.DEVICE, hw.CHAT_ONLY, hw.CHAT_ONLY_REASON, hw.IS_ROCM, hw._CPU_TRAINING_REASON)
try:
yield
finally:
hw.DEVICE, hw.CHAT_ONLY, hw.CHAT_ONLY_REASON, hw.IS_ROCM, hw._CPU_TRAINING_REASON = saved
def test_apple_silicon_without_mlx_is_chat_only_with_reason(monkeypatch):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: True)
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: False)
hw.detect_hardware()
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
def test_apple_silicon_with_mlx_enables_training(monkeypatch):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: True)
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: True)
hw.detect_hardware()
assert hw.CHAT_ONLY is False
assert hw.CHAT_ONLY_REASON is None
def test_apple_silicon_with_incomplete_mlx_stack_stays_chat_only(monkeypatch):
# mlx imports but the full mlx/mlx-lm/mlx-vlm stack does not; stay chat-only.
monkeypatch.setattr(hw, "is_apple_silicon", lambda: True)
monkeypatch.setattr(hw, "_has_mlx", lambda: True)
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: False)
assert hw.detect_hardware() == hw.DeviceType.CPU
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
def _no_torch_apple_silicon(monkeypatch, *, mlx_on_disk: bool):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: True)
monkeypatch.setattr(hw, "_installed_without_torch", lambda: True)
monkeypatch.setattr(hw, "_mlx_distribution_installed", lambda: mlx_on_disk)
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: False)
_NVIDIA_CARD = {"vendor": "nvidia", "index": 0, "name": "NVIDIA GeForce RTX 4090"}
_INTEL_IGPU = {"vendor": "intel", "index": 0, "name": "Intel(R) UHD Graphics 770"}
_INTEL_ARC = {"vendor": "intel", "index": 1, "name": "Intel(R) Arc(TM) A770 Graphics"}
def _no_torch_off_mac(
monkeypatch,
*,
devices,
unknown = False,
):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Windows")
monkeypatch.setattr(hw, "_installed_without_torch", lambda: True)
monkeypatch.setattr(
hw,
"get_physical_gpu_inventory",
lambda **_: {
"available": bool(devices),
"devices": devices,
"sources": [],
"unknown": unknown,
},
)
# Pinned: the test host's own torch and install record must not vouch for an Intel iGPU.
monkeypatch.setattr(hw, "_expected_xpu_flavor_was_chosen", lambda: False)
monkeypatch.setattr(hw, "_torch_reports_an_xpu_runtime", lambda: False)
# An emptied mask on the test host (CUDA_VISIBLE_DEVICES="") would hide the card.
for var in (
"CUDA_VISIBLE_DEVICES",
"HIP_VISIBLE_DEVICES",
"ROCR_VISIBLE_DEVICES",
"ZE_AFFINITY_MASK",
):
monkeypatch.delenv(var, raising = False)
def test_a_no_torch_install_off_mac_is_off_by_request_not_missing_a_gpu(monkeypatch):
# A chat-only Windows / Linux install on a GPU host: "needs an NVIDIA or AMD GPU" is wrong.
_no_torch_off_mac(monkeypatch, devices = [_NVIDIA_CARD])
assert hw.detect_hardware() == hw.DeviceType.CPU
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "no_torch"
assert hw.current_chat_only_verdict() == ("no_torch", None)
assert hw.trains_on_cpu("no_torch") is False
@pytest.mark.parametrize("devices", [[], [_INTEL_IGPU]], ids = ["no-gpu", "intel-igpu"])
def test_a_no_torch_install_without_a_trainable_gpu_is_offered_cpu_training(monkeypatch, devices):
# The full install trains here on the CPU backend, so the Desktop offers it; it still brings no export.
_no_torch_off_mac(monkeypatch, devices = devices)
monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CPU)
hw.detect_hardware()
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "no_torch"
assert hw.current_chat_only_verdict() == ("no_torch", None)
assert hw.trains_on_cpu("no_torch") is True
export = hw.export_capability()
assert export["export_unsupported_reason"] == "no_accelerator"
assert "--no-torch" not in export["export_unsupported_message"]
def test_a_no_torch_install_whose_inventory_cannot_answer_keeps_no_torch(monkeypatch):
# A probe that timed out is not "no GPU".
_no_torch_off_mac(monkeypatch, devices = [], unknown = True)
monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CPU)
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "no_torch"
assert hw.trains_on_cpu("no_torch") is False
assert hw.export_capability()["export_unsupported_reason"] == "no_torch"
_AMD_CARD = {"vendor": "amd", "index": 0, "name": "AMD Radeon RX 7900 XTX", "gfx": "gfx1100"}
@pytest.mark.parametrize(
"devices, nodes_closed, hinted",
[
([_AMD_CARD], True, True),
([_AMD_CARD], False, False),
([_AMD_CARD, _NVIDIA_CARD], True, False),
([_AMD_CARD, _INTEL_ARC], True, True),
],
ids = ["amd-closed-nodes", "amd-open-nodes", "amd-closed-beside-nvidia", "amd-closed-beside-arc"],
)
def test_a_no_torch_amd_host_behind_closed_nodes_gets_no_full_install_offer(
monkeypatch, devices, nodes_closed, hinted
):
# The full install would restart into torch_cuda_unavailable: no reinstall opens /dev/kfd (#14067).
import utils.hardware.amd as amd
_no_torch_off_mac(monkeypatch, devices = devices)
monkeypatch.setattr(hw, "_amd_device_can_establish_a_mismatch", lambda _device: True)
monkeypatch.setattr(amd, "amd_closed_nodes_block_the_runtime", lambda **_: nodes_closed)
monkeypatch.setattr(
amd, "amd_node_permission_hint", lambda **_: "Add this user to the render group."
)
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "no_torch"
expected = "Add this user to the render group." if hinted else None
assert hw.chat_only_permission_hint("no_torch", None) == expected
def test_a_torch_install_off_mac_without_an_accelerator_stays_no_gpu(monkeypatch):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Linux")
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "no_gpu"
def test_apple_silicon_no_torch_install_without_mlx_is_off_by_request(monkeypatch):
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = False)
assert hw.detect_hardware() == hw.DeviceType.CPU
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "no_torch"
assert hw.CHAT_ONLY_DETAIL is None
assert hw.trains_on_cpu("no_torch") is False
@pytest.mark.parametrize(
"release, min_python, blocker",
[
("15.1", (3, 10), None),
("13.6.1", (3, 10), "macOS 14 or later"),
# install_python_stack reads it as too old.
("", (3, 10), "macOS 14 or later"),
("14.5", (99, 0), "Python 99.0 or later"),
],
ids = ["macos-15", "macos-13", "macos-unreadable", "python-too-old"],
)
def test_a_no_torch_mac_the_mlx_wheels_skip_gets_no_full_install_offer(
monkeypatch, release, min_python, blocker
):
# The installer skips MLX there. The hint withholds the offer; the reason stays no_torch.
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = False)
monkeypatch.setattr(hw.platform, "mac_ver", lambda: (release, ("", "", ""), ""))
monkeypatch.setattr(hw, "_MLX_MIN_PYTHON", min_python)
monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CPU)
monkeypatch.setattr(hw, "current_chat_only_verdict", lambda: ("no_torch", None))
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "no_torch"
hint = hw.chat_only_permission_hint("no_torch", None)
message = hw.export_capability()["export_unsupported_message"]
if blocker is None:
assert hint is None
assert "--no-torch" in message
else:
assert hint == f"Training on this Mac needs MLX, which requires {blocker}."
assert message == f"Export on this Mac needs MLX, which requires {blocker}."
def test_an_old_macos_hint_is_for_apple_silicon_only(monkeypatch):
# Off Mac, mac_ver() is empty, which reads as too old.
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
monkeypatch.setattr(hw.platform, "mac_ver", lambda: ("", ("", "", ""), ""))
assert hw.chat_only_permission_hint("no_torch", None) is None
def test_apple_silicon_no_torch_install_with_mlx_on_disk_waits_for_the_probe(monkeypatch):
# A hand-installed stack can lose the warm's import race and recover; keep polling.
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = True)
hw.detect_hardware()
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
assert hw.verdict_blames_the_mlx_stack() is True
def test_the_probe_settles_a_no_torch_host_once_the_stack_measures_unusable(monkeypatch):
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = True)
hw.detect_hardware()
assert hw.settle_the_no_torch_verdict(hw.current_detection_epoch()) is True
assert hw.CHAT_ONLY_REASON == "no_torch"
assert hw.CHAT_ONLY_DETAIL is None
assert hw.verdict_blames_the_mlx_stack() is False
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "no_torch"
def test_a_probe_retired_by_a_shutdown_settles_nothing(monkeypatch):
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = True)
hw.detect_hardware()
assert hw.settle_the_no_torch_verdict(hw.current_detection_epoch() - 1) is False
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
assert hw._NO_TORCH_SETTLED_EPOCH is None
def test_a_settled_flag_does_not_outlive_its_lifespan(monkeypatch):
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = True)
monkeypatch.setattr(hw, "_NO_TORCH_SETTLED_EPOCH", hw.current_detection_epoch() - 1)
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
def test_settling_leaves_any_other_verdict_alone(monkeypatch):
for chat_only, reason in ((False, None), (True, "intel_mac"), (True, "no_torch")):
hw.CHAT_ONLY, hw.CHAT_ONLY_REASON = chat_only, reason
assert hw.settle_the_no_torch_verdict(hw.current_detection_epoch()) is False
assert (hw.CHAT_ONLY, hw.CHAT_ONLY_REASON) == (chat_only, reason)
def test_a_declined_settle_does_not_mark_the_epoch(monkeypatch):
# A declined settle must not record the epoch, or a later failure reads as settled.
_no_torch_apple_silicon(monkeypatch, mlx_on_disk = True)
hw.CHAT_ONLY, hw.CHAT_ONLY_REASON = False, None
assert hw.settle_the_no_torch_verdict(hw.current_detection_epoch()) is False
assert hw._NO_TORCH_SETTLED_EPOCH != hw.current_detection_epoch()
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
def test_apple_silicon_no_torch_install_with_usable_mlx_enables_training(monkeypatch):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: True)
monkeypatch.setattr(hw, "_installed_without_torch", lambda: True)
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: True)
hw.detect_hardware()
assert hw.CHAT_ONLY is False
assert hw.CHAT_ONLY_REASON is None
def test_intel_mac_reason(monkeypatch):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
# Pinned: a translated (Rosetta) test Python would otherwise answer "rosetta".
monkeypatch.setattr(hw, "_running_under_rosetta", lambda: False)
monkeypatch.setattr(hw, "_has_mlx", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Darwin")
hw.detect_hardware()
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "intel_mac"
def _fake_sysctl(arm64: str, calls: list):
def run(cmd, *args, **kwargs):
calls.append(cmd)
return types.SimpleNamespace(returncode = 0, stdout = arm64 + "\n", stderr = "")
return run
@pytest.mark.parametrize(
"machine, arm64, expected",
[
("x86_64", "1", "rosetta"),
("x86_64", "0", "intel_mac"),
],
)
def test_rosetta_reason(monkeypatch, machine, arm64, expected):
calls = []
monkeypatch.setattr(hw, "_ROSETTA", None, raising = False)
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
monkeypatch.setattr(hw, "_has_mlx", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Darwin")
monkeypatch.setattr(hw.platform, "machine", lambda: machine)
monkeypatch.setattr(hw.subprocess, "run", _fake_sysctl(arm64, calls))
hw.detect_hardware()
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == expected
assert calls == [["sysctl", "-n", "hw.optional.arm64"]]
def test_rosetta_probe_fails_open_to_intel_mac(monkeypatch):
def boom(*args, **kwargs):
raise OSError("no sysctl")
monkeypatch.setattr(hw, "_ROSETTA", None, raising = False)
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
monkeypatch.setattr(hw, "_has_mlx", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Darwin")
monkeypatch.setattr(hw.platform, "machine", lambda: "x86_64")
monkeypatch.setattr(hw.subprocess, "run", boom)
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "intel_mac"
def test_native_arm64_mac_never_probes_rosetta(monkeypatch):
calls = []
monkeypatch.setattr(hw, "_ROSETTA", None, raising = False)
monkeypatch.setattr(hw, "_has_mlx", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Darwin")
monkeypatch.setattr(hw.platform, "machine", lambda: "arm64")
monkeypatch.setattr(hw.subprocess, "run", _fake_sysctl("1", calls))
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: False, raising = False)
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
assert ["sysctl", "-n", "hw.optional.arm64"] not in calls
def test_cpu_only_non_mac_reason(monkeypatch):
monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
monkeypatch.setattr(hw, "_has_mlx", lambda: False)
monkeypatch.setattr(hw.platform, "system", lambda: "Linux")
hw.detect_hardware()
assert hw.CHAT_ONLY is True
assert hw.CHAT_ONLY_REASON == "no_gpu"
assert hw.trains_on_cpu("no_gpu") is False
@pytest.mark.parametrize("tegra, chosen", [(True, True), (False, False)])
def test_an_automatic_cpu_record_counts_as_chosen_only_on_a_jetson(monkeypatch, tegra, chosen):
# A pre-CUDA-13 Jetson always resolves to cpu, so offering a GPU repair there loops back to cpu (#4856).
from utils import tegra as tegra_mod
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY", raising = False)
monkeypatch.setattr(hw, "_recorded_install_flavor", lambda: ("cpu", False))
monkeypatch.setattr(tegra_mod, "tegra_before_cuda13", lambda: tegra)
assert hw._expected_cpu_flavor_was_chosen() is chosen
# A pinned cpu record stays a choice everywhere.
monkeypatch.setattr(hw, "_recorded_install_flavor", lambda: ("cpu", True))
assert hw._expected_cpu_flavor_was_chosen() is True
@pytest.mark.parametrize(
"var, value",
[
("UNSLOTH_TORCH_INDEX_FAMILY", "cu126"),
("UNSLOTH_TORCH_INDEX_URL", "https://example.test/whl/cu126"),
],
)
def test_a_stated_gpu_index_beats_the_jetson_cpu_record(monkeypatch, var, value):
# An explicit GPU pin wins over the automatic cpu history: the CPU build is reported as before.
from utils import tegra as tegra_mod
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY", raising = False)
monkeypatch.setenv(var, value)
monkeypatch.setattr(hw, "_recorded_install_flavor", lambda: ("cpu", False))
monkeypatch.setattr(tegra_mod, "tegra_before_cuda13", lambda: True)
assert hw._expected_cpu_flavor_was_chosen() is False
@pytest.mark.parametrize(
"release, compatible, expected",
[
("# R36 (release), REVISION: 4.3\n", b"nvidia,tegra234\0", True), # JetPack 6 Orin
("# R35 (release), REVISION: 5.0\n", b"nvidia,tegra194\0", True), # JetPack 5 Xavier
("# R38 (release), REVISION: 2.0\n", b"nvidia,tegra264\0", False), # JetPack 7 Thor
(None, b"nvidia,tegra264\0", False),
(None, b"nvidia,tegra234\0", True),
(None, b"nvidia,grace-hopper\0", False), # not a Jetson
],
)
def test_tegra_before_cuda13_reads_the_l4t_release(
tmp_path, monkeypatch, release, compatible, expected
):
from utils import tegra as tegra_mod
rel = tmp_path / "nv_tegra_release"
if release is not None:
rel.write_text(release)
dt = tmp_path / "compatible"
dt.write_bytes(compatible)
monkeypatch.setattr(tegra_mod, "_TEGRA_RELEASE", str(rel))
monkeypatch.setattr(tegra_mod, "_DEVICE_TREE_COMPATIBLE", str(dt))
tegra_mod.is_tegra.cache_clear()
tegra_mod.tegra_before_cuda13.cache_clear()
try:
assert tegra_mod.tegra_before_cuda13() is expected
finally:
tegra_mod.is_tegra.cache_clear()
tegra_mod.tegra_before_cuda13.cache_clear()