# How to Integrate LTX-2 with ComfyUI Using the Official Integration

> Integrate LTX-2 with ComfyUI easily using the official integration. Install the package and use custom nodes to leverage LTX-2 pipelines for advanced video generation.

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

---

**Integrate LTX-2 with ComfyUI by installing the ltx-pipelines package, cloning the official ComfyUI-LTXVideo bridge into your custom_nodes folder, and using its pre-built nodes that wrap LTX-2 pipelines like DistilledPipeline and TI2VidTwoStagesPipeline.**

The LTX-2 video generation model from Lightricks provides state-of-the-art audio-video synthesis through its modular **ltx-pipelines** package. While the core repository offers powerful generation capabilities, most users want to integrate LTX-2 into **ComfyUI**—the popular node-based interface for generative AI workflows. This guide covers the official integration method using the dedicated bridge repository maintained by Lightricks.

## What the Official ComfyUI-LTXVideo Bridge Provides

The **ComfyUI-LTXVideo** bridge is the officially supported way to use LTX-2 inside ComfyUI. It serves as a thin wrapper around the ltx-pipelines package found in `packages/ltx-pipelines/src/ltx_pipelines/`.

The bridge performs three critical functions:

1. **Package Installation**: Installs LTX-2 into the same Python environment as ComfyUI
2. **Node Wrapping**: Exposes LTX-2 pipelines as native ComfyUI nodes with configurable inputs
3. **Output Conversion**: Transforms generated tensors into MP4 files or PNG sequences that downstream nodes can consume

Each pipeline in LTX-2—`DistilledPipeline`, `TI2VidTwoStagesPipeline`, and `ICLoraPipeline`—receives its own corresponding node in ComfyUI.

## Installing LTX-2 and the ComfyUI Bridge

### Step 1: Install the Core LTX-2 Package

The bridge requires the ltx-pipelines package to be available in your environment. From the repository root:

```bash

# Using uv (recommended)

uv sync --extra natten

# Or using pip

pip install -e .

```

### Step 2: Clone the Official Bridge Repository

Navigate to your ComfyUI installation and clone the bridge into the custom_nodes directory:

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

```

This repository contains the node definitions that import and wrap the LTX-2 pipelines.

### Step 3: Download Model Files

Place the LTX-2.5 checkpoint files in the expected directory structure under `models/ltx-2.5/`:

```

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

```

### Step 4: Restart ComfyUI

The bridge auto-registers its nodes on startup. After restarting, search for **"LTX-2"** in the node library to find available pipeline nodes.

## How the Bridge Wraps LTX-2 Pipelines

The core of the integration happens in files like [`packages/ltx-pipelines/src/ltx_pipelines/distilled.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/distilled.py). The bridge imports these classes directly and exposes their parameters as node inputs.

### Pipeline Import Pattern

Inside the bridge's node implementations, you'll find code similar to this pattern from the source:

```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 node then calls `pipeline(**kwargs)` with user-provided values for prompt, frame count, seed, and other generation parameters.

## Complete Node Implementation Example

Below is a simplified version of what the bridge implements internally for the **Distilled** pipeline node. This demonstrates how LTX-2 parameters map to ComfyUI inputs:

```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",)
    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,
        )
        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
        result.save_video(output_path)
        return (output_path,)

NODE_CLASS_MAPPINGS = {"LTXDistilledNode": LTXDistilledNode}

```

The actual bridge handles additional concerns like model caching, device placement, and ComfyUI's tensor format expectations.

## Exposing Advanced Options as Node Parameters

Because the bridge shares the Python environment with LTX-2, you can expose CLI-equivalent flags as dropdown inputs. For example, to add **quantization** support:

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

```

The node implementation then converts this selection to the appropriate policy object:

```python
from ltx_pipelines.pipelines import QuantizationPolicy

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

```

Other flags like `--offload cpu` follow the same pattern, allowing full control over memory management without leaving the ComfyUI interface.

## Available Pipeline Nodes and Their Sources

The bridge provides multiple nodes corresponding to different LTX-2 use cases:

