# Integrating LTX-2 with ComfyUI for Workflow Management: A Complete Technical Guide

> Learn to integrate LTX-2 with ComfyUI for efficient workflow management. Seamlessly export and load LoRA checkpoints with automatic prefix handling. Get the technical guide now.

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

---

**LTX-2 integrates with ComfyUI through automatic `diffusion_model.` prefix handling in the trainer, enabling seamless LoRA checkpoint export and loading without manual conversion scripts.**

Integrating LTX-2 with ComfyUI for workflow management allows you to leverage LTX-2's video generation pipelines within ComfyUI's visual node editor. The repository is architected specifically for this interoperability, with built-in weight naming conventions that bridge both environments.

## Understanding the LTX-2 Package Structure

LTX-2 is organized as a monorepo with three interdependent packages. Each serves a distinct role in the ComfyUI integration workflow.

### ltx-core: Foundation Components

The **ltx-core** package implements low-level model primitives: transformer blocks, text encoders, VAE, tiling utilities, and tensor operations. These components are agnostic to any UI framework but expose standardized interfaces that both Python pipelines and ComfyUI nodes consume.

Key utilities for device handling and model configuration reside in [`packages/ltx-core/src/ltx_core/utils.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-core/src/ltx_core/utils.py).

### ltx-pipelines: High-Level Inference

The **ltx-pipelines** package orchestrates end-to-end generation workflows. It provides `DistilledPipeline`, `DFRPipeline`, and `ICLoraPipeline` classes that ComfyUI nodes wrap into visual components. The pipeline implementations in [`packages/ltx-pipelines/src/ltx_pipelines/distilled.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/distilled.py) execute the same code paths regardless of whether they're called from Python scripts or ComfyUI nodes.

### ltx-trainer: Checkpoint Management with ComfyUI Compatibility

