> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-dev.ltx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.ltx.io/_mcp/server.

# Quick Start

> Set up the LTX Trainer and run a first training job, including prerequisites, checkpoint and Gemma encoder setup, and configuration.

Get up and running with LTX family training in a few steps.

> **Tip**
>
> **New to training? Start with the agent.** You don't have to run these steps by hand. You can open the repo in Claude Code
> and run `/train-model`. It makes the same decisions described below and explains each step as it goes, pausing for your
> approval before any heavy work. See the
> [`train-model` skill](https://github.com/Lightricks/LTX-2/tree/main/.claude/skills/train-model) for the full
> phase-by-phase reference.

## Prerequisites

Before you begin, ensure you have:

1. **LTX model checkpoint** — a local `.safetensors` file with the model weights. The trainer supports LTX-2, LTX-2.3,
   and LTX 2.5 through the same configuration API; version-specific components are detected from the checkpoint
   metadata. See the [repository root README](https://github.com/Lightricks/LTX-2#required-models) for the current
   checkpoint download links. For LTX 2.5, the trainable checkpoint is the dev transformer, `ltx-2.5-22b-dev-transformer-bf16.safetensors`, on [Lightricks/LTX-2.5](https://huggingface.co/Lightricks/LTX-2.5).
2. **Matching Gemma text encoder** — a local directory containing the Gemma model. **LTX 2.5 requires the
   LTX-specific fine-tuned Gemma 4 root** (you can find it [here](https://huggingface.co/Lightricks/LTX-2.5/blob/main/text_encoders/)), **not** Google's vanilla Gemma 4 model —
   that version of the model is not the encoder LTX 2.5 was trained with, and will fail the checkpoint/Gemma compatibility check.
   Older LTX-2 and LTX-2.3 checkpoints use the Gemma 3 root they declare. Always use the encoder that matches your
   checkpoint's metadata.
3. **Linux with CUDA** — the trainer requires `triton`, which is Linux-only.
4. **A GPU with enough VRAM** — 80GB recommended for the standard config.

> **Tip**
>
> For 32GB GPUs (e.g. RTX 5090), use the [low-VRAM config](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/t2v_lora_low_vram.yaml), which enables INT8 quantization and other memory optimizations.

## Installation

First install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you haven't already, then clone the
repository:

```bash
git clone https://github.com/Lightricks/LTX-2
```

The `ltx-trainer` package is part of the `LTX-2` monorepo. Install dependencies from the repository root, then move
into the trainer package:

```bash
# From the repository root
uv sync
cd packages/ltx-trainer
```

> **Note**
>
> The trainer depends on the `ltx-core` and `ltx-pipelines` packages, which are installed automatically from the
> monorepo.

## Training Workflow

### 1. Prepare your dataset

Organize your videos with captions, then preprocess them into cached latents and text embeddings:

```bash
uv run python scripts/process_dataset.py dataset.json \
    --resolution-buckets "960x544x49" \
    --model-path /path/to/ltx-2.x-checkpoint.safetensors \
    --text-encoder-path /path/to/gemma-root
```

Audio latents are extracted from your videos automatically. Optional scene splitting (`split_scenes.py`) and automatic
captioning (`caption_videos.py`) are also available. For the full preprocessing workflow — dataset format, captioning
setup, resolution buckets, masks, and all CLI options — see the
[Dataset Preparation guide on GitHub](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/dataset-preparation.md).

> **Note**
>
> **Precomputed text features are specific to the checkpoint and Gemma pair.** The cached `conditions/` embeddings are
> produced by the selected Gemma model and are not interchangeable across versions. When switching from LTX-2.3 to LTX
> 2.5 (Gemma 3 → Gemma 4), preprocess into a fresh output directory or pass `--overwrite` — existing `.pt` files are
> skipped by default. No version flag is required; the checkpoint metadata drives detection.

### 2. Configure training

Create or modify a configuration YAML file. Start from one of the example configs:

* [`t2v_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/t2v_lora.yaml) — text-to-video LoRA
* [`t2v_lora_low_vram.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/t2v_lora_low_vram.yaml) — same, tuned for \~32GB VRAM (INT8 quantization and memory optimizations)
* [`v2v_ic_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/v2v_ic_lora.yaml) — IC-LoRA video-to-video

Key settings to update:

```yaml
model:
  model_path: "/path/to/ltx-2.x-checkpoint.safetensors"
  text_encoder_path: "/path/to/matching-gemma-root"

data:
  preprocessed_data_root: "/path/to/preprocessed/data"

output_dir: "outputs/my_training_run"
```

See the [Configuration Reference](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/configuration-reference.md) for all available options.

### 3. Start training

```bash
uv run python scripts/train.py configs/t2v_lora.yaml
```

For multi-GPU training:

```bash
uv run accelerate launch scripts/train.py configs/t2v_lora.yaml
```

See the [Training Guide](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/training-guide.md) for distributed training (DDP/FSDP), HuggingFace Hub uploads, and Weights & Biases logging.

## Training Modes

> **Tip**
>
> **First time?** Start with [`t2v_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/t2v_lora.yaml) — it's the simplest mode and only requires videos with captions. Explore other modes once you've confirmed your setup works.

All modes are expressed through the single **`flexible`** training strategy. The trainer supports:

| Mode                  | Description                                 | Example Config                                                                                                                          |
| --------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Text-to-Video**     | Generate video+audio from text prompts      | [`t2v_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/t2v_lora.yaml)                             |
| **Image-to-Video**    | Animate from a starting image               | [`i2v_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/i2v_lora.yaml)                             |
| **Video Extension**   | Extend videos temporally (forward/backward) | [`video_extend_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/video_extend_lora.yaml)           |
| **IC-LoRA (V2V)**     | Video-to-video transformations              | [`v2v_ic_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/v2v_ic_lora.yaml)                       |
| **Audio-to-Video**    | Generate video conditioned on audio         | [`a2v_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/a2v_lora.yaml)                             |
| **Video-to-Audio**    | Generate audio/foley from video             | [`v2a_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/v2a_lora.yaml)                             |
| **Video Inpainting**  | Fill in masked regions of video             | [`video_inpainting_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/video_inpainting_lora.yaml)   |
| **Video Outpainting** | Extend video spatially                      | [`video_outpainting_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/video_outpainting_lora.yaml) |
| **Text-to-Audio**     | Generate audio from text prompts            | [`t2a_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/t2a_lora.yaml)                             |
| **Audio Extension**   | Extend audio temporally                     | [`audio_extend_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/audio_extend_lora.yaml)           |
| **Audio Inpainting**  | Fill in masked regions of audio             | [`audio_inpainting_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/audio_inpainting_lora.yaml)   |
| **IC-LoRA (A2A)**     | Audio-to-audio transformations              | [`a2a_ic_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/a2a_ic_lora.yaml)                       |
| **AV2AV IC-LoRA**     | Audio+video IC-LoRA transformations         | [`av2av_ic_lora.yaml`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/configs/av2av_ic_lora.yaml)                   |
| **Full Fine-tuning**  | Full model training (any mode above)        | Set `model.training_mode: "full"`                                                                                                       |

See [Training Modes](/open-source-model/ltx-trainer/training-modes) for detailed explanations of each mode.

## Reference docs on GitHub

#### [Dataset Preparation](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/dataset-preparation.md)

Preprocess videos, generate captions, and build resolution buckets.

#### [Configuration Reference](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/configuration-reference.md)

Every available training parameter.

#### [Training Guide](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/training-guide.md)

Distributed training (DDP/FSDP), HuggingFace Hub, and W\&B logging.

#### [Utility Scripts](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/utility-scripts.md)

Tools for dataset management and debugging.

#### [Custom Training Strategies](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/custom-training-strategies.md)

Go beyond the flexible strategy with your own training logic.

#### [Troubleshooting](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/docs/troubleshooting.md)

Solutions to common training problems.

> **Tip**
>
> 🎬 **Happy training!** May your loss curves trend down and your VRAM never run out.