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.