The **ltx-trainer** package handles training and—critically for ComfyUI integration—checkpoint serialization. As implemented in [`packages/ltx-trainer/src/ltx_trainer/trainer.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/src/ltx_trainer/trainer.py), the trainer automatically manages the `diffusion_model.` weight prefix that ComfyUI expects.

## The `diffusion_model.` Prefix: Core Interoperability Mechanism

ComfyUI and the official **ComfyUI-LTXVideo** extension require all diffusion model tensors to be prefixed with `diffusion_model.` in state dict keys. LTX-2's trainer handles this transparently.

### Loading LoRA Checkpoints: Prefix Stripping

When loading a ComfyUI-exported LoRA into the trainer, the prefix is removed:

```python

# packages/ltx-trainer/src/ltx_trainer/trainer.py (Lines 518-521)

state_dict = {
    k.replace("diffusion_model.", "", 1): v 
    for k, v in state_dict.items()
}

```

This ensures LTX-2's internal model components receive keys without the ComfyUI namespace.

### Saving LoRA Checkpoints: Prefix Addition

When exporting a trained LoRA for ComfyUI consumption, the trainer reverses the operation, adding `diffusion_model.` to every tensor key (Lines 517-520 in the same file). The resulting `.safetensors` file loads directly into ComfyUI without conversion.

## Step-by-Step Integration Workflow

### 1. Install the ComfyUI-LTXVideo Extension

Clone the official extension repository into your ComfyUI installation:

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

```

This extension provides nodes for `LTX-Distilled`, `LTX-IC-LoRA`, and LoRA weight injection.

### 2. Prepare Model Checkpoints

Download the required LTX-2.5 model files from Hugging Face and organize them as specified in the main README:

```

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
└── spatial_upsamplers/
    └── ltx-2.5-spatial-upscaler-bf16.safetensors

```

### 3. Train and Export a ComfyUI-Compatible LoRA

Use `ltx-trainer` with LoRA configuration. The checkpoint is automatically ComfyUI-ready:

```python
from ltx_trainer import Trainer, Config

# Load LoRA training configuration

cfg = Config.load("configs/t2v_lora.yaml")
trainer = Trainer(cfg)

# Training executes...

trainer.train()

# Export: `diffusion_model.` prefix added automatically

trainer.save_checkpoint("my_lora.safetensors")

# File is immediately usable in ComfyUI

```

### 4. Load and Use the LoRA in ComfyUI

The **ComfyUI-LTXVideo** extension handles prefix stripping internally. In a node graph:

- Add an `LTX-LoRA` node
- Connect it to your model loader
- The node strips `diffusion_model.` and injects weights into the pipeline

### 5. Execute Inference

The ComfyUI nodes mirror Python pipeline APIs. The `LTX-Distilled` node calls `DistilledPipeline` from `ltx-pipelines`, executing identical core functions.

## Code Reference: Loading LoRA Weights Programmatically

For custom node development or debugging, this pattern shows how the prefix handling works:

```python
import safetensors.torch
from ltx_core import LTXModel

# Initialize base model with standard paths

model = LTXModel.from_hf(
    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",
)

# Load LoRA: strip ComfyUI prefix manually (extension does this automatically)

lora_state = safetensors.torch.load_file("my_lora.safetensors")
lora_state = {
    k.replace("diffusion_model.", "", 1): v 
    for k, v in lora_state.items()
}

# Apply to model (actual node implements equivalent logic)

model.apply_lora(lora_state)

# Run inference via pipeline

from ltx_pipelines import DistilledPipeline

pipeline = DistilledPipeline(
    transformer=model.transformer,
    text_encoder=model.text_encoder,
    video_vae=model.video_vae,
    spatial_upsampler=model.spatial_upsampler,
)

output = pipeline(
    prompt="A sunrise over a misty forest, cinematic lighting",
    num_frames=64,
    seed=12345,
)
output.save("output.mp4")

```

## Critical Files for Integration Development

| Package | File | Relevance to ComfyUI Integration |
|---------|------|--------------------------------|
| `ltx-trainer` | [`trainer.py`](https://github.com/Lightricks/LTX-2/blob/main/trainer.py) (Lines 517-521) | Prefix add/remove logic for checkpoint compatibility |
| `ltx-pipelines` | [`distilled.py`](https://github.com/Lightricks/LTX-2/blob/main/distilled.py) | `DistilledPipeline` class wrapped by ComfyUI nodes |
| `ltx-core` | [`utils.py`](https://github.com/Lightricks/LTX-2/blob/main/utils.py) | Shared tensor utilities used by both environments |
| External | `ComfyUI-LTXVideo` repo | Node implementations that consume exported checkpoints |

## Key Integration Principles

- **No conversion scripts required**: The trainer produces ComfyUI-native checkpoints directly
- **Symmetric prefix handling**: Load strips, save adds—maintaining clean internal state
- **Shared pipeline code**: ComfyUI nodes call the same inference routines as the Python API
- **Version synchronization**: Updates to `ltx-pipelines` automatically propagate to ComfyUI when the extension updates

## Summary

- LTX-2's three-package architecture (`ltx-core`, `ltx-pipelines`, `ltx-trainer`) enables clean separation between model primitives, inference workflows, and training infrastructure
- The `diffusion_model.` prefix convention in [`trainer.py`](https://github.com/Lightricks/LTX-2/blob/main/trainer.py) (Lines 517-521) provides seamless ComfyUI compatibility without manual conversion
- LoRA checkpoints exported from `ltx-trainer` load directly into **ComfyUI-LTXVideo** nodes
- Both environments execute identical pipeline code from `ltx-pipelines`, ensuring consistent generation results
- The official ComfyUI extension repository provides ready-to-use nodes for `DistilledPipeline`, `ICLoraPipeline`, and LoRA injection

## Frequently Asked Questions

### Why does LTX-2 use the `diffusion_model.` prefix convention?

ComfyUI's node system expects this prefix to distinguish diffusion model weights from other tensor collections (VAEs, text encoders, etc.). LTX-2 adopts this convention to ensure checkpoints work immediately in existing ComfyUI workflows without transformation layers. The trainer's bidirectional prefix handling keeps LTX-2's internal APIs clean while maintaining external compatibility.

### Can I use LTX-2 checkpoints from other sources in ComfyUI?

Checkpoints must either originate from LTX-2's trainer (which adds the prefix) or be manually converted to include `diffusion_model.` on all diffusion-related tensors. The **ComfyUI-LTXVideo** extension specifically expects this format and will fail to load weights without proper prefixing.

### Does the ComfyUI integration support full-model fine-tuning or only LoRA?

The prefix handling in [`trainer.py`](https://github.com/Lightricks/LTX-2/blob/main/trainer.py) primarily targets LoRA checkpoints, which is the most common workflow for ComfyUI users. Full-model checkpoints from `ltx-trainer` follow standard Hugging Face formats and require separate loading mechanisms in ComfyUI, typically through custom loader nodes.

### How do pipeline updates in LTX-2 propagate to ComfyUI?

The **ComfyUI-LTXVideo** extension imports `ltx-pipelines` as a dependency. When the LTX-2 repository updates—adding new samplers, attention optimizations, or conditioning methods—updating the extension pulls the new pipeline code. This shared codebase ensures feature parity between Python API and ComfyUI workflows.