Instructions to use Lightricks/LTX-2.5 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Diffusion Single File
How to use Lightricks/LTX-2.5 with Diffusion Single File:
# No code snippets available yet for this library. # To use this model, check the repository files and the library's documentation. # Want to help? PRs adding snippets are welcome at: # https://github.com/huggingface/huggingface.js
- LTX-2
How to use Lightricks/LTX-2.5 with LTX-2:
# Install the LTX-2 pipelines git clone https://github.com/Lightricks/LTX-2.git cd LTX-2 uv sync --extra natten
# Download weights from this repo # Substitute filenames from this repo's "Files and versions" if they differ hf download Lightricks/LTX-2.5 \ diffusion_models/<distilled-transformer>.safetensors \ text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \ vae/<video-vae>.safetensors \ vae/<audio-vae>.safetensors \ latent_upscale_models/<spatial-upsampler>.safetensors \ latent_upscale_models/<temporal-upsampler>.safetensors \ --local-dir models/LTX-2.5 # DFR requires the detailing IC-LoRA (separate repo; strength is fixed at 0.5) hf download Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler --local-dir models/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler# Distilled LTX-2.5 pipeline (fast) uv run python -m ltx_pipelines.distilled \ --transformer-path models/LTX-2.5/diffusion_models/<distilled-transformer>.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/<video-vae>.safetensors \ --audio-vae-path models/LTX-2.5/vae/<audio-vae>.safetensors \ --spatial-upsampler-path models/LTX-2.5/latent_upscale_models/<spatial-upsampler>.safetensors \ --num-frames 121 \ --prompt "A beautiful sunset over the ocean" \ --output-path output.mp4 # For image-to-video, add: --image path/to/image.jpg 0 0.8# DFR pipeline (higher detail fidelity; optional temporal 2x/4x) uv run python -m ltx_pipelines.dfr_pipeline \ --transformer-path models/LTX-2.5/diffusion_models/<distilled-transformer>.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/<video-vae>.safetensors \ --audio-vae-path models/LTX-2.5/vae/<audio-vae>.safetensors \ --spatial-upsampler-path models/LTX-2.5/latent_upscale_models/<spatial-upsampler>.safetensors \ --temporal-upsampler-path models/LTX-2.5/latent_upscale_models/<temporal-upsampler>.safetensors \ --detailing-lora models/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler/ltx-2.5-22b-ic-lora-pixel-spatial-upscaler-x2-1.0.safetensors \ --spatial-upscalings 1 \ --temporal-upscalings 1 \ --height 1088 \ --width 1920 \ --num-frames 121 \ --prompt "A beautiful sunset over the ocean" \ --output-path output.mp4 # For 4K: --spatial-upscalings 2 --width 3840 --height 2176 # For image-to-video, add: --image path/to/image.jpg 0 0.8 - Notebooks
- Google Colab
- Kaggle
Naming something that is not in the frame makes the model bring it into the frame
Title: I2V: naming a person or object that is not in the frame makes the model bring it in (with numbers and a workaround)
Setup: LTX-2.5 distilled bf16, ComfyUI two-stage I2V, 720p, 121 frames @ 24 fps, one seed per clip; a few hundred clips across three episodes of a film series.
An off-screen listener walks into the frame. In 10 prompts that mentioned someone "out of frame" / "outside the frame" (e.g. "speaks to a man who kneels out of frame"), that person entered the shot in 6 clips: a head at the edge, a shoulder, or a whole person, often in modern clothing that has nothing to do with the start frame. "Someone just below and in front of the camera" did the same. The line "He is alone in the frame and nobody else enters it." was in the same prompts and did not prevent it. A different seed does not fix it: on seed 11 only 1 of 7 such shots came out clean.
A light source named in the setting pulls the camera away from the face. Close-ups of a woman indoors had the setting line "soft daylight from a smoke-hole in the roof". In 4 of 7 close-ups the camera left her face at second 2–3 and showed an empty room with a hole in the roof. A part of the same scene whose setting line named a lamp that was in the frame had no such drift.
Workaround that held for us: never name what is not in the frame. Describe gaze by direction ("looks to the left of the frame"), not by addressee; in close-ups give light only ("soft dim daylight indoors, warm brown shadows"), with no objects or sources. After this change, none of the next 188 clips drifted away from the subject.
- Smaller sample, for what it's worth: in a two-person shot, a gesture written for one character (holding up a torch and looking at the sky) was performed by the other one in 2 of 2 clips (same start frame and seed), while the line of dialogue was spoken by the right character.
Our reading is that the text encoder treats every noun as something to show. If that is expected behaviour, a line about it in the prompting guide would help; if not, we hope these numbers are useful. Happy to share frame strips if the team wants them.
Thanks for documenting this with examples and numbers. Describing gaze direction and visible lighting instead of naming off-screen people or objects sounds like a useful approach.
I’m working on a film-restoration project where preserving composition, actor identity, expressions, and movement matters. A few questions that could help explore this further:
Controlled comparisons: Have you rerun the original failing shots using the revised wording while keeping the starting image, seed, and settings identical? A before-and-after prompt pair with frame strips would be especially helpful.
Prompt enhancement: Was any automatic prompt enhancement enabled? If so, could you share the final text passed to the model? It would be interesting to see whether the enhancement introduced or emphasized off-screen details.
Character actions: For the gesture assigned to the wrong person, have you tried identifying each character by screen position and visible clothing—for example, “the person on the left wearing a brown robe raises the torch”? Does that improve action assignment?
Performance fidelity: After removing off-screen references, did you also see better preservation of gaze, expressions, and intended movement, or was the improvement mainly in keeping the camera on the subject?
Your results seem worth including in the prompting guide. I’d also be interested in the team’s interpretation of whether this comes from text encoding, the model’s learned response to those descriptions, or another part of the pipeline.