Installation and containers

Use Python 3.10 or newer and a PyTorch build matching your device: CUDA, ROCm, or Ascend. Some registered models require newer Diffusers and Transformers versions than the package minimum. Use an environment or container that supports your selected checkpoint.

Pip or source

Install the base package, then add the extras needed by your workload:

pip install xfuser
# Cache-DiT and torchao quantization, when needed:
pip install "xfuser[cache-dit,torchao]"

To use this checkout and its current model support:

git clone https://github.com/xdit-project/xDiT.git
cd xDiT
pip install -e ".[cache-dit,torchao]"

Combine extras in either install command. Base dependencies include DistVAE, Yunchang, Diffusers, Transformers, Accelerate, and PEFT. A published xfuser release can differ from this checkout. Inspect your installed parser with python -m xfuser.runner --help.

Extra When to install it
cache-dit DBCache, stage-aware PipeFusion caching, and model adapters using Cache-DiT. The current package requires cache-dit>=1.5.0,<1.6.0.
torchao Supported torchao GEMM and text-encoder quantization paths. AITER has separate installation requirements.
flash-attn FlashAttention 2 (>=2.7.0). Other FlashAttention generations need their corresponding package; Ring requirements depend on the selected backend.
optimum-quanto FP8 T5 conversion in legacy pipeline examples; separate from the runner's GEMM/text-encoder controls.
opencv-python ConsisID examples; installs opencv-python-headless.

Install the device runtime separately. Check attention backend and quantization requirements before selecting optional kernels.

Device environments

For external setup guidance, see platform and ecosystem guides.

For offline MiniMax-H3 and VDN-H3 runs, download all required components first, then set HF_HUB_OFFLINE=1. Component loading uses local files and fails if a required component cannot load. See Hugging Face offline mode.

CUDA

Use a CUDA-compatible PyTorch build and attention kernels supported by your GPU. For a container, build the CUDA Dockerfile locally using its build instructions.

ROCm

Use a ROCm-compatible PyTorch build. AITER kernels have separate architecture and package requirements; see attention and quantization. The container build guide covers Instinct and RDNA 4. Release images are available at rocm/pytorch-xdit; choose a tag matching your hardware and model. Check the tag's dependency versions and xDiT revision for supported features.

For adapted hardware configurations, see hardware recipes. The linked YAML files configure a separate benchmark harness. The runner has no xdit --config option.

Ascend

Install a compatible Ascend runtime and PyTorch NPU environment. The Ring path also needs yunchang.ring.utils.update_npu_out; one compatible helper revision is:

pip install "yunchang @ git+https://github.com/feifeibear/long-context-attention.git@56118e0"

Check that helper's signature when using another revision. See USP for backend and Ring constraints.