How to Integrate LTX-2 with ComfyUI: A Complete Setup Guide

To integrate LTX-2 with ComfyUI, install the LTX-2 Python package, clone the official ComfyUI-LTXVideo bridge into your custom_nodes folder, and place the model checkpoints in the correct directory—the bridge will then expose LTX-2's pipelines as native ComfyUI nodes.

The Lightricks LTX-2 repository provides state-of-the-art video generation capabilities through modular pipelines defined in the ltx-pipelines package. While these pipelines are designed for standalone use, the official ComfyUI-LTXVideo bridge allows you to harness LTX-2's power directly inside ComfyUI's node-based workflow engine. This guide covers the complete integration process, from installation to advanced configuration.

Prerequisites and Repository Structure

Before integrating, understand how LTX-2 organizes its codebase. The generation logic lives in packages/ltx-pipelines/src/ltx_pipelines/, with each pipeline implemented as a separate Python module:

• distilled.py – Fast, distilled inference pipeline
• ti2vid_two_stages.py – Full-quality two-stage generation
• ic_lora.py – Image-to-video and video-to-video transformations

All pipelines share a common interface, which the ComfyUI bridge exploits to provide consistent node behavior.

Installation Steps

Step 1: Install the LTX-2 Package

The bridge requires the LTX-2 Python package installed in the same environment as ComfyUI. From the repository root:

# Using uv (recommended)

uv sync --extra natten

# Or using pip

pip install -e .

This installs the ltx-pipelines package and its dependencies, including the natten kernel for efficient attention computation.

Step 2: Clone the Official Bridge

The ComfyUI-LTXVideo repository contains the custom node definitions that wrap LTX-2 pipelines:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/Lightricks/ComfyUI-LTXVideo.git

The bridge automatically registers its nodes when ComfyUI starts, provided the LTX-2 package is importable.

Step 3: Download and Place Model Checkpoints

Create the expected directory structure and download the LTX-2.5 checkpoints:

models/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
│   └── ltx-2.5-audio-vae-bf16.safetensors
└── latent_upscale_models/
    └── ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors

Refer to packages/ltx-pipelines/README.md for direct download links and checksums.

Step 4: Restart ComfyUI

Launch ComfyUI normally. The bridge imports the pipelines and registers nodes under the "LTX-2" category in the node palette.

How the Bridge Works Internally

The ComfyUI-LTXVideo bridge operates as a thin wrapper around LTX-2's pipeline classes. Understanding this architecture helps when customizing or debugging.

Pipeline Instantiation

Each node class imports and instantiates its corresponding pipeline. For the distilled variant, this occurs in ComfyUI-LTXVideo's node implementation:

from ltx_pipelines.distilled import DistilledPipeline

pipeline = DistilledPipeline(
    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",
    spatial_upsampler_path="models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors",
)

The pipeline loads all model weights into VRAM (or CPU memory, depending on offload settings) once per node instantiation.

Node Input Mapping

The bridge exposes pipeline parameters as ComfyUI widget inputs. A simplified distilled node illustrates the pattern:

import os
from pathlib import Path
from ltx_pipelines.distilled import DistilledPipeline

class LTXDistilledNode:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "prompt": ("STRING", {"multiline": True}),
                "num_frames": ("INT", {"default": 121, "min": 1}),
                "seed": ("INT", {"default": 42}),
                "output_path": ("STRING", {"default": "output.mp4"}),
            }
        }

    RETURN_TYPES = ("STRING",)   # path to generated video file

    FUNCTION = "run"

    def run(self, prompt, num_frames, seed, output_path):
        pipeline = DistilledPipeline(
            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",
            spatial_upsampler_path="models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors",
        )
        
        result = pipeline(
            prompt=prompt,
            num_frames=num_frames,
            seed=seed,
        )
        
        # Convert tensor output to video file

        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
        result.save_video(output_path)  # uses ffmpeg internally

        
        return (output_path,)

NODE_CLASS_MAPPINGS = {"LTXDistilledNode": LTXDistilledNode}

The actual bridge implementation includes additional error handling, progress callbacks, and caching optimizations.

Output Conversion and Workflow Continuation

After generation, the bridge writes the video tensor to disk using utilities from packages/ltx-core/src/ltx_core/utils.py. The output can be:

• An MP4 file path (STRING type) for direct download or further encoding
• A folder of PNG frames for frame-by-frame processing in ComfyUI

Connect these outputs to standard ComfyUI nodes like Video Encode, Load Image, or custom post-processing chains.

