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.

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.py
index 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.py
new file mode 100644
index 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.py
index 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.py
index b75fb20d75c..4e369a30010 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -94,6 +94,33 @@ except:
from pathlib import Path
from 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] = None
if j % 10 == 0:
clean_gpu_cache()
- gc.collect()
state_dict = None
del state_dict
clean_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()
return
arguments = 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()
return
arguments = 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()
return
arguments = 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()
return
arguments = 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")