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
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.pynew file mode 100644index 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.pyindex 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_codeTrainer._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.pyindex 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_modelif 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:+ passtransformer_path = "0_Transformer"modules_path = os.path.join(save_directory, "modules.json")diff --git a/unsloth/save.py b/unsloth/save.pyindex 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(raisetry:- 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