Welcome to LightX2V! This guide will help you quickly set up the environment and start using LightX2V for video generation.

• System Requirements
• Linux Environment Setup
  • Docker Environment (Recommended)
  • Conda Environment Setup
• Windows Environment Setup
• Inference Usage

• Operating System: Linux (Ubuntu 18.04+) or Windows 10/11
• Python: 3.10 or higher
• GPU: NVIDIA GPU with CUDA support, at least 8GB VRAM
• Memory: 16GB or more recommended
• Storage: At least 50GB available space

We strongly recommend using the Docker environment, which is the simplest and fastest installation method.

Visit LightX2V's Docker Hub, select a tag with the latest date, such as 26052801-cu130:

docker pull lightx2v/lightx2v:26052801-cu130

We recommend using the cuda130 environment for faster inference speed. If you need to use the cuda128 and cuda124 environment, you can use image versions with the -cu128 and -cu124 suffix:

docker pull lightx2v/lightx2v:26011201-cu128
docker pull lightx2v/lightx2v:25101501-cu124

docker run --gpus all -itd --ipc=host --name [container_name] -v [mount_settings] --entrypoint /bin/bash [image_id]

For mainland China, if the network is unstable when pulling images, you can pull from Alibaba Cloud:

# cuda130
docker pull registry.cn-hangzhou.aliyuncs.com/yongyang/lightx2v:26052801-cu130

# cuda128
docker pull registry.cn-hangzhou.aliyuncs.com/yongyang/lightx2v:26011201-cu128

# cuda124
docker pull registry.cn-hangzhou.aliyuncs.com/yongyang/lightx2v:25101501-cu124

If you prefer to set up the environment yourself using Conda, please follow these steps:

# Download project code
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V

# Create and activate conda environment
conda create -n lightx2v python=3.11 -y
conda activate lightx2v

pip install -v -e .

Option A: Flash Attention 2

git clone https://github.com/Dao-AILab/flash-attention.git --recursive
cd flash-attention && python setup.py install

Option B: Flash Attention 3 (for Hopper architecture GPUs)

cd flash-attention/hopper && python setup.py install

Option C: SageAttention 2 (Recommended)

git clone https://github.com/thu-ml/SageAttention.git
cd SageAttention && CUDA_ARCHITECTURES="8.0,8.6,8.9,9.0,12.0" EXT_PARALLEL=4 NVCC_APPEND_FLAGS="--threads 8" MAX_JOBS=32 pip install -v -e .

Quantization operators are used to support model quantization, which can significantly reduce memory usage and accelerate inference. Choose the appropriate quantization operator based on your needs:

Option A: VLLM Kernels (Recommended) Suitable for various quantization schemes, supports FP8 and other quantization formats.

pip install vllm

Or install from source for the latest features:

git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -e .

Option B: SGL Kernels Suitable for SGL quantization scheme, requires torch == 2.8.0.

pip install sgl-kernel --upgrade

Option C: Q8 Kernels Suitable for Ada architecture GPUs (such as RTX 4090, L40S, etc.).

git clone https://github.com/KONAKONA666/q8_kernels.git
cd q8_kernels && git submodule init && git submodule update
python setup.py install

💡 Note:

• You can skip this step if you don't need quantization functionality
• Quantized models can be downloaded from LightX2V HuggingFace
• For more quantization information, please refer to the Quantization Documentation

import lightx2v
print(f"LightX2V Version: {lightx2v.__version__}")

Windows systems only support Conda environment setup. Please follow these steps:

First, confirm your GPU driver and CUDA version:

nvidia-smi

Record the CUDA Version information in the output, which needs to be consistent in subsequent installations.

# Create new environment (Python 3.12 recommended)
conda create -n lightx2v python=3.12 -y

# Activate environment
conda activate lightx2v

💡 Note: Python 3.10 or higher is recommended for best compatibility.

Method 1: Download Official Wheel Package (Recommended)

1. Visit the PyTorch Official Download Page
2. Select the corresponding version wheel package, paying attention to matching:
   • Python Version: Consistent with your environment
   • CUDA Version: Matches your GPU driver
   • Platform: Select Windows version

