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.

Upload merged models to the requested branch or pull request (#10760)

Nilay6a5b21b2a638
diff --git a/tests/test_merged_hub_destination.py b/tests/test_merged_hub_destination.py
new file mode 100644
index 00000000000..ba160838bd7
--- /dev/null
+++ b/tests/test_merged_hub_destination.py
@@ -0,0 +1,442 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+import ast
+import gc
+import json
+import os
+import sys
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+
+import pytest
+from huggingface_hub import HfApi, ModelCard
+from huggingface_hub.errors import (
+ EntryNotFoundError,
+ HfHubHTTPError,
+ LocalEntryNotFoundError,
+ RevisionNotFoundError,
+)
+
+
+class PeftModel:
+ config = SimpleNamespace(_name_or_path = "base/model", model_type = "llama")
+
+
+class FullModel:
+ config = PeftModel.config
+
+ def state_dict(self):
+ return {}
+
+ def save_pretrained(self, directory, **kwargs):
+ (Path(directory) / "config.json").write_text('{"model_type": "llama"}')
+ (Path(directory) / "model.safetensors").write_bytes(b"model weights")
+
+ def push_to_hub(self, **kwargs):
+ raise AssertionError("Model files must join the single staged commit")
+
+
+def saving(monkeypatch, tmp_path):
+ source = Path(__file__).resolve().parents[1] / "unsloth/save.py"
+ tree = ast.parse(source.read_text(encoding = "utf-8"))
+ records = {
+ "merges": [],
+ "uploads": [],
+ "repos": [],
+ "directories": [],
+ "branches": [],
+ "downloads": [],
+ "revisions": {"main"},
+ }
+ artifacts = {
+ "config.json": '{"model_type": "llama"}',
+ "generation_config.json": "{}",
+ "tokenizer.json": "{}",
+ "tokenizer_config.json": "{}",
+ "model.safetensors.index.json": json.dumps(
+ {
+ "weight_map": {
+ "first": "model-00001-of-00002.safetensors",
+ "second": "model-00002-of-00002.safetensors",
+ }
+ }
+ ),
+ "model-00001-of-00002.safetensors": "first weights",
+ "model-00002-of-00002.safetensors": "second weights",
+ }
+
+ def merge(*args, **kwargs):
+ records["merges"].append(kwargs)
+ if kwargs["push_to_hub"]:
+ return
+ directory = Path(kwargs["save_directory"])
+ records["directories"].append(directory)
+ for filename, content in artifacts.items():
+ (directory / filename).write_text(content)
+ for filename, content in records.get("extra_files", {}).items():
+ path = directory / filename
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_text(content)
+ if records.get("fail_merge"):
+ raise OSError("merge failed")
+ if records.get("existing_card"):
+ (directory / "README.md").write_text(
+ "---\nlicense: mit\ntags:\n- existing\n---\nOriginal card"
+ )
+
+ zoo = ModuleType("unsloth_zoo.saving_utils")
+ zoo.merge_and_overwrite_lora = merge
+ zoo.get_original_model_id = lambda path: records.get("original_model_id")
+ monkeypatch.setitem(sys.modules, "unsloth_zoo.saving_utils", zoo)
+
+ def download(
+ repo_id,
+ filename,
+ *,
+ revision = None,
+ token = None,
+ **kwargs,
+ ):
+ records["downloads"].append((repo_id, filename, revision, token))
+ if records.get("download_error"):
+ raise records["download_error"]
+ content = records.get("remote_cards", {}).get(revision or "main")
+ if content is None:
+ raise EntryNotFoundError("No README at destination")
+ path = tmp_path / "remote-card.md"
+ path.write_text(content)
+ return str(path)
+
+ monkeypatch.setattr("huggingface_hub.hf_hub_download", download)
+
+ class Api:
+ def __init__(self, token):
+ self.token = token
+
+ def create_repo(self, **kwargs):
+ records["repos"].append(kwargs)
+
+ def create_branch(self, **kwargs):
+ records["branches"].append(kwargs)
+ records["revisions"].add(kwargs["branch"])
+
+ def create_commit(self, **kwargs):
+ if (
+ records.get("enforce_revision")
+ and (kwargs["revision"] or "main") not in records["revisions"]
+ ):
+ raise RevisionNotFoundError("Requested branch does not exist")
+ if kwargs["commit_message"] is None:
+ HfApi(token = False).create_commit(
+ repo_id = kwargs["repo_id"], operations = [], commit_message = None
+ )
+ files = {
+ operation.path_in_repo: Path(operation.path_or_fileobj).read_text(encoding = "utf-8")
+ for operation in kwargs["operations"]
+ }
+ records["uploads"].append({**kwargs, "files": files, "token": self.token})
+ if records.get("fail_upload"):
+ raise OSError("upload failed")
+ return "commit-info"
+
+ env = dict(
+ os = os,
+ gc = gc,
+ Path = Path,
+ HfApi = Api,
+ PeftModel = PeftModel,
+ PreTrainedTokenizerBase = type("Tokenizer", (), {}),
+ ProcessorMixin = type("Processor", (), {}),
+ torch = SimpleNamespace(
+ save = lambda: None,
+ float16 = "float16",
+ bfloat16 = "bfloat16",
+ cuda = SimpleNamespace(is_bf16_supported = lambda: False),
+ ),
+ get_token = lambda: "cached-fixture",
+ _determine_username = lambda repo, old, token: (repo, repo.split("/")[0]),
+ _prewarm_base_model_hub_cache = lambda *args, **kwargs: None,
+ get_model_name = lambda name: name,
+ _normalize_compressed_method = lambda method: None,
+ _normalize_torchao_method = lambda method: None,
+ _is_qwen3_5_vlm = lambda model: False,
+ logger = SimpleNamespace(warning_once = lambda *args: None),
+ )
+ names = {
+ "_push_merged_to_hub_revision",
+ "unsloth_generic_save",
+ "unsloth_generic_push_to_hub_merged",
+ }
+ nodes = []
+ for node in tree.body:
+ if isinstance(node, ast.FunctionDef) and node.name in names:
+ node.decorator_list = []
+ nodes.append(node)
+ elif isinstance(node, ast.Assign) and any(
+ isinstance(t, ast.Name) and t.id == "MODEL_CARD" for t in node.targets
+ ):
+ nodes.append(node)
+ module = ast.Module(
+ body = [
+ ast.ImportFrom(module = "__future__", names = [ast.alias(name = "annotations")], level = 0),
+ *nodes,
+ ],
+ type_ignores = [],
+ )
+ exec(compile(ast.fix_missing_locations(module), str(source), "exec"), env)
+ return env, records, artifacts
+
+
+ "revision, create_pr", [("release-candidate", False), (None, True), ("release-candidate", True)]
+)
+def test_public_merged_push_commits_all_artifacts_to_one_destination(saving, revision, create_pr):
+ env, records, artifacts = saving
+ env["unsloth_generic_push_to_hub_merged"](
+ PeftModel(),
+ "owner/model",
+ token = "explicit-fixture",
+ private = True,
+ revision = revision,
+ create_pr = create_pr,
+ datasets = ["owner/data"],
+ tags = ["fine-tuned"],
+ commit_message = "Merge result",
+ commit_description = "Review all artifacts",
+ )
+ assert len(records["uploads"]) == 1
+ upload = records["uploads"][0]
+ assert upload["revision"] == revision and upload["create_pr"] is create_pr
+ assert upload["token"] == "explicit-fixture"
+ assert upload["repo_id"] == "owner/model"
+ assert upload["commit_message"] == "Merge result"
+ assert upload["commit_description"] == "Review all artifacts"
+ assert set(upload["files"]) == {*artifacts, "README.md"}
+ assert all(upload["files"][name] == content for name, content in artifacts.items())
+ card = ModelCard(upload["files"]["README.md"])
+ assert card.data.datasets == ["owner/data"]
+ assert "fine-tuned" in card.data.tags and "unsloth" in card.data.tags
+ assert records["repos"] == [
+ {"repo_id": "owner/model", "repo_type": "model", "private": True, "exist_ok": True}
+ ]
+ assert all(not call["push_to_hub"] for call in records["merges"])
+ assert not any(directory.exists() for directory in records["directories"])
+
+
+def test_existing_local_card_metadata_and_body_survive(saving):
+ env, records, _ = saving
+ records["existing_card"] = True
+ env["unsloth_generic_push_to_hub_merged"](PeftModel(), "owner/model", revision = "candidate")
+ upload = records["uploads"][0]
+ card = ModelCard(upload["files"]["README.md"])
+ assert card.data.license == "mit"
+ assert card.data.tags == ["existing", "unsloth"]
+ assert "Original card" in card.content
+ assert upload["token"] == "cached-fixture"
+
+
[email protected]("failure", ["fail_merge", "fail_upload"])
+def test_staging_is_cleaned_on_failure(saving, failure):
+ env, records, _ = saving
+ records[failure] = True
+ with pytest.raises(OSError, match = "failed"):
+ env["unsloth_generic_push_to_hub_merged"](PeftModel(), "owner/model", create_pr = True)
+ if failure == "fail_merge":
+ assert records["uploads"] == []
+ assert not any(directory.exists() for directory in records["directories"])
+
+
+def test_default_push_keeps_streaming_merger(saving):
+ env, records, _ = saving
+ env["unsloth_generic_push_to_hub_merged"](PeftModel(), "owner/model", token = "fixture")
+ assert records["merges"][0]["push_to_hub"] is True
+ assert records["uploads"] == []
+ assert records["repos"] == []
+
+
+def test_non_main_rank_does_not_create_or_upload(saving):
+ env, records, _ = saving
+ env["unsloth_generic_save"](
+ PeftModel(), None, "owner/model", push_to_hub = True, create_pr = True, is_main_process = False
+ )
+ assert records["repos"] == records["uploads"] == records["merges"] == []
+
+
+def test_full_finetune_stages_model_and_metadata_together(saving):
+ env, records, _ = saving
+ env["unsloth_generic_push_to_hub_merged"](
+ FullModel(), "owner/model", create_pr = True, datasets = ["owner/data"]
+ )
+ assert len(records["uploads"]) == 1
+ upload = records["uploads"][0]
+ assert upload["create_pr"] is True
+ assert set(upload["files"]) == {"config.json", "model.safetensors", "README.md"}
+ assert ModelCard(upload["files"]["README.md"]).data.datasets == ["owner/data"]
+ assert records["merges"] == []
+
+
[email protected]("original_id", ["upstream/base-model", None])
+def test_local_base_model_card_uses_hub_identifier(saving, tmp_path, original_id):
+ env, records, _ = saving
+ records["original_model_id"] = original_id
+ model = PeftModel()
+ model.config = SimpleNamespace(_name_or_path = str(tmp_path), model_type = "llama")
+ env["unsloth_generic_push_to_hub_merged"](model, "owner/model", revision = "candidate")
+ card = ModelCard(records["uploads"][0]["files"]["README.md"])
+ assert card.data.base_model == (original_id or "owner/model")
+
+
+def test_staged_cache_metadata_is_excluded_but_nested_artifacts_survive(saving):
+ env, records, artifacts = saving
+ records["extra_files"] = {
+ ".cache/huggingface/download/model.metadata": "download metadata",
+ ".git/config": "local git metadata",
+ "nested/.cache/huggingface/download/model.lock": "lock",
+ "nested/tokenizer.json": "nested tokenizer",
+ }
+ env["unsloth_generic_push_to_hub_merged"](PeftModel(), "owner/model", create_pr = True)
+ assert set(records["uploads"][0]["files"]) == {*artifacts, "README.md", "nested/tokenizer.json"}
+
+
+def test_none_commit_message_uses_default(saving):
+ env, records, _ = saving
+ env["unsloth_generic_push_to_hub_merged"](
+ FullModel(), "owner/model", create_pr = True, commit_message = None
+ )
+ assert records["uploads"][0]["commit_message"] == "Trained with Unsloth"
+
+
[email protected]("options", [{"revision": "candidate"}, {"create_pr": True}, {}])
+def test_unforced_4bit_rejection_does_not_create_hub_resources(saving, options):
+ env, records, _ = saving
+ with pytest.raises(RuntimeError, match = "merged_4bit_forced"):
+ env["unsloth_generic_push_to_hub_merged"](
+ PeftModel(), "owner/new-model", save_method = "merged_4bit", **options
+ )
+ assert records["repos"] == records["branches"] == records["merges"] == records["uploads"] == []
+
+
+def test_forced_4bit_mode_still_reaches_staged_save(saving):
+ env, records, _ = saving
+ env["unsloth_generic_push_to_hub_merged"](
+ PeftModel(), "owner/model", save_method = "merged_4bit_forced", revision = "candidate"
+ )
+ assert records["merges"][0]["save_method"] == "merged_4bit"
+ assert len(records["uploads"]) == 1
+ assert records["uploads"][0]["revision"] == "candidate"
+
+
[email protected]("create_pr", [False, True])
+def test_missing_destination_branch_is_created(saving, create_pr):
+ env, records, _ = saving
+ records["enforce_revision"] = True
+ env["unsloth_generic_push_to_hub_merged"](
+ FullModel(), "owner/model", revision = "candidate", create_pr = create_pr
+ )
+ assert records["branches"] == [
+ {"repo_id": "owner/model", "repo_type": "model", "branch": "candidate", "exist_ok": True}
+ ]
+ assert records["uploads"][0]["revision"] == "candidate"
+
+
+def test_existing_pull_request_ref_is_not_created_as_a_branch(saving):
+ env, records, _ = saving
+ records["enforce_revision"] = True
+ records["revisions"].add("refs/pr/3")
+ env["unsloth_generic_push_to_hub_merged"](FullModel(), "owner/model", revision = "refs/pr/3")
+ assert records["branches"] == []
+ assert records["uploads"][0]["revision"] == "refs/pr/3"
+
+
[email protected]("create_pr", [False, True])
[email protected]("status", [403, 500])
+def test_branch_errors_allow_only_forbidden_pr_contributions(
+ saving, monkeypatch, create_pr, status
+):
+ import huggingface_hub.hf_api as hf_api
+
+ env, records, _ = saving
+ error = HfHubHTTPError(
+ "branch request failed",
+ response = SimpleNamespace(status_code = status, headers = {}, request = None),
+ )
+ monkeypatch.setattr(
+ hf_api, "get_session", lambda: SimpleNamespace(post = lambda **kwargs: object())
+ )
+
+ def fail_request(response):
+ raise error
+
+ monkeypatch.setattr(hf_api, "hf_raise_for_status", fail_request)
+ api = HfApi(token = False)
+ monkeypatch.setattr(
+ api,
+ "list_repo_refs",
+ lambda **kwargs: SimpleNamespace(branches = [SimpleNamespace(name = "release/candidate")]),
+ )
+ monkeypatch.setattr(
+ env["HfApi"], "create_branch", lambda self, **kwargs: api.create_branch(**kwargs)
+ )
+ kwargs = dict(revision = "release/candidate", create_pr = create_pr)
+ if status == 403 and create_pr:
+ env["unsloth_generic_push_to_hub_merged"](FullModel(), "owner/model", **kwargs)
+ assert records["uploads"][0]["create_pr"] is True
+ assert records["uploads"][0]["revision"] == "release/candidate"
+ else:
+ with pytest.raises(HfHubHTTPError, match = "branch request failed"):
+ env["unsloth_generic_push_to_hub_merged"](FullModel(), "owner/model", **kwargs)
+ assert records["uploads"] == []
+
+
[email protected]("revision", [None, "candidate", "refs/pr/3"])
[email protected]("model_class", [FullModel, PeftModel])
+def test_remote_destination_card_survives(saving, revision, model_class):
+ env, records, _ = saving
+ records["existing_card"] = True
+ records["remote_cards"] = {
+ revision
+ or "main": "---\nlicense: apache-2.0\ntags:\n- custom\ndatasets:\n- owner/original\n---\nCustom destination description"
+ }
+ env["unsloth_generic_push_to_hub_merged"](
+ model_class(),
+ "owner/model",
+ revision = revision,
+ create_pr = revision is None,
+ token = "explicit-fixture",
+ tags = ["fine-tuned"],
+ )
+ card = ModelCard(records["uploads"][0]["files"]["README.md"])
+ assert card.data.license == "apache-2.0"
+ assert card.data.datasets == ["owner/original"]
+ assert card.data.tags == ["custom", "fine-tuned", "unsloth"]
+ assert "Custom destination description" in card.content
+ assert records["downloads"] == [("owner/model", "README.md", revision, "explicit-fixture")]
+
+
[email protected]("revision", [None, "candidate", "refs/pr/3"])
+def test_reused_destination_refreshes_merged_adapter_provenance(saving, revision):
+ env, records, _ = saving
+ records["remote_cards"] = {
+ revision
+ or "main": "---\nbase_model: previous/base\nlicense: mit\ncustom_field: retained\n---\nUser description"
+ }
+ env["unsloth_generic_push_to_hub_merged"](
+ PeftModel(), "owner/model", revision = revision, create_pr = revision is None
+ )
+ card = ModelCard(records["uploads"][0]["files"]["README.md"])
+ assert card.data.base_model == "base/model"
+ assert card.data.license == "mit"
+ assert card.data.to_dict()["custom_field"] == "retained"
+ assert "User description" in card.content
+
+
[email protected]("error", [OSError, LocalEntryNotFoundError])
+def test_card_download_failure_does_not_overwrite_remote_card(saving, error):
+ env, records, _ = saving
+ records["download_error"] = error("connection failed")
+ with pytest.raises(error, match = "connection failed"):
+ env["unsloth_generic_push_to_hub_merged"](FullModel(), "owner/model", create_pr = True)
+ assert records["uploads"] == []
+ assert not any(directory.exists() for directory in records["directories"])
diff --git a/unsloth/save.py b/unsloth/save.py
index 6cdccda3dd2..e37a51dec97 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -5384,6 +5384,101 @@ def save_to_gguf_generic(
return metadata
+def _push_merged_to_hub_revision(save_kwargs):
+ import tempfile
+ from huggingface_hub import CommitOperationAdd, ModelCard, hf_hub_download
+ from huggingface_hub.errors import EntryNotFoundError, HfHubHTTPError, LocalEntryNotFoundError
+ from unsloth_zoo.saving_utils import get_original_model_id
+
+ if not save_kwargs["is_main_process"]:
+ return
+ token = save_kwargs["token"]
+ if token is None:
+ token = get_token()
+ repo_id, username = _determine_username(save_kwargs["save_directory"], None, token)
+ api = HfApi(token = token)
+ api.create_repo(
+ repo_id = repo_id,
+ repo_type = "model",
+ private = save_kwargs["private"],
+ exist_ok = True,
+ )
+ revision = save_kwargs["revision"]
+ if revision is not None and not revision.startswith("refs/pr/"):
+ try:
+ api.create_branch(repo_id = repo_id, repo_type = "model", branch = revision, exist_ok = True)
+ except HfHubHTTPError as error:
+ # PR contributions do not require branch-write permission.
+ if not save_kwargs["create_pr"] or error.response.status_code != 403:
+ raise
+ with tempfile.TemporaryDirectory(prefix = "unsloth-merged-") as directory:
+ unsloth_generic_save(
+ **{**save_kwargs, "save_directory": directory, "push_to_hub": False, "token": token}
+ )
+ card_path = Path(directory) / "README.md"
+ try:
+ remote_card_path = hf_hub_download(
+ repo_id = repo_id,
+ filename = "README.md",
+ repo_type = "model",
+ revision = revision,
+ token = token,
+ )
+ card = ModelCard.load(remote_card_path)
+ except LocalEntryNotFoundError:
+ raise
+ except EntryNotFoundError:
+ card = ModelCard.load(card_path) if card_path.is_file() else None
+ model = save_kwargs["model"]
+ if card is None or isinstance(model, PeftModel):
+ base_model = model.config._name_or_path
+ if os.path.isdir(base_model):
+ original_model_id = get_original_model_id(base_model)
+ base_model = (
+ original_model_id
+ if original_model_id is not None and not os.path.exists(original_model_id)
+ else repo_id
+ )
+ if card is None:
+ card = ModelCard(
+ MODEL_CARD.format(
+ username = username,
+ base_model = base_model,
+ model_type = model.config.model_type,
+ method = "",
+ extra = "unsloth",
+ )
+ )
+ if isinstance(model, PeftModel):
+ card.data.base_model = base_model
+ if save_kwargs["datasets"]:
+ card.data.datasets = save_kwargs["datasets"]
+ card.data.tags = list(
+ dict.fromkeys([*(card.data.tags or []), *(save_kwargs["tags"] or []), "unsloth"])
+ )
+ card.save(card_path)
+ return api.create_commit(
+ repo_id = repo_id,
+ repo_type = "model",
+ operations = [
+ CommitOperationAdd(
+ path_in_repo = path.relative_to(directory).as_posix(), path_or_fileobj = path
+ )
+ for path in sorted(Path(directory).rglob("*"))
+ if path.is_file()
+ and not {".cache", ".git"}.intersection(path.relative_to(directory).parts)
+ ],
+ revision = save_kwargs["revision"],
+ create_pr = save_kwargs["create_pr"],
+ commit_message = (
+ save_kwargs["commit_message"]
+ if save_kwargs["commit_message"] is not None
+ else "Trained with Unsloth"
+ ),
+ commit_description = save_kwargs["commit_description"],
+ )
+
+
@_normalize_tied_weights_keys_for_save
@torch.inference_mode
def unsloth_generic_save(
@@ -5411,12 +5506,6 @@ def unsloth_generic_save(
maximum_memory_usage: float = 0.9,
datasets: Optional[List[str]] = None,
):
- if isinstance(tokenizer, (PreTrainedTokenizerBase, ProcessorMixin)):
- tokenizer = patch_saving_functions(tokenizer)
-
- if token is None and push_to_hub:
- token = get_token()
-
if save_method == "merged_4bit":
raise RuntimeError(
"Unsloth: Merging into 4bit will cause your model to lose accuracy if you plan\n"
@@ -5424,7 +5513,17 @@ def unsloth_generic_save(
"if you're planning to do multiple saves.\n"
"If you are certain, change `save_method` to `merged_4bit_forced`."
)
- elif save_method == "merged_4bit_forced":
+
+ if push_to_hub and (create_pr or revision is not None):
+ return _push_merged_to_hub_revision(dict(locals()))
+
+ if isinstance(tokenizer, (PreTrainedTokenizerBase, ProcessorMixin)):
+ tokenizer = patch_saving_functions(tokenizer)
+
+ if token is None and push_to_hub:
+ token = get_token()
+
+ if save_method == "merged_4bit_forced":
save_method = "merged_4bit"
# Full-finetuned models have no adapters to merge, so fall back to save_pretrained, mirroring the torchao and GGUF save paths.