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.

Reject an hf_xet that is only an empty namespace package (#11205)

Daniel Han0175e7a739fc
diff --git a/tests/test_hf_xet_broken_wheel.py b/tests/test_hf_xet_broken_wheel.py
index f369ede779c..45c3f67c83b 100644
--- a/tests/test_hf_xet_broken_wheel.py
+++ b/tests/test_hf_xet_broken_wheel.py
@@ -159,7 +159,11 @@ def _install_fake_environment(
if name == "hf_xet":
if import_error is not None:
raise import_error
- return object()
+ # A real module, not a bare object: __file__ is what separates an installed package
+ # from the empty namespace shell the confirm step has to reject.
+ loaded = types.ModuleType("hf_xet")
+ loaded.__file__ = "/site-packages/hf_xet/__init__.py"
+ return loaded
return importlib.import_module(name, package)
monkeypatch.setattr(importlib.util, "find_spec", fake_find_spec)
@@ -256,7 +260,9 @@ def test_an_imported_hf_xet_short_circuits_before_any_lookup(monkeypatch):
find_spec would not show it either since the lookup sits inside an `except Exception: return`.
So the lookups are recorded and the assertion is that there were none."""
monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
- monkeypatch.setitem(IF.sys.modules, "hf_xet", types.ModuleType("hf_xet"))
+ working = types.ModuleType("hf_xet")
+ working.__file__ = "/site-packages/hf_xet/__init__.py" # a bare ModuleType is a shell
+ monkeypatch.setitem(IF.sys.modules, "hf_xet", working)
lookups = []
@@ -274,6 +280,106 @@ def test_an_imported_hf_xet_short_circuits_before_any_lookup(monkeypatch):
assert "HF_HUB_DISABLE_XET" not in IF.os.environ
+def test_fires_when_hf_xet_is_only_an_empty_namespace_package(monkeypatch, caplog, tmp_path):
+ """REGRESSION. An hf_xet/ directory with no __init__.py and no extension is a NAMESPACE
+ package: it imports cleanly and defines nothing, so confirming with a bare import cleared a
+ suspicion that was correct. huggingface_hub does `from hf_xet import PyXetDownloadInfo,
+ download_files`, which still fails. Reproduced against huggingface_hub 0.36.2 with the package
+ contents deleted and the directory and dist-info left: find_spec returned a namespace spec,
+ `import hf_xet` succeeded, and every download still went to Xet and died with
+ "cannot import name 'PyXetDownloadInfo' from 'hf_xet' (unknown location)".
+ """
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ monkeypatch.delitem(IF.sys.modules, "hf_xet", raising = False)
+ monkeypatch.setattr(IF, "_hf_xet_distribution_is_installed", lambda: True)
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ())
+
+ package = tmp_path / "hf_xet"
+ package.mkdir() # no __init__.py, no extension: exactly what makes it a namespace package
+ spec = importlib.machinery.ModuleSpec("hf_xet", None, is_package = True)
+ spec.submodule_search_locations = [str(package)]
+
+ real_find_spec = importlib.util.find_spec
+
+ def fake_find_spec(name, package = None):
+ if name == "huggingface_hub":
+ return importlib.machinery.ModuleSpec("huggingface_hub", None)
+ if name == "hf_xet":
+ return spec
+ return real_find_spec(name, package)
+
+ namespace_module = types.ModuleType("hf_xet")
+ namespace_module.__file__ = None # what CPython gives a namespace package
+
+ def fake_import_module(name, package = None):
+ if name == "hf_xet":
+ IF.sys.modules["hf_xet"] = namespace_module
+ return namespace_module
+ return importlib.import_module(name, package)
+
+ monkeypatch.setattr(importlib.util, "find_spec", fake_find_spec)
+ monkeypatch.setattr(IF.importlib, "import_module", fake_import_module)
+
+ assert (
+ IF._hf_xet_extension_is_missing(spec) is True
+ ), "the suspicion itself must still be raised"
+
+ with caplog.at_level("WARNING", logger = IF.logger.name):
+ IF.fix_broken_hf_xet_wheel()
+
+ assert IF.os.environ.get("HF_HUB_DISABLE_XET") == "1"
+ assert "namespace package" in caplog.records[0].getMessage()
+ # The shell must not be left behind for the next importer to trip over.
+ assert "hf_xet" not in IF.sys.modules
+
+
+def test_fires_when_the_hub_already_cached_the_namespace_shell(monkeypatch, caplog, tmp_path):
+ """REGRESSION. huggingface_hub's own `from hf_xet import PyXetDownloadInfo, download_files`
+ leaves hf_xet in sys.modules even when those symbols are missing, because the PACKAGE imported
+ fine and only the attribute lookup failed. A cached module is therefore not proof of a working
+ one, and short-circuiting on its mere presence left the user broken. Reproduced against
+ huggingface_hub 0.36.2, Hub used before unsloth: the import raised "cannot import name
+ 'PyXetDownloadInfo' from 'hf_xet' (unknown location)", the shell stayed cached with
+ __file__ None, and routes_to_xet was still True afterwards.
+ """
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ monkeypatch.setattr(IF, "_hf_xet_distribution_is_installed", lambda: True)
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ())
+
+ package = tmp_path / "hf_xet"
+ package.mkdir()
+ spec = importlib.machinery.ModuleSpec("hf_xet", None, is_package = True)
+ spec.submodule_search_locations = [str(package)]
+
+ shell = types.ModuleType("hf_xet")
+ shell.__file__ = None # what the Hub left behind
+ monkeypatch.setitem(IF.sys.modules, "hf_xet", shell)
+
+ real_find_spec = importlib.util.find_spec
+
+ def fake_find_spec(name, package = None):
+ if name == "huggingface_hub":
+ return importlib.machinery.ModuleSpec("huggingface_hub", None)
+ if name == "hf_xet":
+ return spec
+ return real_find_spec(name, package)
+
+ def fake_import_module(name, package = None):
+ if name == "hf_xet":
+ IF.sys.modules["hf_xet"] = shell
+ return shell
+ return importlib.import_module(name, package)
+
+ monkeypatch.setattr(importlib.util, "find_spec", fake_find_spec)
+ monkeypatch.setattr(IF.importlib, "import_module", fake_import_module)
+
+ with caplog.at_level("WARNING", logger = IF.logger.name):
+ IF.fix_broken_hf_xet_wheel()
+
+ assert IF.os.environ.get("HF_HUB_DISABLE_XET") == "1"
+ assert "hf_xet" not in IF.sys.modules, "the shell must not be left cached"
+
+
def test_fires_when_only_the_distribution_metadata_survives(monkeypatch, caplog):
"""REGRESSION. find_spec says "not installed", but is_xet_available() asks
importlib.metadata, which still succeeds, so every download still goes down the Xet branch."""
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index d8fffe396b7..cd7d77672ef 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -1636,6 +1636,17 @@ def _disable_xet_on_already_imported_huggingface_hub():
return tuple(patched)
+def _hf_xet_module_is_real(module):
+ """False for the empty namespace package an incomplete hf_xet directory produces.
+
+ A namespace package imports cleanly and defines nothing, so it satisfies neither
+ `import hf_xet` nor huggingface_hub's `from hf_xet import PyXetDownloadInfo, download_files`.
+ Its __file__ is None, which every genuinely installed package (extension modules included)
+ sets, so that is the whole test.
+ """
+ return getattr(module, "__file__", None) is not None
+
+
def fix_broken_hf_xet_wheel():
"""Route Hugging Face downloads over plain HTTPS when hf_xet is installed but unimportable."""
explicit = os.environ.get("HF_HUB_DISABLE_XET", "").strip()
@@ -1646,8 +1657,14 @@ def fix_broken_hf_xet_wheel():
if explicit.upper() in _HF_HUB_ENV_TRUE_VALUES:
_disable_xet_on_already_imported_huggingface_hub()
return
- if "hf_xet" in sys.modules:
- return # already imported, so it works; also makes repeat calls free
+ cached = sys.modules.get("hf_xet", None)
+ if cached is not None:
+ # Already imported, so it works, and repeat calls stay free. Unless it is the namespace
+ # shell: huggingface_hub's own `from hf_xet import ...` leaves that cached even though the
+ # symbols it wanted were missing, so a cached module is not proof of a working one.
+ if _hf_xet_module_is_real(cached):
+ return
+ sys.modules.pop("hf_xet", None)
try:
if importlib.util.find_spec("huggingface_hub") is None:
return
@@ -1673,9 +1690,17 @@ def fix_broken_hf_xet_wheel():
# Confirm the suspicion by importing. If it imports after all, we misread the metadata and Xet
# stays on. Only reached for an already-suspect install, so a healthy one never pays for it.
+ #
+ # Importing the package is not enough on its own: an hf_xet/ directory with no __init__.py and
+ # no extension in it is a NAMESPACE package, which imports fine and defines nothing, while
+ # huggingface_hub does `from hf_xet import PyXetDownloadInfo, download_files` and fails. So the
+ # module has to carry real code, which a namespace package never does (its __file__ is None).
try:
- importlib.import_module("hf_xet")
- return
+ module = importlib.import_module("hf_xet")
+ if _hf_xet_module_is_real(module):
+ return
+ sys.modules.pop("hf_xet", None)
+ failure = "ImportError: hf_xet resolves to an empty namespace package, which defines none of the symbols huggingface_hub imports"
except Exception as error:
failure = f"{type(error).__name__}: {error}"