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.

Say when xformers is installed but cannot load, and how to fix it (#13410)

Daniel Hanff64a01d6639
diff --git a/tests/utils/test_xformers_broken_message.py b/tests/utils/test_xformers_broken_message.py
new file mode 100644
index 00000000000..9868a2c2b92
--- /dev/null
+++ b/tests/utils/test_xformers_broken_message.py
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""unslothai/unsloth#4381: an installed xformers whose CUDA extension cannot load
+(PyPI's cu128 Windows wheel beside a cu130 torch) left only "Xformers = None" in
+the banner. Unsloth must say why and how to fix it, and stay quiet when it loads."""
+
+import importlib.util
+import os
+import subprocess
+import sys
+
+import pytest
+from real_accelerator import has_real_cuda # tests/_shared, on sys.path via tests/conftest.py
+
+pytestmark = pytest.mark.skipif(
+ not has_real_cuda() or importlib.util.find_spec("xformers") is None,
+ reason = "needs a CUDA GPU and an installed xformers",
+)
+
+# Raise xformers' own exception, so the message format Unsloth parses is the installed package's.
+_BREAK_XFORMERS = """
+import xformers._cpp_lib as c
+def _register_extensions():
+ raise c.xFormersInvalidLibException(c._build_metadata) from OSError("libcudart.so.12: cannot open shared object file")
+c._register_extensions = _register_extensions
+"""
+
+# The generic tests must not trip the Blackwell + old-xformers guard, which disables xformers on purpose.
+_PAST_VERSION_GUARD = """
+import xformers
+xformers.__version__ = "0.0.35"
+"""
+
+_IMPORT_UNSLOTH = """
+import unsloth.models._utils as u
+print("XFORMERS_IS_NONE", u.xformers is None)
+"""
+
+
+def _run(code):
+ env = {k: v for k, v in os.environ.items() if k != "UNSLOTH_ENABLE_LOGGING"}
+ result = subprocess.run(
+ [sys.executable, "-c", code],
+ capture_output = True,
+ text = True,
+ env = env,
+ timeout = 600,
+ )
+ assert result.returncode == 0, result.stderr[-3000:]
+ return result.stdout
+
+
+def test_broken_xformers_is_reported():
+ import xformers._cpp_lib as c
+
+ out = _run(_PAST_VERSION_GUARD + _BREAK_XFORMERS + _IMPORT_UNSLOTH)
+ assert "XFORMERS_IS_NONE True" in out
+ assert "xformers is installed but cannot load with torch" in out
+ # No build metadata (xformers already failed its own load here) means no version to name.
+ assert ("(it was built for " in out) is (c._build_metadata is not None)
+ assert "unsloth install-kernels xformers" in out
+
+
+def test_version_guard_keeps_its_own_fix():
+ # install-kernels maps torch 2.8 back to 0.0.32.post2, so it cannot fix this guard.
+ old_blackwell_xformers = (
+ "import torch, xformers\n"
+ "xformers.__version__ = '0.0.32.post2'\n"
+ "torch.cuda.get_device_capability = lambda *args, **kwargs: (12, 0)\n"
+ )
+ out = _run(old_blackwell_xformers + _IMPORT_UNSLOTH)
+ assert "XFORMERS_IS_NONE True" in out
+ assert "has a broken FA3 dispatch" in out
+ assert "unsloth install-kernels xformers" not in out
+
+
+def test_working_xformers_prints_nothing():
+ import xformers._cpp_lib as c
+
+ if c._cpp_library_load_exception is not None:
+ pytest.skip("installed xformers does not load here")
+ out = _run(_PAST_VERSION_GUARD + _IMPORT_UNSLOTH)
+ assert "XFORMERS_IS_NONE False" in out
+ assert "xformers is installed but cannot load" not in out
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 444ec1d4771..e8327fec208 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -3840,7 +3840,7 @@ try:
"Then confirm if it's correctly installed by running:\n"
"python -m xformers.info\n\n"
"Longer error message:\n" + str(error)
- )
+ ) from error
import xformers.ops.fmha as xformers
xformers_attention = xformers.memory_efficient_attention
@@ -3852,6 +3852,20 @@ except Exception as e:
if UNSLOTH_ENABLE_LOGGING:
print("========\nSwitching to PyTorch attention since your Xformers is broken.\n========\n")
print(str(e))
+ elif DEVICE_TYPE == "cuda" and str(e).startswith("Unsloth:") and e.__cause__ is None:
+ # The version guards above (e.g. Blackwell FA3 dispatch) carry their own fix; install-kernels would not apply it.
+ print(str(e))
+ elif DEVICE_TYPE == "cuda":
+ # xformers' own warning is silenced above; usually PyPI's cu128 wheel beside a cu130 torch (#4381).
+ _built_for = re.search(r"PyTorch (\S+) with CUDA \S+ \(you have", str(e))
+ print(
+ "Unsloth: xformers is installed but cannot load with torch "
+ f"{torch_version}{f' (it was built for {_built_for.group(1)})' if _built_for else ''}, "
+ "so PyTorch attention is used instead.\n"
+ "To install a matching xformers, run `unsloth install-kernels xformers`, "
+ "or `pip uninstall xformers` to hide this. UNSLOTH_ENABLE_LOGGING=1 shows the full error."
+ )
+ del _built_for
xformers = None
xformers_attention = None
xformers_version = None