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
fix(cli): make `unsloth doctor` MLX-aware on Apple Silicon (#14457)
charlie1cd3674aea92
diff --git a/unsloth_cli/commands/doctor.py b/unsloth_cli/commands/doctor.pyindex 3dc7f322030..7e8a0827366 100644--- a/unsloth_cli/commands/doctor.py+++ b/unsloth_cli/commands/doctor.py@@ -3,7 +3,10 @@"""unsloth doctor --gpus: multi-GPU preflight; torch imported lazily to keep --help fast."""+import importlib+import importlib.metadataimport os+import platformimport shutilimport socketimport subprocess@@ -544,11 +547,166 @@ def doctor(if mcp:typer.echo("")try:- _gpu_checks(timeout)+ if mlx_backend_active():+ _mlx_checks()+ else:+ _gpu_checks(timeout)except typer.Exit as e:raise typer.Exit(max(e.exit_code, code))+def mlx_backend_active() -> bool:+ """True when this machine trains through the MLX backend instead of CUDA / ROCm.++ Apple Silicon runs Unsloth through `unsloth_zoo.mlx`, so the CUDA checks in+ `_gpu_checks` cannot see anything and would report a false failure.+ """+ if os.environ.get("UNSLOTH_FORCE_GPU_PATH") == "1":+ return False+ # Not gated on mlx being importable: a Mac without it should get the MLX+ # verdict's install hint, not the CUDA path's nvidia-smi one.+ try:+ from studio.backend.core.training.training import should_use_mlx_training_backend+ return bool(should_use_mlx_training_backend())+ except Exception:+ # The repo gate is a platform check; keep it if the studio backend can't import.+ return platform.system() == "Darwin" and platform.machine() == "arm64"+++def collect_mlx_info() -> dict:+ """Everything the MLX preflight needs. Never raises."""+ info = {+ "platform": f"{platform.system()} {platform.machine()}",+ "mlx": None,+ "metal": False,+ "device": None,+ "architecture": None,+ "memory_gib": None,+ "working_set_gib": None,+ "zoo": None,+ "zoo_mlx": False,+ "stack_blockers": None,+ "errors": [],+ }+ try:+ info["mlx"] = importlib.metadata.version("mlx")+ except Exception as e:+ info["errors"].append(f"mlx version: {type(e).__name__}: {e}")+ try:+ import mlx.core as mx++ info["metal"] = bool(mx.metal.is_available())+ details = None+ get_info = getattr(mx, "device_info", None)+ if callable(get_info):+ try:+ details = get_info()+ except Exception:+ details = None+ if details is None:+ # mx.metal.device_info() is deprecated; keep it only as a fallback.+ details = mx.metal.device_info()+ details = dict(details or {})+ info["device"] = details.get("device_name")+ info["architecture"] = details.get("architecture")+ memory = details.get("memory_size")+ if isinstance(memory, (int, float)):+ info["memory_gib"] = round(memory / (1024**3), 2)+ working_set = details.get("max_recommended_working_set_size")+ if isinstance(working_set, (int, float)):+ info["working_set_gib"] = round(working_set / (1024**3), 2)+ except Exception as e:+ info["errors"].append(f"mlx: {type(e).__name__}: {e}")+ try:+ info["zoo"] = importlib.metadata.version("unsloth_zoo")+ except Exception as e:+ info["errors"].append(f"unsloth_zoo version: {type(e).__name__}: {e}")+ info["zoo_mlx"] = True+ # Names written out: the risky-loader lint flags import_module on a variable.+ for module, load in (+ ("unsloth_zoo.mlx.trainer", lambda: importlib.import_module("unsloth_zoo.mlx.trainer")),+ ("unsloth_zoo.mlx.loader", lambda: importlib.import_module("unsloth_zoo.mlx.loader")),+ ):+ try:+ load()+ except Exception as e:+ info["errors"].append(f"{module}: {type(e).__name__}: {e}")+ info["zoo_mlx"] = False+ # The gate Unsloth Studio uses for Train/Export: mlx-lm / mlx-vlm imports and minimum versions.+ try:+ from unsloth_cli._inference import ensure_studio_backend_path++ ensure_studio_backend_path(seed_cache_env = False)+ from utils.mlx_repair import mlx_stack_blockers++ info["stack_blockers"] = list(mlx_stack_blockers())+ except Exception as e:+ info["errors"].append(f"mlx stack check: {type(e).__name__}: {e}")+ return info+++def verdict_mlx(info: dict) -> Tuple[bool, List[str]]:+ """(healthy, hints). Pure, so every branch is testable without an Apple Silicon GPU."""+ # `unsloth studio update` installs with the pins that keep Transformers where Unsloth+ # expects it; a plain `pip install mlx-lm` can move it and leave Train/Export disabled.+ if not info.get("mlx"):+ return False, [+ "mlx is not installed. Run `unsloth studio update` to install the Apple Silicon stack."+ ]+ if not info.get("zoo_mlx"):+ return False, [+ "The installed unsloth_zoo has no usable `unsloth_zoo.mlx` backend. Run "+ "`unsloth studio update` to upgrade it."+ ]+ blockers = info.get("stack_blockers")+ if blockers is None:+ # It needs the same modules training does, so a check that cannot run is a failure.+ return False, [+ "The MLX stack check could not run (see the note above). Run "+ "`unsloth studio update` to repair the install."+ ]+ if blockers:+ return False, [+ "The MLX stack cannot train: "+ + "; ".join(blockers)+ + ". Run `unsloth studio update` to repair it."+ ]+ if not info.get("metal"):+ return False, [+ "Metal is not available, so MLX cannot use the GPU. Check that this is a "+ "supported Apple Silicon machine and that macOS is up to date."+ ]+ if not info.get("device"):+ return False, ["MLX did not report a device. The GPU may be unavailable to this process."]+ return True, [+ "Apple Silicon GPU through the MLX backend. Multi-GPU, NCCL and peer-copy "+ "checks do not apply to this backend, so they were skipped."+ ]+++def _mlx_checks():+ info = collect_mlx_info()+ typer.echo("=== Versions ===")+ typer.echo(f"platform {info['platform']}")+ typer.echo("backend mlx")+ typer.echo(f"mlx {info['mlx']}")+ typer.echo(f"unsloth_zoo {info['zoo']}")+ typer.echo(f"Metal {'available' if info['metal'] else 'unavailable'}")+ typer.echo("")+ typer.echo("=== Device ===")+ typer.echo(f" {info['device']} {info['architecture']}")+ typer.echo(f" memory {info['memory_gib']} GiB")+ typer.echo(f" recommended working set {info['working_set_gib']} GiB")+ for error in info["errors"]:+ typer.echo(f"note: {error}")+ healthy, hints = verdict_mlx(info)+ typer.echo("")+ typer.echo(f"=== Verdict: {'OK' if healthy else 'PROBLEMS FOUND'} ===")+ for hint in hints:+ typer.echo(f"- {hint}")+ raise typer.Exit(code = 0 if healthy else 1)++def _gpu_checks(timeout: float):try:import torchdiff --git a/unsloth_cli/tests/test_doctor_gpus.py b/unsloth_cli/tests/test_doctor_gpus.pyindex f788a86b316..1866e739c98 100644--- a/unsloth_cli/tests/test_doctor_gpus.py+++ b/unsloth_cli/tests/test_doctor_gpus.py@@ -200,6 +200,8 @@ def _run_doctor(p2p_disable = None,):monkeypatch.setitem(sys.modules, "torch", torch)+ # These tests cover the CUDA path, so keep the doctor off the MLX path.+ monkeypatch.setattr(doctor_mod, "mlx_backend_active", lambda: False)monkeypatch.setattr(doctor_mod, "_load_pynvml", lambda: None)monkeypatch.setattr(doctor_mod, "driver_version", lambda pynvml = None: "550.1")monkeypatch.setattr(doctor_mod, "p2p_copy_probe", lambda t, n: {(0, 1): "ok", (1, 0): "ok"})@@ -379,6 +381,8 @@ def test_doctor_reports_a_torch_that_fails_to_load(monkeypatch):monkeypatch.delitem(sys.modules, "torch", raising = False)monkeypatch.setattr(builtins, "__import__", broken)+ # This test is about the CUDA path's torch import, so keep the doctor off the MLX path.+ monkeypatch.setattr(doctor_mod, "mlx_backend_active", lambda: False)cli = typer.Typer()cli.command()(doctor_mod.doctor)result = CliRunner().invoke(cli, ["--gpus"])diff --git a/unsloth_cli/tests/test_doctor_mlx.py b/unsloth_cli/tests/test_doctor_mlx.pynew file mode 100644index 00000000000..cb36557a543--- /dev/null+++ b/unsloth_cli/tests/test_doctor_mlx.py@@ -0,0 +1,240 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""`unsloth doctor` on Apple Silicon, where the MLX backend runs and torch sees no GPU.++These tests never need an Apple Silicon host: the verdict is a pure function of the+collected facts, exactly like `verdict` for the CUDA path.+"""++from __future__ import annotations++import sys+import types+from pathlib import Path++_REPO_ROOT = Path(__file__).resolve().parents[2]+if str(_REPO_ROOT) not in sys.path:+ sys.path.insert(0, str(_REPO_ROOT))++import pytest+import typer+from typer.testing import CliRunner++import unsloth_cli+import unsloth_cli.commands.doctor as doctor_mod+++def _healthy_info(**overrides):+ info = {+ "platform": "Darwin arm64",+ "mlx": "0.32.4",+ "metal": True,+ "device": "Apple M5",+ "architecture": "applegpu_g17g",+ "memory_gib": 32.0,+ "working_set_gib": 24.96,+ "zoo": "2026.10.7",+ "zoo_mlx": True,+ "stack_blockers": [],+ "errors": [],+ }+ info.update(overrides)+ return info+++def _fake_studio_gate(monkeypatch, mlx_active):+ """Install a fake studio.backend.core.training.training with the MLX gate."""+ for name in ("studio", "studio.backend", "studio.backend.core", "studio.backend.core.training"):+ module = types.ModuleType(name)+ module.__path__ = []+ monkeypatch.setitem(sys.modules, name, module)+ training = types.ModuleType("studio.backend.core.training.training")+ training.should_use_mlx_training_backend = lambda **kwargs: mlx_active+ monkeypatch.setitem(sys.modules, "studio.backend.core.training.training", training)+++def test_verdict_mlx_healthy_on_apple_silicon():+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info())+ assert healthy is True+ assert hints and "MLX backend" in hints[0]+++def test_verdict_mlx_reports_missing_mlx():+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info(mlx = None))+ assert healthy is False+ assert "mlx is not installed" in hints[0]+++def test_verdict_mlx_reports_old_unsloth_zoo():+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info(zoo_mlx = False))+ assert healthy is False+ assert "unsloth_zoo" in hints[0]+++def test_verdict_mlx_reports_missing_metal():+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info(metal = False))+ assert healthy is False+ assert "Metal is not available" in hints[0]+++def test_verdict_mlx_reports_missing_device():+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info(device = None))+ assert healthy is False+ assert "did not report a device" in hints[0]+++def _broken_studio_gate(monkeypatch):+ _fake_studio_gate(monkeypatch, True)+ # A None entry makes the import raise ImportError, like a studio backend missing a dependency.+ monkeypatch.setitem(sys.modules, "studio.backend.core.training.training", None)+++def test_verdict_mlx_reports_stack_blockers():+ blocker = "mlx_lm does not import (ModuleNotFoundError: No module named 'mlx_lm')"+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info(stack_blockers = [blocker]))+ assert healthy is False+ assert blocker in hints[0]+ assert "unsloth studio update" in hints[0]+++def test_verdict_mlx_fails_when_stack_check_could_not_run():+ healthy, hints = doctor_mod.verdict_mlx(_healthy_info(stack_blockers = None))+ assert healthy is False+ assert "could not run" in hints[0]+++ "overrides",+ [+ {"mlx": None},+ {"zoo_mlx": False},+ {"stack_blockers": ["mlx-vlm 0.4.0 is older than 0.4.4"]},+ {"stack_blockers": None},+ ],+)+def test_verdict_mlx_never_suggests_a_bare_pip_install(overrides):+ # A plain pip resolve can move Transformers and leave Train/Export disabled.+ _, hints = doctor_mod.verdict_mlx(_healthy_info(**overrides))+ assert "unsloth studio update" in hints[0]+ assert "pip install" not in hints[0]+++def _fake_mlx_repair(+ monkeypatch,+ blockers = None,+ broken = False,+):+ import unsloth_cli._inference as inference++ monkeypatch.setattr(inference, "ensure_studio_backend_path", lambda **kwargs: None)+ if broken:+ monkeypatch.setitem(sys.modules, "utils.mlx_repair", None)+ return+ utils = types.ModuleType("utils")+ utils.__path__ = []+ repair = types.ModuleType("utils.mlx_repair")+ repair.mlx_stack_blockers = lambda: list(blockers or [])+ monkeypatch.setitem(sys.modules, "utils", utils)+ monkeypatch.setitem(sys.modules, "utils.mlx_repair", repair)+++def test_collect_mlx_info_reads_the_studio_mlx_gate(monkeypatch):+ _fake_mlx_repair(monkeypatch, blockers = ["mlx_vlm does not import (ImportError: boom)"])+ info = doctor_mod.collect_mlx_info()+ assert info["stack_blockers"] == ["mlx_vlm does not import (ImportError: boom)"]+++def test_collect_mlx_info_notes_when_the_studio_mlx_gate_is_missing(monkeypatch):+ _fake_mlx_repair(monkeypatch, broken = True)+ info = doctor_mod.collect_mlx_info()+ assert info["stack_blockers"] is None+ assert any(e.startswith("mlx stack check:") for e in info["errors"])+++def test_mlx_backend_active_honours_force_gpu_path(monkeypatch):+ _fake_studio_gate(monkeypatch, True)+ monkeypatch.setenv("UNSLOTH_FORCE_GPU_PATH", "1")+ assert doctor_mod.mlx_backend_active() is False+++def test_mlx_backend_active_on_apple_silicon(monkeypatch):+ _fake_studio_gate(monkeypatch, True)+ monkeypatch.delenv("UNSLOTH_FORCE_GPU_PATH", raising = False)+ assert doctor_mod.mlx_backend_active() is True+++def test_mlx_backend_active_without_mlx_installed(monkeypatch):+ # Missing mlx still routes to the MLX checks, whose verdict says how to install it.+ _fake_studio_gate(monkeypatch, True)+ monkeypatch.setitem(sys.modules, "mlx", None)+ monkeypatch.delenv("UNSLOTH_FORCE_GPU_PATH", raising = False)+ assert doctor_mod.mlx_backend_active() is True+++def test_mlx_backend_active_false_off_apple_silicon(monkeypatch):+ _fake_studio_gate(monkeypatch, False)+ monkeypatch.delenv("UNSLOTH_FORCE_GPU_PATH", raising = False)+ assert doctor_mod.mlx_backend_active() is False+++ "system, machine, expected",+ [("Darwin", "arm64", True), ("Darwin", "x86_64", False), ("Linux", "x86_64", False)],+)+def test_mlx_backend_active_falls_back_to_platform(monkeypatch, system, machine, expected):+ _broken_studio_gate(monkeypatch)+ monkeypatch.setattr(doctor_mod.platform, "system", lambda: system)+ monkeypatch.setattr(doctor_mod.platform, "machine", lambda: machine)+ monkeypatch.delenv("UNSLOTH_FORCE_GPU_PATH", raising = False)+ assert doctor_mod.mlx_backend_active() is expected+++def test_collect_mlx_info_needs_every_zoo_mlx_module(monkeypatch):+ def fake_import(name):+ if name == "unsloth_zoo.mlx.trainer":+ raise ImportError("broken trainer")+ return types.ModuleType(name)++ monkeypatch.setattr(doctor_mod.importlib, "import_module", fake_import)+ info = doctor_mod.collect_mlx_info()+ assert info["zoo_mlx"] is False+ assert any("unsloth_zoo.mlx.trainer" in e for e in info["errors"])+++def test_collect_mlx_info_never_raises():+ info = doctor_mod.collect_mlx_info()+ for key in ("platform", "mlx", "metal", "device", "zoo", "zoo_mlx", "errors"):+ assert key in info+++def test_doctor_uses_the_mlx_path_and_exits_zero(monkeypatch):+ monkeypatch.setattr(doctor_mod, "mlx_backend_active", lambda: True)+ monkeypatch.setattr(doctor_mod, "collect_mlx_info", lambda: _healthy_info())+ result = CliRunner().invoke(unsloth_cli.app, ["doctor"])+ assert result.exit_code == 0, result.output+ assert "backend mlx" in result.output+ assert "Apple M5" in result.output+ assert "PROBLEMS FOUND" not in result.output+ assert "nvidia-smi" not in result.output+++def test_doctor_keeps_the_cuda_path_when_mlx_is_inactive(monkeypatch):+ monkeypatch.setattr(doctor_mod, "mlx_backend_active", lambda: False)++ def _fail(timeout):+ raise typer.Exit(code = 1)++ monkeypatch.setattr(doctor_mod, "_gpu_checks", _fail)+ result = CliRunner().invoke(unsloth_cli.app, ["doctor"])+ assert result.exit_code == 1+++def test_doctor_without_mlx_points_at_installing_it(monkeypatch):+ monkeypatch.setattr(doctor_mod, "mlx_backend_active", lambda: True)+ info = _healthy_info(mlx = None, metal = False, device = None, zoo_mlx = False)+ monkeypatch.setattr(doctor_mod, "collect_mlx_info", lambda: info)+ result = CliRunner().invoke(unsloth_cli.app, ["doctor"])+ assert result.exit_code == 1+ assert "mlx is not installed" in result.output+ assert "nvidia-smi" not in result.output