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.

Legacy CLI: accept true/false spellings for --use_gradient_checkpointing (#17115)

Vineeth Sai Varikuntlaa19090400b56
diff --git a/unsloth-cli.py b/unsloth-cli.py
index 7d03c19df53..75bd8ec9bd7 100644
--- a/unsloth-cli.py
+++ b/unsloth-cli.py
@@ -32,6 +32,20 @@ def _normalize_dtype(dtype):
return dtype
+def _normalize_gradient_checkpointing(value):
+ # get_peft_model asserts the value is True, False or "unsloth"; checked before the model loads.
+ text = str(value).strip().lower()
+ if text in {"", "unsloth", "mlx"}:
+ return "unsloth"
+ if text in {"true", "1", "yes"}:
+ return True
+ if text in {"false", "0", "no", "none", "off"}:
+ return False
+ raise ValueError(
+ f"Unsloth: --use_gradient_checkpointing must be unsloth, true or false, got {value!r}."
+ )
+
+
def _prepare_device_map(is_mlx):
if is_mlx:
return None, False
@@ -212,6 +226,7 @@ def _build_sft_config(SFTConfig, args, is_mlx, bf16_supported):
def run(args):
+ use_gradient_checkpointing = _normalize_gradient_checkpointing(args.use_gradient_checkpointing)
import unsloth
from unsloth import FastLanguageModel
from datasets import load_dataset
@@ -253,7 +268,7 @@ def run(args):
lora_alpha = args.lora_alpha,
lora_dropout = args.lora_dropout,
bias = args.bias,
- use_gradient_checkpointing = args.use_gradient_checkpointing,
+ use_gradient_checkpointing = use_gradient_checkpointing,
random_state = args.random_state,
use_rslora = args.use_rslora,
loftq_config = args.loftq_config,
@@ -387,7 +402,7 @@ if __name__ == "__main__":
"--use_gradient_checkpointing",
type = str,
default = "unsloth",
- help = "Use gradient checkpointing",
+ help = "Gradient checkpointing: unsloth, true or false",
)
lora_group.add_argument(
"--random_state",
diff --git a/unsloth_cli/tests/test_legacy_cli_dtype.py b/unsloth_cli/tests/test_legacy_cli_dtype.py
index 33cdd5d79fd..343ae607004 100644
--- a/unsloth_cli/tests/test_legacy_cli_dtype.py
+++ b/unsloth_cli/tests/test_legacy_cli_dtype.py
@@ -70,6 +70,7 @@ def test_dtype_reaches_the_loader_as_none_or_unchanged(monkeypatch, spelling, ex
dtype = spelling,
load_in_4bit = True,
use_dora = False,
+ use_gradient_checkpointing = "unsloth",
)
with pytest.raises(_Stop):
legacy_cli.run(args)
diff --git a/unsloth_cli/tests/test_legacy_cli_gradient_checkpointing.py b/unsloth_cli/tests/test_legacy_cli_gradient_checkpointing.py
new file mode 100644
index 00000000000..c3c057d3da3
--- /dev/null
+++ b/unsloth_cli/tests/test_legacy_cli_gradient_checkpointing.py
@@ -0,0 +1,118 @@
+# 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-cli.py reads --use_gradient_checkpointing as a string, but get_peft_model wants True, False or "unsloth"."""
+
+import importlib.util
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+class _Stop(Exception):
+ pass
+
+
+def _load_legacy_cli():
+ spec = importlib.util.spec_from_file_location(
+ "unsloth_legacy_cli_gradient_checkpointing", _REPO_ROOT / "unsloth-cli.py"
+ )
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _module(name, **attrs):
+ module = types.ModuleType(name)
+ module.__dict__.update(attrs)
+ return module
+
+
+def _setup(monkeypatch, spelling):
+ seen = {}
+
+ class FastLanguageModel:
+ @staticmethod
+ def from_pretrained(**kwargs):
+ seen["loaded"] = True
+ return object(), types.SimpleNamespace(eos_token = "</s>")
+
+ @staticmethod
+ def get_peft_model(model, **kwargs):
+ seen.update(kwargs)
+ raise _Stop
+
+ for name, module in {
+ "unsloth": _module(
+ "unsloth",
+ FastLanguageModel = FastLanguageModel,
+ is_bfloat16_supported = lambda: False,
+ RawTextDataLoader = object,
+ ),
+ "unsloth.models": _module("unsloth.models"),
+ "unsloth.models.loader_utils": _module(
+ "unsloth.models.loader_utils", prepare_device_map = lambda: (None, False)
+ ),
+ "datasets": _module("datasets", load_dataset = None),
+ "transformers": _module("transformers"),
+ "transformers.utils": _module("transformers.utils", strtobool = None),
+ "trl": _module("trl", SFTTrainer = None, SFTConfig = None),
+ }.items():
+ monkeypatch.setitem(sys.modules, name, module)
+
+ args = types.SimpleNamespace(
+ model_name = "unsloth/llama-3-8b",
+ max_seq_length = 2048,
+ dtype = None,
+ load_in_4bit = True,
+ use_dora = False,
+ r = 16,
+ lora_alpha = 16,
+ lora_dropout = 0,
+ bias = "none",
+ use_gradient_checkpointing = spelling,
+ random_state = 3407,
+ use_rslora = False,
+ loftq_config = None,
+ )
+ return _load_legacy_cli(), args, seen
+
+
+ "spelling, expected",
+ [
+ ("unsloth", "unsloth"),
+ ("Unsloth", "unsloth"),
+ ("", "unsloth"),
+ ("mlx", "unsloth"),
+ ("true", True),
+ ("True", True),
+ ("1", True),
+ ("yes", True),
+ ("false", False),
+ ("False", False),
+ ("0", False),
+ ("no", False),
+ ("none", False),
+ ("off", False),
+ ],
+)
+def test_gradient_checkpointing_reaches_get_peft_model_as_a_supported_value(
+ monkeypatch, spelling, expected
+):
+ legacy_cli, args, seen = _setup(monkeypatch, spelling)
+ with pytest.raises(_Stop):
+ legacy_cli.run(args)
+ got = seen["use_gradient_checkpointing"]
+ assert type(got) is type(expected) and got == expected
+
+
+def test_unknown_gradient_checkpointing_fails_before_the_model_loads(monkeypatch):
+ legacy_cli, args, seen = _setup(monkeypatch, "flase")
+ with pytest.raises(ValueError, match = "unsloth, true or false"):
+ legacy_cli.run(args)
+ assert "loaded" not in seen