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 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
"""`import unsloth` scans the installed distributions once, not once per library that asks."""
import ast
import importlib.metadata as metadata
import importlib.util
import os
import pathlib
import subprocess
import sys
import textwrap
import threading
import time
import pytest
_UNSLOTH = pathlib.Path(__file__).resolve().parents[1] / "unsloth"
_REPO = _UNSLOTH.parent
pytestmark = pytest.mark.skipif(
not hasattr(metadata, "packages_distributions"),
reason = "importlib.metadata.packages_distributions needs Python 3.10",
)
def _load(name = "_unsloth_import_metadata_cache_under_test"):
spec = importlib.util.spec_from_file_location(name, _UNSLOTH / "_import_metadata_cache.py")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
@pytest.fixture
def cache_module():
original = metadata.packages_distributions
module = _load()
try:
yield module
finally:
metadata.packages_distributions = original
@pytest.fixture
def counted(monkeypatch):
"""The real scan, counted; installed before the cache so the cache wraps it."""
real = metadata.packages_distributions
calls = []
def scan():
calls.append(1)
return real()
monkeypatch.setattr(metadata, "packages_distributions", scan)
return calls
def _write_dist(site, name, top_level):
dist_info = site / f"{name}-1.0.dist-info"
dist_info.mkdir()
(dist_info / "METADATA").write_text(f"Metadata-Version: 2.1\nName: {name}\nVersion: 1.0\n")
(dist_info / "top_level.txt").write_text(top_level + "\n")
def _bump_mtime(path):
# Some filesystems keep coarse mtimes; force a visible change.
stat = os.stat(path)
os.utime(path, ns = (stat.st_atime_ns, stat.st_mtime_ns + 2_000_000_000))
def test_repeat_call_reuses_the_scan_and_matches_it(cache_module, counted):
token = cache_module.install()
first = metadata.packages_distributions()
second = metadata.packages_distributions()
assert len(counted) == 1
cache_module.uninstall(token)
reference = metadata.packages_distributions()
assert first == second == reference
assert list(first) == list(second) == list(reference) # key order too
def test_callers_get_independent_copies(cache_module, counted):
cache_module.install()
first = metadata.packages_distributions()
key = next(iter(first))
first[key].append("mutated")
first["__unsloth_injected__"] = ["x"]
second = metadata.packages_distributions()
assert "mutated" not in second[key]
assert "__unsloth_injected__" not in second
assert len(counted) == 1
def test_new_distribution_on_sys_path_is_seen(cache_module, counted, tmp_path, monkeypatch):
site = tmp_path / "site"
site.mkdir()
monkeypatch.syspath_prepend(str(site))
cache_module.install()
assert "unsloth_cache_probe_pkg" not in metadata.packages_distributions()
_write_dist(site, "unsloth-cache-probe", "unsloth_cache_probe_pkg")
_bump_mtime(site)
after = metadata.packages_distributions()
assert after["unsloth_cache_probe_pkg"] == ["unsloth-cache-probe"]
assert len(counted) == 2
def test_removed_distribution_is_dropped(cache_module, counted, tmp_path, monkeypatch):
site = tmp_path / "site"
site.mkdir()
_write_dist(site, "unsloth-cache-gone", "unsloth_cache_gone_pkg")
monkeypatch.syspath_prepend(str(site))
cache_module.install()
assert "unsloth_cache_gone_pkg" in metadata.packages_distributions()
for child in (site / "unsloth-cache-gone-1.0.dist-info").iterdir():
child.unlink()
(site / "unsloth-cache-gone-1.0.dist-info").rmdir()
_bump_mtime(site)
assert "unsloth_cache_gone_pkg" not in metadata.packages_distributions()
assert len(counted) == 2
def test_sys_path_change_rescans(cache_module, counted, tmp_path, monkeypatch):
site = tmp_path / "site"
site.mkdir()
_write_dist(site, "unsloth-cache-late", "unsloth_cache_late_pkg")
cache_module.install()
assert "unsloth_cache_late_pkg" not in metadata.packages_distributions()
monkeypatch.syspath_prepend(str(site))
assert metadata.packages_distributions()["unsloth_cache_late_pkg"] == ["unsloth-cache-late"]
assert len(counted) == 2
def test_new_distribution_finder_rescans(cache_module, counted, monkeypatch):
class Finder:
def find_spec(self, *args, **kwargs):
return None
def find_distributions(self, context = None):
return iter(())
cache_module.install()
metadata.packages_distributions()
monkeypatch.setattr(sys, "meta_path", sys.meta_path + [Finder()])
metadata.packages_distributions()
assert len(counted) == 2
def test_a_plain_import_hook_does_not_rescan(cache_module, counted, monkeypatch):
# unsloth_zoo adds a modeling-module finder between the transformers and TRL scans.
class ImportOnly:
def find_spec(self, *args, **kwargs):
return None
cache_module.install()
metadata.packages_distributions()
monkeypatch.setattr(sys, "meta_path", [ImportOnly()] + sys.meta_path)
metadata.packages_distributions()
assert len(counted) == 1
def test_uninstall_restores_and_forgets(cache_module, counted):
before = metadata.packages_distributions
token = cache_module.install()
assert metadata.packages_distributions is token
metadata.packages_distributions()
cache_module.uninstall(token)
assert metadata.packages_distributions is before
assert token._unsloth_metadata_cache[0] is None
cache_module.uninstall(None) # a failed install is a no-op
def test_uninstall_leaves_a_later_wrapper_in_place(cache_module, counted):
token = cache_module.install()
def outer():
return token()
metadata.packages_distributions = outer
cache_module.uninstall(token)
assert metadata.packages_distributions is outer
metadata.packages_distributions()
metadata.packages_distributions()
assert len(counted) == 2
def test_a_reference_kept_past_the_window_reaches_the_original(cache_module, counted):
token = cache_module.install()
bound = metadata.packages_distributions # e.g. `from importlib.metadata import ...` meanwhile
bound()
cache_module.uninstall(token)
bound()
bound()
assert len(counted) == 3
assert token._unsloth_metadata_cache[0] is None
def _fake_owner(monkeypatch, name = "_unsloth_metadata_owner_under_test"):
import types
owner = types.ModuleType(name)
monkeypatch.setitem(sys.modules, name, owner)
return owner
def test_a_failed_import_does_not_leave_the_wrapper(cache_module, counted, monkeypatch):
# `import unsloth` raised midway: uninstall never ran and the module left sys.modules.
real = metadata.packages_distributions
owner = _fake_owner(monkeypatch)
token = cache_module.install(owner)
metadata.packages_distributions()
metadata.packages_distributions()
assert len(counted) == 1
del sys.modules[owner.__name__]
assert metadata.packages_distributions is token
metadata.packages_distributions() # the first call after the failure restores the original
assert metadata.packages_distributions is real
assert len(counted) == 2
token() # a kept reference passes through
assert len(counted) == 3
def test_retrying_a_failed_import_does_not_stack(cache_module, counted, monkeypatch):
real = metadata.packages_distributions
first = _fake_owner(monkeypatch)
cache_module.install(first)
del sys.modules[first.__name__] # failed, nobody called the wrapper since
second = _fake_owner(monkeypatch)
token = cache_module.install(second)
assert token.__wrapped__ is real
metadata.packages_distributions()
metadata.packages_distributions()
assert len(counted) == 1
cache_module.uninstall(token)
assert metadata.packages_distributions is real
def test_inner_failure_inside_an_outer_window(cache_module, counted, monkeypatch):
# Studio's worker window is open; unsloth's import inside it raises; the worker's finally runs.
real = metadata.packages_distributions
outer = cache_module.install()
inner_module = _load("_unsloth_import_metadata_cache_inner_fail")
owner = _fake_owner(monkeypatch)
inner = inner_module.install(owner)
assert inner.__wrapped__ is outer
del sys.modules[owner.__name__]
cache_module.uninstall(outer) # inner is still on top: left in place
assert metadata.packages_distributions is inner
metadata.packages_distributions() # inner closes, finds outer closed too, unwraps both
assert metadata.packages_distributions is real
assert len(counted) == 1
def test_nested_scopes_share_the_outer_scan(cache_module, counted):
outer = cache_module.install()
metadata.packages_distributions() # transformers
inner_module = _load("_unsloth_import_metadata_cache_inner")
inner = inner_module.install()
metadata.packages_distributions() # TRL, during import unsloth
inner_module.uninstall(inner)
assert metadata.packages_distributions is outer
cache_module.uninstall(outer)
assert len(counted) == 1
def test_concurrent_callers_agree(cache_module, counted):
cache_module.install()
reference = metadata.packages_distributions()
results, errors = [], []
def worker():
try:
for _ in range(5):
results.append(metadata.packages_distributions())
except Exception as exc: # pragma: no cover
errors.append(exc)
threads = [threading.Thread(target = worker) for _ in range(8)]
for thread in threads:
thread.start()
for thread in threads:
thread.join()
assert not errors
assert all(result == reference for result in results)
assert len(counted) == 1
def test_unreadable_entries_do_not_break_it(cache_module, counted, monkeypatch):
monkeypatch.setattr(
sys, "path", sys.path + [os.path.join(os.sep, "nonexistent-unsloth-dir"), ""]
)
cache_module.install()
assert metadata.packages_distributions() == metadata.packages_distributions()
assert len(counted) == 1
def test_helper_is_stdlib_only():
tree = ast.parse((_UNSLOTH / "_import_metadata_cache.py").read_text(encoding = "utf-8"))
imported = set()
for node in ast.walk(tree):
if isinstance(node, ast.Import):
imported.update(alias.name.split(".")[0] for alias in node.names)
elif isinstance(node, ast.ImportFrom):
assert node.level == 0, "Studio loads this file by path: no relative imports"
imported.add(node.module.split(".")[0])
assert imported <= set(sys.stdlib_module_names)
def test_init_installs_first_and_removes_last():
source = (_UNSLOTH / "__init__.py").read_text(encoding = "utf-8")
tree = ast.parse(source)
calls = [
node.func.id
for node in ast.walk(tree)
if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
]
assert "_install_metadata_cache" in calls and "_uninstall_metadata_cache" in calls
lines = source.splitlines()
install = next(i for i, l in enumerate(lines) if "_install_metadata_cache(sys.modules" in l)
uninstall = next(i for i, l in enumerate(lines) if "_uninstall_metadata_cache(" in l)
first_import = next(
i
for i, l in enumerate(lines)
if l.startswith(("from .", "import "))
and "_import_gc" not in l
and "_import_metadata_cache" not in l
and not l.startswith("import os")
)
assert install < first_import, "must be in place before transformers / TRL can be imported"
assert uninstall > len(lines) - 20, "must stay in place for the whole import"
_COUNT_SCRIPT = textwrap.dedent(
"""
import importlib.metadata as md, json, sys
real = md.packages_distributions
calls = []
def scan():
calls.append(1)
return real()
md.packages_distributions = scan
import unsloth
restored = md.packages_distributions is scan
import importlib.util
print("R12COUNT " + json.dumps({"scans": len(calls), "restored": restored,
"trl": "trl" in sys.modules, "transformers": "transformers" in sys.modules}))
"""
)
_FAILED_IMPORT_SCRIPT = textwrap.dedent(
"""
import importlib.metadata as md, json, sys
real = md.packages_distributions
sys.modules["unsloth_zoo"] = None # any failure partway through unsloth/__init__.py
try:
import unsloth
failed = False
except ImportError:
failed = True
md.packages_distributions()
print("R12FAIL " + json.dumps({"failed": failed, "restored": md.packages_distributions is real}))
"""
)
def test_import_unsloth_that_raises_gives_the_function_back():
env = dict(os.environ, PYTHONWARNINGS = "ignore", UNSLOTH_DISABLE_AUTO_UPDATES = "1")
env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(_REPO), env.get("PYTHONPATH")]))
result = subprocess.run(
[sys.executable, "-c", _FAILED_IMPORT_SCRIPT],
env = env,
cwd = str(_REPO),
capture_output = True,
text = True,
timeout = 900,
)
lines = [l for l in result.stdout.splitlines() if l.startswith("R12FAIL ")]
assert lines, (result.returncode, result.stderr[-4000:])
import json
report = json.loads(lines[-1].split(" ", 1)[1])
assert report == {"failed": True, "restored": True}, report
def _scan_callers_at_import():
"""How many of transformers / TRL call packages_distributions() at import (versions differ)."""
found = 0
for name in ("transformers.utils.import_utils", "trl.import_utils"):
try:
spec = importlib.util.find_spec(name)
except (ImportError, ValueError):
continue
if spec is None or not spec.origin or not os.path.isfile(spec.origin):
continue
with open(spec.origin, encoding = "utf-8") as fh:
for line in fh:
if not line[:1].isspace() and "packages_distributions()" in line:
found += 1
break
return found
def _has_accelerator():
try:
import torch
return bool(
torch.cuda.is_available() or (hasattr(torch, "xpu") and torch.xpu.is_available())
)
except Exception:
return False
def test_import_unsloth_scans_distributions_at_most_once():
if _scan_callers_at_import() < 2:
pytest.skip(
reason = "transformers < 5 / TRL < 1 do not call packages_distributions() at import"
)
env = dict(os.environ, PYTHONWARNINGS = "ignore", UNSLOTH_DISABLE_AUTO_UPDATES = "1")
# tests/conftest.py sets this for in-process tests; a GPU-less child still imports through the CPU path.
if not _has_accelerator():
env.pop("UNSLOTH_DISABLE_CPU_FALLBACK", None)
env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(_REPO), env.get("PYTHONPATH")]))
started = time.time()
result = subprocess.run(
[sys.executable, "-c", _COUNT_SCRIPT],
env = env,
cwd = str(_REPO),
capture_output = True,
text = True,
timeout = 900,
)
lines = [l for l in result.stdout.splitlines() if l.startswith("R12COUNT ")]
assert lines, (result.returncode, result.stderr[-4000:], time.time() - started)
import json
report = json.loads(lines[-1].split(" ", 1)[1])
assert report["transformers"] and report["trl"], report
assert report["scans"] == 1, report
assert report["restored"], report # the caller's function is back after the import