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.

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.py
index 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.py
index 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" = None
diff --git a/tests/conftest.py b/tests/conftest.py
index 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.py
index 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 the
documented 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.py
new file mode 100644
index 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__.py
index 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_hooks
except Exception:
pass
diff --git a/unsloth/_cpu_init.py b/unsloth/_cpu_init.py
new file mode 100644
index 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.py
index 818610ed5ec..e1ee188fc54 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -257,6 +257,12 @@ except:
raise
del 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 torch
except ModuleNotFoundError:
diff --git a/unsloth/chat_templates.py b/unsloth/chat_templates.py
index 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_functions
tokenizer = patch_saving_functions(tokenizer, vision = _processor is not None)
diff --git a/unsloth/device_type.py b/unsloth/device_type.py
index 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.cache
def 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 = None
if 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 0
else:
return 1