Skip to content

installation.md

Latest commit

 

History

History
103 lines (79 loc) · 7.6 KB

installation.md

File metadata and controls

103 lines (79 loc) · 7.6 KB
Raw

Installation & Usage

Installation

# From the repository root
uv sync --frozen

# Or install as a package
pip install -e packages/ltx-pipelines

Requirements

  • LTX-2 Model Checkpoint - Local .safetensors file
  • Gemma Text Encoder - Local Gemma model directory
  • Spatial Upscaler - Required by two-stage pipelines, for the upsampling stage
  • Distilled LoRA - Required by two-stage non-distilled pipelines (TI2Vid, Keyframe, A2Vid), used for the stage-2 refinement. Not used by DFR.
  • Detailing IC-LoRA - Required by DFR (--detailing-lora)
  • Temporal Upscaler - Required by DFR when --temporal-upscalings is 1 or 2

Running Pipelines

All pipelines can be run directly from the command line. Each pipeline module is executable:

# Run a pipeline (example: two-stage text-to-video)
python -m ltx_pipelines.ti2vid_two_stages \
    --checkpoint-path path/to/checkpoint.safetensors \
    --distilled-lora path/to/distilled_lora.safetensors 0.8 \
    --spatial-upsampler-path path/to/upsampler.safetensors \
    --gemma-root path/to/gemma \
    --prompt "A beautiful sunset over the ocean" \
    --output-path output.mp4

# View all available options for any pipeline
python -m ltx_pipelines.ti2vid_two_stages --help

Checkpoint layouts: monolith vs split

Every pipeline CLI accepts one of two mutually exclusive path sets.

Monolith (legacy) -- one fat .safetensors plus a HuggingFace Gemma directory:

--checkpoint-path path/to/checkpoint.safetensors --gemma-root path/to/gemma

DistilledPipeline and DFR use --distilled-checkpoint-path instead of --checkpoint-path.

Split (Comfy-aligned) -- one file per component. Pass the subset this pipeline needs (unused flags may be omitted; the pipeline validates required slots on ModelPaths):

python -m ltx_pipelines.distilled \
    --transformer-path      path/to/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
    --text-encoder-path   path/to/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
    --video-vae-path      path/to/vae/ltx-2.5-video-vae-bf16.safetensors \
    --audio-vae-path      path/to/vae/ltx-2.5-audio-vae-bf16.safetensors \
    --duration-head-path  path/to/duration_head/ltx-2.5-duration-head-bf16.safetensors \
    ...

Mixing the two sets is an error. In split mode --text-encoder-path is a single file -- the HuggingFace sidecars (config, tokenizer, processor) are embedded in it and loaded in memory, so no --gemma-root is needed. Both layouts resolve to the same ModelPaths object, which is what pipeline constructors take.

Available pipeline modules

  • ltx_pipelines.distilled - Fast text/image-to-video pipeline using only the distilled model (starting point). (docs, source)
  • ltx_pipelines.dfr_pipeline - Production-quality text/image-to-video: distilled checkpoint, generated keyframes, spatial detailing, optional temporal 2x/4x. (docs, how to run, source)
  • ltx_pipelines.dfr_mgpu - Multi-GPU DFR: sequence parallelism on both stages. (docs, source)
  • ltx_pipelines.ti2vid_two_stages - Two-stage text/image-to-video. (docs, source)
  • ltx_pipelines.ti2vid_two_stages_hq - Two-stage text/image-to-video (different sampler, better quality). (docs, source)
  • ltx_pipelines.ti2vid_one_stage - Single-stage text/image-to-video. (docs, source)
  • ltx_pipelines.t2a_one_stage - Single-stage text-to-audio (audio-only output). (docs, source)
  • ltx_pipelines.ic_lora - Video-to-video with IC-LoRA. (docs, source)
  • ltx_pipelines.keyframe_interpolation - Keyframe interpolation. (docs, source)
  • ltx_pipelines.a2vid_two_stage - Audio-to-video generation conditioned on an input audio. (docs, source)
  • ltx_pipelines.retake - Regenerate a time region of an existing video. (docs, source)
  • ltx_pipelines.hdr_ic_lora - Video-to-video with HDR output (linear float via LogC3 inverse decode). (docs, source)
  • ltx_pipelines.dubit - Dub-It / re-voicing with IC-LoRA and audio reference conditioning. (docs, source)

Use --help with any pipeline module to see all available options and parameters.

For native EXR conditioning and HDR encode on the standard pipelines, see HDR Support.

Common CLI flags

These flags are shared across the pipeline CLIs (they come from a common base parser); run a module with --help for its full set.

  • --seed <int> - random seed for reproducible generation (default 10).
  • --offload {none,cpu,disk} - offload transformer weights to reduce peak GPU memory. cpu holds them in system RAM; disk streams them from disk when RAM is also limited (slower). Default none.
  • --quantization {fp8-cast,fp8-scaled-mm} - run the transformer in FP8 to cut memory. fp8-cast downcasts a bf16 checkpoint on the fly (any FP8-capable GPU); fp8-scaled-mm expects an fp8 checkpoint and native FP8 support (best on Hopper+).
  • --max-batch-size <int> - max batch per transformer forward pass (default 1). Higher values reduce layer-streaming transfers at the cost of peak memory.
  • --compile [key=value ...] - enable torch.compile. Bare --compile compiles without CUDA graphs. CUDA-graph modes (capture=true, mode=reduce-overhead, mode=max-autotune) need --offload cpu or disk on single GPU (streaming reuses GPU weight slots; a registry by itself does not). capture=true captures one graph per (shape, perturbation); max_video_tokens / max_audio_tokens size a shared static input pool so those graphs do not each allocate their own activation buffers. See Compilation.
  • --lora <path> [strength] - apply a LoRA (repeatable; default strength 1.0).
  • --enhance-prompt - rewrite the prompt with the built-in enhancer before generation.
  • --hdr {SRGB_LINEAR,ACESCG,ACESCCT} - on pipelines that accept image / video conditioning (not Dub-It, HDR IC-LoRA, or T2A): declare the source colour space for EXR stills / EXR-frame folders. Required whenever any EXR input is passed; omit for SDR. With --hdr set, encode writes half EXR frames plus a BT.2020/HLG master. See HDR Support.
  • --video-vae-path <path> - video VAE .safetensors (encoder + decoder). Split: the vae/ component. Monolith: optional override of the VAE bundled in --checkpoint-path/--distilled-checkpoint-path. When it is a diffusion VAE, decoding builds a DiffusionVideoDecoder, which for best performance requires the natten extra. See Optimization Tips.
  • --diffvae-optimization {chunked_eager,chunked_compile,combined_compile,blackwell_dsl} - DiffVAE decode preset (ignored for convolutional VAEs). blackwell_dsl is the fast path on datacenter Blackwell.