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.

MLX: build trl.__all__ on first read instead of importing every TRL export at import (#15561)

Daniel Han80fcd255606c
diff --git a/tests/test_mlx_trl_lazy_all.py b/tests/test_mlx_trl_lazy_all.py
new file mode 100644
index 00000000000..8609bc8128f
--- /dev/null
+++ b/tests/test_mlx_trl_lazy_all.py
@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+"""On MLX, trl.__all__ is filtered on first read: resolving every name at import pulled torch in."""
+
+import importlib.util
+import pathlib
+import platform
+import subprocess
+import sys
+import types
+
+import pytest
+
+_PATH = pathlib.Path(__file__).resolve().parents[1] / "unsloth" / "_mlx_trl_all.py"
+
+
+def lazy_all():
+ spec = importlib.util.spec_from_file_location("_unsloth_mlx_trl_all_under_test", _PATH)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _filter(trl, names):
+ """Same contract as unsloth's _safe_mlx_trl_star_exports."""
+ kept = []
+ for name in names:
+ try:
+ getattr(trl, name)
+ except Exception:
+ continue
+ kept.append(name)
+ for name in ("SFTConfig", "SFTTrainer"):
+ if name not in kept:
+ kept.append(name)
+ return kept
+
+
+class _LazyLike(types.ModuleType):
+ """trl's _LazyModule shape: a class-level __getattr__ importing on demand."""
+
+ def __init__(self, name, lazy):
+ super().__init__(name)
+ self._lazy = lazy
+ self.resolved = []
+ self.__all__ = list(lazy)
+
+ def __getattr__(self, name):
+ if name not in self._lazy:
+ raise AttributeError(name)
+ self.resolved.append(name)
+ value = self._lazy[name]()
+ setattr(self, name, value)
+ return value
+
+
+def _broken():
+ raise RuntimeError("optional dependency missing")
+
+
+def test_nothing_resolves_until_all_is_read(lazy_all, monkeypatch):
+ trl = _LazyLike("trl", {"DataCollator": object, "Broken": _broken, "GRPOTrainer": object})
+ trl.SFTTrainer = trl.SFTConfig = object
+ lazy_all.install_lazy_trl_all(trl, _filter)
+ assert trl.resolved == []
+ assert lazy_all.raw_trl_all(trl) == ["DataCollator", "Broken", "GRPOTrainer"]
+ assert trl.resolved == []
+ assert trl.__all__ == ["DataCollator", "GRPOTrainer", "SFTConfig", "SFTTrainer"]
+ assert sorted(trl.resolved) == ["Broken", "DataCollator", "GRPOTrainer"]
+ # Cached: a second read resolves nothing more.
+ trl.resolved.clear()
+ assert trl.__all__[-1] == "SFTTrainer" and trl.resolved == []
+ monkeypatch.setitem(sys.modules, "trl", trl)
+ namespace = {}
+ exec("from trl import *", namespace)
+ assert set(namespace) - {"__builtins__"} == {
+ "DataCollator",
+ "GRPOTrainer",
+ "SFTConfig",
+ "SFTTrainer",
+ }
+
+
+def test_class_level_getattr_still_serves_other_names(lazy_all):
+ trl = _LazyLike("trl", {"DataCollator": lambda: "collator"})
+ lazy_all.install_lazy_trl_all(trl, _filter)
+ assert trl.DataCollator == "collator"
+ with pytest.raises(AttributeError):
+ trl.missing_name
+ assert "DataCollator" in dir(trl)
+
+
+def test_module_dict_getattr_is_chained(lazy_all):
+ trl = types.ModuleType("trl")
+ trl.ExistingExport = object()
+ trl.__all__ = ["ExistingExport", "BrokenExport"]
+
+ def _module_getattr(name):
+ if name == "BrokenExport":
+ raise RuntimeError("optional dependency missing")
+ raise AttributeError(name)
+
+ trl.__getattr__ = _module_getattr
+ lazy_all.install_lazy_trl_all(trl, _filter)
+ with pytest.raises(RuntimeError):
+ trl.BrokenExport
+ assert trl.__all__ == ["ExistingExport", "SFTConfig", "SFTTrainer"]
+
+
+def test_reinstall_keeps_the_original_names_and_getattr(lazy_all):
+ trl = types.ModuleType("trl")
+ trl.__all__ = ["A"]
+ trl.A = 1
+ original = lambda name: (_ for _ in ()).throw(AttributeError(name)) # noqa: E731
+ trl.__getattr__ = original
+ lazy_all.install_lazy_trl_all(trl, _filter)
+ assert trl.__all__ == ["A", "SFTConfig", "SFTTrainer"]
+ lazy_all.install_lazy_trl_all(trl, _filter)
+ assert lazy_all.raw_trl_all(trl) == ["A"]
+ assert trl.__getattr__._unsloth_previous is original
+ assert trl.__all__ == ["A", "SFTConfig", "SFTTrainer"]
+
+
+def test_module_without_all(lazy_all):
+ trl = types.ModuleType("trl")
+ lazy_all.install_lazy_trl_all(trl, _filter)
+ assert trl.__all__ == ["SFTConfig", "SFTTrainer"]
+
+
+def test_a_reentrant_all_read_during_filtering_sees_the_raw_names(lazy_all):
+ install_lazy_trl_all = lazy_all.install_lazy_trl_all
+
+ trl = types.ModuleType("fake_trl_reentrant")
+ trl.__all__ = ["A", "B"]
+ seen = []
+
+ def filter_exports(module, names):
+ # An export whose import reads trl.__all__ again mid-filter.
+ seen.append(list(module.__all__))
+ return [n for n in names if n != "B"]
+
+ install_lazy_trl_all(trl, filter_exports)
+ assert trl.__all__ == ["A"]
+ assert seen == [["A", "B"]]
+ assert trl.__all__ == ["A"]
+
+
+class _LazyDirLike(_LazyLike):
+ """trl's _LazyModule.__dir__: the namespace listing, then any __all__ name not in it."""
+
+ def __dir__(self):
+ result = super().__dir__()
+ for attr in self.__all__:
+ if attr not in result:
+ result.append(attr)
+ return result
+
+
[email protected]("dir_first", [True, False])
+def test_dir_matches_the_eager_filter(lazy_all, dir_first):
+ def make():
+ trl = _LazyDirLike(
+ "trl", {"DataCollator": object, "Broken": _broken, "GRPOTrainer": object}
+ )
+ trl.SFTTrainer = trl.SFTConfig = object
+ return trl
+
+ eager = make()
+ eager.__all__ = _filter(eager, list(eager.__all__))
+ lazy = make()
+ lazy_all.install_lazy_trl_all(lazy, _filter)
+ if dir_first:
+ listed = dir(lazy)
+ assert lazy.__all__ == eager.__all__
+ else:
+ assert lazy.__all__ == eager.__all__
+ listed = dir(lazy)
+ assert listed == dir(eager)
+ # Built: no hook or bookkeeping name is left in trl's namespace.
+ assert not {"__getattr__", "__dir__", "_unsloth_mlx_trl_all"} & set(vars(lazy))
+
+
+ platform.system() != "Darwin"
+ or platform.machine() != "arm64"
+ or importlib.util.find_spec("mlx") is None
+ or importlib.util.find_spec("trl") is None,
+ reason = "the real MLX import path needs Apple Silicon with mlx and trl",
+)
+def test_real_mlx_import_leaves_trl_all_unbuilt():
+ probe = (
+ "import sys, unsloth, trl\n"
+ "assert unsloth.DEVICE_TYPE == 'mlx', unsloth.DEVICE_TYPE\n"
+ "assert '__all__' not in vars(trl), 'import unsloth filtered trl.__all__ eagerly'\n"
+ "names = trl.__all__\n"
+ "assert {'SFTConfig', 'SFTTrainer'} <= set(names), names\n"
+ "ns = {}\n"
+ "exec('from trl import *', ns)\n"
+ "assert set(names) <= set(ns), set(names) - set(ns)\n"
+ "assert ns['SFTTrainer'] is unsloth.UnslothTrainer\n"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", probe],
+ cwd = pathlib.Path(__file__).resolve().parents[1],
+ capture_output = True,
+ text = True,
+ timeout = 600,
+ )
+ assert result.returncode == 0, result.stdout[-2000:] + result.stderr[-4000:]
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 3dcc26c8f15..7b280779e3a 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -1549,9 +1549,8 @@ if _IS_MLX:
)
return _train_on_responses_only(*args, **kwargs)
- def _safe_mlx_trl_star_exports(_trl):
+ def _safe_mlx_trl_star_exports(_trl, exports):
"""Return importable TRL star exports plus the MLX SFT shims."""
- exports = list(getattr(_trl, "__all__", ()))
safe_exports = []
for name in exports:
try:
@@ -1602,6 +1601,11 @@ if _IS_MLX:
kwargs.setdefault("num_train_epochs", 3)
super().__init__(*args, **kwargs)
+ from ._mlx_trl_all import (
+ install_lazy_trl_all as _install_lazy_trl_all,
+ raw_trl_all as _raw_trl_all,
+ )
+
def _install_mlx_trl_sft_shim():
"""Install MLX-backed TRL SFT shims without replacing the TRL module."""
_trl = _sys.modules.get("trl")
@@ -1619,7 +1623,7 @@ if _IS_MLX:
_trl.SFTTrainer = UnslothTrainer
_trl.SFTConfig = _MLXSFTConfig
# Names come from trl's __all__, never a getattr probe: that triggers trl's lazy import and pulls torch.
- _trl_exports = set(getattr(_trl, "__all__", ()) or ())
+ _trl_exports = set(_raw_trl_all(_trl))
# Stub every non-SFT trl trainer so newer ones fail clearly too; take names from __all__ and never resolve them, since that pulls torch.
_unsupported = set(_MLX_UNSUPPORTED_TRL_TRAINERS) | {
_n for _n in _trl_exports if _n.endswith("Trainer") and _n != "SFTTrainer"
@@ -1630,7 +1634,8 @@ if _IS_MLX:
continue
if _name in _trl_exports or _current is not None:
setattr(_trl, _name, _make_mlx_unsupported_trl_trainer(_name))
- _trl.__all__ = _safe_mlx_trl_star_exports(_trl)
+ # Filtered on first read of trl.__all__: resolving every name here imported all of trl (datasets, peft, ...).
+ _install_lazy_trl_all(_trl, _safe_mlx_trl_star_exports)
_trl.__UNSLOTH_MLX_COMPAT__ = True
def _install_mlx_unsloth_trainer_shim():
diff --git a/unsloth/_mlx_trl_all.py b/unsloth/_mlx_trl_all.py
new file mode 100644
index 00000000000..df1c60f3de9
--- /dev/null
+++ b/unsloth/_mlx_trl_all.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""MLX `trl.__all__`, filtered on first read (PEP 562): filtering resolves every name, importing all of trl."""
+
+import weakref
+
+# Kept outside trl's namespace so dir(trl) gains no bookkeeping entry.
+_RAW_ALL = weakref.WeakKeyDictionary()
+
+
+def raw_trl_all(trl):
+ """trl's own export names, never resolving one."""
+ if trl in _RAW_ALL:
+ return list(_RAW_ALL[trl])
+ return list(vars(trl).get("__all__", ()) or ())
+
+
+def install_lazy_trl_all(trl, filter_exports):
+ """Serve `trl.__all__` as `filter_exports(trl, names)`, computed on first access."""
+ namespace = vars(trl)
+ _RAW_ALL[trl] = raw_trl_all(trl)
+ namespace.pop("__all__", None)
+ previous = namespace.get("__getattr__")
+ previous = getattr(previous, "_unsloth_previous", previous)
+ previous_dir = namespace.get("__dir__")
+ previous_dir = getattr(previous_dir, "_unsloth_previous", previous_dir)
+
+ building = []
+
+ def _hand_back():
+ # Leave the namespace exactly as the eager filter did, so dir(trl) is unchanged.
+ for key, hook, prior in (
+ ("__getattr__", __getattr__, previous),
+ ("__dir__", __dir__, previous_dir),
+ ):
+ if namespace.get(key) is hook:
+ if prior is None:
+ del namespace[key]
+ else:
+ namespace[key] = prior
+
+ def __getattr__(name):
+ if name == "__all__":
+ raw = raw_trl_all(trl)
+ # Re-entrant read mid-filter gets the raw list, as with the eager filter.
+ if building:
+ return raw
+ building.append(True)
+ try:
+ exports = filter_exports(trl, raw)
+ finally:
+ building.clear()
+ namespace["__all__"] = exports
+ _hand_back()
+ return exports
+ if previous is not None:
+ return previous(name)
+ # A class-level __getattr__ (trl's _LazyModule) still runs after this AttributeError.
+ raise AttributeError(f"module {trl.__name__!r} has no attribute {name!r}")
+
+ def __dir__():
+ # ModuleType.__dir__ (under trl's _LazyModule.__dir__) lists the namespace: build first.
+ getattr(trl, "__all__")
+ return previous_dir() if previous_dir is not None else list(namespace)
+
+ __getattr__._unsloth_previous = previous
+ __dir__._unsloth_previous = previous_dir
+ namespace["__getattr__"] = __getattr__
+ namespace["__dir__"] = __dir__