Install & Compatibility
Where this runs
tested against v0.0.35 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ dependency_conflict
2/4 runs
py 3.11
✕ dependency_conflict
3/4 runs
py 3.12
✕ dependency_conflict
3/4 runs
py 3.13
✕ dependency_conflict
3/4 runs
py 3.9
✕ dependency_conflict
✕ timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
memory_efficient_attention
✓ from xformers.ops import memory_efficient_attention
The primary optimized attention function.
LowerTriangularMask
✓ from xformers.ops.fmha.attn_bias import LowerTriangularMask
Common attention bias for causal masking.
AttentionOpBase
✓ from xformers.ops import AttentionOpBase
Base class for attention operators, used for dispatching or enforcing specific backends.
This quickstart demonstrates how to use `xformers.ops.memory_efficient_attention` with dummy PyTorch tensors for both standard and causal attention patterns. It highlights the typical tensor shape and the common practice of using half-precision floating-point numbers (float16) for performance on GPUs. The `xformers.info` utility is also mentioned for diagnostics. Ensure PyTorch and CUDA are properly installed and configured.
import torch
from xformers.ops import memory_efficient_attention, LowerTriangularMask
# Ensure tensors are on CUDA if available
device = "cuda" if torch.cuda.is_available() else "cpu"
# Assume batch_size=2, seq_len=128, num_heads=8, head_dim=64
batch_size = 2
seq_len = 128
num_heads = 8
head_dim = 64
# Create dummy query, key, value tensors
# xFormers memory_efficient_attention typically expects (batch_size, seq_len, num_heads, head_dim)
query = torch.randn(batch_size, seq_len, num_heads, head_dim, device=device)
key = torch.randn(batch_size, seq_len, num_heads, head_dim, device=device)
value = torch.randn(batch_size, seq_len, num_heads, head_dim, device=device)
# It's common to use float16 (half precision) for performance with xFormers
query = query.half()
key = key.half()
value = value.half()
# Example 1: Standard memory-efficient attention
# xFormers automatically dispatches to the best available operator
output_attn = memory_efficient_attention(query, key, value)
print(f"Output attention shape (standard): {output_attn.shape}")
# Example 2: Causal attention with a lower triangular mask
# Note: The attn_bias argument structure has changed in newer versions (e.g., v0.0.21+)
# For LowerTriangularMask, it often handles internal expansion if num_heads is implicitly available.
attn_bias = LowerTriangularMask()
output_causal_attn = memory_efficient_attention(query, key, value, attn_bias=attn_bias)
print(f"Output attention shape (causal): {output_causal_attn.shape}")
# To verify installation and available kernels:
# import subprocess
# subprocess.run(["python", "-m", "xformers.info"])
Debug
Known issues
breakingStrict compatibility requirements with PyTorch and CUDA versions. Installing 'xformers' via pip without specifying a PyTorch index URL can lead to incompatibility issues or an unwanted PyTorch upgrade.fixAlways install xformers with a matching PyTorch wheel via `--index-url https://download.pytorch.org/whl/cuXXx` (e.g., `cu126`) or build from source if a specific PyTorch/CUDA combination is needed.
affects: All versions
gotchaMany xFormers optimizations, particularly `memory_efficient_attention`, can produce non-deterministic results, meaning repeated runs with the same inputs might yield slightly different outputs.fixIf reproducibility is critical, avoid using xFormers' non-deterministic kernels or use alternative attention implementations. Check `xformers.info` output for deterministic kernel availability.
affects: All versions using optimized kernels
breakingDropped support for V100 and older NVIDIA GPUs, following PyTorch's deprecation schedule. Flash-Attention 2 support for building as part of xFormers is also deprecated.fixUpgrade GPU hardware or use older xFormers/PyTorch versions if V100 compatibility is essential. Consider using Flash-Attention 3 on Ampere GPUs or Flash-Attention 2 through PyTorch on Linux.
affects: 0.0.33.post2 and later
deprecatedMany classes and modules within `xformers.factory`, `xformers.triton`, and `xformers.components` have been or will be deprecated.fixConsult the official xFormers documentation and CHANGELOG for updated API usage and recommended alternatives for constructing Transformer components.
affects: 0.0.22 and later (tracking issue #848)
breakingThe `memory_efficient_attention` function now expects the `attn_bias` argument to explicitly have a head dimension. It no longer automatically broadcasts batch/head dimensions for `attn_bias`.fixManually ensure your `attn_bias` tensor has the correct dimensions, including the head dimension (e.g., by using `.expand()` or `.repeat()` if broadcasting is intended).
affects: 0.0.21 and later
gotchaBuilding xFormers from source on Windows can be complex due to dependencies on Visual Studio Build Tools, specific CUDA Toolkit versions, and potential long path issues. Pre-built wheels are highly recommended.fixPrioritize `pip install` with appropriate PyTorch/CUDA index URLs. If building from source, ensure Visual Studio Build Tools (C++ desktop development), correct CUDA Toolkit, and `git config --global core.longpaths true` are configured.
affects: All versions when building from source on Windows
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'xformers'
The xformers library is either not installed in the current Python environment or its installation failed.
fixInstall xformers using `pip install xformers` or `pip install -v -U xformers --no-deps --pre --force-reinstall --index-url https://download.pytorch.org/whl/cu118 --extra-index-url https://pypi.org/simple` (adjust 'cu118' to your CUDA version).
error: Microsoft Visual C++ 14.0 or greater is required.
Compiling xformers from source on Windows requires the Microsoft C++ Build Tools, which are either not installed or not correctly configured in the system PATH.
fixInstall the Microsoft Build Tools for Visual Studio, ensuring the 'Desktop development with C++' workload is selected during installation.
undefined symbol: _ZN3c104cuda6set_smERi
This ABI incompatibility error indicates that xformers was built against a different CUDA toolkit or PyTorch version than what is currently installed or active, leading to symbol mismatches.
fixEnsure PyTorch and xformers are installed with compatible CUDA versions. Reinstall xformers using a pre-built wheel matching your exact PyTorch and CUDA setup, or rebuild from source.
RuntimeError: CUDA out of memory. Tried to allocate XXX MiB
Despite xformers' memory optimizations, the GPU does not have enough memory to perform the requested operations, often due to large models, batch sizes, or high-resolution inputs.
fixReduce the batch size, model size, image/sequence dimensions, or consider offloading parts of the model to the CPU if feasible. Monitor GPU memory usage more closely.
Upgrade
Version history
0.0.35latest on PyPI · released Feb 20, 2026
Audit
Dependencies
torchrequiredCore dependency; strict version compatibility with xformers and CUDA is critical.
tritonoptionalOptional, but recommended for some optimized kernels like Triton Flash Attention.
ninjaoptionalOptional, significantly speeds up building from source.