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
Load the zoo Hub download helpers without unsloth_zoo's package init (#13849)
Daniel Hanf9d41b1f5e77
diff --git a/studio/backend/tests/test_hf_xet_fallback.py b/studio/backend/tests/test_hf_xet_fallback.pyindex 6c4ca66696e..2dd5fbc8acd 100644--- a/studio/backend/tests/test_hf_xet_fallback.py+++ b/studio/backend/tests/test_hf_xet_fallback.py@@ -193,12 +193,20 @@ def test_degrades_gracefully_without_shared_helper(monkeypatch):path = None,target = None,):- if name == "unsloth_zoo.hf_xet_fallback":+ if (+ name == "unsloth_zoo.hf_xet_fallback"+ or name.split(".")[0] == "unsloth_zoo_downloads"+ ):raise ModuleNotFoundError(f"No module named '{name}'", name = name)return Nonefinder = _BlockShared()saved_shared = sys.modules.pop("unsloth_zoo.hf_xet_fallback", None)+ saved_light = {+ k: sys.modules.pop(k)+ for k in list(sys.modules)+ if k.split(".")[0] == "unsloth_zoo_downloads"+ }saved_shim = sys.modules.pop("utils.hf_xet_fallback", None)sys.meta_path.insert(0, finder)try:@@ -254,6 +262,7 @@ def test_degrades_gracefully_without_shared_helper(monkeypatch):sys.modules.pop("utils.hf_xet_fallback", None)if saved_shared is not None:sys.modules["unsloth_zoo.hf_xet_fallback"] = saved_shared+ sys.modules.update(saved_light)if saved_shim is not None:sys.modules["utils.hf_xet_fallback"] = saved_shim@@ -271,15 +280,16 @@ def test_degrades_when_unsloth_zoo_entirely_absent():target = None,):# Whole package absent, so ModuleNotFoundError.name is the top-level 'unsloth_zoo'.- if name == "unsloth_zoo" or name.startswith("unsloth_zoo."):- raise ModuleNotFoundError("No module named 'unsloth_zoo'", name = "unsloth_zoo")+ if name.split(".")[0] in ("unsloth_zoo", "unsloth_zoo_downloads"):+ top = name.split(".")[0]+ raise ModuleNotFoundError(f"No module named '{top}'", name = top)return Nonefinder = _BlockZoo()saved = {k: vfor k, v in list(sys.modules.items())- if k == "unsloth_zoo" or k.startswith("unsloth_zoo.")+ if k.split(".")[0] in ("unsloth_zoo", "unsloth_zoo_downloads")}for k in saved:del sys.modules[k]@@ -314,9 +324,17 @@ def test_degrades_when_shared_helper_import_raises_importerror():if name == "unsloth_zoo.hf_xet_fallback":# Mirror a torch-less install: a plain ImportError with no .name.raise ImportError("Unsloth: Pytorch is not installed.")+ if name == "unsloth_zoo_downloads":+ # A zoo predating the init-free package.+ raise ModuleNotFoundError(f"No module named '{name}'", name = name)return Nonefinder = _BlockWithImportError()+ saved_light = {+ k: sys.modules.pop(k)+ for k in list(sys.modules)+ if k.split(".")[0] == "unsloth_zoo_downloads"+ }saved_shared = sys.modules.pop("unsloth_zoo.hf_xet_fallback", None)saved_zoo = sys.modules.pop("unsloth_zoo", None)saved_shim = sys.modules.pop("utils.hf_xet_fallback", None)@@ -334,6 +352,7 @@ def test_degrades_when_shared_helper_import_raises_importerror():sys.modules["unsloth_zoo.hf_xet_fallback"] = saved_sharedif saved_zoo is not None:sys.modules["unsloth_zoo"] = saved_zoo+ sys.modules.update(saved_light)if saved_shim is not None:sys.modules["utils.hf_xet_fallback"] = saved_shim@@ -373,6 +392,7 @@ def test_no_light_gpu_init_retry_on_an_accelerator_host(monkeypatch):try:shim = importlib.import_module("utils.hf_xet_fallback")monkeypatch.setattr(shim, "_gpu_present", lambda: True)+ monkeypatch.setattr(shim, "_import_light", lambda name: None)assert shim._load_shared() is False# Exactly ONE attempt, made without the light-init flag.assert attempts == [None], attempts@@ -404,6 +424,7 @@ def test_optional_loader_does_not_retry_under_light_gpu_init_on_an_accelerator_hmonkeypatch.setitem(sys.modules, "triton", real_triton)monkeypatch.setattr(shim, "_gpu_present", lambda: True)monkeypatch.delitem(sys.modules, "unsloth_zoo.hf_xet_health", raising = False)+ monkeypatch.setattr(shim, "_import_light", lambda name: None)shim._reset_optional_module_cache()attempts = []@@ -431,6 +452,7 @@ def test_optional_loader_keeps_a_submodule_a_late_zoo_init_failure_left_loaded(mmonkeypatch.setattr(shim, "_gpu_present", lambda: True)monkeypatch.delitem(sys.modules, "unsloth_zoo.hf_xet_health", raising = False)survivor = _types.ModuleType("unsloth_zoo.hf_xet_tuning")+ monkeypatch.setattr(shim, "_import_light", lambda name: None)shim._reset_optional_module_cache()attempts = []@@ -547,6 +569,7 @@ def test_retries_under_light_gpu_init_when_import_fails(monkeypatch):degraded = importlib.import_module("utils.hf_xet_fallback")# The retry only applies to a host with no accelerator (see _gpu_present); pin that on the freshly imported module.monkeypatch.setattr(degraded, "_gpu_present", lambda: False)+ monkeypatch.setattr(degraded, "_import_light", lambda name: None)# Import is light (lazy backend); unsloth_zoo not loaded yet.assert seen_env == [], seen_env# First use of a heavy helper triggers the load (attempt without the light env, then a retry@@ -602,6 +625,7 @@ def test_a_worker_spawned_during_the_gpu_init_retry_does_not_inherit_the_overrid# There is only a retry to spawn into on a host with no accelerator (see _gpu_present),# so pin that rather than letting the runner's hardware decide the assertion.monkeypatch.setattr(shim, "_gpu_present", lambda: False)+ monkeypatch.setattr(shim, "_import_light", lambda name: None)shim.DownloadStallError # drives the load: plain attempt, then the retryassert len(child_envs) == 2, child_envs# The retry is the attempt that sets it; neither child may see it.@@ -1432,3 +1456,89 @@ class _FakeFn:def _fail_on_kill(pid, sig):raise AssertionError("os.kill must never be reached on Windows")+++def fake_light_package(tmp_path, monkeypatch):+ """A stand-in ``unsloth_zoo_downloads``, independent of the installed zoo."""+ pkg = tmp_path / "light" / "unsloth_zoo_downloads"+ pkg.mkdir(parents = True)+ (pkg / "__init__.py").write_text("")+ for name in ("hf_xet_fallback", "hf_xet_health", "hf_xet_tuning"):+ (pkg / f"{name}.py").write_text(f"MARKER = 'light {name}'\n")+ _is_light = lambda k: k.split(".")[0] == "unsloth_zoo_downloads"+ saved = {k: v for k, v in sys.modules.items() if _is_light(k)}+ for k in saved:+ del sys.modules[k]+ monkeypatch.syspath_prepend(str(pkg.parent))+ yield+ for k in [k for k in sys.modules if _is_light(k)]:+ del sys.modules[k]+ sys.modules.update(saved)+++class _ZooInitExplodes:+ """``import unsloth_zoo`` raising, as on a GPU-less host; records every attempt."""++ def __init__(self):+ self.attempts = []++ def find_spec(+ self,+ name,+ path = None,+ target = None,+ ):+ if name == "unsloth_zoo":+ self.attempts.append(os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT"))+ raise NotImplementedError("Unsloth cannot find any torch accelerator")+ return None+++def test_shared_backend_comes_from_the_light_package_without_zoo_init(+ monkeypatch, fake_light_package+):+ for k in [k for k in sys.modules if k == "unsloth_zoo" or k.startswith("unsloth_zoo.")]:+ monkeypatch.delitem(sys.modules, k)+ monkeypatch.delenv("UNSLOTH_ZOO_DISABLE_GPU_INIT", raising = False)+ monkeypatch.setattr(shim, "_shared", None)+ monkeypatch.setattr(shim, "_shared_available", None)+ gated = []+ monkeypatch.setattr(shim, "_gate_torch_stack", gated.append)+ finder = _ZooInitExplodes()+ sys.meta_path.insert(0, finder)+ try:+ assert shim._load_shared() is True+ assert shim._shared.MARKER == "light hf_xet_fallback"+ assert finder.attempts == [] and gated == []+ assert "unsloth_zoo" not in sys.modules+ assert os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT") is None+ finally:+ sys.meta_path.remove(finder)+++def test_optional_module_comes_from_the_light_package_without_zoo_init(+ monkeypatch, fake_light_package+):+ monkeypatch.delitem(sys.modules, "unsloth_zoo.hf_xet_health", raising = False)+ monkeypatch.setattr(shim, "_optional_modules", {})+ gated = []+ monkeypatch.setattr(shim, "_gate_torch_stack", gated.append)+ finder = _ZooInitExplodes()+ sys.meta_path.insert(0, finder)+ try:+ module = shim._load_optional("unsloth_zoo.hf_xet_health")+ assert module.MARKER == "light hf_xet_health"+ assert finder.attempts == [] and gated == []+ # Memoised under the name callers use, so cached_xet_health sees it.+ assert shim._optional_modules["unsloth_zoo.hf_xet_health"] is module+ finally:+ sys.meta_path.remove(finder)+++def test_an_already_loaded_zoo_module_wins_over_the_light_package(monkeypatch, fake_light_package):+ """Keeps the object identity of an earlier full import (and of test doubles)."""+ loaded = _types.ModuleType("unsloth_zoo.hf_xet_health")+ monkeypatch.setitem(sys.modules, "unsloth_zoo.hf_xet_health", loaded)+ monkeypatch.setattr(shim, "_optional_modules", {})+ assert shim._load_optional("unsloth_zoo.hf_xet_health") is loadeddiff --git a/studio/backend/tests/test_hub_download_transport_auto.py b/studio/backend/tests/test_hub_download_transport_auto.pyindex 7bfc1f1288c..aa2aba29916 100644--- a/studio/backend/tests/test_hub_download_transport_auto.py+++ b/studio/backend/tests/test_hub_download_transport_auto.py@@ -416,6 +416,7 @@ def test_optional_loader_retries_with_gpu_init_disabled(monkeypatch):monkeypatch.setattr(importlib, "import_module", _fake_import)monkeypatch.delenv("UNSLOTH_ZOO_DISABLE_GPU_INIT", raising = False)monkeypatch.setattr(shim, "_gpu_present", lambda: False)+ monkeypatch.setattr(shim, "_import_light", lambda name: None)assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is sentinelassert attempts == [None, "1"]@@ -429,6 +430,7 @@ def test_optional_loader_returns_none_when_truly_absent(monkeypatch):raise ModuleNotFoundError(name)monkeypatch.setattr(importlib, "import_module", _always_fail)+ monkeypatch.setattr(shim, "_import_light", lambda name: None)for name in ("unsloth_zoo.hf_xet_tuning", "unsloth_zoo.hf_xet_health"):monkeypatch.delitem(sys.modules, name, raising = False)assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is Nonediff --git a/studio/backend/utils/hf_xet_fallback.py b/studio/backend/utils/hf_xet_fallback.pyindex e899b51c221..970bfe3fe5c 100644--- a/studio/backend/utils/hf_xet_fallback.py+++ b/studio/backend/utils/hf_xet_fallback.py@@ -84,6 +84,29 @@ def _gate_torch_stack(reason: str) -> None:pass+def _import_light(module_name: str) -> Any:+ """``unsloth_zoo.<name>`` from the init-free ``unsloth_zoo_downloads`` (unsloth-zoo#1752), else ``None``.++ An already-loaded ``unsloth_zoo.<name>`` wins, keeping its identity (and test doubles).+ """+ import sys as _sys++ module = _sys.modules.get(module_name)+ if module is not None and not getattr(+ getattr(module, "__spec__", None), "_initializing", False+ ):+ return module+ try:+ from unsloth_zoo_downloads import hf_xet_fallback, hf_xet_health, hf_xet_tuning+ except Exception: # noqa: BLE001 - absent on older zoo releases: take the full-init path+ return None+ return {+ "unsloth_zoo.hf_xet_fallback": hf_xet_fallback,+ "unsloth_zoo.hf_xet_health": hf_xet_health,+ "unsloth_zoo.hf_xet_tuning": hf_xet_tuning,+ }.get(module_name)++def _load_shared() -> bool:"""Import ``unsloth_zoo.hf_xet_fallback`` on demand; return True if available. Deferred soimporting this module at worker startup does not pull transformers in before the sidecar is@@ -91,6 +114,12 @@ def _load_shared() -> bool:global _shared, _shared_available, _shared_import_errorif _shared_available is not None:return _shared_available+ light = _import_light("unsloth_zoo.hf_xet_fallback")+ if light is not None:+ with _load_lock:+ if _shared_available is None:+ _shared, _shared_available, _shared_import_error = light, True, None+ return _shared_available# Outside _load_lock: a thread waiting on the warm must not hold up the env-var bookkeeping._gate_torch_stack("unsloth_zoo.hf_xet_fallback import")with _load_lock:@@ -188,6 +217,11 @@ def _load_optional(module_name: str) -> Any:if cached is not _UNTRIED:return cached+ light = _import_light(module_name)+ if light is not None:+ _optional_modules[module_name] = light+ return light+_gate_torch_stack(f"{module_name} import")try:module = importlib.import_module(module_name)diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.pyindex a3ca27973a8..f0c7dd8cb8d 100644--- a/unsloth/_gpu_init.py+++ b/unsloth/_gpu_init.py@@ -46,24 +46,31 @@ from .import_fixes import (# transformers / vllm (disable_broken_vllm probes `import vllm`, check_fbgemm_gpu_version imports# transformers, fix_huggingface_hub imports huggingface_hub), any of which would freeze Hub's# cache constants with the un-redirected paths. hf_cache.py is stdlib-only, so it loads straight-# from its file without triggering the full unsloth_zoo init this early.+# from unsloth_zoo_downloads (or, on older zoo, its file) without the full unsloth_zoo init.try:- import importlib.util as _importlib_util- from pathlib import Path as _Path-- _zoo_spec = _importlib_util.find_spec("unsloth_zoo")- if _zoo_spec is not None and _zoo_spec.origin:- _hf_cache_file = _Path(_zoo_spec.origin).with_name("hf_cache.py")- if _hf_cache_file.is_file():- _hf_cache_spec = _importlib_util.spec_from_file_location(- "unsloth_zoo._early_hf_cache", _hf_cache_file- )- _hf_cache = _importlib_util.module_from_spec(_hf_cache_spec)- _hf_cache_spec.loader.exec_module(_hf_cache)- _hf_cache.redirect_hf_cache_if_readonly()- del _hf_cache, _hf_cache_spec- del _hf_cache_file- del _zoo_spec, _importlib_util, _Path+ try:+ from unsloth_zoo_downloads.hf_cache import redirect_hf_cache_if_readonly as _redirect+ except ImportError:+ import importlib.util as _importlib_util+ from pathlib import Path as _Path++ _redirect = None+ _zoo_spec = _importlib_util.find_spec("unsloth_zoo")+ if _zoo_spec is not None and _zoo_spec.origin:+ _hf_cache_file = _Path(_zoo_spec.origin).with_name("hf_cache.py")+ if _hf_cache_file.is_file():+ _hf_cache_spec = _importlib_util.spec_from_file_location(+ "unsloth_zoo._early_hf_cache", _hf_cache_file+ )+ _hf_cache = _importlib_util.module_from_spec(_hf_cache_spec)+ _hf_cache_spec.loader.exec_module(_hf_cache)+ _redirect = _hf_cache.redirect_hf_cache_if_readonly+ del _hf_cache, _hf_cache_spec+ del _hf_cache_file+ del _zoo_spec, _importlib_util, _Path+ if _redirect is not None:+ _redirect()+ del _redirectexcept Exception:pass