Install HunyuanVideo-1.5: Tencent Video AI Guide

Why bother deploying Tencent video AI right now?

Cloud video generators still throttle or watermark everything. HunyuanVideo-1.5 – Tencent’s 8.3B open T2V/I2V model released Nov 20 2025 – runs on a single consumer card once you clear 14 GB VRAM with offloading. I burned a weekend on the main-branch path so you skip rediscovering the gated encoder and the exact distill flags.

Scope is the code as of the Dec 2025 updates: FP8 gemm, step-distilled 480p I2V, training scripts. Skip “what is a DiT.”

System requirements that actually matter

Floor straight from the HunyuanVideo-1.5 repo:

• OS: Linux (tested path)
• Python: 3.10+
• GPU: NVIDIA with CUDA-compatible PyTorch
• VRAM: 14 GB minimum with model offloading; 24 GB feels sane for 720p without constant swapping
• Disk: ckpts plus outputs grow fast when you pull multiple resolution variants – leave plenty of headroom
• RAM: group offloading loves system RAM; tight CPU RAM is why you flip --overlap_group_offloading false

RTX 4090-class matches the published ~75-second 480p step-distill numbers. Smaller cards still move with FP8 + offload. Steps just crawl.

Official source and first download

Start here:

git clone https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5.git
cd HunyuanVideo-1.5

Weights and text/vision encoders sit on Hugging Face (tencent/HunyuanVideo-1.5). Grab the CLI:

pip install -U "huggingface_hub[cli]"
pip install modelscope

Bulk pull (slow):

hf download tencent/HunyuanVideo-1.5 --local-dir ./ckpts

China networks: prefix HF_ENDPOINT=https://hf-mirror.com. The command resumes if it dies mid-file.

Step-by-step install commands for HunyuanVideo-1.5

After the clone:

1. Basic deps:

   pip install -r requirements.txt
   pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python

2. Flash Attention. Upstream build docs apply; ninja first cuts pain:

   pip install ninja
   # then build per https://github.com/Dao-AILab/flash-attention

3. Optional accelerators (as of Dec 23 2025 FP8 gemm landed in-tree news):

   # FP8 gemm
   pip install sgl-kernel==0.3.18
   
   # SageAttention (disables flex-block)
   git clone https://github.com/cooper1637/SageAttention.git
   cd SageAttention
   export EXT_PARALLEL=4 NVCC_APPEND_FLAGS="--threads 8" MAX_JOBS=32
   python3 setup.py install
   cd ..

   Sparse attention on 720p only if you need it:

   git clone https://github.com/Tencent-Hunyuan/flex-block-attn.git
   cd flex-block-attn && git submodule update --init --recursive && python3 setup.py install

Text and vision encoders are separate. This is what tripped me on pass one – main weights finished, generate still screamed missing modules:

hf download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ./ckpts/text_encoder/llm
hf download google/byt5-small --local-dir ./ckpts/text_encoder/byt5-small
modelscope download --model AI-ModelScope/Glyph-SDXL-v2 --local_dir ./ckpts/text_encoder/Glyph-SDXL-v2

The catch is SigLIP. It rides gated black-forest-labs/FLUX.1-Redux-dev. Request access on the model card, then:

hf download black-forest-labs/FLUX.1-Redux-dev --local-dir ./ckpts/vision_encoder/siglip --token <your_hf_token>

Keep the token in an env var. Never commit it. Partial downloads leave broken safetensors – wipe the folder and retry when sizes look wrong.

Minimum viable first-time config and generate

No custom config file required. Rewrite endpoints stay optional (defaults off if unset). Bare test:

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True,max_split_size_mb:128

PROMPT='A girl holding a paper with words "Hello, world!"'
IMAGE_PATH=none # or /path/to/start.png for I2V
SEED=1
ASPECT_RATIO=16:9
RESOLUTION=480p
OUTPUT_PATH=./outputs/test.mp4
MODEL_PATH=./ckpts

torchrun --nproc_per_node=1 generate.py 
 --prompt "$PROMPT" 
 --image_path $IMAGE_PATH 
 --resolution $RESOLUTION 
 --aspect_ratio $ASPECT_RATIO 
 --seed $SEED 
 --rewrite false 
 --enable_step_distill true 
 --cfg_distilled true 
 --output_path $OUTPUT_PATH 
 --model_path $MODEL_PATH 
 --offloading true

Fast 480p I2V path (~75 s end-to-end on a 4090 per the Dec 05 2025 notes) needs the matching step-distilled transformer in ckpts, --enable_step_distill true, and 8 or 12 steps. Full flags sit in the README Command Line Arguments table.

That first clean 480p clip felt like cheating after the older heavy model’s VRAM wall. Same box, usable motion, no OOM on load.

Verify the install works

When generate.py exits you want a playable .mp4 under outputs/. Scan the console for missing-checkpoint warnings.

ls -lh ./outputs/
ffprobe ./outputs/test.mp4 # or just open it

Process starts, DiT + VAE + encoders load, frames write, no CUDA OOM – you’re done. Prefer pipelines? Diffusers integration exists; use that instead of torchrun.

Common install errors and the fixes that worked

Big HF pulls time out often. Rerun the same hf download; it resumes.

Upgrade and uninstall

git pull inside the repo. Re-run pip install -r requirements.txt when requirements shift. Re-download new transformer folders (step-distill, SR, sparse) when they appear on the HF card. Original HunyuanVideo ckpts are not drop-in for 1.5.

Cleanup: deactivate the env, rm -rf HunyuanVideo-1.5 (and ckpts if you want the space). 1.5 currently leans source + ComfyUI/Diffusers more than a polished first-party Docker story.

Fire the 480p step-distill command with your own prompt. Then try --sr true for the 1080p upscaler once the base clip looks right. Architecture deep-dive: arXiv:2511.18870 (SSTA, 3D VAE, SR network). License is Tencent Hunyuan Community – territory limits apply, read NOTICE before commercial use.

FAQ

Does HunyuanVideo-1.5 really run on 14 GB?

Yes. Official minimum with offloading on. 24 GB is where comfort and 720p headroom show up.

I only have one GPU. Do I still need torchrun?

For the stock generate.py path, yes. --nproc_per_node=1 is the single-card recipe. Raise the count only when you actually have more GPUs. That is the consumer layout 1.5 expects.

Can I skip the gated vision encoder?

Pure T2V sometimes limps along if the pipeline falls back. I2V and best quality still expect SigLIP from FLUX.1-Redux-dev. Request access before you need the run – waiting on approval mid-deadline is miserable. Some ComfyUI community bundles already pack converted copies; the plain torchrun path does not.