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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
"""Patched TRL configs must stay picklable by `torch.save`, and the file must load without Unsloth."""
from __future__ import annotations
import dataclasses
import json
import os
import pickle
import subprocess
import sys
import pytest
pytest.importorskip("trl")
@pytest.fixture(scope = "module")
def patched():
import unsloth # noqa: F401
import trl.trainer.sft_config as config_module
return config_module.SFTConfig
def _make(config_class, output_dir):
"""Pins CPU, since TRL turns bf16=None into True and transformers refuses without an accelerator."""
kwargs = {"output_dir": str(output_dir)}
declared = (
{field.name for field in dataclasses.fields(config_class)}
if dataclasses.is_dataclass(config_class)
else None
)
for name, value in (("bf16", False), ("fp16", False), ("use_cpu", True)):
if declared is None or name in declared:
kwargs[name] = value
return config_class(**kwargs)
def test_patched_config_answers_to_the_trl_name(patched):
# Otherwise the class pickles under a compiled-cache module unreadable elsewhere.
assert patched.__module__ == "trl.trainer.sft_config"
assert patched.__qualname__ == "SFTConfig"
import trl.trainer.sft_config as config_module
assert getattr(config_module, "SFTConfig") is patched
def test_pristine_config_instance_still_pickles(patched, tmp_path):
pristine = patched.__mro__[1]
assert not pristine.__name__.startswith("Unsloth")
args = _make(pristine, tmp_path)
restored = pickle.loads(pickle.dumps(args))
assert restored.output_dir == args.output_dir
def test_patched_config_instance_pickles(patched, tmp_path):
args = _make(patched, tmp_path)
restored = pickle.loads(pickle.dumps(args))
assert restored.output_dir == args.output_dir
@pytest.mark.parametrize("use_pristine", [False, True])
def test_torch_save_load_round_trip(patched, tmp_path, use_pristine):
torch = pytest.importorskip("torch")
config_class = patched.__mro__[1] if use_pristine else patched
args = _make(config_class, tmp_path)
path = tmp_path / f"training_args_{int(use_pristine)}.bin"
torch.save(args, path)
restored = torch.load(path, weights_only = False)
assert restored.output_dir == args.output_dir
assert restored.max_steps == args.max_steps
def test_checkpoint_loads_without_unsloth(patched, tmp_path):
"""Checkpoints pickled under the TRL name must open where only transformers and TRL exist."""
torch = pytest.importorskip("torch")
path = tmp_path / "training_args.bin"
torch.save(_make(patched, tmp_path), path)
script = (
# Baseline first; an editable install's import finder is already in sys.modules.
"import sys\n"
"preloaded = set(sys.modules)\n"
"import json, torch\n"
"obj = torch.load(sys.argv[1], weights_only = False)\n"
"leaked = sorted(\n"
" m for m in set(sys.modules) - preloaded\n"
" if 'unsloth' in m.lower() or m.startswith('Unsloth')\n"
")\n"
"print(json.dumps({\n"
" 'cls': type(obj).__module__ + '.' + type(obj).__name__,\n"
" 'output_dir': obj.output_dir,\n"
" 'leaked': leaked,\n"
"}))\n"
)
env = dict(os.environ)
env.pop("PYTHONPATH", None)
env.pop("UNSLOTH_COMPILE_LOCATION", None)
process = subprocess.run(
[sys.executable, "-c", script, str(path)],
capture_output = True,
text = True,
env = env,
cwd = str(tmp_path),
)
assert process.returncode == 0, process.stderr[-3000:]
result = json.loads(process.stdout.strip().splitlines()[-1])
assert result["cls"] == "trl.trainer.sft_config.SFTConfig", result
assert result["output_dir"] == str(tmp_path)
assert result["leaked"] == [], result
def test_training_arguments_conversion_keeps_unsloth_fields(patched, tmp_path):
"""TRL converts a plain `TrainingArguments` with `args = SFTConfig(**dict_args)`.
That has to land on the Unsloth subclass, or the config reaches the trainer
without the fields the patched trainer reads (unslothai/unsloth#3931)."""
pytest.importorskip("transformers")
from transformers import TrainingArguments
import inspect
generated = sys.modules.get("UnslothSFTTrainer")
if generated is None:
pytest.skip("UnslothSFTTrainer compiled module not loaded")
source = inspect.getsource(generated._UnslothSFTTrainer.__init__)
if "dict_args" not in source:
pytest.skip("this TRL release does not convert TrainingArguments inline")
# The bare TRL global was imported before patching and points at the pristine class.
assert "args = UnslothSFTConfig(**dict_args)" in source, source[:2000]
training_arguments = TrainingArguments(
output_dir = str(tmp_path),
bf16 = False,
fp16 = False,
use_cpu = True,
)
dict_args = training_arguments.to_dict()
dict_args["hub_token"] = training_arguments.hub_token
dict_args.pop("push_to_hub_token", None)
converted = generated.UnslothSFTConfig(**dict_args)
assert isinstance(converted, patched)
assert hasattr(converted, "unsloth_num_chunks")
assert pickle.loads(pickle.dumps(converted)).output_dir == str(tmp_path)
def test_every_patched_config_pickles_portably(tmp_path):
"""Sweep: no patched config may pickle under a compiled-cache module."""
import trl
import unsloth # noqa: F401
checked = 0
for name in sorted(x for x in dir(trl) if x.endswith("Config")):
config_class = getattr(trl, name)
if not isinstance(config_class, type):
continue
try:
args = _make(config_class, tmp_path)
except TypeError:
continue
pickle.dumps(args, protocol = 2)
assert not config_class.__module__.startswith("Unsloth"), (
f"{name} pickles under {config_class.__module__}, which does not exist "
"without a compiled cache"
)
checked += 1
assert checked > 0, "no TRL configs were exercised"
def _assert_the_patch_applied(patched):
"""Fails with the cause when the patch fell back, so tests do not describe TRL's own class."""
assert getattr(patched, "_unsloth_patched_rl_config", False), (
f"trl.SFTConfig is {patched.__name__!r} from {patched.__module__!r} but carries "
"no _unsloth_patched_rl_config, so Unsloth's RL patch fell back and these tests "
"are describing TRL's own class. `import unsloth` reports the cause as a warning "
"(_patch_trl_rl_trainers in unsloth/models/rl.py), not an error."
)
def test_patched_config_still_subclasses_the_pristine_one(patched):
"""The patched class takes TRL's name, so a later patch pass must not make it its own base."""
_assert_the_patch_applied(patched)
base = patched.__mro__[1]
assert base is not patched
assert base.__name__ == "SFTConfig"
assert base.__module__.startswith("trl.")
assert "_unsloth_patched_rl_config" not in base.__dict__
def test_reducer_registration_is_idempotent(patched, tmp_path):
"""Patching can run more than once; it must not stack reducers or recurse."""
import copyreg
from unsloth.models.rl import _patch_trl_rl_trainers
import trl.trainer.sft_config as config_module
before = len(copyreg.dispatch_table)
for _ in range(3):
_patch_trl_rl_trainers("sft_trainer")
assert len(copyreg.dispatch_table) == before, "reducers stacked on re-patch"
assert config_module.SFTConfig is patched, "re-patching swapped the class"
assert pickle.loads(pickle.dumps(_make(patched, tmp_path))).output_dir == str(tmp_path)
def test_a_displaced_sibling_wrapper_is_covered(patched, tmp_path):
"""TRL's shim configs are siblings of the patched class, so a subclass-only guard misses them."""
import copyreg
from unsloth.models.rl import (
_UNSLOTH_CONFIG_PICKLE_TARGET,
_register_config_pickle_fallback,
)
experimental_parent = patched.__mro__[1]
class _Shim(experimental_parent):
pass
assert not issubclass(patched, _Shim), "not the sibling shape this test is about"
registered = copyreg.dispatch_table.get(_Shim)
try:
_register_config_pickle_fallback(_Shim, patched)
assert copyreg.dispatch_table.get(_Shim) is not None, "sibling shim left unregistered"
assert getattr(_Shim, _UNSLOTH_CONFIG_PICKLE_TARGET, None) is patched
restored = pickle.loads(pickle.dumps(_make(_Shim, tmp_path)))
assert restored.output_dir == str(tmp_path)
assert type(restored) is patched
finally:
copyreg.dispatch_table.pop(_Shim, None)
if registered is not None:
copyreg.dispatch_table[_Shim] = registered
def test_an_unrelated_class_is_not_reduced_through_the_patched_one(patched):
"""Unrelated classes must not be rebuilt as the patched one, or their fields silently drop."""
import copyreg
from unsloth.models.rl import _register_config_pickle_fallback
class _Unrelated:
pass
_register_config_pickle_fallback(_Unrelated, patched)
assert _Unrelated not in copyreg.dispatch_table
# trl -> config -> unsloth ordering needs a fresh subprocess; unsloth is already imported here.
_PRISTINE_PROBE = r"""
import json, os, pickle, sys, tempfile
from trl import SFTConfig as pristine
import trl.trainer.sft_config as config_module
result = {"captured_pristine": config_module.SFTConfig is pristine}
config = pristine(output_dir = "unused", bf16 = False, fp16 = False, use_cpu = True)
import unsloth
from unsloth import FastLanguageModel
import torch
result["rebound"] = config_module.SFTConfig is not pristine
try:
pickle.dumps(config)
result["pickle"] = "ok"
except Exception as error:
result["pickle"] = "%s: %s" % (type(error).__name__, error)
try:
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "training_args.bin")
torch.save(config, path)
restored = torch.load(path, weights_only = False)
assert restored.output_dir == "unused"
assert restored.per_device_train_batch_size == config.per_device_train_batch_size
result["torch_round_trip"] = "ok"
except Exception as error:
result["torch_round_trip"] = "%s: %s" % (type(error).__name__, error)
print("UNSLOTH_PROBE " + json.dumps(result))
"""
@pytest.fixture(scope = "module")
def pristine_probe(tmp_path_factory):
environment = dict(os.environ)
environment["UNSLOTH_COMPILE_LOCATION"] = str(tmp_path_factory.mktemp("compiled_cache"))
finished = subprocess.run(
[sys.executable, "-c", _PRISTINE_PROBE],
capture_output = True,
text = True,
timeout = 1800,
env = environment,
)
marker = [line for line in finished.stdout.splitlines() if line.startswith("UNSLOTH_PROBE ")]
if not marker:
pytest.skip(
"could not run the trl-before-unsloth probe:\n"
f"{finished.stdout[-2000:]}\n{finished.stderr[-2000:]}"
)
payload = json.loads(marker[-1][len("UNSLOTH_PROBE ") :])
if not payload.get("captured_pristine"):
pytest.skip("trl was already patched before the probe captured the class")
if not payload.get("rebound"):
pytest.skip("this TRL/Unsloth pair does not rebind the config module")
return payload
def test_config_captured_before_patching_still_pickles(pristine_probe):
"""The reported regression, in the order it was reported."""
assert pristine_probe["pickle"] == "ok", pristine_probe["pickle"]
def test_config_captured_before_patching_survives_torch_save(pristine_probe):
"""Mirrors `Trainer._save`, which is where the crash surfaced."""
assert pristine_probe["torch_round_trip"] == "ok", pristine_probe["torch_round_trip"]