Available Pipeline Nodes

The bridge exposes one node per major pipeline, each optimized for different use cases:

Node Name	Source Pipeline	Best For	Location in Source
LTX-2 Distilled	`DistilledPipeline``	Fast preview, iterative refinement	packages/ltx-pipelines/src/ltx_pipelines/distilled.py
LTX-2 TI2Vid Two Stages	TI2VidTwoStagesPipeline	Maximum quality, longer videos	packages/ltx-pipelines/src/ltx_pipelines/ti2vid_two_stages.py
LTX-2 IC-LoRA	ICLoraPipeline	Image-to-video, video-to-video, style transfer	packages/ltx-pipelines/src/ltx_pipelines/ic_lora.py

Switch between pipelines by replacing the node in your workflow—all share compatible output types.

Advanced Configuration: Quantization and Offloading

Because the bridge forwards arguments directly to pipeline constructors, you can expose advanced options as node parameters.

Adding Quantization Support

Extend the node to support FP8 inference for reduced VRAM usage:

@classmethod
def INPUT_TYPES(cls):
    return {
        "required": {
            # ... existing inputs ...

            "quantization": (["none", "fp8-cast", "fp8-scaled-mm"], {"default": "none"}),
        }
    }

Then translate the selection to a QuantizationPolicy when constructing the pipeline:

from ltx_pipelines.common import QuantizationPolicy

quant_map = {
    "none": None,
    "fp8-cast": QuantizationPolicy.fp8_cast(),
    "fp8-scaled-mm": QuantizationPolicy.fp8_scaled_mm(),
}

pipeline = DistilledPipeline(
    # ... paths ...

    quantization=quant_map[quantization],
)

Memory Offloading

Pass --offload cpu equivalent behavior by setting offload_policy in the pipeline constructor, enabling generation on GPUs with limited VRAM.

Troubleshooting Integration Issues

Symptom	Cause	Solution
"ModuleNotFoundError: No module named 'ltx_pipelines'"	LTX-2 not installed in ComfyUI's Python environment	Re-run pip install -e . from the LTX-2 repo using ComfyUI's Python executable
"FileNotFoundError" for model paths	Checkpoints not in expected location	Verify directory structure matches models/ltx-2.5/ layout exactly
Nodes appear but generation fails silently	VRAM exhaustion	Enable quantization or CPU offloading; reduce num_frames
Slow first generation	Model cold-start loading	Expected behavior; subsequent generations use cached pipelines

Summary

• Install LTX-2 in your ComfyUI Python environment using uv sync --extra natten or pip install -e .
• Clone ComfyUI-LTXVideo into custom_nodes/ to register pipeline wrappers
• Place model checkpoints in the models/ltx-2.5/ directory with the exact structure expected by DistilledPipeline and other classes
• Select pipeline nodes based on your quality/speed needs: Distilled for fast iteration, TI2Vid Two Stages for final renders, IC-LoRA for transformations
• Extend nodes with quantization and offloading parameters to optimize for your hardware

The integration preserves full access to LTX-2's capabilities while leveraging ComfyUI's visual workflow composition, enabling complex video generation pipelines without writing Python code.

Frequently Asked Questions

Can I run LTX-2 in ComfyUI without the official bridge?

You can, but you would need to reimplement the node classes yourself. The ComfyUI-LTXVideo bridge is the officially maintained solution that stays synchronized with LTX-2 API changes. Manual integration requires handling pipeline instantiation, tensor-to-video conversion using ltx_core.utils, and proper node registration—substantial work for equivalent functionality.

How much VRAM is required for LTX-2 in ComfyUI?

VRAM requirements vary by pipeline and settings. The DistilledPipeline with FP8 quantization runs on 24GB GPUs for standard resolutions. Full TI2VidTwoStagesPipeline generation may require 48GB+ or CPU offloading. Enable quantization and reduce num_frames to fit your hardware.

Where are generated videos saved when using the bridge?

The bridge writes outputs to paths specified by the output_path widget, defaulting to ComfyUI's output directory. When connecting to downstream nodes, the file path (STRING) is passed directly—use ComfyUI's native Save Video or custom nodes to relocate or rename files post-generation.

Can I use custom fine-tuned LTX-2 checkpoints in ComfyUI?

Yes. The bridge passes checkpoint paths directly to pipeline constructors, so you can substitute paths to fine-tuned transformers, VAEs, or LoRA weights. Ensure your custom files follow the same SafeTensors format and naming conventions as the official releases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}