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
Keep gradient checkpointing settings working on transformers 5.23 (#16833)
Nilaye8aaca2e0b19
diff --git a/tests/test_decision_model.py b/tests/test_decision_model.pyindex de756c545f8..4f2be2d7d16 100644--- a/tests/test_decision_model.py+++ b/tests/test_decision_model.py@@ -362,6 +362,26 @@ def test_head_learning_rate_and_weight_decay(checkpoint, tmp_path, lora):assert group["weight_decay"] == (0.0 if name in no_decay else 0.01)+ not hasattr(TrainingArguments, "activation_checkpointing"),+ reason = "transformers < 5.23 reads gradient_checkpointing",+)+def test_trainer_checkpoints_the_encoder_not_the_wrapper(checkpoint, tmp_path):+ model, tokenizer = FastDecisionModel.from_pretrained(+ str(checkpoint), use_gradient_checkpointing = False+ )+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(4)], tokenizer, model)+ trainer = DecisionTrainer(+ model = model,+ args = _args(tmp_path, max_steps = 1, gradient_checkpointing = True),+ train_dataset = items,+ processing_class = tokenizer,+ )+ assert trainer.args.activation_checkpointing is False+ assert model.encoder.is_gradient_checkpointing+ trainer.train()++def test_length_grouping_only_with_gradient_accumulation(checkpoint, tmp_path):model, tokenizer = FastDecisionModel.from_pretrained(str(checkpoint), use_gradient_checkpointing = Falsediff --git a/tests/test_gc_enable_kwargs.py b/tests/test_gc_enable_kwargs.pyindex 590dd70d167..d3995802464 100644--- a/tests/test_gc_enable_kwargs.py+++ b/tests/test_gc_enable_kwargs.py@@ -24,6 +24,7 @@ FUNCS = ()ASSIGNS = ("_OFFLOADING_CHECKPOINT_SHIMS", "_GC_KWARGS_WARNED")NATIVE = "offload" in inspect.signature(PreTrainedModel.gradient_checkpointing_enable).parameters+RENAMED = hasattr(PreTrainedModel, "activation_checkpointing_enable")def _load():@@ -41,13 +42,22 @@ def _load():@pytest.fixturedef patched():- original = PreTrainedModel.__dict__["gradient_checkpointing_enable"]+ original = {+ name: PreTrainedModel.__dict__[name]+ for name in (+ "gradient_checkpointing_enable",+ "activation_checkpointing_enable",+ "_activation_checkpointing_enable",+ )+ if name in PreTrainedModel.__dict__+ }previous_checkpoint = hf_modeling_utils.checkpointpatch = _load().get("patch_gradient_checkpointing_enable_kwargs")if patch is not None:patch()yield- PreTrainedModel.gradient_checkpointing_enable = original+ for name, function in original.items():+ setattr(PreTrainedModel, name, function)hf_modeling_utils.checkpoint = previous_checkpoint@@ -149,6 +159,73 @@ def test_every_n_layers_survives_for_training_flag_rewrite(patched):assert _flags(model) == [True, True, True, True]+ not RENAMED, reason = "the Trainer calls activation_checkpointing_enable from transformers 5.23"+)+def test_every_n_layers_survives_flag_rewrite_through_activation_checkpointing_enable(patched):+ model = _model()+ model.activation_checkpointing_enable(activation_checkpointing_kwargs = None, every_n_layers = 2)+ assert _flags(model) == [True, False, True, False]+ for module in model.modules():+ if hasattr(module, "gradient_checkpointing"):+ module.gradient_checkpointing = True+ assert _flags(model) == [True, False, True, False]++[email protected](RENAMED, reason = "before transformers 5.23 the patched method is the public one")+def test_explicit_every_n_layers_beats_the_dict_on_the_legacy_api(patched):+ model = _model()+ model.gradient_checkpointing_enable({"every_n_layers": 2}, every_n_layers = 1)+ assert _flags(model) == [True, True, True, True]+++ not RENAMED,+ reason = "the old name is an alias of activation_checkpointing_enable from transformers 5.23",+)+def test_every_n_layers_dict_through_instance_wrapper_of_old_name(patched):+ # vision.py wraps the old name per instance (gemma3n / gemma4, forced non-reentrant).+ model = _model()+ original = model.gradient_checkpointing_enable+ model.gradient_checkpointing_enable = lambda **kwargs: original(**kwargs)+ model.gradient_checkpointing_enable(+ gradient_checkpointing_kwargs = {"use_reentrant": False, "every_n_layers": 2}+ )+ assert _flags(model) == [True, False, True, False]+ _grads(model)+++ not RENAMED, reason = "the Trainer calls activation_checkpointing_enable from transformers 5.23"+)+def test_offload_dropped_under_offloading_shim_through_activation_checkpointing_enable(+ patched, smart_gc, monkeypatch+):+ entered = []+ real = hf_modeling_utils.save_on_cpu++ class Counting(real):+ def __init__(+ self,+ pin_memory = False,+ device_type = "cuda",+ ):+ pin_memory = pin_memory and torch.accelerator.is_available()+ super().__init__(pin_memory = pin_memory, device_type = device_type)++ def __enter__(self):+ entered.append(1)+ return super().__enter__()++ monkeypatch.setattr(hf_modeling_utils, "save_on_cpu", Counting)+ model = _model()+ model.activation_checkpointing_enable(+ activation_checkpointing_kwargs = {"use_reentrant": True}, offload = True+ )+ _grads(model)+ assert entered == []++@pytest.mark.skipif(not NATIVE, reason = "offload is a gradient_checkpointing_enable argument from transformers 5.17")diff --git a/tests/test_gc_every_n_cpu_route.py b/tests/test_gc_every_n_cpu_route.pyindex d96d6e2c9a9..8d986491b1f 100644--- a/tests/test_gc_every_n_cpu_route.py+++ b/tests/test_gc_every_n_cpu_route.py@@ -46,7 +46,8 @@ def run(m):out = {"device_type": unsloth.DEVICE_TYPE,"models_loaded": sorted(n for n in sys.modules if n == "unsloth.models" or n.startswith("unsloth.models.")),- "patched": bool(getattr(PreTrainedModel.gradient_checkpointing_enable, "_unsloth_gc_kwargs", False))}+ "patched": any(getattr(getattr(PreTrainedModel, n, None), "_unsloth_gc_kwargs", False)+ for n in ("_activation_checkpointing_enable", "activation_checkpointing_enable", "gradient_checkpointing_enable"))}res = {}# dict form (TrainingArguments on transformers < 5.17, PEFT prepare_model_for_kbit_training, direct calls)m = model()diff --git a/tests/test_gradient_checkpointing_off_honoured.py b/tests/test_gradient_checkpointing_off_honoured.pyindex 85f18e6e9f7..66bcbcc4b76 100644--- a/tests/test_gradient_checkpointing_off_honoured.py+++ b/tests/test_gradient_checkpointing_off_honoured.py@@ -93,6 +93,55 @@ def test_honour_rules(capsys):assert foreign.gradient_checkpointing is True+def test_off_reaches_activation_checkpointing():+ module = _load_module()+ Config = _config_class()+ module.track_explicit_gradient_checkpointing(Config)+ args = Config()+ args.__dict__["activation_checkpointing"] = True+ assert module.honour_gradient_checkpointing_off(args, _Model(False))+ assert args.gradient_checkpointing is False+ assert args.activation_checkpointing is False+++def _renamed_config_class():+ class Config:+ def __init__(+ self,+ output_dir = None,+ activation_checkpointing = None,+ gradient_checkpointing = True,+ **kwargs,+ ):+ self.output_dir = output_dir+ if activation_checkpointing is None:+ activation_checkpointing = gradient_checkpointing+ self.activation_checkpointing = activation_checkpointing+ self.gradient_checkpointing = activation_checkpointing++ return Config+++def test_explicit_activation_checkpointing_is_kept():+ module = _load_module()+ Config = _renamed_config_class()+ assert module.track_explicit_gradient_checkpointing(Config)+ assert Config().__dict__[module.EXPLICIT_FLAG] is False++ passed = Config(activation_checkpointing = True)+ assert not module.honour_gradient_checkpointing_off(passed, _Model(False))+ assert passed.activation_checkpointing is True++ assigned = Config()+ assigned.activation_checkpointing = True+ assert not module.honour_gradient_checkpointing_off(assigned, _Model(False))+ assert assigned.activation_checkpointing is True++ default = Config()+ assert module.honour_gradient_checkpointing_off(default, _Model(False))+ assert default.activation_checkpointing is False++def test_assignment_after_construction_is_explicit():import dataclassesdiff --git a/tests/test_gradient_checkpointing_reentrant.py b/tests/test_gradient_checkpointing_reentrant.pyindex cd8495bc901..3ee7adcb040 100644--- a/tests/test_gradient_checkpointing_reentrant.py+++ b/tests/test_gradient_checkpointing_reentrant.py@@ -104,3 +104,15 @@ def test_the_snippet_pins_true_rather_than_deleting_the_key():"deleting the key is not enough: a config that never set it leaves ""None, and transformers substitutes False")+++class _RenamedConfig(_Config):+ def __init__(self, kwargs = None):+ super().__init__(kwargs = kwargs)+ self.activation_checkpointing_kwargs = kwargs+++def test_the_pin_reaches_activation_checkpointing_kwargs():+ config = _run_post(_RenamedConfig(kwargs = None))+ assert config.activation_checkpointing_kwargs == {"use_reentrant": True}+ assert config.gradient_checkpointing_kwargs == {"use_reentrant": True}diff --git a/tests/test_pp_native_gloo.py b/tests/test_pp_native_gloo.pyindex d8d88793457..e138060bf55 100644--- a/tests/test_pp_native_gloo.py+++ b/tests/test_pp_native_gloo.py@@ -772,6 +772,30 @@ def test_layer_call_format_reads_tuple_loops():assert ppn._layer_call_format(Decoder(), "layers") == "tuple"+def test_layer_call_format_knows_the_renamed_checkpointing_layer():+ class ActivationCheckpointingLayer(torch.nn.Module):+ pass++ class Decoder(torch.nn.Module):+ gradient_checkpointing = True++ def __init__(self):+ super().__init__()+ self.layers = torch.nn.ModuleList()++ def forward(self, hidden_states):+ for decoder_layer in self.layers:+ if isinstance(decoder_layer, ActivationCheckpointingLayer):+ hidden_states = decoder_layer(hidden_states)+ else:+ hidden_states = self._gradient_checkpointing_func(+ decoder_layer.__call__, hidden_states+ )+ return hidden_states++ assert ppn._layer_call_format(Decoder(), "layers") == "tensor"++def test_non_last_stage_compiles_as_one_graph():from torch._dynamo.utils import countersdiff --git a/unsloth/_gc_kwargs.py b/unsloth/_gc_kwargs.pyindex 466b7376cec..6c8d78b161b 100644--- a/unsloth/_gc_kwargs.py+++ b/unsloth/_gc_kwargs.py@@ -90,16 +90,28 @@ def patch_gradient_checkpointing_enable_kwargs():import transformers.modeling_utils as hf_modeling_utilsexcept Exception:return- original = PreTrainedModel.gradient_checkpointing_enable+ # transformers >= 5.23: both public names and instance wrappers of the old one end here.+ name = next(+ (+ n+ for n in ("_activation_checkpointing_enable", "activation_checkpointing_enable")+ if hasattr(PreTrainedModel, n)+ ),+ "gradient_checkpointing_enable",+ )+ original = getattr(PreTrainedModel, name)if getattr(original, "_unsloth_gc_kwargs", False):returntry:params = list(inspect.signature(original).parameters)except Exception:return- positional = [p for p in params if p not in ("self", "gradient_checkpointing_kwargs")]+ kwargs_name = name.lstrip("_").replace("_enable", "_kwargs")+ positional = [p for p in params if p not in ("self", kwargs_name)]native_every = "every_n_layers" in paramsnative_offload = "offload" in params+ # transformers >= 5.23 always passes the defaults (1, False) here, so they cannot override the dict.+ forwards_defaults = name == "_activation_checkpointing_enable"@functools.wraps(original)def gradient_checkpointing_enable(@@ -108,6 +120,7 @@ def patch_gradient_checkpointing_enable_kwargs():*args,**kwargs,):+ gradient_checkpointing_kwargs = kwargs.pop(kwargs_name, gradient_checkpointing_kwargs)kwargs.update(zip(positional, args))every = kwargs.pop("every_n_layers", None)offload = kwargs.pop("offload", None)@@ -115,6 +128,9 @@ def patch_gradient_checkpointing_enable_kwargs():gc_kwargs = dict(gradient_checkpointing_kwargs)dict_every = gc_kwargs.pop("every_n_layers", None)dict_offload = gc_kwargs.pop("offload", None)+ if forwards_defaults:+ every = None if every == 1 else every+ offload = offload or Noneevery = dict_every if every is None else everyoffload = dict_offload if offload is None else offloadif len(gc_kwargs) != len(gradient_checkpointing_kwargs):@@ -154,4 +170,4 @@ def patch_gradient_checkpointing_enable_kwargs():return outgradient_checkpointing_enable._unsloth_gc_kwargs = True- PreTrainedModel.gradient_checkpointing_enable = gradient_checkpointing_enable+ setattr(PreTrainedModel, name, gradient_checkpointing_enable)diff --git a/unsloth/models/_gc_config_default.py b/unsloth/models/_gc_config_default.pyindex 73e3bc2d866..21b6142c1ec 100644--- a/unsloth/models/_gc_config_default.py+++ b/unsloth/models/_gc_config_default.py@@ -27,6 +27,7 @@ __all__ = [EXPLICIT_FLAG = "_unsloth_gradient_checkpointing_explicit"_WRAPPED_FLAG = "_unsloth_tracks_explicit_gradient_checkpointing"_NOTED = set()+_FIELDS = ("gradient_checkpointing", "activation_checkpointing")def _note(key, message):@@ -47,11 +48,13 @@ def track_explicit_gradient_checkpointing(config_class):return Falseif "gradient_checkpointing" not in names:return False- position = names.index("gradient_checkpointing") - 1+ # transformers >= 5.23 renames it activation_checkpointing and mirrors the old name from the new one.+ fields = [name for name in _FIELDS if name in names]+ positions = [names.index(name) - 1 for name in fields]@functools.wraps(init)def __init__(self, *args, **kwargs):- explicit = "gradient_checkpointing" in kwargs or len(args) > position+ explicit = any(name in kwargs for name in fields) or len(args) > min(positions)init(self, *args, **kwargs)# Not a dataclass field: to_dict(), to_json_string() and asdict() never see it.self.__dict__[EXPLICIT_FLAG] = explicit@@ -65,7 +68,7 @@ def track_explicit_gradient_checkpointing(config_class):def __setattr__(self, name, value):original_setattr(self, name, value)- if name == "gradient_checkpointing" and EXPLICIT_FLAG in self.__dict__:+ if name in _FIELDS and EXPLICIT_FLAG in self.__dict__:self.__dict__[EXPLICIT_FLAG] = Trueconfig_class.__setattr__ = __setattr__@@ -98,6 +101,8 @@ def honour_gradient_checkpointing_off(args, model):)return Falseargs.gradient_checkpointing = False+ if hasattr(args, "activation_checkpointing"):+ args.activation_checkpointing = False_note("off","Unsloth: the model was set up with use_gradient_checkpointing = False, so gradient checkpointing stays "diff --git a/unsloth/models/decision.py b/unsloth/models/decision.pyindex f8e87e1b3ad..28029b6179c 100644--- a/unsloth/models/decision.py+++ b/unsloth/models/decision.py@@ -1267,6 +1267,8 @@ class DecisionTrainer(Trainer):# Trainer would call model.gradient_checkpointing_enable, which only the encoder has.# Clef's backbone already got Unsloth's checkpointing when it loaded.args.gradient_checkpointing = False+ if hasattr(args, "activation_checkpointing"):+ args.activation_checkpointing = Falseif not clef and not model.encoder.is_gradient_checkpointing:_gradient_checkpointing(model, True)if kwargs.get("processing_class") is None:diff --git a/unsloth/models/pp_native.py b/unsloth/models/pp_native.pyindex 19a0ba52a7b..1e90619fd5d 100644--- a/unsloth/models/pp_native.py+++ b/unsloth/models/pp_native.py@@ -838,7 +838,10 @@ def _layer_call_format(decoder, layers_name):and any(var in ast.unparse(a) for a in node.args)and "checkpoint" in ast.unparse(node.func).lower()):- if "GradientCheckpointingLayer" not in text:+ if (+ "GradientCheckpointingLayer" not in text+ and "ActivationCheckpointingLayer" not in text+ ):formats.add("checkpointed")if "checkpointed" in formats:if getattr(decoder, "gradient_checkpointing", False):diff --git a/unsloth/models/rl.py b/unsloth/models/rl.pyindex 9f4d24a913a..f46cfacbfd1 100644--- a/unsloth/models/rl.py+++ b/unsloth/models/rl.py@@ -3744,6 +3744,8 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):" if _gc_kwargs.get('context_fn') is None and not _gc_kwargs.get('debug', False):\n"" _gc_kwargs['use_reentrant'] = True\n"" self.gradient_checkpointing_kwargs = _gc_kwargs\n"+ " if hasattr(self, 'activation_checkpointing_kwargs'):\n"+ " self.activation_checkpointing_kwargs = _gc_kwargs\n")if "optim" in call_args: