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
Saving: stop repeated gc.collect passes once a pass finds nothing (#15694)
Daniel Han3d7e798caf75
diff --git a/tests/saving/test_save_method_lora_routing.py b/tests/saving/test_save_method_lora_routing.pyindex 6f293df21a5..c941fcb88df 100644--- a/tests/saving/test_save_method_lora_routing.py+++ b/tests/saving/test_save_method_lora_routing.py@@ -238,6 +238,7 @@ def _routing_environment(monkeypatch, model):namespace = _load(*_GENERIC_SAVE_REAL_HELPERS,+ "_collect_garbage","unsloth_generic_save",os = os,json = json,@@ -262,7 +263,7 @@ def _routing_environment(monkeypatch, model):calls["convert"].append(model) or contextlib.nullcontext()),logger = types.SimpleNamespace(warning_once = lambda *a, **k: None),- gc = types.SimpleNamespace(collect = lambda: None),+ gc = types.SimpleNamespace(collect = lambda: None, get_stats = lambda: [{}, {}, {}]),torch = types.SimpleNamespace(bfloat16 = "bfloat16",float16 = "float16",@@ -411,6 +412,7 @@ def _adapter_save_environment(monkeypatch):return _load("_normalize_safe_serialization","_filter_push_to_hub_kwargs",+ "_collect_garbage","unsloth_save_model",PreTrainedTokenizerBase = type("Tokenizer", (), {}),ProcessorMixin = type("Processor", (), {}),@@ -418,7 +420,7 @@ def _adapter_save_environment(monkeypatch):get_token = lambda: "fixture-token",upload_to_huggingface = upload_to_huggingface,logger = types.SimpleNamespace(warning_once = lambda *a, **k: None),- gc = types.SimpleNamespace(collect = lambda: None),+ gc = types.SimpleNamespace(collect = lambda: None, get_stats = lambda: [{}, {}, {}]),psutil = types.SimpleNamespace(cpu_count = lambda logical = True: 8),torch = types.SimpleNamespace(save = lambda *args, **kwargs: None,diff --git a/tests/test_gc_collect_early_stop.py b/tests/test_gc_collect_early_stop.pynew file mode 100644index 00000000000..f07065a812e--- /dev/null+++ b/tests/test_gc_collect_early_stop.py@@ -0,0 +1,170 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""save.py's repeated gc.collect() passes stop once a pass that really ran finds nothing."""++from __future__ import annotations++import ast+import gc as real_gc+import threading+import time+from pathlib import Path+from types import SimpleNamespace++import pytest++SAVE_PY = Path(__file__).resolve().parents[1] / "unsloth" / "save.py"+CALL_SITES = 26+++def _tree():+ return ast.parse(SAVE_PY.read_text(encoding = "utf-8"))+++def _function(tree, name):+ return next(n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.name == name)+++def _is_collect(node):+ return (+ isinstance(node, ast.Call)+ and isinstance(node.func, ast.Attribute)+ and node.func.attr == "collect"+ and getattr(node.func.value, "id", None) == "gc"+ )+++def _helper(gc):+ namespace = {"gc": gc}+ fn = _function(_tree(), "_collect_garbage")+ exec(compile(ast.Module([fn], []), str(SAVE_PY), "exec"), namespace)+ return namespace["_collect_garbage"]+++class _FakeGC:+ """ "skip" = a pass that returns 0 without collecting (another thread is mid-collection)."""++ def __init__(+ self,+ script,+ callbacks = (),+ ):+ self.script = iter(script)+ self.callbacks = list(callbacks)+ self.stats = {"collections": 0, "collected": 0, "uncollectable": 0}+ self.calls = 0++ def get_stats(self):+ return [{}, {}, dict(self.stats)]++ def collect(self):+ self.calls += 1+ result = next(self.script)+ if result == "skip":+ return 0+ self.stats["collections"] += 1+ self.stats["collected"] += result or 0+ return result+++ "script,expected",+ [+ ([5, 0, 7], 2),+ ([0, 9, 9], 1),+ ([4, 2, 1], 3),+ ([None, None, None], 3), # gc.collect replaced (vLLM graph capture): never "found nothing"+ (["skip", 0, 9], 2), # a skipped pass is not proof the heap is quiet+ (["skip", "skip", "skip"], 3),+ ],+)+def test_stops_after_a_pass_that_ran_and_found_nothing(script, expected):+ gc = _FakeGC(script)+ order = []+ _helper(gc)(before = lambda: order.append("before"), after = lambda: order.append("after"))+ assert gc.calls == expected+ assert order == ["before", "after"] * expected+++def test_keeps_every_pass_with_gc_callbacks():+ gc = _FakeGC([0, 0, 0], callbacks = [print])+ _helper(gc)()+ assert gc.calls == 3+++def test_a_pass_skipped_for_another_threads_collection_does_not_end_it():+ # Thread A is mid-collection, so our first pass returns 0 without collecting.+ collect_garbage = _helper(real_gc)+ started, release = threading.Event(), threading.Event()++ class Slow:+ def __init__(self):+ self.me = self++ def __del__(self):+ started.set()+ release.wait(30)++ class Ours:+ def __init__(self):+ self.me = self++ was_enabled = real_gc.isenabled()+ real_gc.disable()+ a = threading.Thread(target = real_gc.collect)+ try:+ real_gc.collect()+ Slow()+ a.start()+ assert started.wait(30)+ for _ in range(5):+ Ours()+ passes = []++ def before():+ if passes:+ release.set()+ a.join(30)+ passes.append(1)++ collect_garbage(before = before)+ assert len(passes) == 3+ assert not any(type(o) is Ours for o in real_gc.get_objects())+ finally:+ release.set()+ a.join(30)+ if was_enabled:+ real_gc.enable()+++def test_every_repeated_collect_in_save_py_goes_through_the_helper():+ tree = _tree()+ helper = _function(tree, "_collect_garbage")+ inside = set(map(id, ast.walk(helper)))+ loops = [+ n.lineno+ for n in ast.walk(tree)+ if isinstance(n, (ast.For, ast.While))+ and id(n) not in inside+ and any(_is_collect(c) for c in ast.walk(n))+ ]+ assert loops == []+ calls = [+ n+ for n in ast.walk(tree)+ if isinstance(n, ast.Call) and getattr(n.func, "id", None) == "_collect_garbage"+ ]+ assert len(calls) == CALL_SITES+++def test_unsloth_save_model_releases_state_dict_with_one_collect():+ fn = _function(_tree(), "unsloth_save_model")+ loop = next(+ n+ for n in ast.walk(fn)+ if isinstance(n, ast.For) and ast.unparse(n.iter) == "enumerate(state_dict.items())"+ )+ assert not any(_is_collect(c) for c in ast.walk(loop))+ after = fn.body[fn.body.index(loop) + 1 :]+ assert any(_is_collect(c) for stmt in after[:4] for c in ast.walk(stmt))diff --git a/tests/test_merged_hub_destination.py b/tests/test_merged_hub_destination.pyindex 56ef55cfb66..58e2b76c802 100644--- a/tests/test_merged_hub_destination.py+++ b/tests/test_merged_hub_destination.py@@ -196,6 +196,7 @@ def saving(monkeypatch, tmp_path):"_refuse_unsaveable_text_core","_cast_state_dict_16bit","_requests_float32",+ "_collect_garbage",}nodes = []for node in tree.body:diff --git a/unsloth/save.py b/unsloth/save.pyindex b75fb20d75c..4e369a30010 100644--- a/unsloth/save.py+++ b/unsloth/save.py@@ -94,6 +94,33 @@ except:from pathlib import Pathfrom peft import PeftModelForCausalLM, PeftModel++def _collect_garbage(+ passes = 3,+ before = None,+ after = None,+):+ """Up to `passes` gc.collect() passes; stops after one that ran and found nothing (it ran no finalizer, so+ the next finds nothing either). gc.callbacks, a non-zero result, or a pass skipped while another thread+ collects (returns 0, stats unmoved) keep every pass."""+ for _ in range(passes):+ if before is not None:+ before()+ seen = gc.get_stats()[2]+ found = gc.collect()+ ran = gc.get_stats()[2]+ if after is not None:+ after()+ if (+ found == 0+ and not gc.callbacks+ and ran["collections"] == seen["collections"] + 1+ and ran["collected"] == seen["collected"]+ and ran["uncollectable"] == seen["uncollectable"]+ ):+ break++__all__ = ["print_quantization_methods","unsloth_save_model",@@ -1460,9 +1487,7 @@ def unsloth_save_model(assert maximum_memory_usage > 0 and maximum_memory_usage <= 0.95- for _ in range(3):- clean_gpu_cache()- gc.collect()+ _collect_garbage(before = clean_gpu_cache)save_method = save_method.lower().replace(" ", "_")raise_if_merging_mistral_format_view(model, save_method)@@ -1965,11 +1990,11 @@ def unsloth_save_model(save_pretrained_settings["state_dict"] = None+ # No collect per entry: the loop allocates nothing, so the collect below finds the same cycles.for j, (key, value) in enumerate(state_dict.items()):state_dict[key] = Noneif j % 10 == 0:clean_gpu_cache()- gc.collect()state_dict = Nonedel state_dictclean_gpu_cache()@@ -1977,9 +2002,7 @@ def unsloth_save_model(shutil.rmtree(temporary_location, ignore_errors = True)- for _ in range(3):- clean_gpu_cache()- gc.collect()+ _collect_garbage(before = clean_gpu_cache)return save_directory, username@@ -2900,8 +2923,7 @@ def unsloth_save_pretrained_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()return_torchao = _normalize_torchao_method(save_method)@@ -2927,8 +2949,7 @@ def unsloth_save_pretrained_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()returnarguments = dict(locals())@@ -2943,8 +2964,7 @@ def unsloth_save_pretrained_merged(del arguments["max_seq_length"]del arguments["install_missing_dependencies"]unsloth_save_model(**arguments)- for _ in range(3):- gc.collect()+ _collect_garbage()@_model_parallel_refuses_save("push_to_hub_merged")@@ -3026,8 +3046,7 @@ def unsloth_push_to_hub_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()return_torchao = _normalize_torchao_method(save_method)@@ -3055,8 +3074,7 @@ def unsloth_push_to_hub_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()returnarguments = dict(locals())@@ -3072,8 +3090,7 @@ def unsloth_push_to_hub_merged(del arguments["max_seq_length"]del arguments["install_missing_dependencies"]unsloth_save_model(**arguments)- for _ in range(3):- gc.collect()+ _collect_garbage()MODEL_CARD = """---@@ -4864,10 +4881,7 @@ def unsloth_save_pretrained_gguf(if is_processor:tokenizer = tokenizer.tokenizer- for _ in range(3):- import gc- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)try:model_dtype = dtype_from_config(self.config)@@ -6952,8 +6966,7 @@ def unsloth_generic_save_pretrained_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()return_torchao = _normalize_torchao_method(save_method)@@ -6979,8 +6992,7 @@ def unsloth_generic_save_pretrained_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()returnarguments = dict(locals())@@ -6993,8 +7005,7 @@ def unsloth_generic_save_pretrained_merged(del arguments["max_seq_length"]del arguments["install_missing_dependencies"]unsloth_generic_save(**arguments)- for _ in range(3):- gc.collect()+ _collect_garbage()# Like save_pretrained_merged: every rank calls it, rank 0 gathers, merges and uploads.@@ -7102,8 +7113,7 @@ def unsloth_generic_push_to_hub_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()return_torchao = _normalize_torchao_method(save_method)@@ -7131,8 +7141,7 @@ def unsloth_generic_push_to_hub_merged(maximum_memory_usage = maximum_memory_usage,datasets = datasets,)- for _ in range(3):- gc.collect()+ _collect_garbage()returnarguments = dict(locals())@@ -7148,8 +7157,7 @@ def unsloth_generic_push_to_hub_merged(del arguments["max_seq_length"]del arguments["install_missing_dependencies"]unsloth_generic_save(**arguments)- for _ in range(3):- gc.collect()+ _collect_garbage()def _unsloth_save_torchao_with_attached_config(@@ -7309,8 +7317,7 @@ def _unsloth_save_torchao_with_given_config(if untied_lm_head is not None:_untie_merged_checkpoint(save_directory, *untied_lm_head)- for _ in range(3):- gc.collect()+ _collect_garbage()from transformers import (AutoModelForCausalLM,@@ -7342,9 +7349,7 @@ def _unsloth_save_torchao_with_given_config(# Else the original stays resident on every GPU while device_map="auto" below loads a second copy.model_restore = _offload_model_for_quantize_subprocess(model)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)# The original stays offloaded until the quantized copy is saved AND released, else both are resident at once and the restore OOMs.try:@@ -7381,9 +7386,7 @@ def _unsloth_save_torchao_with_given_config(_exc = sys.exc_info()[1]if _exc is not None:traceback.clear_frames(_exc.__traceback__)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)_restore_model_after_quantize_subprocess(model, model_restore)if os.path.exists(save_directory):@@ -7880,9 +7883,7 @@ def _unsloth_save_compressed_tensors(# Free the in-memory model's CUDA memory before the subprocess loads its own copy, so the GPUs need not hold both. Best-effort, restored in finally.model_restore = _offload_model_for_quantize_subprocess(model)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)# Same boundary as the LoRA GGUF converter: False scrubs, it does not merely withhold.env = os.environ.copy()@@ -7946,9 +7947,7 @@ def _unsloth_save_compressed_tensors(shutil.rmtree(calib_tmp, ignore_errors = True)if work_tmp is not None:shutil.rmtree(work_tmp, ignore_errors = True)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)@_model_parallel_refuses_save("save_pretrained_torchao")@@ -8075,9 +8074,7 @@ def _unsloth_save_torchao(# Free the in-memory model's accelerator memory before reloading from disk, else it sits beside the copy and OOMs a device that fit the model once. Covers CUDA, XPU and multi-GPU dispatched shards, which a plain .to("cpu") cannot move.model_restore = _offload_model_for_quantize_subprocess(model)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)# Reload the staged 16bit checkpoint with torchao applied: bfloat16 is required, and device_map="auto" falls back to CPU, so this works on any hardware.print(f"Unsloth: Quantizing the merged model to torchao {kind}...")@@ -8096,9 +8093,7 @@ def _unsloth_save_torchao(quantized_model.save_pretrained(out_dir, safe_serialization = safe_serialization)staged_tokenizer.save_pretrained(out_dir)del quantized_model- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)cfg_path = os.path.join(out_dir, "config.json")cfg = {}@@ -8146,15 +8141,11 @@ def _unsloth_save_torchao(_exc = sys.exc_info()[1]if _exc is not None:traceback.clear_frames(_exc.__traceback__)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)_restore_model_after_quantize_subprocess(model, model_restore)if work_tmp is not None:shutil.rmtree(work_tmp, ignore_errors = True)- for _ in range(3):- gc.collect()- clean_gpu_cache()+ _collect_garbage(after = clean_gpu_cache)# Must match qat_scheme="int8-int4"; export_llm defaults (group_size 128, use_hqq true) do not.@@ -8279,8 +8270,7 @@ def unsloth_save_pretrained_torchao(model_type = getattr(getattr(self, "config", None), "model_type", None),)- for _ in range(3):- gc.collect()+ _collect_garbage()# quantization_type -> `optimum-cli export openvino` options. None and "fp16" still name a weight format: with none, optimum-intel int8-compresses every model over 1B parameters.@@ -8542,8 +8532,7 @@ def _unsloth_save_openvino(return os.fspath(save_directory)finally:shutil.rmtree(work_tmp, ignore_errors = True)- for _ in range(3):- gc.collect()+ _collect_garbage()@_model_parallel_refuses_save("save_pretrained_openvino")