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.

Notebook GGUF export: keep the converter to the load's trust_remote_code decision (#17397)

Daniel Han2966fc41ef05
diff --git a/tests/saving/test_gguf_notebook_remote_code_guard.py b/tests/saving/test_gguf_notebook_remote_code_guard.py
new file mode 100644
index 00000000000..8ed42b950ef
--- /dev/null
+++ b/tests/saving/test_gguf_notebook_remote_code_guard.py
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Notebook GGUF export keeps convert_hf_to_gguf.py to the load's trust_remote_code decision.
+
+The converter loads several architectures' tokenizers with trust_remote_code=True. Without
+consent at load time, the converter child gets an HF_MODULES_CACHE no directory can be created
+at, so a checkpoint's auto_map code cannot be imported there (Studio's export does the same).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import textwrap
+import types
+
+import pytest
+
+_KEY = "HF_MODULES_CACHE"
+
+
+def save_mod():
+ import unsloth.save as save
+ return save
+
+
+class _FakeTokenizer:
+ chat_template = None
+
+ def save_pretrained(self, path):
+ os.makedirs(path, exist_ok = True)
+
+
+class _FakeModel:
+ def __init__(self, name_or_path):
+ self.config = types.SimpleNamespace(
+ _name_or_path = name_or_path,
+ architectures = ["LlamaForCausalLM"],
+ model_type = "llama",
+ )
+
+ def save_pretrained(self, path, *args, **kwargs):
+ os.makedirs(path, exist_ok = True)
+
+
+def _cache_seen_by_converter(monkeypatch, save_mod, tmp_path, model, tokenizer):
+ """Drive `save_pretrained_gguf` with the converter stubbed; return HF_MODULES_CACHE as the converter sees it."""
+ seen = {}
+ monkeypatch.setattr(save_mod, "_is_vlm", lambda _m: False)
+ monkeypatch.setattr(save_mod, "_is_gpt_oss", lambda _m: False)
+ monkeypatch.setattr(save_mod, "fix_tokenizer_bos_token", lambda _t: (False, None))
+ monkeypatch.setattr(save_mod, "_resolve_imatrix_file", lambda *_a, **_k: None)
+ monkeypatch.setattr(save_mod, "dtype_from_config", lambda _c: save_mod.torch.float16)
+ monkeypatch.setattr(save_mod, "create_ollama_modelfile", lambda *_a, **_k: None)
+
+ def _save_to_gguf(**kw):
+ seen["cache"] = os.environ.get(_KEY)
+ out = tmp_path / "export" / "model_gguf" / "model.Q8_0.gguf"
+ out.parent.mkdir(parents = True, exist_ok = True)
+ out.write_bytes(b"GGUF")
+ return [str(out)], True, False
+
+ monkeypatch.setattr(save_mod, "save_to_gguf", _save_to_gguf)
+ save_mod.unsloth_save_pretrained_gguf(
+ model,
+ str(tmp_path / "export" / "model"),
+ tokenizer = tokenizer,
+ quantization_method = "q8_0",
+ )
+ return seen["cache"]
+
+
+def _is_uncreatable(path):
+ try:
+ os.makedirs(path, exist_ok = True)
+ except OSError:
+ return True
+ return False
+
+
+def test_untrusted_load_blocks_converter_remote_code(monkeypatch, tmp_path, save_mod):
+ preset = str(tmp_path / "modules")
+ monkeypatch.setenv(_KEY, preset)
+ model = _FakeModel("some-org/some-model")
+ cache = _cache_seen_by_converter(monkeypatch, save_mod, tmp_path, model, _FakeTokenizer())
+ assert cache != preset
+ assert _is_uncreatable(cache)
+ assert os.environ[_KEY] == preset # restored after the export
+
+
+def test_untrusted_load_restores_unset_cache(monkeypatch, tmp_path, save_mod):
+ monkeypatch.delenv(_KEY, raising = False)
+ model = _FakeModel("some-org/some-model")
+ cache = _cache_seen_by_converter(monkeypatch, save_mod, tmp_path, model, _FakeTokenizer())
+ assert cache is not None and _is_uncreatable(cache)
+ assert _KEY not in os.environ
+
+
+def test_trusted_load_keeps_converter_unchanged(monkeypatch, tmp_path, save_mod):
+ preset = str(tmp_path / "modules")
+ monkeypatch.setenv(_KEY, preset)
+ model = _FakeModel("some-org/some-model")
+ model._unsloth_trust_remote_code = True
+ cache = _cache_seen_by_converter(monkeypatch, save_mod, tmp_path, model, _FakeTokenizer())
+ assert cache == preset
+
+
+def test_remote_code_tokenizer_counts_as_consent(monkeypatch, tmp_path, save_mod):
+ preset = str(tmp_path / "modules")
+ monkeypatch.setenv(_KEY, preset)
+ remote_tok = type(
+ "CustomTokenizer", (_FakeTokenizer,), {"__module__": "transformers_modules.x.tok"}
+ )
+ model = _FakeModel("some-org/some-model")
+ cache = _cache_seen_by_converter(monkeypatch, save_mod, tmp_path, model, remote_tok())
+ assert cache == preset
+
+
+def _write_remote_code_checkpoint(path, marker):
+ path.mkdir()
+ (path / "config.json").write_text(
+ json.dumps(
+ {
+ "model_type": "custom_probe",
+ "auto_map": {"AutoConfig": "configuration_probe.ProbeConfig"},
+ }
+ )
+ )
+ (path / "configuration_probe.py").write_text(
+ textwrap.dedent(
+ f"""
+ open({str(marker)!r}, "w").write("ran")
+ from transformers import PretrainedConfig
+
+ class ProbeConfig(PretrainedConfig):
+ model_type = "custom_probe"
+ """
+ )
+ )
+
+
+def _child_loads_with_trust(checkpoint, env):
+ code = (
+ "import sys\n"
+ "from transformers import AutoConfig\n"
+ "AutoConfig.from_pretrained(sys.argv[1], trust_remote_code=True)\n"
+ )
+ return subprocess.run(
+ [sys.executable, "-c", code, str(checkpoint)],
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 300,
+ )
+
+
+def test_guarded_env_stops_a_child_from_running_auto_map_code(tmp_path, save_mod):
+ """The mechanism itself: a converter-like child that asks for trust_remote_code=True runs the
+ checkpoint's auto_map code with a normal cache, and cannot under the guard."""
+ marker = tmp_path / "ran.txt"
+ checkpoint = tmp_path / "ckpt"
+ _write_remote_code_checkpoint(checkpoint, marker)
+ base_env = dict(os.environ, HF_HUB_OFFLINE = "1", HF_MODULES_CACHE = str(tmp_path / "mods"))
+
+ control = _child_loads_with_trust(checkpoint, base_env)
+ assert control.returncode == 0, control.stderr
+ assert marker.exists(), "control arm must run the remote code, else this test proves nothing"
+ marker.unlink()
+
+ with save_mod._gguf_converter_remote_code(False):
+ guarded_env = dict(base_env, HF_MODULES_CACHE = os.environ[_KEY])
+ guarded = _child_loads_with_trust(checkpoint, guarded_env)
+ assert guarded.returncode != 0
+ assert not marker.exists()
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index a592da20e6d..4ad30b03dab 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -4690,6 +4690,8 @@ class FastLlamaModel:
model.config.update({"unsloth_version": __version__})
patch_saving_functions(model)
+ # The GGUF export keeps its converter to this consent, as FastBaseModel's stamp does.
+ model._unsloth_trust_remote_code = trust_remote_code
Trainer._inner_training_loop = _fast_inner_training_loop
# Fix gradient accumulation; see #4982.
diff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.py
index f19bbe8d723..541bd326e79 100644
--- a/unsloth/models/sentence_transformer.py
+++ b/unsloth/models/sentence_transformer.py
@@ -438,6 +438,12 @@ def _save_pretrained_gguf(
inner_model = self[0].auto_model
if hasattr(inner_model, "_orig_mod"):
inner_model = inner_model._orig_mod
+ # The GGUF saver reads the load's remote-code consent off the model it converts.
+ if getattr(self, "_unsloth_trust_remote_code", False) is True:
+ try:
+ inner_model._unsloth_trust_remote_code = True
+ except Exception:
+ pass
transformer_path = "0_Transformer"
modules_path = os.path.join(save_directory, "modules.json")
diff --git a/unsloth/save.py b/unsloth/save.py
index 197956973bd..eb2a2ebea6a 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -584,6 +584,38 @@ def _loaded_via_remote_code(obj):
return False
+def _gguf_remote_code_approved(model, tokenizer = None):
+ """Did the load consent to remote code? A `trust_remote_code=True` stamp from the loader, or a model / tokenizer class that came from auto_map code (which only runs after consent)."""
+ try:
+ if getattr(model, "_unsloth_trust_remote_code", False) is True:
+ return True
+ except Exception:
+ pass
+ return _loaded_via_remote_code(model) or _loaded_via_remote_code(tokenizer)
+
+
+@contextmanager
+def _gguf_converter_remote_code(approved):
+ """Keep convert_hf_to_gguf.py to the load's trust decision, as Studio's export does.
+
+ The converter loads several architectures' tokenizers with trust_remote_code=True, so a
+ checkpoint loaded without consent could run its auto_map code there. Transformers imports
+ that code only from its HF_MODULES_CACHE copy, which the converter child inherits: a path no
+ directory can be created at refuses it. Checkpoints without auto_map never read it."""
+ if approved:
+ yield
+ return
+ existing = os.environ.get("HF_MODULES_CACHE")
+ os.environ["HF_MODULES_CACHE"] = os.path.join(os.path.abspath(__file__), "no_remote_code")
+ try:
+ yield
+ finally:
+ if existing is None:
+ os.environ.pop("HF_MODULES_CACHE", None)
+ else:
+ os.environ["HF_MODULES_CACHE"] = existing
+
+
def _normalize_compressed_method(save_method):
"""(scheme, needs_calibration, suffix) if `save_method` is an FP8/FP4 compressed export, else None. Near-miss unsupported FP8/FP4 names raise a precise error instead of falling through to the generic "unknown save_method"."""
if not isinstance(save_method, str):
@@ -5085,6 +5117,8 @@ def unsloth_save_pretrained_gguf(
raise ValueError("Unsloth: Saving to GGUF must have a tokenizer.")
if isinstance(tokenizer, (PreTrainedTokenizerBase, ProcessorMixin)):
tokenizer = patch_saving_functions(tokenizer)
+ # Read before the processor is unwrapped to its tokenizer below.
+ remote_code_approved = _gguf_remote_code_approved(self, tokenizer)
save_directory = os.path.normpath(os.fspath(save_directory))
# save_method="lora" exports the adapter itself as a GGUF LoRA, not a merged model.
@@ -5336,21 +5370,22 @@ def unsloth_save_pretrained_gguf(
raise
try:
- all_file_locations, want_full_precision, is_vlm_update = save_to_gguf(
- model_name = model_name,
- model_type = model_type,
- model_dtype = model_dtype,
- is_sentencepiece = False,
- model_directory = save_directory,
- quantization_method = quantization_methods,
- first_conversion = first_conversion,
- is_vlm = is_vlm,
- is_gpt_oss = is_gpt_oss,
- imatrix = imatrix_path,
- gguf_directory = gguf_directory,
- merge_is_disposable = merge_is_disposable,
- preexisting_weights = preexisting_weights,
- )
+ with _gguf_converter_remote_code(remote_code_approved):
+ all_file_locations, want_full_precision, is_vlm_update = save_to_gguf(
+ model_name = model_name,
+ model_type = model_type,
+ model_dtype = model_dtype,
+ is_sentencepiece = False,
+ model_directory = save_directory,
+ quantization_method = quantization_methods,
+ first_conversion = first_conversion,
+ is_vlm = is_vlm,
+ is_gpt_oss = is_gpt_oss,
+ imatrix = imatrix_path,
+ gguf_directory = gguf_directory,
+ merge_is_disposable = merge_is_disposable,
+ preexisting_weights = preexisting_weights,
+ )
except Exception as e:
if _gguf_child_was_oom_killed(e):
raise RuntimeError(
@@ -6618,11 +6653,12 @@ def save_to_gguf_generic(
raise RuntimeError(error)
for quantization_type in new_quantization_methods:
- metadata = _convert_to_gguf(
- save_directory,
- print_output = True,
- quantization_type = quantization_type,
- )
+ with _gguf_converter_remote_code(_gguf_remote_code_approved(model, tokenizer)):
+ metadata = _convert_to_gguf(
+ save_directory,
+ print_output = True,
+ quantization_type = quantization_type,
+ )
if repo_id is not None:
from unsloth_zoo.saving_utils import prepare_saving