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.

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.py
index 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.metadata
import os
+import platform
import shutil
import socket
import 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 torch
diff --git a/unsloth_cli/tests/test_doctor_gpus.py b/unsloth_cli/tests/test_doctor_gpus.py
index 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.py
new file mode 100644
index 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