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 PEFT base export targets silently exporting the base model (#11781)

xiao6c647cabc3d1
diff --git a/tests/saving/test_peft_base_export_guard.py b/tests/saving/test_peft_base_export_guard.py
new file mode 100644
index 00000000000..3e7c24c532e
--- /dev/null
+++ b/tests/saving/test_peft_base_export_guard.py
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+from __future__ import annotations
+
+import ast
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+
+_SAVE_PY = Path(__file__).resolve().parents[2] / "unsloth" / "save.py"
+_SOURCE = _SAVE_PY.read_text(encoding = "utf-8")
+_TREE = ast.parse(_SOURCE)
+_EXPORT_FUNCTIONS = {
+ "unsloth_save_pretrained_gguf",
+ "unsloth_push_to_hub_gguf",
+ "unsloth_generic_save_pretrained_merged",
+ "unsloth_generic_push_to_hub_merged",
+ "unsloth_save_pretrained_torchao",
+}
+
+
+def _function(name: str) -> ast.FunctionDef:
+ for node in ast.walk(_TREE):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ return node
+ raise AssertionError(f"{name} not found in unsloth/save.py")
+
+
+def _function_source(name: str) -> str:
+ node = _function(name)
+ segment = ast.get_source_segment(_SOURCE, node)
+ indent = len(segment) - len(segment.lstrip())
+ return "\n".join(line[indent:] for line in segment.split("\n"))
+
+
+class _FakeBaseTunerLayer:
+ pass
+
+
+class _FakePeftModel:
+ pass
+
+
+class _Model:
+ def __init__(self, *modules):
+ self._modules = modules
+
+ def modules(self):
+ return iter(self._modules)
+
+
+def peft_guard_env(monkeypatch):
+ tuners_utils = types.ModuleType("peft.tuners.tuners_utils")
+ tuners_utils.BaseTunerLayer = _FakeBaseTunerLayer
+ saved = {name: value for name, value in sys.modules.items() if name.startswith("peft")}
+ for name, module in (
+ ("peft", types.ModuleType("peft")),
+ ("peft.tuners", types.ModuleType("peft.tuners")),
+ ("peft.tuners.tuners_utils", tuners_utils),
+ ):
+ monkeypatch.setitem(sys.modules, name, module)
+ yield
+ for name in [name for name in sys.modules if name.startswith("peft")]:
+ if name in saved:
+ sys.modules[name] = saved[name]
+ else:
+ del sys.modules[name]
+
+
+def _load_guard(monkeypatch):
+ namespace = {
+ "PeftModel": _FakePeftModel,
+ }
+ exec(
+ compile(
+ _function_source("_assert_export_target_is_not_base_with_lora_layers"),
+ str(_SAVE_PY),
+ "exec",
+ ),
+ namespace,
+ )
+ return namespace["_assert_export_target_is_not_base_with_lora_layers"]
+
+
+def test_a_base_model_with_lora_layers_raises_before_export(peft_guard_env):
+ guard = _load_guard(None)
+ with pytest.raises(RuntimeError, match = "FastModel.from_pretrained"):
+ guard(_Model(_FakeBaseTunerLayer()))
+
+
+def test_a_peft_wrapper_is_allowed(peft_guard_env):
+ guard = _load_guard(None)
+ model = _FakePeftModel()
+ model.modules = lambda: iter([_FakeBaseTunerLayer()])
+ guard(model)
+
+
+def test_a_full_fine_tune_is_allowed(peft_guard_env):
+ guard = _load_guard(None)
+ guard(_Model(object()))
+
+
[email protected]("name", sorted(_EXPORT_FUNCTIONS))
+def test_export_entrypoints_install_the_guard(name):
+ source = ast.get_source_segment(_SOURCE, _function(name))
+ assert "_assert_export_target_is_not_base_with_lora_layers(self)" in source
diff --git a/tests/test_merged_hub_destination.py b/tests/test_merged_hub_destination.py
index dbbf05917d9..d2685d87937 100644
--- a/tests/test_merged_hub_destination.py
+++ b/tests/test_merged_hub_destination.py
@@ -182,6 +182,7 @@ def saving(monkeypatch, tmp_path):
"_normalize_safe_serialization",
"_is_adapter_save_method",
"_honours_safe_serialization",
+ "_assert_export_target_is_not_base_with_lora_layers",
"_refuse_unsaveable_text_core",
}
nodes = []
diff --git a/unsloth/save.py b/unsloth/save.py
index 6fc1e2af041..a501b2cff6a 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -3807,6 +3807,26 @@ def _model_basename(name_or_path, default = "model") -> str:
return base
+def _assert_export_target_is_not_base_with_lora_layers(self):
+ """`peft.PeftModel.from_pretrained` forwards to the base's bound export method, which would silently write the un-merged base (unsloth#11698)."""
+ if isinstance(self, PeftModel):
+ return
+
+ try:
+ from peft.tuners.tuners_utils import BaseTunerLayer
+ except ImportError:
+ return
+
+ modules = getattr(self, "modules", None)
+ if callable(modules) and any(isinstance(m, BaseTunerLayer) for m in modules()):
+ raise RuntimeError(
+ "Unsloth: This model has LoRA layers, but the save method was called on the "
+ "base model. This happens when the adapter is attached with "
+ "`peft.PeftModel.from_pretrained`. Load the adapter folder with "
+ "`FastModel.from_pretrained(<adapter folder>)` instead."
+ )
+
+
@_normalize_tied_weights_keys_for_save
def unsloth_save_pretrained_gguf(
self,
@@ -3872,6 +3892,8 @@ def unsloth_save_pretrained_gguf(
"iq3_xxs" : "3.06 bpw quantization",
"q3_k_xs" : "3-bit extra small quantization",
"""
+ _assert_export_target_is_not_base_with_lora_layers(self)
+
if tokenizer is None:
raise ValueError("Unsloth: Saving to GGUF must have a tokenizer.")
if isinstance(tokenizer, (PreTrainedTokenizerBase, ProcessorMixin)):
@@ -4481,6 +4503,7 @@ def unsloth_push_to_hub_gguf(
`quantization_method` may be an alias -- "not_quantized" (fast conversion, big files), "fast_quantized" (fast conversion, OK size), "quantized" (slow conversion, small files) -- or a llama.cpp ftype: f32, f16, q8_0, q4_0, q4_1, q5_0, q5_1, or a k-quant q2_k / q3_k_s / q3_k_m / q3_k_l / q4_k_s / q4_k_m / q5_k_s / q5_k_m / q6_k. The _m and _l k-quants keep the attention and feed_forward.w2 tensors a level or two above the nominal width; q2_k_l is the Unsloth preset adding --output-tensor-type q8_0 --token-embedding-type q8_0.
"""
+ _assert_export_target_is_not_base_with_lora_layers(self)
if tokenizer is None:
raise ValueError("Unsloth: Saving to GGUF must have a tokenizer.")
if not is_main_process:
@@ -5708,6 +5731,7 @@ def unsloth_generic_save_pretrained_merged(
roughly 10x slower there, while `None` pins safetensors through that fallback. `False`
asks for a pickle.
"""
+ _assert_export_target_is_not_base_with_lora_layers(self)
if tokenizer is None:
logger.warning_once(
"Unsloth: You're not saving a tokenizer as well?\n"
@@ -5839,6 +5863,7 @@ def unsloth_generic_push_to_hub_merged(
roughly 10x slower there, while `None` pins safetensors through that fallback. `False`
asks for a pickle.
"""
+ _assert_export_target_is_not_base_with_lora_layers(self)
if tokenizer is None:
logger.warning_once(
"Unsloth: You're not saving a tokenizer as well?\n"
@@ -6841,6 +6866,7 @@ def unsloth_save_pretrained_torchao(
`save_directory`: local folder, or a hub id when `push_to_hub` is True.
`torchao_config` (TorchAOBaseConfig): required for PTQ, None for QAT. https://docs.pytorch.org/ao/main/api_ref_quantization.html#inference-apis-for-quantize
"""
+ _assert_export_target_is_not_base_with_lora_layers(self)
if isinstance(tokenizer, (PreTrainedTokenizerBase, ProcessorMixin)):
tokenizer = patch_saving_functions(tokenizer)