Skip to content

Full installation guide

On this page

After setup, follow Generate your first video, or use the Python API.

This page covers Linux and Windows setup, container images, and operator dependencies. For a walkthrough from setup to a generated video, start with Installation and first generation.

📋 Table of Contents

🚀 System Requirements

  • Operating System: Linux (Ubuntu 18.04+) or Windows 10/11
  • Python: 3.10 or higher
  • GPU: NVIDIA GPU with CUDA support; required VRAM depends on the model and configuration
  • Memory: Enough host RAM for the selected model, including CPU offload buffers
  • Storage: At least 50GB available space

🐧 Linux Environment Setup

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

1. Pull Image

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

2. Start and enter the container

Clone the repository on the host, or enter its root directory if it already exists:

git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V

Mount the repository and open a shell in its directory. Replace the image name on the last line if you selected another image:

docker run --gpus all -it --ipc=host --name lightx2v \
  -v "$PWD":/workspace/LightX2V -w /workspace/LightX2V \
  --entrypoint /bin/bash lightx2v/lightx2v:26052801-cu130

Inside the container, install the current checkout, then continue with Generate Your First Video:

pip install -v -e .

Models and outputs stored in the repository directory persist on the host. After exiting, use docker start -ai lightx2v to enter the container again.

3. China Mirror Source (Optional)

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

🐍 Conda Environment Setup

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

Step 1: Clone Repository

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

Step 2: Create Conda Virtual Environment

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

Step 3: Install Dependencies

pip install -v -e .

Step 4: Install Attention Operators

Option A: Flash Attention 2 

test -d flash-attention || 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) 

test -d flash-attention || git clone https://github.com/Dao-AILab/flash-attention.git --recursive
(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 .)

Step 5: Install Quantization Operators (Optional)

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 && pip install -e .)

Option B: SGL Kernels For SGL quantization, choose a release compatible with your PyTorch and CUDA versions; requirements vary by sgl-kernel release. See the SGL Kernel installation guide.

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 update --init --recursive && python setup.py install)

💡 Note:

Step 6: Verify Installation

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

🪟 Windows Environment Setup

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

🐍 Conda Environment Setup

Step 1: Check CUDA Version

First, confirm your GPU driver and CUDA version:

nvidia-smi

The CUDA Version shown by nvidia-smi is the maximum CUDA version supported by the driver, not necessarily the installed toolkit. Use nvcc --version for the local toolkit and python -c "import torch; print(torch.version.cuda)" for the CUDA version used by PyTorch. Select compatible packages rather than requiring all three values to be identical. See NVIDIA's definition.

Step 2: Create Python Environment

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

REM Activate environment
conda activate lightx2v

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

Step 3: Install PyTorch Framework

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:
  3. Python Version: Consistent with your environment
  4. CUDA Version: Matches your GPU driver
  5. Platform: Select Windows version

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

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

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

Method 2: Direct Installation via pip

REM 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

Step 4: Clone Repository and Install Dependencies

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

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

Step 5: Install Attention Mechanism Operators

Option A: Flash Attention 2

pip install flash-attn==2.7.2.post1

Option B: SageAttention 2 (Strongly Recommended)

Download Sources:

REM 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.

Step 6: Install Quantization Operators (Optional)

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
REM 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
pushd q8_kernels
git submodule update --init --recursive
python setup.py install
popd

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

💡 Note:

Step 7: Verify Installation

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

🎯 Inference Usage

📥 Model Preparation

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

📁 Configuration Files and Scripts

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.

🚀 Start Inference

Linux Environment

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

Windows Environment

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

Python Script Launch

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,
    size=(480, 832),  # Height, width; use (720, 1280) for 720p
    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 Python API guide.

📞 Get Help

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!