Registry / ai-ml / xformers

xformers

JSON →
library0.0.35pypypi✓ verified 26d ago

XFormers is a PyTorch-based library providing a collection of composable, optimized building blocks for Transformer models. It aims to accelerate deep learning research by offering flexible and highly efficient components, including advanced attention mechanisms and fused operations that often outperform native PyTorch implementations in terms of speed and memory usage. Actively developed by Meta Platforms, Inc., the library frequently releases updates, with the current stable version being 0.0.35.

pip install xformers
INSTALL
IMPORT
SIG · XFORMERS
X
xformers
ai-mlpythonv0.0.35
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
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.
fix
Always 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.
fix
If 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.
fix
Upgrade 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.
fix
Consult 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`.
fix
Manually 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.
fix
Prioritize `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.
fix
Install 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.
fix
Install 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.
fix
Ensure 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.
fix
Reduce 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.
Agent activity
92 hits · last 30 days
node
82
Perplexity
1
OpenAI (training)
1
Resources
xformers — pip install xformers · libregistry