Example (Python 3.12 + PyTorch 2.6 + CUDA 12.4):

# Download and install PyTorch
pip install torch-2.6.0+cu124-cp312-cp312-win_amd64.whl

# Install supporting packages
pip install torchvision==0.21.0 torchaudio==2.6.0

Method 2: Direct Installation via pip

# CUDA 12.4 version example
pip install torch==2.6.0+cu124 torchvision==0.21.0+cu124 torchaudio==2.6.0+cu124 --index-url https://download.pytorch.org/whl/cu124

Download the corresponding wheel package from vllm-windows releases.

Version Matching Requirements:

• Python version matching
• PyTorch version matching
• CUDA version matching

# Install vLLM (please adjust according to actual filename)
pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl

Option A: Flash Attention 2

pip install flash-attn==2.7.2.post1

Option B: SageAttention 2 (Strongly Recommended)

Download Sources:

• Windows Special Version 1
• Windows Special Version 2

# Install SageAttention (please adjust according to actual filename)
pip install sageattention-2.1.1+cu126torch2.6.0-cp312-cp312-win_amd64.whl

⚠️ Note: SageAttention's CUDA version doesn't need to be strictly aligned, but Python and PyTorch versions must match.

# Clone project code
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V

# Install Windows-specific dependencies
pip install -r requirements_win.txt
pip install -v -e .

By default, LightX2V uses Triton kernel for quantization inference, which is efficient and requires no additional dependencies. Just ensure that triton-windows is installed.

If you need to use other quantization operators, you can install the following options:

1. Install Windows Version of vLLM

Download the corresponding wheel package from vllm-windows releases.

Version Matching Requirements:

• Python version match
• PyTorch version match
• CUDA version match

# Install vLLM (please adjust according to actual filename)
pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl

2. Install q8-kernels

For RTX 40 series GPUs, it is recommended to install q8_kernel==0.1.0:

git clone https://github.com/KONAKONA666/q8_kernels.git
cd q8_kernels && git submodule init && git submodule update
python setup.py install

For other GPUs, it is recommended to install q8_kernel==0.5.0. Please refer to LTX-Video-Q8-Kernels.

💡 Note:

• It is recommended to use the default Triton kernel for inference
• Quantized models can be downloaded from LightX2V HuggingFace
• For more quantization information, please refer to the Quantization Documentation

Before starting inference, you need to download the model files in advance. We recommend:

• Download Source: Download models from LightX2V Official Hugging Face or other open-source model repositories
• Storage Location: It's recommended to store models on SSD disks for better read performance
• Available Models: Including Wan2.1-I2V, Wan2.1-T2V, and other models supporting different resolutions and functionalities

The configuration files used for inference are available here, and scripts are available here.

You need to configure the downloaded model path in the run script. In addition to the input arguments in the script, there are also some necessary parameters in the configuration file specified by --config_json. You can modify them as needed.

# Run after modifying the path in the script
bash scripts/wan/run_wan_t2v.sh

# Use Windows batch script
scripts\win\run_wan_t2v.bat

from lightx2v import LightX2VPipeline

pipe = LightX2VPipeline(
    model_path="/path/to/Wan2.1-T2V-14B",
    model_cls="wan2.1",
    task="t2v",
)

pipe.create_generator(
    attn_mode="sage_attn2",
    infer_steps=50,
    height=480,  # 720
    width=832,   # 1280
    num_frames=81,
    guidance_scale=5.0,
    sample_shift=5.0,
)

seed = 42
prompt = "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."
negative_prompt = "镜头晃动，色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走"
save_result_path="/path/to/save_results/output.mp4"

pipe.generate(
    seed=seed,
    prompt=prompt,
    negative_prompt=negative_prompt,
    save_result_path=save_result_path,
)

💡 More Examples: For more usage examples including quantization, offloading, caching, and other advanced configurations, please refer to the examples directory.

If you encounter problems during installation or usage, please:

1. Search for related issues in GitHub Issues
2. Submit a new Issue describing your problem

🎉 Congratulations! You have successfully set up the LightX2V environment and can now start enjoying video generation!