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
Train on CPU when no GPU is found, instead of refusing to import (#14717)
Daniel Hane89baf3d03c4
diff --git a/studio/backend/main.py b/studio/backend/main.pyindex 9008075e9a6..28b56c265ae 100644--- a/studio/backend/main.py+++ b/studio/backend/main.py@@ -336,6 +336,9 @@ del _guard_dataset_media# The studio bundles unsloth_zoo; declare unsloth present (as `import unsloth` does) so its# lazy submodule imports and the DiffusionGemma runner don't trip the install guard.os.environ.setdefault("UNSLOTH_IS_PRESENT", "1")+# Studio decides training / export / chat-only from its own hardware detection, so keep+# `import unsloth` refusing on a GPU-less host here instead of loading the CPU training backend.+os.environ.setdefault("UNSLOTH_DISABLE_CPU_FALLBACK", "1")# Same rule as unsloth/__init__.py, reached through Studio's own copy because this parent must# not import unsloth: that runs unsloth/__init__.py, whose GPU branch pulls torch, Triton,diff --git a/studio/backend/run.py b/studio/backend/run.pyindex 5aabc633e9c..a4289e6e936 100644--- a/studio/backend/run.py+++ b/studio/backend/run.py@@ -1377,6 +1377,9 @@ if _STUDIO_ROOT_RESOLVED != _LEGACY_STUDIO_ROOT or _MASTER_ROOT is not None:# The studio bundles unsloth_zoo; declare unsloth present (as `import unsloth` does) so its lazy# submodule imports and the DiffusionGemma runner never trip the install guard on a clean install.os.environ.setdefault("UNSLOTH_IS_PRESENT", "1")+# Studio decides training / export / chat-only from its own hardware detection, so keep+# `import unsloth` refusing on a GPU-less host here instead of loading the CPU training backend.+os.environ.setdefault("UNSLOTH_DISABLE_CPU_FALLBACK", "1")_OWN_PID_FILE: "Path | None" = Nonediff --git a/tests/conftest.py b/tests/conftest.pyindex 54fd1fcdf27..b72402cd9b5 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -26,6 +26,11 @@ for _up in _iso.parents:# Loaded by path: tests/_shared is put on sys.path only below.import os as _os # noqa: E402+# The suite predates the CPU training backend: a GPU-less runner must keep refusing `import unsloth`+# (so GPU-path tests skip there, as before) and stubbed-torch tests must not inherit this host's+# CPU-fallback answer. tests/test_cpu_backend_init.py removes it to exercise the backend itself.+_os.environ.setdefault("UNSLOTH_DISABLE_CPU_FALLBACK", "1")+_share_path = _iso.parent / "_shared" / "xdist_cpu_share.py"if _share_path.is_file():_spec = _ilu.spec_from_file_location("xdist_cpu_share", _share_path)diff --git a/tests/test_allow_cpu_import_driverless.py b/tests/test_allow_cpu_import_driverless.pyindex 97a4060e9ea..595d0d508a4 100644--- a/tests/test_allow_cpu_import_driverless.py+++ b/tests/test_allow_cpu_import_driverless.py@@ -110,9 +110,10 @@ def _under(path, directory):def test_the_devices_really_are_hidden_and_the_variable_is_what_opens_the_import():"""Without the variable the import must still refuse, and refuse with thedocumented message. If this ever passes, the host has a visible GPU and every- other case in this file is vacuous."""+ other case in this file is vacuous. A driverless host now gets the CPU training backend, so+ opt out of it to reach the refusal."""_needs_the_cuda_branch()- out = _run("import unsloth")+ out = _run("import unsloth", UNSLOTH_DISABLE_CPU_FALLBACK = "1")assert out.returncode != 0, "a device is visible; this file proves nothing here"assert "You need a GPU" in out.stderr, out.stderr[-3000:]diff --git a/tests/test_cpu_backend_init.py b/tests/test_cpu_backend_init.pynew file mode 100644index 00000000000..24a8c5c7966--- /dev/null+++ b/tests/test_cpu_backend_init.py@@ -0,0 +1,266 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.+"""CPU training fallback: `import unsloth` with no accelerator loads the CPU backend; a GPU host never does."""++from __future__ import annotations++import ast+import json+import os+import subprocess+import sys+from pathlib import Path++import pytest++_ROOT = Path(__file__).resolve().parents[1]+_INIT = _ROOT / "unsloth" / "__init__.py"+_GPU_INIT = _ROOT / "unsloth" / "_gpu_init.py"++# Modules the CPU backend must never load: GPU kernels, compiled model patches, the GPU bootstrap.+_GPU_ONLY = (+ "unsloth._gpu_init",+ "unsloth.models",+ "unsloth.kernels",+ "unsloth_zoo.temporary_patches",+ "unsloth_zoo.compiler",+ "unsloth_zoo.fused_losses",+ "unsloth_zoo.gradient_checkpointing",+)+_CPU_ONLY = ("unsloth._cpu_init", "unsloth_zoo.cpu")++_PROBE = r"""+import json, sys+import unsloth+if unsloth.DEVICE_TYPE == "cpu":+ from unsloth.trainer import UnslothTrainer+mods = sorted(sys.modules)+print("PROBE " + json.dumps({+ "device_type": getattr(unsloth, "DEVICE_TYPE", None),+ "fast": [c.__name__ for c in unsloth.FastLanguageModel.__mro__],+ "modules": mods,+ "trainer_file": getattr(sys.modules.get("unsloth.trainer"), "__file__", None),+}))+"""+++def _import_unsloth(env_update):+ env = {+ k: v+ for k, v in os.environ.items()+ if k not in ("UNSLOTH_ALLOW_CPU", "UNSLOTH_FORCE_CPU", "UNSLOTH_DISABLE_CPU_FALLBACK")+ }+ env.update(env_update)+ env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(_ROOT), env.get("PYTHONPATH")]))+ out = subprocess.run(+ [sys.executable, "-c", _PROBE],+ capture_output = True,+ text = True,+ env = env,+ timeout = 1200,+ )+ for line in out.stdout.splitlines():+ if line.startswith("PROBE "):+ return json.loads(line[6:]), out+ return None, out+++def _loaded(modules, prefixes):+ return [m for m in modules if any(m == p or m.startswith(p + ".") for p in prefixes)]+++def _zoo_has_cpu_backend():+ import importlib.util+ spec = importlib.util.find_spec(+ "unsloth_zoo"+ ) # locates only; the package __init__ does not run+ return bool(spec and spec.submodule_search_locations) and any(+ (Path(p) / "cpu" / "loader.py").is_file() for p in spec.submodule_search_locations+ )++[email protected](not _zoo_has_cpu_backend(), reason = "unsloth_zoo without the CPU backend")+def test_no_accelerator_loads_the_cpu_backend():+ torch = pytest.importorskip("torch")+ for name in ("xpu", "npu"):+ try:+ if getattr(torch, name).is_available():+ pytest.skip(f"{name} host: hiding CUDA leaves that accelerator selected")+ except Exception:+ pass+ # UNSLOTH_FORCE_GPU_PATH keeps an Apple Silicon host off the MLX backend.+ probe, out = _import_unsloth({"CUDA_VISIBLE_DEVICES": "", "UNSLOTH_FORCE_GPU_PATH": "1"})+ if probe is None and "ROCm" in out.stderr:+ pytest.skip("ROCm runtime host without a ROCm torch keeps its install hint")+ assert probe is not None, out.stderr[-3000:]+ assert probe["device_type"] == "cpu"+ assert "FastCPUModel" in probe["fast"]+ assert _loaded(probe["modules"], _GPU_ONLY) == []+ assert _loaded(probe["modules"], _CPU_ONLY)+ assert (+ probe["trainer_file"] is None+ ), "unsloth.trainer must be the CPU shim, not unsloth/trainer.py"+++def test_gpu_host_never_loads_the_cpu_backend():+ torch = pytest.importorskip("torch")+ if not torch.cuda.is_available():+ pytest.skip("needs a GPU")+ probe, out = _import_unsloth({})+ assert probe is not None, out.stderr[-3000:]+ assert probe["device_type"] in ("cuda", "hip")+ assert _loaded(probe["modules"], _CPU_ONLY) == []+++def test_cpu_handoff_sits_before_any_gpu_setup():+ """_gpu_init raises the handoff right after `import unsloth_zoo` and before `import torch`."""+ tree = ast.parse(_GPU_INIT.read_text(encoding = "utf-8"))+ raises = [+ n+ for n in ast.walk(tree)+ if isinstance(n, ast.Raise)+ and isinstance(n.exc, ast.Call)+ and getattr(n.exc.func, "id", None) == "_CPUBackendSelected"+ ]+ assert len(raises) == 1+ zoo_import = min(+ n.lineno+ for n in ast.walk(tree)+ if isinstance(n, ast.Import) and any(a.name == "unsloth_zoo" for a in n.names)+ )+ first_torch = min(+ n.lineno+ for n in tree.body+ if isinstance(n, ast.Try)+ and any(+ isinstance(s, ast.Import) and any(a.name == "torch" for a in s.names) for s in n.body+ )+ )+ assert zoo_import < raises[0].lineno < first_torch+++def test_cpu_init_only_reached_from_the_handoff():+ tree = ast.parse(_INIT.read_text(encoding = "utf-8"))+ handlers = [+ n+ for n in ast.walk(tree)+ if isinstance(n, ast.ExceptHandler) and getattr(n.type, "id", None) == "_CPUBackendSelected"+ ]+ assert len(handlers) == 1, "unsloth/__init__.py must catch _CPUBackendSelected exactly once"+ inside = [+ n+ for n in ast.walk(handlers[0])+ if isinstance(n, ast.ImportFrom) and n.module == "_cpu_init" and n.level == 1+ ]+ everywhere = [+ n+ for n in ast.walk(tree)+ if isinstance(n, ast.ImportFrom) and n.module == "_cpu_init" and n.level == 1+ ]+ assert inside and len(inside) == len(everywhere), "_cpu_init must only load from the handoff"+++def test_cpu_backend_query_only_reads_an_already_imported_zoo(monkeypatch):+ """unsloth.device_type asks zoo about the CPU backend without importing it: an import from there+ reorders zoo's own initialisation under harnesses that preload device_type (CUDA spoof in the+ test suite), which sent Qwen3.5's linear attention down the Triton path on CPU runners."""+ import builtins+ import types++ src = (_ROOT / "unsloth" / "device_type.py").read_text(encoding = "utf-8")+ tree = ast.parse(src)+ fn = next(+ n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name == "_zoo_cpu_backend"+ )+ namespace = {}+ exec(compile(ast.Module(body = [fn], type_ignores = []), "device_type.py", "exec"), namespace)+ query = namespace["_zoo_cpu_backend"]+ imports = []+ real_import = builtins.__import__+ monkeypatch.setattr(+ builtins,+ "__import__",+ lambda name, *a, **k: imports.append(name) or real_import(name, *a, **k),+ )+ monkeypatch.delitem(sys.modules, "unsloth_zoo.device_type", raising = False)+ assert query("cpu_backend_forced") is False+ assert not any(name.startswith("unsloth_zoo") for name in imports)+ monkeypatch.setitem(+ sys.modules,+ "unsloth_zoo.device_type",+ types.SimpleNamespace(cpu_backend_forced = lambda: True),+ )+ assert query("cpu_backend_forced") is True+ assert query("cpu_backend_allowed") is False # an older zoo without the function++[email protected]("entry", ["studio/backend/main.py", "studio/backend/run.py"])+def test_studio_keeps_training_off_on_cpu_only_hosts(entry):+ """Studio / Desktop stay chat-only without a GPU: both entry points opt out of the CPU training backend+ at module level, before anything can import unsloth, and spawned training workers inherit it."""+ tree = ast.parse((_ROOT / entry).read_text(encoding = "utf-8"))+ opt_out = first_unsloth_import = None+ for node in tree.body:+ line = ast.unparse(node)+ if opt_out is None and "UNSLOTH_DISABLE_CPU_FALLBACK" in line and "'1'" in line:+ opt_out = node.lineno+ if first_unsloth_import is None and isinstance(node, (ast.Import, ast.ImportFrom)):+ names = (+ [a.name for a in node.names]+ if isinstance(node, ast.Import)+ else [node.module or ""]+ )+ if any(n == "unsloth" or n.startswith("unsloth.") for n in names):+ first_unsloth_import = node.lineno+ assert opt_out is not None, f"{entry} no longer sets UNSLOTH_DISABLE_CPU_FALLBACK=1"+ assert first_unsloth_import is None or opt_out < first_unsloth_import+++_NO_TRL_PROBE = r"""+import importlib.abc, json, sys++class _NoTRL(importlib.abc.MetaPathFinder):+ def find_spec(self, name, path = None, target = None):+ if name == "trl" or name.startswith("trl."):+ raise ImportError("No module named 'trl'")++sys.meta_path.insert(0, _NoTRL())+import unsloth+from unsloth import UnslothTrainingArguments+try:+ UnslothTrainingArguments(output_dir = "x")+ error = None+except ImportError as e:+ error = str(e)+print("PROBE " + json.dumps({"device_type": unsloth.DEVICE_TYPE, "error": error}))+"""++[email protected](not _zoo_has_cpu_backend(), reason = "unsloth_zoo without the CPU backend")+def test_cpu_backend_imports_without_trl():+ """trl is not a default dependency on Apple Silicon: `import unsloth` on the CPU backend still works,+ and only building a trainer asks for it."""+ pytest.importorskip("torch")+ env = {+ k: v+ for k, v in os.environ.items()+ if k not in ("UNSLOTH_ALLOW_CPU", "UNSLOTH_DISABLE_CPU_FALLBACK")+ }+ env.update(+ {+ "UNSLOTH_FORCE_CPU": "1",+ # Keeps an Apple Silicon host off the MLX backend, as in the test above.+ "UNSLOTH_FORCE_GPU_PATH": "1",+ "PYTHONPATH": os.pathsep.join(filter(None, [str(_ROOT), env.get("PYTHONPATH")])),+ }+ )+ out = subprocess.run(+ [sys.executable, "-c", _NO_TRL_PROBE], capture_output = True, text = True, env = env, timeout = 1200+ )+ probe = next(+ (json.loads(line[6:]) for line in out.stdout.splitlines() if line.startswith("PROBE ")),+ None,+ )+ assert probe is not None, out.stderr[-3000:]+ assert probe["device_type"] == "cpu"+ assert probe["error"] and "pip install trl" in probe["error"]diff --git a/unsloth/__init__.py b/unsloth/__init__.pyindex a1577b2fc92..4e2d54a8052 100644--- a/unsloth/__init__.py+++ b/unsloth/__init__.py@@ -140,6 +140,10 @@ class _UnslothDeviceStats:self.multi_processor_count = 0+class _CPUBackendSelected(Exception):+ """Raised by _gpu_init when unsloth_zoo found no accelerator and selected the CPU backend."""++def _bytes_to_gb(value):"""Convert byte counts to GiB rounded"""return round(float(value or 0) / 1024 / 1024 / 1024, 3)@@ -1680,16 +1684,25 @@ if _IS_MLX:_install_mlx_unsloth_trainer_shim()else:- # GPU path: load everything from _gpu_init- from ._gpu_init import *- from ._gpu_init import __version__+ try:+ # GPU path: load everything from _gpu_init+ from ._gpu_init import *+ from ._gpu_init import __version__+ _IS_CPU_BACKEND = False+ except _CPUBackendSelected:+ _IS_CPU_BACKEND = True+ _sys_mod = __import__("sys").modules+ _sys_mod.pop(f"{__name__}._gpu_init", None)+ del _sys_mod+ from ._cpu_init import * # __all__ carries __version__# Raw `Accelerator.prepare()` loops never reach the Trainer init that also installs these, and# `Accelerator(fsdp_plugin = ...)` leaves no launcher env to gate on. Inert unless FSDP2 wraps.try:- from .models.fsdp2 import install_fsdp2_hooks as _install_fsdp2_hooks- _install_fsdp2_hooks()- del _install_fsdp2_hooks+ if not _IS_CPU_BACKEND:+ from .models.fsdp2 import install_fsdp2_hooks as _install_fsdp2_hooks+ _install_fsdp2_hooks()+ del _install_fsdp2_hooksexcept Exception:passdiff --git a/unsloth/_cpu_init.py b/unsloth/_cpu_init.pynew file mode 100644index 00000000000..dc72fb420f6--- /dev/null+++ b/unsloth/_cpu_init.py@@ -0,0 +1,215 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.++# CPU backend: reached only when unsloth_zoo found no accelerator (or UNSLOTH_FORCE_CPU=1). Like the+# MLX branch it never imports the GPU model / kernel stack: stock transformers + PEFT + TRL, with+# unsloth_zoo.cpu choosing dtype, 4-bit, chunked cross entropy and trainer defaults.++import os+import torch++from ._version import __version__+from unsloth_zoo.cpu import (+ FastCPUModel,+ cpu_capabilities,+ cpu_bf16_supported,+ install_cpu_training_defaults,+)++DEVICE_TYPE = "cpu"+DEVICE_TYPE_TORCH = "cpu"+DEVICE_COUNT = 0++install_cpu_training_defaults()++print(+ f"Unsloth {__version__}: no GPU found, training on CPU ({__import__('platform').machine()}, "+ f"{torch.get_num_threads()} threads, bfloat16 = {cpu_bf16_supported()}). CPU training is much "+ f"slower than GPU training; supported: text LoRA / full finetuning with SFTTrainer. "+ f"Set UNSLOTH_DISABLE_CPU_FALLBACK=1 to raise instead."+)+++class FastLanguageModel(FastCPUModel):+ pass+++FastModel = FastLanguageModel+FastTextModel = FastLanguageModel+++class FastVisionModel(FastLanguageModel):+ @staticmethod+ def from_pretrained(*args, **kwargs):+ raise NotImplementedError(+ "Unsloth: vision / audio models are not supported on the CPU backend yet."+ )+++def is_bfloat16_supported(including_emulation = False):+ return True if including_emulation else cpu_bf16_supported()+++def is_vLLM_available():+ return False+++def get_chat_template(*args, **kwargs):+ from .chat_templates import get_chat_template as _get_chat_template+ return _get_chat_template(*args, **kwargs)+++def apply_chat_template(*args, **kwargs):+ from .chat_templates import apply_chat_template as _apply_chat_template+ return _apply_chat_template(*args, **kwargs)+++def standardize_data_formats(*args, **kwargs):+ from unsloth_zoo.dataset_utils import standardize_data_formats as _standardize_data_formats+ return _standardize_data_formats(*args, **kwargs)+++def standardize_sharegpt(*args, **kwargs):+ return standardize_data_formats(*args, **kwargs)+++def train_on_responses_only(*args, **kwargs):+ from .chat_templates import train_on_responses_only as _train_on_responses_only+ if _train_on_responses_only is None:+ from unsloth_zoo.dataset_utils import train_on_responses_only as _train_on_responses_only+ return _train_on_responses_only(*args, **kwargs)+++try:+ from trl import SFTConfig as _SFTConfig, SFTTrainer as _SFTTrainer+except ImportError:+ # trl is not a default dependency on Apple Silicon: importing unsloth must still work there.+ class _SFTConfig:+ def __init__(self, *args, **kwargs):+ raise ImportError("Unsloth: CPU training needs TRL. Install it with `pip install trl`.")++ _SFTTrainer = _SFTConfig+++class UnslothTrainingArguments(_SFTConfig):+ def __init__(+ self,+ embedding_learning_rate = None,+ q_galore_config = None,+ *args,+ loraplus_lr_ratio = None,+ **kwargs,+ ):+ # Same positional order as the GPU class; Q-GaLore and LoRA+ are GPU-only, so they must stay unset.+ if q_galore_config is not None or loraplus_lr_ratio is not None:+ raise NotImplementedError(+ "Unsloth: q_galore_config / loraplus_lr_ratio are not supported on the CPU backend."+ )+ self.embedding_learning_rate = embedding_learning_rate+ super().__init__(*args, **kwargs)+++class UnslothTrainer(_SFTTrainer):+ def create_optimizer(self, *args, **kwargs):+ embedding_lr = getattr(self.args, "embedding_learning_rate", None)+ if embedding_lr is None or self.optimizer is not None:+ return super().create_optimizer(*args, **kwargs)+ # Same split as the GPU UnslothTrainer: trained embed_tokens / lm_head copies get their own lr.+ model = self.model+ decay = set(self.get_decay_parameter_names(model))+ custom = getattr(self, "optimizer_cls_and_kwargs", None)+ if custom is not None:+ optimizer_cls, optimizer_kwargs = custom[0], dict(custom[1])+ else:+ optimizer_cls, optimizer_kwargs = _SFTTrainer.get_optimizer_cls_and_kwargs(+ self.args, model+ )+ if any(key in optimizer_kwargs for key in ("params", "model", "optimizer_dict")):+ raise NotImplementedError(+ f"Unsloth: embedding_learning_rate cannot be combined with optim = {self.args.optim!r} on CPU."+ )+ embedding_ids = set()+ for getter in ("get_input_embeddings", "get_output_embeddings"):+ module = getattr(model, getter, lambda: None)()+ if getattr(module, "weight", None) is not None:+ embedding_ids.add(id(module.weight))+ # Older transformers models can return None from get_output_embeddings yet still own an lm_head.+ for owner in (model, getattr(getattr(model, "base_model", None), "model", None)):+ weight = getattr(getattr(owner, "lm_head", None), "weight", None)+ if weight is not None:+ embedding_ids.add(id(weight))+ groups = {}+ for name, param in model.named_parameters():+ if not param.requires_grad:+ continue+ is_embedding = (+ name.endswith("modules_to_save.default.weight") or id(param) in embedding_ids+ )+ key = (is_embedding, name in decay)+ groups.setdefault(key, []).append(param)+ self.optimizer = optimizer_cls(+ [+ {+ "params": params,+ "lr": embedding_lr if is_embedding else self.args.learning_rate,+ "weight_decay": self.args.weight_decay if decays else 0.0,+ }+ # Same order as the GPU trainer's groups, so its checkpoints resume here.+ for (is_embedding, decays), params in sorted(+ groups.items(), key = lambda kv: (kv[0][0], not kv[0][1])+ )+ ],+ **optimizer_kwargs,+ )+ return self.optimizer+++class UnslothVisionDataCollator:+ def __init__(self, *args, **kwargs):+ raise NotImplementedError(+ "Unsloth: vision / audio models are not supported on the CPU backend yet."+ )+++def _install_cpu_trainer_module():+ # `from unsloth.trainer import ...` would otherwise load unsloth/trainer.py and the GPU kernel stack.+ import sys+ import types+ import importlib.machinery++ module_name = __name__.rsplit(".", 1)[0] + ".trainer"+ trainer = types.ModuleType(module_name)+ trainer.__package__ = module_name.rsplit(".", 1)[0]+ trainer.__spec__ = importlib.machinery.ModuleSpec(module_name, loader = None)+ trainer.UnslothTrainer = UnslothTrainer+ trainer.UnslothTrainingArguments = UnslothTrainingArguments+ trainer.UnslothVisionDataCollator = UnslothVisionDataCollator+ sys.modules[module_name] = trainer+ package = sys.modules.get(trainer.__package__)+ if package is not None:+ setattr(package, "trainer", trainer)+++_install_cpu_trainer_module()+del _install_cpu_trainer_module++__all__ = [+ "FastLanguageModel",+ "FastModel",+ "FastTextModel",+ "FastVisionModel",+ "is_bfloat16_supported",+ "is_vLLM_available",+ "get_chat_template",+ "apply_chat_template",+ "standardize_data_formats",+ "standardize_sharegpt",+ "train_on_responses_only",+ "UnslothTrainer",+ "UnslothTrainingArguments",+ "UnslothVisionDataCollator",+ "DEVICE_TYPE",+ "DEVICE_TYPE_TORCH",+ "DEVICE_COUNT",+ "__version__",+]diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.pyindex 818610ed5ec..e1ee188fc54 100644--- a/unsloth/_gpu_init.py+++ b/unsloth/_gpu_init.py@@ -257,6 +257,12 @@ except:raisedel PackageNotFoundError, importlib_version+# No accelerator at all: zoo chose its CPU backend and skipped every GPU patch. Stop here, before+# any CUDA/Triton work, and let __init__ load the CPU backend instead (as the MLX branch does).+if unsloth_zoo.__dict__.get("_IS_CPU_BACKEND", False):+ from . import _CPUBackendSelected+ raise _CPUBackendSelected()+try:import torchexcept ModuleNotFoundError:diff --git a/unsloth/chat_templates.py b/unsloth/chat_templates.pyindex c430e85e515..3c57b259219 100644--- a/unsloth/chat_templates.py+++ b/unsloth/chat_templates.py@@ -2466,9 +2466,12 @@ def get_chat_template():assert(type(map_eos_token) is bool)import sys- is_mlx_backend = getattr(sys.modules.get("unsloth"), "DEVICE_TYPE", None) == "mlx"+ _backend = getattr(sys.modules.get("unsloth"), "DEVICE_TYPE", None)+ is_mlx_backend = _backend == "mlx"+ # The CPU backend, like MLX, never loads the GPU model stack that models._utils / save pull in.+ is_light_backend = _backend in ("mlx", "cpu")if use_zoo_tokenizer_patch is None:- use_zoo_tokenizer_patch = is_mlx_backend+ use_zoo_tokenizer_patch = is_light_backend# mlx-lm's TokenizerWrapper._tokenizer is the HF tokenizer, not the Rust backend the vocab-edit# paths below need; unwrap here, re-wrap before return.@@ -2729,7 +2732,7 @@ def get_chat_template(setattr(_processor, _token + "_id", getattr(tokenizer, _token + "_id"))tokenizer = _processor- if patch_saving and not is_mlx_backend:+ if patch_saving and not is_light_backend:from .save import patch_saving_functionstokenizer = patch_saving_functions(tokenizer, vision = _processor is not None)diff --git a/unsloth/device_type.py b/unsloth/device_type.pyindex 38940bcfa52..6a60f96183d 100644--- a/unsloth/device_type.py+++ b/unsloth/device_type.py@@ -83,6 +83,20 @@ def npu_is_available():return False+def _zoo_cpu_backend(name):+ """The CPU-fallback rules live in unsloth_zoo.device_type; an older zoo has none.++ Only consulted once `import unsloth` has imported unsloth_zoo (as _gpu_init does before this+ module). Importing it from here would pull the whole zoo package into anything that loads+ unsloth.device_type on its own (Studio's hardware probes, the test harness's preload).+ """+ import sys++ _zoo_device_type = sys.modules.get("unsloth_zoo.device_type")+ check = getattr(_zoo_device_type, name, None)+ return bool(check()) if callable(check) else False++@functools.cachedef get_device_type():# MLX first: torch is never imported on the MLX runtime, so claiming "cuda" here would NameError in@@ -93,6 +107,8 @@ def get_device_type():# Read once per process (function is cached).if os.environ.get("UNSLOTH_ALLOW_CPU", "0") == "1":return "cuda"+ if _zoo_cpu_backend("cpu_backend_forced"):+ return "cpu"if hasattr(torch, "cuda") and torch.cuda.is_available():if is_hip():return "hip"@@ -105,6 +121,8 @@ def get_device_type():accelerator = Noneif hasattr(torch, "accelerator"):if not torch.accelerator.is_available():+ if _zoo_cpu_backend("cpu_backend_allowed"):+ return "cpu"raise NotImplementedError("Unsloth cannot find any torch accelerator? You need a GPU.")accelerator = str(torch.accelerator.current_accelerator())# Listed, not returned: torch.npu is unusable here, so it only defers the AttributeError.@@ -114,6 +132,8 @@ def get_device_type():f"But `torch.accelerator.current_accelerator()` works with it being = `{accelerator}`\n"f"Please reinstall torch - it's most likely broken :(")+ if accelerator is None and _zoo_cpu_backend("cpu_backend_allowed"):+ return "cpu"# torch.accelerator only exists from torch 2.6, so below that there is no name.raise NotImplementedError(f"Unsloth does not currently work on {accelerator}."@@ -139,6 +159,8 @@ def get_device_count():return torch.xpu.device_count()elif DEVICE_TYPE == "npu":return torch.npu.device_count()+ elif DEVICE_TYPE == "cpu":+ return 0else:return 1