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.

Fall back to HTTPS when hf_xet is installed but cannot be imported (#11167)

Daniel Han6ed7f221519e
diff --git a/tests/test_hf_xet_broken_wheel.py b/tests/test_hf_xet_broken_wheel.py
new file mode 100644
index 00000000000..f369ede779c
--- /dev/null
+++ b/tests/test_hf_xet_broken_wheel.py
@@ -0,0 +1,597 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""``fix_broken_hf_xet_wheel``: the host platform, wheel metadata and extension headers are all
+faked, so this runs on every OS and Linux CI exercises the Windows on ARM paths."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.machinery
+import importlib.metadata
+import importlib.util
+import platform
+import struct
+import sys
+import sysconfig
+import types
+from pathlib import Path
+
+import pytest
+
+
+def _load_import_fixes():
+ """`import unsloth` needs torch and an accelerator, so importing the package would make every
+ test here an ImportError on a stock runner. This module needs only stdlib and packaging."""
+ path = Path(__file__).resolve().parents[1] / "unsloth" / "import_fixes.py"
+ spec = importlib.util.spec_from_file_location("unsloth_import_fixes_under_test", path)
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+IF = _load_import_fixes()
+
+
+def _fake_host(
+ monkeypatch,
+ sysconfig_platform,
+ machine = "unknown-cpu",
+):
+ """`machine` defaults to something unmappable, so a passing test is passing on
+ sysconfig.get_platform() alone, which is the point."""
+ monkeypatch.setattr(sysconfig, "get_platform", lambda: sysconfig_platform)
+ monkeypatch.setattr(platform, "machine", lambda: machine)
+
+
+def _platform_tag_cases():
+ return (
+ ("win_amd64", "x86_64"),
+ ("win_arm64", "arm64"),
+ ("win32", "x86"),
+ ("manylinux2014_x86_64", "x86_64"),
+ ("manylinux_2_28_aarch64", "arm64"),
+ ("musllinux_1_2_x86_64", "x86_64"),
+ ("linux_armv7l", "armv7l"),
+ ("macosx_11_0_arm64", "arm64"),
+ ("macosx_10_12_x86_64", "x86_64"),
+ # Unreadable on purpose: these must never be reported as a mismatch.
+ ("macosx_10_9_universal2", None),
+ ("any", None),
+ ("something_else", None),
+ )
+
+
[email protected]("platform_tag,expected", _platform_tag_cases())
+def test_cpu_family_from_platform_tag(platform_tag, expected):
+ assert IF._cpu_family_from_platform_tag(platform_tag) == expected
+
+
+ "host_platform,tags,expected",
+ (
+ ("win-arm64", ("win_amd64",), True),
+ ("win-arm64", ("win_arm64",), False),
+ ("win-amd64", ("win_amd64",), False),
+ ("win-amd64", ("win_arm64",), True),
+ ("linux-aarch64", ("manylinux2014_x86_64",), True),
+ ("linux-x86_64", ("manylinux2014_x86_64", "manylinux_2_17_x86_64"), False),
+ ("macosx-11.0-arm64", ("macosx_11_0_arm64",), False),
+ ("macosx-11.0-arm64", ("macosx_10_12_x86_64",), True),
+ # Anything unreadable on either side is "cannot tell", never a mismatch.
+ ("macosx-11.0-arm64", ("macosx_10_9_universal2",), None),
+ ("linux-riscv64", ("manylinux_2_28_aarch64",), None),
+ ("win-arm64", (), None),
+ ),
+)
+def test_architecture_mismatch_verdicts(monkeypatch, host_platform, tags, expected):
+ _fake_host(monkeypatch, host_platform)
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: tags)
+ assert IF._hf_xet_architecture_mismatch() is expected
+
+
+ "host_platform,machine,expected",
+ (
+ ("win-amd64", "AMD64", "x86_64"),
+ ("win-arm64", "ARM64", "arm64"),
+ ("win32", "x86", "x86"),
+ ("linux-x86_64", "x86_64", "x86_64"),
+ ("linux-aarch64", "aarch64", "arm64"),
+ ("macosx-11.0-arm64", "arm64", "arm64"),
+ ("macosx-10.12-x86_64", "x86_64", "x86_64"),
+ # sysconfig cannot name a single CPU for a universal2 build, so platform.machine()
+ # is the right answer there and only there.
+ ("macosx-10.9-universal2", "arm64", "arm64"),
+ ("something-unparseable", "x86_64", "x86_64"),
+ ("something-unparseable", "sparc64", None),
+ ),
+)
+def test_host_cpu_family_prefers_sysconfig(monkeypatch, host_platform, machine, expected):
+ monkeypatch.setattr(sysconfig, "get_platform", lambda: host_platform)
+ monkeypatch.setattr(platform, "machine", lambda: machine)
+ assert IF._host_cpu_family() == expected
+
+
+def test_host_cpu_family_ignores_the_physical_cpu_on_windows(monkeypatch):
+ """REGRESSION. platform.machine() on Windows asks WMI for the PHYSICAL processor, so an
+ emulated x86-64 interpreter on Windows on ARM answers "ARM64" while being win-amd64. The case
+ that matters is the unloadable win_arm64 wheel read as healthy."""
+ monkeypatch.setattr(sysconfig, "get_platform", lambda: "win-amd64")
+ monkeypatch.setattr(platform, "machine", lambda: "ARM64")
+
+ assert IF._host_cpu_family() == "x86_64"
+
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ assert IF._hf_xet_architecture_mismatch() is False, "healthy win_amd64 wheel called broken"
+
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_arm64",))
+ assert IF._hf_xet_architecture_mismatch() is True, "unloadable win_arm64 wheel called healthy"
+
+
+def _install_fake_environment(
+ monkeypatch,
+ hf_xet_present,
+ import_error,
+ distribution_installed = None,
+):
+ """`distribution_installed` is what importlib.metadata would say, a SEPARATE question from
+ what the import system says, and the only one is_xet_available() asks."""
+ monkeypatch.delitem(IF.sys.modules, "hf_xet", raising = False)
+ real_find_spec = importlib.util.find_spec
+ if distribution_installed is None:
+ distribution_installed = hf_xet_present
+ monkeypatch.setattr(IF, "_hf_xet_distribution_is_installed", lambda: distribution_installed)
+
+ def fake_find_spec(name, package = None):
+ if name == "huggingface_hub":
+ return importlib.machinery.ModuleSpec("huggingface_hub", None)
+ if name == "hf_xet":
+ if not hf_xet_present:
+ return None
+ spec = importlib.machinery.ModuleSpec("hf_xet", None, is_package = True)
+ spec.submodule_search_locations = []
+ return spec
+ return real_find_spec(name, package)
+
+ def fake_import_module(name, package = None):
+ if name == "hf_xet":
+ if import_error is not None:
+ raise import_error
+ return object()
+ return importlib.import_module(name, package)
+
+ monkeypatch.setattr(importlib.util, "find_spec", fake_find_spec)
+ monkeypatch.setattr(IF.importlib, "import_module", fake_import_module)
+
+
+def _raise_package_not_found(name):
+ raise importlib.metadata.PackageNotFoundError(name)
+
+
+_WRONG_ARCHITECTURE = ImportError(
+ "DLL load failed while importing hf_xet: %1 is not a valid Win32 application."
+)
+
+
+def test_fires_on_a_wrong_architecture_wheel(monkeypatch, caplog):
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+
+ 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"
+ # one line, naming the real cause rather than repeating "pip install hf_xet"
+ assert len(caplog.records) == 1
+ message = caplog.records[0].getMessage()
+ assert "architecture" in message and "win_amd64" in message
+
+ # idempotent
+ caplog.clear()
+ IF.fix_broken_hf_xet_wheel()
+ assert IF.os.environ.get("HF_HUB_DISABLE_XET") == "1"
+ assert not caplog.records
+
+
+def test_does_not_fire_when_hf_xet_imports(monkeypatch):
+ """The metadata only raises a suspicion; a successful import overrules it."""
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = None)
+
+ IF.fix_broken_hf_xet_wheel()
+ assert "HF_HUB_DISABLE_XET" not in IF.os.environ
+
+
+def test_does_not_fire_on_a_healthy_wheel(monkeypatch):
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_arm64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+
+ IF.fix_broken_hf_xet_wheel()
+ assert "HF_HUB_DISABLE_XET" not in IF.os.environ
+
+
+def test_does_not_fire_when_hf_xet_is_absent(monkeypatch):
+ """huggingface_hub already downgrades to HTTP by itself when hf_xet is not installed."""
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _install_fake_environment(monkeypatch, hf_xet_present = False, import_error = None)
+
+ IF.fix_broken_hf_xet_wheel()
+ assert "HF_HUB_DISABLE_XET" not in IF.os.environ
+
+
+def test_absence_is_decided_by_real_metadata_not_by_a_stub(monkeypatch):
+ """REGRESSION. Every other no-fire test stubs `_hf_xet_distribution_is_installed`, so one that
+ answered True for an uninstalled package would keep them green while a user with no hf_xet got
+ the warning and HF_HUB_DISABLE_XET=1. Here the real helper is used."""
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ monkeypatch.delitem(IF.sys.modules, "hf_xet", raising = False)
+ monkeypatch.setattr(IF, "importlib_version", _raise_package_not_found, raising = False)
+
+ 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 None
+ return real_find_spec(name, package)
+
+ monkeypatch.setattr(importlib.util, "find_spec", fake_find_spec)
+
+ assert IF._hf_xet_distribution_is_installed() is False
+ IF.fix_broken_hf_xet_wheel()
+ assert "HF_HUB_DISABLE_XET" not in IF.os.environ
+
+
+def test_an_imported_hf_xet_short_circuits_before_any_lookup(monkeypatch):
+ """REGRESSION. Removing that early return changes no other assertion, and raising from
+ 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"))
+
+ lookups = []
+
+ def recording_find_spec(name, package = None):
+ lookups.append(name)
+ return None
+
+ monkeypatch.setattr(importlib.util, "find_spec", recording_find_spec)
+ monkeypatch.setattr(
+ IF, "_hf_xet_distribution_is_installed", lambda: lookups.append("metadata") or False
+ )
+
+ IF.fix_broken_hf_xet_wheel()
+ assert lookups == []
+ assert "HF_HUB_DISABLE_XET" not in IF.os.environ
+
+
+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."""
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _install_fake_environment(
+ monkeypatch,
+ hf_xet_present = False, # find_spec -> None
+ import_error = ModuleNotFoundError("No module named 'hf_xet'"),
+ distribution_installed = True, # ...but importlib.metadata still sees it
+ )
+
+ 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 "not importable" in caplog.records[0].getMessage()
+
+
+def _compiled_object(kind, machine):
+ """Smallest ELF / PE / Mach-O header that carries a machine id."""
+ if kind == "elf":
+ return b"\x7fELF\x02\x01" + b"\0" * 12 + struct.pack("<H", machine) + b"\0" * 40
+ if kind == "pe":
+ head = bytearray(b"\0" * 0x100)
+ head[:2] = b"MZ"
+ struct.pack_into("<I", head, 0x3C, 0x80)
+ head[0x80:0x84] = b"PE\0\0"
+ struct.pack_into("<H", head, 0x84, machine)
+ return bytes(head)
+ return struct.pack("<II", 0xFEEDFACF, machine) + b"\0" * 40
+
+
+ "kind,machine,expected",
+ (
+ ("elf", 0x3E, "x86_64"),
+ ("elf", 0xB7, "arm64"),
+ ("elf", 0x28, "armv7l"),
+ ("elf", 0x1234, None),
+ ("pe", 0x8664, "x86_64"),
+ ("pe", 0xAA64, "arm64"),
+ ("pe", 0x014C, "x86"),
+ ("pe", 0x1234, None),
+ ("macho", 0x01000007, "x86_64"),
+ ("macho", 0x0100000C, "arm64"),
+ ("macho", 0x1234, None),
+ ),
+)
+def test_cpu_family_from_compiled_object(tmp_path, kind, machine, expected):
+ binary = tmp_path / "hf_xet.bin"
+ binary.write_bytes(_compiled_object(kind, machine))
+ assert IF._cpu_family_from_compiled_object(str(binary)) == expected
+
+
+def test_cpu_family_from_compiled_object_survives_garbage(tmp_path):
+ for name, payload in (("empty.bin", b""), ("short.bin", b"MZ"), ("text.bin", b"not a binary")):
+ binary = tmp_path / name
+ binary.write_bytes(payload)
+ assert IF._cpu_family_from_compiled_object(str(binary)) is None
+ assert IF._cpu_family_from_compiled_object(str(tmp_path / "missing.bin")) is None
+
+
+def test_extension_header_decides_when_wheel_metadata_is_unreadable(monkeypatch, tmp_path):
+ """REGRESSION. WHEEL metadata gone but the wrong-architecture extension still there.
+ huggingface_hub still routes to Xet, so giving up at "no readable tags" left it broken."""
+ package = tmp_path / "hf_xet"
+ package.mkdir()
+ extension = package / ("hf_xet" + importlib.machinery.EXTENSION_SUFFIXES[0])
+ extension.write_bytes(_compiled_object("pe", 0x8664)) # x86-64 binary
+
+ spec = importlib.machinery.ModuleSpec("hf_xet", None, is_package = True)
+ spec.submodule_search_locations = [str(package)]
+
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ())
+ _fake_host(monkeypatch, "win-arm64")
+ assert IF._hf_xet_architecture_mismatch(spec) is True
+
+ _fake_host(monkeypatch, "win-amd64")
+ assert IF._hf_xet_architecture_mismatch(spec) is False
+
+
+def test_extension_header_is_not_consulted_when_the_wheel_tag_is_readable(monkeypatch, tmp_path):
+ package = tmp_path / "hf_xet"
+ package.mkdir()
+ (package / ("hf_xet" + importlib.machinery.EXTENSION_SUFFIXES[0])).write_bytes(
+ _compiled_object("pe", 0x8664)
+ )
+ spec = importlib.machinery.ModuleSpec("hf_xet", None, is_package = True)
+ spec.submodule_search_locations = [str(package)]
+
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("macosx_10_9_universal2",))
+ _fake_host(monkeypatch, "win-arm64")
+ assert IF._hf_xet_architecture_mismatch(spec) is None
+
+
[email protected]("user_value", ("0", "1", "false"))
+def test_never_overrides_an_explicit_setting(monkeypatch, user_value):
+ monkeypatch.setenv("HF_HUB_DISABLE_XET", user_value)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+
+ IF.fix_broken_hf_xet_wheel()
+ assert IF.os.environ["HF_HUB_DISABLE_XET"] == user_value
+
+
[email protected]("user_value", ("1", "true", "YES", "on"))
+def test_an_explicit_disable_set_after_the_hub_was_imported_is_carried_through(
+ monkeypatch, user_value
+):
+ """REGRESSION. Setting the variable late is read by nobody, so honour it on the constant.
+
+ The user who imports transformers first and only then sets HF_HUB_DISABLE_XET=1 asked for Xet
+ off and, without this, still gets every download routed to Xet. The truthy set is
+ huggingface_hub's own ENV_VARS_TRUE_VALUES, matched case-insensitively as constants.py does.
+ """
+ monkeypatch.setenv("HF_HUB_DISABLE_XET", user_value)
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": False})
+
+ IF.fix_broken_hf_xet_wheel()
+
+ assert modules["constants"].HF_HUB_DISABLE_XET is True
+ assert IF.os.environ["HF_HUB_DISABLE_XET"] == user_value
+
+
[email protected]("user_value", ("0", "false", "no", "off"))
+def test_an_explicit_enable_is_never_carried_through(monkeypatch, user_value):
+ """The opposite direction must still win: a user who asked for Xet keeps it."""
+ monkeypatch.setenv("HF_HUB_DISABLE_XET", user_value)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": False})
+
+ IF.fix_broken_hf_xet_wheel()
+
+ assert modules["constants"].HF_HUB_DISABLE_XET is False
+ assert IF.os.environ["HF_HUB_DISABLE_XET"] == user_value
+
+
+def _fake_hub_modules(monkeypatch, bindings):
+ """`bindings` maps a module suffix ("" is the package) to its starting HF_HUB_DISABLE_XET, or
+ to `_UNBOUND` for a module that does not define the flag (every module before 0.34)."""
+ modules = {}
+ for suffix, value in bindings.items():
+ name = "huggingface_hub" + (f".{suffix}" if suffix else "")
+ module = types.ModuleType(name)
+ if value is not _UNBOUND:
+ module.HF_HUB_DISABLE_XET = value
+ monkeypatch.setitem(sys.modules, name, module)
+ modules[suffix] = module
+ return modules
+
+
+_UNBOUND = object()
+
+
+def test_patches_the_frozen_constant_when_the_hub_is_already_imported(monkeypatch):
+ """REGRESSION. huggingface_hub >= 0.34 evaluates HF_HUB_DISABLE_XET once, at import time, so
+ for a user whose script starts with `import transformers` the variable alone fixes nothing."""
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": False})
+
+ IF.fix_broken_hf_xet_wheel()
+
+ assert IF.os.environ.get("HF_HUB_DISABLE_XET") == "1", "the variable must still be set too"
+ assert (
+ modules["constants"].HF_HUB_DISABLE_XET is True
+ ), "the already frozen constant was left False, so this process still routes to Xet"
+
+
+def test_patches_every_module_that_binds_the_flag(monkeypatch):
+ """Patch by attribute, not by hardcoded module name: a module that ever does
+ `from .constants import HF_HUB_DISABLE_XET` would hold its own copy that patching constants.py
+ could not reach. Today constants.py is the only binding that exists.
+ """
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+ modules = _fake_hub_modules(
+ monkeypatch,
+ {
+ "": _UNBOUND,
+ "constants": False,
+ "file_download": False, # a hypothetical `from .constants import ...` copy
+ "utils._xet": False, # ditto
+ "utils._runtime": _UNBOUND, # reads constants.X, holds no copy: must stay unbound
+ },
+ )
+ # a look-alike package must not be caught by the prefix match
+ decoy = types.ModuleType("huggingface_hubby")
+ decoy.HF_HUB_DISABLE_XET = False
+ monkeypatch.setitem(sys.modules, "huggingface_hubby", decoy)
+
+ IF.fix_broken_hf_xet_wheel()
+
+ for suffix in ("constants", "file_download", "utils._xet"):
+ assert modules[suffix].HF_HUB_DISABLE_XET is True, f"{suffix} kept its stale copy"
+ assert not hasattr(modules["utils._runtime"], "HF_HUB_DISABLE_XET")
+ assert not hasattr(modules[""], "HF_HUB_DISABLE_XET")
+ assert decoy.HF_HUB_DISABLE_XET is False, "patched an unrelated package by prefix"
+
+
+def test_does_not_invent_the_flag_on_hub_versions_that_never_had_it(monkeypatch):
+ """Before 0.34 the Hub read os.environ per call, so the variable alone is the whole fix and
+ creating the attribute would put a value into a namespace upstream does not own.
+ """
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE)
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": _UNBOUND})
+
+ IF.fix_broken_hf_xet_wheel()
+
+ assert IF.os.environ.get("HF_HUB_DISABLE_XET") == "1"
+ assert not hasattr(modules["constants"], "HF_HUB_DISABLE_XET")
+
+
+def test_does_not_import_huggingface_hub_just_to_patch_it(monkeypatch):
+ """The normal ordering. Nothing is frozen yet, and importing the Hub here would move its cost
+ into every unsloth import."""
+ monkeypatch.delitem(sys.modules, "huggingface_hub", raising = False)
+ for name in [n for n in sys.modules if n.startswith("huggingface_hub.")]:
+ monkeypatch.delitem(sys.modules, name, raising = False)
+
+ assert IF._disable_xet_on_already_imported_huggingface_hub() == ()
+ assert "huggingface_hub" not in sys.modules
+
+
[email protected]("scenario", ("healthy", "absent", "explicit"))
+def test_leaves_the_frozen_constant_alone_when_the_fix_does_not_fire(monkeypatch, scenario):
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": False})
+ _fake_host(monkeypatch, "win-arm64")
+ monkeypatch.setattr(IF, "_hf_xet_wheel_platform_tags", lambda: ("win_amd64",))
+
+ if scenario == "healthy":
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _install_fake_environment(monkeypatch, hf_xet_present = True, import_error = None)
+ elif scenario == "absent":
+ monkeypatch.delenv("HF_HUB_DISABLE_XET", raising = False)
+ _install_fake_environment(monkeypatch, hf_xet_present = False, import_error = None)
+ else:
+ monkeypatch.setenv("HF_HUB_DISABLE_XET", "0")
+ _install_fake_environment(
+ monkeypatch, hf_xet_present = True, import_error = _WRONG_ARCHITECTURE
+ )
+
+ IF.fix_broken_hf_xet_wheel()
+
+ assert modules["constants"].HF_HUB_DISABLE_XET is False
+
+
+def test_patching_is_idempotent_and_reports_only_real_changes(monkeypatch):
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": False})
+
+ assert IF._disable_xet_on_already_imported_huggingface_hub() == ("huggingface_hub.constants",)
+ assert modules["constants"].HF_HUB_DISABLE_XET is True
+ assert IF._disable_xet_on_already_imported_huggingface_hub() == ()
+
+
+def test_patching_survives_hostile_modules(monkeypatch):
+ """Lazy packages raise from __getattr__, None entries linger, modules refuse setattr. A bad
+ neighbour must not stop the module that matters from being patched."""
+ modules = _fake_hub_modules(monkeypatch, {"": _UNBOUND, "constants": False})
+
+ class Exploding(types.ModuleType):
+ def __getattr__(self, item):
+ raise RuntimeError("lazy import blew up")
+
+ class ReadOnly(types.ModuleType):
+ HF_HUB_DISABLE_XET = False
+
+ def __setattr__(self, item, value):
+ raise AttributeError("read only module")
+
+ monkeypatch.setitem(sys.modules, "huggingface_hub.lazy", Exploding("huggingface_hub.lazy"))
+ monkeypatch.setitem(sys.modules, "huggingface_hub.frozen", ReadOnly("huggingface_hub.frozen"))
+ monkeypatch.setitem(sys.modules, "huggingface_hub.gone", None)
+
+ patched = IF._disable_xet_on_already_imported_huggingface_hub()
+
+ assert patched == ("huggingface_hub.constants",)
+ assert modules["constants"].HF_HUB_DISABLE_XET is True
+
+
+def test_runs_before_anything_imports_huggingface_hub():
+ source = (Path(__file__).resolve().parent.parent / "unsloth" / "_gpu_init.py").read_text(
+ encoding = "utf-8"
+ )
+ assert "fix_broken_hf_xet_wheel()" in source, (
+ "DRIFT DETECTED: fix_broken_hf_xet_wheel is defined but never called in _gpu_init.py, "
+ "so real imports never apply it."
+ )
+ assert source.index("fix_broken_hf_xet_wheel()") < source.index("fix_huggingface_hub()"), (
+ "fix_broken_hf_xet_wheel() must run before fix_huggingface_hub(), which imports "
+ "huggingface_hub and freezes HF_HUB_DISABLE_XET."
+ )
+
+
+def test_is_the_very_first_import_fix_called():
+ """Survives refactoring, unlike the pairwise check above: a fix added later could freeze
+ HF_HUB_DISABLE_XET before we set it with no failure anywhere to say so."""
+ gpu_init = Path(__file__).resolve().parent.parent / "unsloth" / "_gpu_init.py"
+ source = gpu_init.read_text(encoding = "utf-8")
+
+ imported = source.split("from .import_fixes import (", 1)[1].split(")", 1)[0]
+ names = [line.strip().rstrip(",") for line in imported.splitlines() if line.strip()]
+ assert "fix_broken_hf_xet_wheel" in names
+
+ calls = sorted((source.index(f"\n{name}("), name) for name in names if f"\n{name}(" in source)
+ assert calls[0][1] == "fix_broken_hf_xet_wheel", (
+ f"fix_broken_hf_xet_wheel() must be the first import fix invoked in _gpu_init.py, but "
+ f"{calls[0][1]}() runs before it. huggingface_hub freezes HF_HUB_DISABLE_XET into "
+ f"constants.py at import time, so anything that reaches the Hub first makes this fix a "
+ f"no-op."
+ )
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 91a3877e6b3..bc4592c119e 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -37,6 +37,7 @@ from .import_fixes import (
disable_torchaudio_if_cuda_mismatched,
fix_diffusers_warnings,
fix_huggingface_hub,
+ fix_broken_hf_xet_wheel,
)
# Redirect a read-only Hugging Face cache before anything below imports huggingface_hub /
@@ -64,6 +65,10 @@ try:
except Exception:
pass
+# Before anything imports huggingface_hub (disable_broken_vllm, check_fbgemm_gpu_version and
+# fix_huggingface_hub all reach it): the Hub freezes HF_HUB_DISABLE_XET at import time. Stdlib
+# only, so it does not disturb the torch ordering the next comment describes.
+fix_broken_hf_xet_wheel()
# Configure libdrm ids table path early so ROCm can resolve AMD GPU names. Stdlib only,
# and it must stay ahead of the first `import torch` in this file: it sets
# AMDGPU_ASIC_ID_TABLE_PATH, and a torch that has already brought up libdrm would not see
@@ -113,6 +118,7 @@ del check_triton_py_ssize_t_clean
del torchvision_compatibility_check
del fix_diffusers_warnings
del fix_huggingface_hub
+del fix_broken_hf_xet_wheel
# Unsloth patches these libraries at import time; if they are imported first the unoptimized
# versions run, risking OOM or slower training.
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 3d410e3eb65..d8fffe396b7 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -1403,6 +1403,298 @@ def ignore_logger_messages():
pass
+# huggingface_hub routes to Xet on `is_xet_available()`, which asks importlib.metadata whether the
+# hf_xet DISTRIBUTION is installed and never whether it IMPORTS, so an unloadable hf_xet is still
+# routed to and dies as transformers' misleading "you need to install the hf_xet package".
+# HF_HUB_DISABLE_XET=1 is the Hub's own way off that path, and constants.py freezes it at import
+# time, which is why this is wired into the FIRST block of _gpu_init.py, not the late fixes.
+# unsloth_zoo.hf_xet_fallback does not cover this: it is a stall watchdog around its own wrappers,
+# and an ImportError at import time never reaches it.
+_CPU_FAMILY_BY_MACHINE = {
+ "amd64": "x86_64",
+ "x86_64": "x86_64",
+ "x64": "x86_64",
+ "arm64": "arm64",
+ "aarch64": "arm64",
+ "i386": "x86",
+ "i686": "x86",
+ "x86": "x86",
+ "armv7l": "armv7l",
+ "ppc64le": "ppc64le",
+ "s390x": "s390x",
+}
+# Windows tags name the cpu outright; every other OS carries it as the tag's last token.
+_WINDOWS_PLATFORM_TAG_CPU = {
+ "win_amd64": "x86_64",
+ "win_arm64": "arm64",
+ "win32": "x86",
+}
+_MULTI_ARCH_PLATFORM_TAG_PREFIXES = ("macosx_", "manylinux", "musllinux", "linux_")
+# Header machine ids, for installs whose WHEEL metadata cannot be read. A family absent here reads
+# as "cannot tell", which is never a mismatch.
+_ELF_MACHINE_CPU = {
+ 0x03: "x86",
+ 0x15: "ppc64le",
+ 0x16: "s390x",
+ 0x28: "armv7l",
+ 0x3E: "x86_64",
+ 0xB7: "arm64",
+}
+_PE_MACHINE_CPU = {0x014C: "x86", 0x01C4: "armv7l", 0x8664: "x86_64", 0xAA64: "arm64"}
+# huggingface_hub.constants.ENV_VARS_TRUE_VALUES, matched after .upper(), so an explicit disable
+# is read exactly the way the Hub itself would have read it.
+_HF_HUB_ENV_TRUE_VALUES = ("1", "ON", "TRUE", "YES")
+_MACHO_CPU_TYPE_CPU = {7: "x86", 12: "armv7l", 0x01000007: "x86_64", 0x0100000C: "arm64"}
+
+
+def _host_cpu_family():
+ """CPU family of THIS interpreter, or None when it cannot be told.
+
+ sysconfig first: it reports what the interpreter was BUILT for, which is what a wheel tag must
+ match. platform.machine() is WRONG on Windows, where CPython asks WMI for the PHYSICAL cpu, so
+ an emulated x86-64 process on Windows on ARM answers "ARM64" while being win-amd64. It stays
+ only as the fallback for platforms sysconfig cannot name a cpu for, chiefly macOS universal2.
+ """
+ import platform
+ import sysconfig
+
+ try:
+ host_platform = sysconfig.get_platform().strip().lower()
+ except Exception:
+ host_platform = ""
+ if host_platform:
+ family = _WINDOWS_PLATFORM_TAG_CPU.get(host_platform.replace("-", "_"))
+ if family is None:
+ # linux-x86_64, macosx-11.0-arm64: cpu is the last token.
+ family = _CPU_FAMILY_BY_MACHINE.get(host_platform.rsplit("-", 1)[-1])
+ if family is not None:
+ return family
+ try:
+ return _CPU_FAMILY_BY_MACHINE.get(platform.machine().strip().lower())
+ except Exception:
+ return None
+
+
+def _cpu_family_from_compiled_object(path):
+ """CPU family an ELF / PE / Mach-O file targets, read from its header, or None."""
+ import struct
+
+ try:
+ with open(path, "rb") as binary:
+ head = binary.read(4096)
+ except Exception:
+ return None
+ try:
+ if head[:4] == b"\x7fELF":
+ endian = "<" if head[5] == 1 else ">"
+ return _ELF_MACHINE_CPU.get(struct.unpack_from(endian + "H", head, 18)[0])
+ if head[:2] == b"MZ":
+ pe_offset = struct.unpack_from("<I", head, 0x3C)[0]
+ if head[pe_offset : pe_offset + 4] != b"PE\0\0":
+ return None
+ return _PE_MACHINE_CPU.get(struct.unpack_from("<H", head, pe_offset + 4)[0])
+ magic = struct.unpack_from("<I", head, 0)[0]
+ if magic in (0xFEEDFACE, 0xFEEDFACF): # little endian Mach-O, 32 and 64 bit
+ return _MACHO_CPU_TYPE_CPU.get(struct.unpack_from("<i", head, 4)[0] & 0xFFFFFFFF)
+ if magic in (0xCEFAEDFE, 0xCFFAEDFE): # byte swapped
+ return _MACHO_CPU_TYPE_CPU.get(struct.unpack_from(">i", head, 4)[0] & 0xFFFFFFFF)
+ except Exception:
+ return None
+ return None # Mach-O universal binaries carry several cpus: unreadable on purpose.
+
+
+def _hf_xet_extension_cpu_families(spec):
+ """CPU families of hf_xet's compiled extensions, or () when unreadable. The fallback when the
+ WHEEL metadata is gone: the .pyd/.so still says what it was built for."""
+ families = set()
+ for location in list(getattr(spec, "submodule_search_locations", None) or []):
+ try:
+ names = os.listdir(location)
+ except Exception:
+ continue
+ for name in names:
+ if not name.endswith(tuple(importlib.machinery.EXTENSION_SUFFIXES)):
+ continue
+ family = _cpu_family_from_compiled_object(os.path.join(location, name))
+ if family is None:
+ return ()
+ families.add(family)
+ return tuple(sorted(families))
+
+
+def _cpu_family_from_platform_tag(platform_tag):
+ """CPU family a wheel platform tag targets, or None when it cannot be told: a tag we cannot
+ read (`any`, macOS universal2) must never be reported as a mismatch."""
+ platform_tag = platform_tag.strip().lower()
+ if platform_tag in _WINDOWS_PLATFORM_TAG_CPU:
+ return _WINDOWS_PLATFORM_TAG_CPU[platform_tag]
+ if not platform_tag.startswith(_MULTI_ARCH_PLATFORM_TAG_PREFIXES):
+ return None
+ for machine, family in _CPU_FAMILY_BY_MACHINE.items():
+ if platform_tag.endswith("_" + machine):
+ return family
+ return None
+
+
+def _hf_xet_distribution_is_installed():
+ """True when importlib.metadata sees an hf_xet distribution, the only question
+ huggingface_hub's is_xet_available() asks before routing a download to Xet."""
+ try:
+ importlib_version("hf_xet")
+ except Exception:
+ return False
+ return True
+
+
+def _hf_xet_wheel_platform_tags():
+ """Platform components of the installed hf_xet's WHEEL tags, or () when unreadable."""
+ try:
+ wheel_metadata = importlib_distribution("hf_xet").read_text("WHEEL")
+ except Exception:
+ return ()
+ if not wheel_metadata:
+ return ()
+ platform_tags = []
+ for line in wheel_metadata.splitlines():
+ if not line.lower().startswith("tag:"):
+ continue
+ tag = line.split(":", 1)[1].strip()
+ parts = tag.rsplit("-", 1)
+ if len(parts) != 2 or not parts[1]:
+ continue
+ # compressed tag sets join platforms with a dot
+ platform_tags.extend(parts[1].split("."))
+ return tuple(platform_tags)
+
+
+def _hf_xet_architecture_mismatch(spec = None):
+ """True if hf_xet targets a CPU family this interpreter is not, False if it matches, None when
+ either side cannot be read. Metadata and file headers only: nothing is imported here."""
+ host_family = _host_cpu_family()
+ if host_family is None:
+ return None
+ wheel_families = set()
+ for platform_tag in _hf_xet_wheel_platform_tags():
+ family = _cpu_family_from_platform_tag(platform_tag)
+ if family is None:
+ return None # one unreadable tag makes the whole verdict unsafe
+ wheel_families.add(family)
+ if not wheel_families:
+ # No readable WHEEL metadata. The extension's own header is the better source anyway.
+ wheel_families = set(_hf_xet_extension_cpu_families(spec))
+ if not wheel_families:
+ return None
+ return host_family not in wheel_families
+
+
+def _hf_xet_extension_is_missing(spec):
+ """True only when hf_xet's package directory holds no compiled extension at all."""
+ locations = list(getattr(spec, "submodule_search_locations", None) or [])
+ if not locations:
+ return False
+ suffixes = tuple(importlib.machinery.EXTENSION_SUFFIXES)
+ for location in locations:
+ try:
+ names = os.listdir(location)
+ except Exception:
+ return False
+ if any(name.endswith(suffixes) for name in names):
+ return False
+ return True
+
+
+def _disable_xet_on_already_imported_huggingface_hub():
+ """Turn Xet off in an ALREADY imported huggingface_hub, returning the bindings changed.
+
+ The variable alone is not enough: >= 0.34 freezes it into `constants.HF_HUB_DISABLE_XET` at
+ import time. Readers go through the module attribute, never a local copy, so rebinding does
+ take effect. Every module is scanned, not constants.py alone, so a future
+ `from .constants import HF_HUB_DISABLE_XET` is covered; versions without the attribute are
+ left alone rather than given one.
+ """
+ if "huggingface_hub" not in sys.modules:
+ # Nothing frozen yet, and importing the Hub just to patch it would cost every user.
+ return ()
+
+ patched = []
+ for name, module in list(sys.modules.items()):
+ if module is None:
+ continue
+ if name != "huggingface_hub" and not name.startswith("huggingface_hub."):
+ continue
+ try:
+ current = getattr(module, "HF_HUB_DISABLE_XET")
+ except Exception:
+ continue # no binding here to fix, and we must not invent one
+ if current is True:
+ continue
+ try:
+ setattr(module, "HF_HUB_DISABLE_XET", True)
+ except Exception:
+ continue
+ patched.append(name)
+ return tuple(patched)
+
+
+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()
+ if explicit != "":
+ # Set explicitly, in either direction: the user's choice outranks ours. A TRUTHY value set
+ # after the Hub was already imported is read by nobody, though, so carry it to the frozen
+ # constant. Falsey values are left alone, so an explicit opt back IN to Xet still wins.
+ 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
+ try:
+ if importlib.util.find_spec("huggingface_hub") is None:
+ return
+ spec = importlib.util.find_spec("hf_xet")
+ except Exception:
+ return
+ if spec is None:
+ # find_spec cannot see it, but huggingface_hub never asks find_spec: a leftover
+ # hf_xet-*.dist-info with no package beside it still reports Xet available and still dies
+ # in `from hf_xet import XetFileInfo`. A genuinely absent hf_xet has no metadata either
+ # and is left alone, since huggingface_hub handles that case correctly.
+ if not _hf_xet_distribution_is_installed():
+ return
+ suspicion = (
+ "its distribution metadata is installed but the package itself is not importable"
+ )
+ elif _hf_xet_architecture_mismatch(spec) is True:
+ suspicion = "it is built for a different CPU architecture than this interpreter"
+ elif _hf_xet_extension_is_missing(spec):
+ suspicion = "its compiled extension module is missing from the installed package"
+ else:
+ return
+
+ # 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.
+ try:
+ importlib.import_module("hf_xet")
+ return
+ except Exception as error:
+ failure = f"{type(error).__name__}: {error}"
+
+ # The variable is what child processes inherit; the helper is what fixes THIS process when
+ # something already imported the Hub and froze the constant.
+ os.environ["HF_HUB_DISABLE_XET"] = "1"
+ _disable_xet_on_already_imported_huggingface_hub()
+ logger.warning(
+ f"Unsloth: `hf_xet` is installed but cannot be imported ({failure}) because {suspicion} "
+ f"(wheel platform tag(s): {', '.join(_hf_xet_wheel_platform_tags()) or 'unknown'}). "
+ "Set HF_HUB_DISABLE_XET=1, so Hugging Face downloads use plain HTTPS instead: same files, "
+ "same cache, only the Xet transport is skipped. Note that without this, transformers "
+ "reports 'you need to install the hf_xet package', which is misleading: hf_xet IS "
+ "installed, it is simply not loadable by this Python, and reinstalling the same wheel "
+ "cannot fix it. To get Xet back, install an hf_xet built for this interpreter, for example "
+ "`pip install --force-reinstall --no-cache-dir hf_xet`."
+ )
+
+
def patch_ipykernel_hf_xet():
# HF-XET 1.1.10 with ipykernel 7.0.0 / 7.0.1 raises LookupError on ContextVar 'shell_parent';
# see huggingface/xet-core#526.