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

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.

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

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

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:

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:

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 (Lines 517-521)	Prefix add/remove logic for checkpoint compatibility
ltx-pipelines	distilled.py	DistilledPipeline class wrapped by ComfyUI nodes
ltx-core	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 (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 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.

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