How to Install xformers

xformers publishes wheels on both PyPI and the PyTorch indexes. Use the upstream-recommended CUDA index to select compatible xformers and PyTorch builds together.

Prerequisites

• Linux x86-64 with glibc 2.28 or later, or Windows AMD64, for the CUDA wheels. No official macOS wheel.
• Python 3.10 or later for the current PyTorch dependency. The xformers wheel’s py39 filename does not establish Python 3.9 support for the whole environment.
• An NVIDIA GPU supported by the selected PyTorch build and attention operator, with a driver compatible with the packaged CUDA runtime.

The current wheels use PyTorch’s stable API/ABI and declare torch>=2.10; they do not pin one exact PyTorch release. Older xformers releases use tighter pins. Check the release notes before combining an existing torch pin with an older xformers wheel.

Install matching CUDA builds

In an existing virtual environment, install with uv:

uv pip install torch xformers --index https://download.pytorch.org/whl/cu128

Expect CUDA 12.8 PyTorch and an xformers wheel. The URL selects the packaged runtime, not a locally installed toolkit; select a driver-compatible index from upstream’s installation commands. The CUDA wheel path needs no local nvcc.

For a uv project, add this configuration to pyproject.toml:

[tool.uv.sources]
torch = { index = "pytorch-cu128" }
xformers = { index = "pytorch-cu128" }

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

Then declare both packages directly:

uv add torch xformers

This updates the dependencies, lockfile, and environment. Source mappings for an undeclared transitive torch dependency do not replace declaring torch in the project.

Verify an attention operation

Save this script on the GPU host. Float16 inputs exercise the attention dispatcher without restricting it to a float32-compatible kernel. FlashAttention operators require Ampere or newer; CUTLASS operators have different hardware limits.

import torch
import xformers.ops

assert torch.cuda.is_available(), 'CUDA is unavailable to PyTorch'
assert torch.version.hip is None, 'This check targets NVIDIA CUDA'
print(torch.__version__, torch.version.cuda, torch.cuda.get_device_name())
q = torch.randn(1, 128, 8, 64, device='cuda', dtype=torch.float16)
k, v = torch.randn_like(q), torch.randn_like(q)
out = xformers.ops.memory_efficient_attention(q, k, v)
torch.cuda.synchronize()
assert out.is_cuda and out.shape == q.shape
assert torch.isfinite(out).all()
print('xformers CUDA attention OK')

From the uv project, run:

uv run python check_xformers.py

uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. For an activated standalone virtual environment, use uv run --no-project --active python check_xformers.py instead.

Expect the GPU name and xformers CUDA attention OK. Installing or importing the package during a GPU-less image build does not validate this operation.

Diagnose unavailable kernels

uv run python -m xformers.info

For an activated standalone virtual environment, use uv run --no-project --active python -m xformers.info.

The report lists installed kernels, build information, and GPU availability. A kernel listed as available still needs input dtypes, shapes, and hardware that it supports; the attention check establishes whether a real call succeeds.

For No available kernel, read the rejected-kernel reasons in the exception, including dtype and compute capability. For undefined symbol or DLL errors, compare the installed PyTorch, CUDA build, and xformers requirements; reinstalling from the same index is useful, but CUDA version mismatch is not the only cause.

If no wheel matches, a source build needs PyTorch installed first, a matching CUDA toolkit, a supported C++ compiler, and --no-build-isolation. For a GPU-less build host, set TORCH_CUDA_ARCH_LIST for the deployment GPU rather than relying on device detection. Source builds do not make an unsupported kernel run on older hardware.

Upstream also lists experimental Linux ROCm wheels. Follow its ROCm-specific instructions and validate on supported AMD hardware; the CUDA index and NVIDIA check do not cover ROCm. For conda-based environments, follow the Pixi GPU guidance and verify the resolved build.