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
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.pynew file mode 100644index 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.pyindex 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_cleandel torchvision_compatibility_checkdel fix_diffusers_warningsdel 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.pyindex 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.