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

> Integrate LTX-2 with ComfyUI using our complete setup guide. Install the LTX-2 package, clone the ComfyUI-LTXVideo bridge, and place model checkpoints to unlock powerful video generation nodes.

- Repository: [Lightricks/LTX-2](https://github.com/Lightricks/LTX-2)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/Lightricks/LTX-2/blob/main/distilled.py) – Fast, distilled inference pipeline
- [`ti2vid_two_stages.py`](https://github.com/Lightricks/LTX-2/blob/main/ti2vid_two_stages.py) – Full-quality two-stage generation
- [`ic_lora.py`](https://github.com/Lightricks/LTX-2/blob/main/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:

```bash

# 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:

```bash
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`](https://github.com/Lightricks/LTX-2/blob/main/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:

```python
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:

```python
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`](https://github.com/Lightricks/LTX-2/blob/main/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`](https://github.com/Lightricks/LTX-2/blob/main/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`](https://github.com/Lightricks/LTX-2/blob/main/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`](https://github.com/Lightricks/LTX-2/blob/main/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:

```python
@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:

```python
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.