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.

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.py
index 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 None
finder = _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 None
finder = _BlockZoo()
saved = {
k: v
for 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 None
finder = _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_shared
if 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_h
monkeypatch.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(m
monkeypatch.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 retry
assert 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 loaded
diff --git a/studio/backend/tests/test_hub_download_transport_auto.py b/studio/backend/tests/test_hub_download_transport_auto.py
index 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 sentinel
assert 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 None
diff --git a/studio/backend/utils/hf_xet_fallback.py b/studio/backend/utils/hf_xet_fallback.py
index 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 so
importing 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_error
if _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.py
index 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 _redirect
except Exception:
pass