PyTorch API

For developers who want direct Python integration or custom workflows beyond ComfyUI, LTX-2 offers two paths: the native ltx-pipelines package (full control, all features) and the HuggingFace Diffusers integration (familiar API, quick start).

Repository Structure

The LTX-2 codebase is a monorepo with three packages:

Requirements

• Python >= 3.12
• CUDA >= 12.7
• PyTorch ~= 2.7

See System Requirements for full hardware specifications.

Installation

$
# Clone the repository
$
git clone https://github.com/Lightricks/LTX-2.git
$
cd LTX-2
$
$
# Set up the environment
$
uv sync
$
source .venv/bin/activate

Download Models

LTX-2.5 ships as a split pack — one .safetensors file per component (transformer, text encoder, video/audio VAEs, duration head). The distilled text-to-video pipeline needs the files below. Download them with the Hugging Face CLI (click Agree and Access on the model page on first download):

$
hf auth login
$
$
# LTX-2.5 distilled split pack
$
hf download Lightricks/LTX-2.5 \
>
  diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
>
  text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
>
  vae/ltx-2.5-video-vae-bf16.safetensors \
>
  vae/ltx-2.5-audio-vae-bf16.safetensors \
>
  model_patches/ltx-2.5-duration-head-bf16.safetensors \
>
  --local-dir models/ltx-2.5
$
$
# Spatial upscaler (still hosted on the LTX-2.3 repo; required by the distilled pipeline)
$
hf download Lightricks/LTX-2.3 \
>
  ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
>
  --local-dir models/ltx-2.3

Use the bf16 files with ltx-pipelines. The *-comfy-int8_convrot variants are ComfyUI-only and are not loaded by the PyTorch path. For the full checkpoint list (dev transformer, conv VAE, distilled LoRA, upscalers), see the LTX-2.5 model card.

Option 1: Native Pipelines (ltx-pipelines)

The ltx-pipelines package provides the most complete feature set, including two-stage generation, IC-LoRA, and fine-grained guidance control.

Available Pipelines

All pipelines also run from the command line (python -m ltx_pipelines.<module> --help). For the full module list, shared CLI flags, and a per-pipeline reference, see Installation & Usage and Available Pipelines on GitHub.

Text-to-Video Example

This runs the distilled pipeline from the command line — the same interface as the Pipeline Quick Start. Each split component is passed with its own path flag:

$
uv run python -m ltx_pipelines.distilled \
>
    --transformer-path       models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
>
    --text-encoder-path      models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
>
    --video-vae-path         models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
>
    --audio-vae-path         models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
>
    --duration-head-path     models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors \
>
    --spatial-upsampler-path models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
>
    --prompt "A golden retriever running through a sunlit meadow, cinematic lighting. Sound of panting, rustling grass, distant birdsong." \
>
    --seed 42 \
>
    --output-path output.mp4

You can drive the same pipeline from Python, passing the split paths through ModelPaths:

1
from ltx_pipelines.distilled import DistilledPipeline
2
from ltx_pipelines.utils.model_paths import ModelPaths
3
4
model_paths = ModelPaths.from_split(
5
    transformer_path="models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors",
6
    text_encoder_path="models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors",
7
    video_vae_path="models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors",
8
    audio_vae_path="models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors",
9
    duration_head_path="models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors",
10
)
11
12
pipe = DistilledPipeline(
13
    model_paths=model_paths,
14
    spatial_upsampler_path="models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors",
15
)
16
# See packages/ltx-pipelines for the __call__ arguments (prompt, seed, num_frames, images, …).

Add --help to any pipeline module to see its full option list, including the guidance parameters below.

Guidance Parameters

The native pipelines expose MultiModalGuiderParams for fine-grained control over generation:

Memory Optimization

For consumer GPUs, reduce VRAM by running the transformer in FP8 and offloading weights to CPU — add these flags to any pipeline command:

$
uv run python -m ltx_pipelines.distilled \
>
    ...model + prompt flags... \
>
    --quantization fp8-cast \
>
    --offload cpu

• --quantization fp8-cast downcasts the bf16 transformer on the fly and works on any FP8-capable GPU. Use the bf16 checkpoints for this — the *-comfy-int8_convrot files are ComfyUI-only.
• --quantization fp8-scaled-mm is the alternative for a native-FP8 checkpoint on Hopper+ GPUs.
• --offload cpu streams weights from system RAM per layer; --offload disk reads them from disk on demand (lowest memory, slower).

Additional tip: set PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True to improve memory allocation.

Option 2: HuggingFace Diffusers

LTX-2.5 is published as a Diffusers-compatible pack in a separate repo, Lightricks/LTX-2.5-Diffusers — the same model in Diffusers-friendly packaging. Load it with from_pretrained against that repo id:

1
import torch
2
from diffusers import LTX2Pipeline
3
4
pipeline = LTX2Pipeline.from_pretrained(
5
    "Lightricks/LTX-2.5-Diffusers",
6
    torch_dtype=torch.bfloat16,
7
)
8
pipeline.to("cuda")
9
10
result = pipeline(
11
    prompt="A golden retriever running through a sunlit meadow, "
12
           "wildflowers swaying in a gentle breeze.",
13
    width=768,
14
    height=512,
15
)

For the exact pipeline class and current examples, see the Lightricks/LTX-2.5-Diffusers model card.

Generation Parameters Reference

Resolution

Standard aspect ratios:

Higher resolutions are supported (up to 4K) but require significantly more VRAM. Start with lower resolutions for testing.

Frame Count & Duration

Sampling