| Node Name | Source File | Use Case |
|-----------|-------------|----------|
| LTX-2 Distilled | [`packages/ltx-pipelines/src/ltx_pipelines/distilled.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/distilled.py) | Fastest generation, single-stage inference |
| LTX-2 TI2Vid Two Stages | [`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) | Higher quality, two-stage refinement |
| LTX-2 IC-LoRA | [`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) | Video-to-video and image-to-video transformation |

All pipelines share a common interface design, so switching between them only requires changing the node type in your workflow—the input parameters remain consistent.

## Connecting to Downstream ComfyUI Nodes

The bridge outputs video files that integrate seamlessly with ComfyUI's native nodes. Typical workflow connections include:

- **Video Encode** nodes for format conversion
- **Load Image** sequences for frame-by-frame processing
- **Video Combine** for merging with other sources
- **Preview** nodes for immediate playback

The output path returned by LTX-2 nodes follows ComfyUI's temporary file conventions, automatically cleaning up after workflow completion unless explicitly saved.

## Key Files for Understanding the Integration

| File | Location | Purpose |
|------|----------|---------|
| [`distilled.py`](https://github.com/Lightricks/LTX-2/blob/main/distilled.py) | `packages/ltx-pipelines/src/ltx_pipelines/` | Fast pipeline implementation used by the Distilled node |
| [`ti2vid_two_stages.py`](https://github.com/Lightricks/LTX-2/blob/main/ti2vid_two_stages.py) | `packages/ltx-pipelines/src/ltx_pipelines/` | Quality-focused two-stage pipeline |
| [`ic_lora.py`](https://github.com/Lightricks/LTX-2/blob/main/ic_lora.py) | `packages/ltx-pipelines/src/ltx_pipelines/` | Image/video conditioning pipelines |
| [`utils.py`](https://github.com/Lightricks/LTX-2/blob/main/utils.py) | `packages/ltx-core/src/ltx_core/` | Tensor-to-video conversion utilities |
| [`README.md`](https://github.com/Lightricks/LTX-2/blob/main/README.md) | `packages/ltx-pipelines/` | Pipeline documentation and CLI reference |

The external **ComfyUI-LTXVideo** repository contains the actual node definitions that import these modules.

## Summary

- **Install LTX-2** using `uv sync --extra natten` or `pip install -e .` from the repository root
- **Clone the official bridge** from `https://github.com/Lightricks/ComfyUI-LTXVideo` into `custom_nodes/`
- **Place model files** in `models/ltx-2.5/` following the directory structure in the main README
- **Use pipeline nodes** that directly import from `packages/ltx-pipelines/src/ltx_pipelines/` modules
- **Expose CLI flags** as node inputs by passing them to pipeline constructors
- **Connect outputs** to standard ComfyUI video and image processing nodes

The official integration maintains full compatibility with LTX-2's capabilities while providing ComfyUI's visual workflow benefits.

## Frequently Asked Questions

### What is the difference between the LTX-2 Distilled and TI2Vid nodes?

**The Distilled node uses `DistilledPipeline` from [`distilled.py`](https://github.com/Lightricks/LTX-2/blob/main/distilled.py) for faster single-pass generation, while the TI2Vid node uses `TI2VidTwoStagesPipeline` from [`ti2vid_two_stages.py`](https://github.com/Lightricks/LTX-2/blob/main/ti2vid_two_stages.py) for higher quality through a two-stage refinement process.** The Distilled node is ideal for rapid iteration and lower resource usage, whereas TI2Vid produces superior results at the cost of longer generation times. Both use identical input parameters, so you can swap between them without restructuring your workflow.

### Can I use custom LTX-2 checkpoints with the ComfyUI bridge?

**Yes, the bridge accepts custom checkpoint paths through its node inputs.** The model path parameters in nodes like `LTXDistilledNode` can be overridden to point to fine-tuned or experimental checkpoints. Ensure your custom files follow the same naming convention and format as the official LTX-2.5 releases (BF16 SafeTensors with appropriate projection layers).

### How do I enable memory optimization features like CPU offloading?

**Add a dropdown or boolean input to your node definition and pass the corresponding flag to the pipeline constructor.** For CPU offloading, expose a `"device"` parameter that maps to `device="cpu"` or use LTX-2's built-in offloading utilities. The bridge can forward any argument that the underlying pipelines accept, including quantization policies and attention implementations.

### Where can I find the complete node implementation code?

**The full node definitions are in the separate ComfyUI-LTXVideo repository, not in the main LTX-2 repository.** While this guide shows simplified examples, the production implementation includes additional features like model caching, progress callbacks, and ComfyUI's specific tensor handling. Clone `https://github.com/Lightricks/ComfyUI-LTXVideo` to examine the actual node classes and customize them for your needs.