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.

Import fix: torchao 0.17+ on torch 2.6 (torch.utils._pytree.register_constant) (#14299)

Daniel Han2c3245915b7d
diff --git a/tests/test_torchao_torch_symbol_skew.py b/tests/test_torchao_torch_symbol_skew.py
index 2f3ac67cc9f..6d2e59cf9a7 100644
--- a/tests/test_torchao_torch_symbol_skew.py
+++ b/tests/test_torchao_torch_symbol_skew.py
@@ -292,5 +292,74 @@ def test_a_missing_version_is_not_patched(monkeypatch):
assert IF.fix_torchao_torch_symbol_skew() is False
+def _fake_torchao(monkeypatch, version):
+ import unsloth.import_fixes as IF
+
+ real_find_spec = importlib.util.find_spec
+ monkeypatch.setattr(
+ IF.importlib.util,
+ "find_spec",
+ lambda name, *a, **k: object() if name == "torchao" else real_find_spec(name, *a, **k),
+ )
+ monkeypatch.setattr(IF, "importlib_version", lambda name: version)
+ return IF
+
+
+def test_register_constant_pass_through_on_a_torch_without_it(monkeypatch):
+ """torch 2.6 has no torch.utils._pytree.register_constant; torchao >= 0.16 calls it at import."""
+ import torch.utils._pytree as pytree
+
+ IF = _fake_torchao(monkeypatch, "0.18.0")
+ had = hasattr(pytree, "register_constant")
+ monkeypatch.delattr(pytree, "register_constant", raising = False)
+ try:
+ assert IF.fix_torchao_pytree_register_constant() is True
+ assert pytree.register_constant.__unsloth_placeholder__ is True
+
+ class Enumish:
+ pass
+
+ assert pytree.register_constant(Enumish) is None
+ assert IF.fix_torchao_pytree_register_constant() is False, "a second call must not stack"
+ finally:
+ # monkeypatch restores only what existed; on torch 2.6 the placeholder must not outlive the test.
+ if not had and hasattr(pytree, "register_constant"):
+ delattr(pytree, "register_constant")
+
+
+def test_register_constant_left_alone_where_torch_has_it_or_torchao_is_older(monkeypatch):
+ import torch.utils._pytree as pytree
+
+ IF = _fake_torchao(monkeypatch, "0.18.0")
+ sentinel = lambda cls: cls
+ monkeypatch.setattr(pytree, "register_constant", sentinel, raising = False)
+ assert IF.fix_torchao_pytree_register_constant() is False
+ assert pytree.register_constant is sentinel
+
+ IF = _fake_torchao(monkeypatch, "0.16.0")
+ monkeypatch.delattr(pytree, "register_constant", raising = False)
+ assert IF.fix_torchao_pytree_register_constant() is False
+ assert not hasattr(pytree, "register_constant")
+
+
+def test_register_constant_fix_runs_before_unsloth_zoo_and_is_cleaned_up():
+ src = GPU_INIT.read_text(encoding = "utf-8")
+ lines = src.splitlines()
+ call = next(
+ i for i, l in enumerate(lines) if l.strip() == "fix_torchao_pytree_register_constant()"
+ )
+ zoo = next(i for i, l in enumerate(lines) if l.strip() == "import unsloth_zoo")
+ assert call < zoo
+ assert "fix_torchao_pytree_register_constant," in src
+ assert "del fix_torchao_pytree_register_constant" in src
+
+
+def test_the_mlx_path_applies_the_register_constant_fix_too():
+ lines = INIT.read_text(encoding = "utf-8").splitlines()
+ fix = next(i for i, l in enumerate(lines) if "_fix_pytree()" in l)
+ zoo = next(i for i, l in enumerate(lines) if l.strip() == "import unsloth_zoo")
+ assert fix < zoo, "the fix must precede the MLX unsloth_zoo import"
+
+
if __name__ == "__main__":
raise SystemExit(pytest.main([__file__, "-q"]))
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 2a1e70f35f7..f24def56590 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -186,6 +186,13 @@ if _IS_MLX:
del _fix_torchao
except Exception:
pass
+ try:
+ # Same for torchao 0.17+ on torch 2.6 (`register_constant`).
+ from .import_fixes import fix_torchao_pytree_register_constant as _fix_pytree
+ _fix_pytree()
+ del _fix_pytree
+ except Exception:
+ pass
try:
# Same reason: MLX audio reaches xcodec2 -> torchtune -> the old torchao.dtypes.nf4tensor path.
from .import_fixes import fix_torchao_nf4tensor_move as _fix_nf4
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index d0029b77ebe..91f655791b7 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -28,6 +28,7 @@ from .import_fixes import (
check_transformers_prequantized_vlm_quant_state,
fix_torch_check_is_size,
fix_torchao_torch_symbol_skew,
+ fix_torchao_pytree_register_constant,
propagate_torchao_fix_to_subprocesses,
check_fbgemm_gpu_version,
check_transformers_dependency_versions,
@@ -92,6 +93,8 @@ patch_torch_missing_attribute_error()
fix_bitsandbytes_rocm_arch_detection()
# Torch-only, so it can run first; torchao 0.18 on torch < 2.10 needs it before any torchao import.
fix_torchao_torch_symbol_skew()
+# Same skew for torchao 0.17+ on torch 2.6 (no pytree register_constant).
+fix_torchao_pytree_register_constant()
# Before unsloth_zoo and transformers (and vllm, below): real torchao on a torch without torch.distributed.
from ._torchao_nodist import fix_torchao_without_torch_distributed
@@ -128,6 +131,7 @@ del fix_message_factory_issue
del patch_torch_missing_attribute_error
del fix_torch_check_is_size
del fix_torchao_torch_symbol_skew
+del fix_torchao_pytree_register_constant
del propagate_torchao_fix_to_subprocesses
del check_fbgemm_gpu_version
del check_transformers_dependency_versions
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 3d87fab1fdb..5878c8f9919 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -11332,6 +11332,45 @@ def fix_torchao_torch_symbol_skew():
return bool(patched)
+def fix_torchao_pytree_register_constant():
+ """Let `import unsloth` survive torchao 0.17+ on torch 2.6.
+
+ torchao 0.17+ calls `torch.utils._pytree.register_constant` on its config enums at import
+ time (0.16 only in its MX prototype), and that function arrived in torch 2.7, so on
+ torch 2.6 importing transformers (which imports torchao) raises AttributeError. A
+ pass-through is the exact torch 2.6 behaviour: there are no pytree constants, so the
+ enums stay plain leaves for dynamo, and nothing is computed differently.
+ """
+ if importlib.util.find_spec("torchao") is None:
+ return False
+ try:
+ torchao_version = importlib_version("torchao")
+ if Version(torchao_version) < Version("0.17.0"):
+ return False
+ import torch
+ import torch.utils._pytree as pytree
+ except Exception:
+ return False
+ if hasattr(pytree, "register_constant"):
+ return False
+
+ def register_constant(cls):
+ return None
+
+ register_constant.__unsloth_placeholder__ = True
+ try:
+ pytree.register_constant = register_constant
+ except Exception:
+ return False
+ logger.info(
+ "Unsloth: torchao %s needs torch.utils._pytree.register_constant, which torch %s "
+ "does not have (it arrived in torch 2.7). Adding a pass-through so the import succeeds.",
+ torchao_version,
+ torch.__version__,
+ )
+ return True
+
+
# vLLM inspects architectures in a separate process that imports torchao itself, never sees a
# parent monkey-patch, and fails the same way. sitecustomize is the one hook reaching a process
# we do not launch: site imports it at startup off the inherited PYTHONPATH. A .pth would need