LTX-2.5 22B distilled transformer — GGUF Q5_K_M

Experimental Q5_K_M GGUF quantization of the distilled LTX-2.5 22B audio-video transformer from Lightricks/LTX-2.5. This repository contains the transformer only.

The required quantized LTX Gemma 4 text encoder is in elix3r/gemma4-12b-with-proj-ltx-2.5-GGUF. It is the LTX-specific encoder with both projection heads, not a stock Gemma 4 chat checkpoint.

File

Requirements

• Git, Python, and the Hugging Face hf CLI.
• Access to the gated Lightricks/LTX-2.5 repository for the VAEs and optional spatial upscaler.
• Current ComfyUI core LTX-2.5 nodes plus ComfyUI-GGUF.
• Enough storage for both GGUFs and the support models.

The known-good combination used for this audit is:

The end-to-end GPU runs used Python 3.14.4, PyTorch 2.10.0+cu128, an RTX 4070 Ti SUPER with 16 GB VRAM, 32 GB system RAM, and swap. This is a tested configuration, not a universal minimum.

Installation

The commands below use a dedicated ComfyUI virtual environment and pin the two tested source revisions. Set COMFY_DIR to the absolute path where ComfyUI should live.

1. Install or update ComfyUI

Fresh install:

export COMFY_DIR=/absolute/path/to/ComfyUI
git clone https://github.com/comfyanonymous/ComfyUI.git "$COMFY_DIR"
git -C "$COMFY_DIR" checkout 2f35f4a08176d993cded35dac3332be4f7287f41
python3 -m venv "$COMFY_DIR/venv"
"$COMFY_DIR/venv/bin/python" -m pip install -U pip
"$COMFY_DIR/venv/bin/python" -m pip install -r "$COMFY_DIR/requirements.txt"

For an existing clean checkout, inspect git status first, then fetch and check out the tested revision:

export COMFY_DIR=/absolute/path/to/ComfyUI
git -C "$COMFY_DIR" status --short
git -C "$COMFY_DIR" fetch origin
git -C "$COMFY_DIR" checkout 2f35f4a08176d993cded35dac3332be4f7287f41
"$COMFY_DIR/venv/bin/python" -m pip install -r "$COMFY_DIR/requirements.txt"

Do not discard a dirty worktree to follow these instructions. Preserve or commit your changes first.

2. Install or update ComfyUI-GGUF

Fresh install:

git clone https://github.com/city96/ComfyUI-GGUF.git \
  "$COMFY_DIR/custom_nodes/ComfyUI-GGUF"
git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" checkout \
  6ea2651e7df66d7585f6ffee804b20e92fb38b8a
"$COMFY_DIR/venv/bin/python" -m pip install -r \
  "$COMFY_DIR/custom_nodes/ComfyUI-GGUF/requirements.txt"

For an existing clean plugin checkout:

git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" status --short
git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" fetch origin
git -C "$COMFY_DIR/custom_nodes/ComfyUI-GGUF" checkout \
  6ea2651e7df66d7585f6ffee804b20e92fb38b8a
"$COMFY_DIR/venv/bin/python" -m pip install -r \
  "$COMFY_DIR/custom_nodes/ComfyUI-GGUF/requirements.txt"

3. Download the transformer

"$COMFY_DIR/venv/bin/python" -m pip install -U huggingface_hub
"$COMFY_DIR/venv/bin/hf" auth login
"$COMFY_DIR/venv/bin/hf" download elix3r/LTX-2.5-22b-distilled-GGUF \
  ltx-2.5-22b-distilled-transformer-Q5_K_M.gguf \
  --local-dir "$COMFY_DIR/models/diffusion_models"

4. Download the Gemma 4 LTX encoder

The canonical current ComfyUI directory is models/text_encoders/. models/clip/ remains a legacy alias in current ComfyUI, but it is not the recommended install path.

"$COMFY_DIR/venv/bin/hf" download elix3r/gemma4-12b-with-proj-ltx-2.5-GGUF \
  gemma4-12b-with-proj-ltx-2.5-Q5_K_M.gguf \
  --local-dir "$COMFY_DIR/models/text_encoders"

Verify both large downloads before loading them:

printf '%s  %s\n' \
  cd82849aec38d2be84805b725c803bad44bc67df9850c23a24ef011a51fd7988 \
  "$COMFY_DIR/models/diffusion_models/ltx-2.5-22b-distilled-transformer-Q5_K_M.gguf" \
  | sha256sum -c -
printf '%s  %s\n' \
  1d35d4fbfa34cca1513d8e9fdd77c0573778b21ffdcbe4ca9c906f37a8c502f9 \
  "$COMFY_DIR/models/text_encoders/gemma4-12b-with-proj-ltx-2.5-Q5_K_M.gguf" \
  | sha256sum -c -

5. Download the official support models

Accept the upstream LTX-2.5 license on Hugging Face before running these commands. The convolutional video VAE is the lower-memory choice used by the examples.

"$COMFY_DIR/venv/bin/hf" download Lightricks/LTX-2.5 \
  vae/ltx-2.5-audio-vae-bf16.safetensors \
  vae/ltx-2.5-video-vae-conv-bf16.safetensors \
  --local-dir "$COMFY_DIR/models"

The two-stage example also requires:

"$COMFY_DIR/venv/bin/hf" download Lightricks/LTX-2.5 \
  latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
  --local-dir "$COMFY_DIR/models"

6. Apply the compatibility patch

As of the tested ComfyUI-GGUF revision, the patch is required. Download the copy shipped with this repository, check it before applying, and do not force it onto a different source tree. The audited patch SHA-256 is 1c36aa38fa9c86ec503926bc6b35226e2575b3bfd27b352bff50deccb1cd958e.

export LTX_GGUF_SUPPORT="$COMFY_DIR/.ltx25-gguf-support"
"$COMFY_DIR/venv/bin/hf" download elix3r/LTX-2.5-22b-distilled-GGUF \
  patches/ComfyUI-GGUF-ltx25-gemma4.patch \
  --local-dir "$LTX_GGUF_SUPPORT"
export LTX_GGUF_PATCH="$LTX_GGUF_SUPPORT/patches/ComfyUI-GGUF-ltx25-gemma4.patch"
cd "$COMFY_DIR/custom_nodes/ComfyUI-GGUF"
git apply --check "$LTX_GGUF_PATCH"
git apply "$LTX_GGUF_PATCH"
git diff --check

The patch changes only loader.py:

1. Registers truthful text architecture gemma4 in TXT_ARCH_LIST.
2. Decodes the three named raw BF16 LTXAV parameters—audio_embeddings_connector.learnable_registers, keyframes_abs_pos_embedding, and video_embeddings_connector.learnable_registers—before they bypass quantized linear operations.

It does not rename tensors, change tokenizer behavior, or rewrite GGUF metadata. Do not change general.architecture to gemma3.

If git apply --check fails, test whether the patch is already present:

git apply --reverse --check "$LTX_GGUF_PATCH"

If both checks fail, return the plugin to the exact clean tested revision or wait for an updated patch. Do not use --reject or --3way to force it.

7. Launch ComfyUI

Fully restart ComfyUI after patching. The tested low-VRAM command was:

cd "$COMFY_DIR"
"$COMFY_DIR/venv/bin/python" main.py \
  --lowvram --disable-dynamic-vram --preview-method none

8. Load an example workflow

Download both examples:

mkdir -p "$COMFY_DIR/user/default/workflows/LTX25-GGUF"
"$COMFY_DIR/venv/bin/hf" download elix3r/LTX-2.5-22b-distilled-GGUF \
  examples/ltx25-gguf-local-smoke.json \
  examples/ltx25-gguf-local-two-stage-hq.json \
  --local-dir "$COMFY_DIR/user/default/workflows/LTX25-GGUF"

Open LTX25-GGUF/examples/ltx25-gguf-local-smoke.json in ComfyUI first. It uses UnetLoaderGGUF, CLIPLoaderGGUF with CLIP type ltxv, local CLIPTextEncode, the official audio and convolutional video VAEs, the distilled eight-step schedule, and synchronized video/audio output.

The two-stage example performs native LTX 2× latent spatial upscaling followed by the workflow's four-value refinement sigma schedule. It is substantially more memory intensive.

GGUF metadata and loading

The transformer keeps the metadata needed for detection:

• general.architecture=ltxv
• general.file_type=17 (MOSTLY_Q5_K_M)
• general.quantization_version=2
• model_version=2.5.0
• config: the original serialized LTX model and scheduler configuration

The embedded configuration identifies an AVTransformer3DModel with 48 layers, video and audio cross-attention, both embedding connectors, keyframe positional embedding, and the rectified-flow scheduler. Current ComfyUI uses the tensor signature and this configuration to select LTXAV; removing or falsifying this metadata breaks reliable model detection.

The file contains 4,349 tensors: 1,072 Q5_K, 368 Q6_K, 2,906 F32, and 3 BF16. See QUANTIZATION.md for the precision policy and limitations.

Validation status

Validated against the exact revisions listed above:

• Full GGUF header, metadata, tensor-bound, tensor-name, and logical-shape audit.
• Exact SHA-256 and file-size verification.
• Patched ComfyUI-GGUF loaded all 4,349 tensors through its real diffusion loader.
• Current ComfyUI selected the LTXAV configuration with 48 layers.
• Both bundled projection heads in the companion encoder produced finite conditioning.
• The workflow node classes, inputs, links, combo values, and filename references were checked against a live ComfyUI 0.33.0 /object_info response.
• Single-stage 608×352, 49-frame, eight-step inference completed with video and audio.
• Two-stage 1216×704, 49-frame inference completed with video and audio in 267.91 seconds from a cold server state.

The two-stage run peaked at approximately 14,554 MiB VRAM, 22.0 GiB process RSS, and 4.4 GiB swap. These measurements are workflow- and system-specific. They establish technical inference compatibility, not BF16-versus-Q5 quality parity.

Troubleshooting

Unexpected text model architecture type in GGUF file: 'gemma4'

Stock ComfyUI-GGUF at the tested revision does not register gemma4 as a text architecture. Apply the included patch, confirm git diff --check, and fully restart ComfyUI. Do not relabel the file as gemma3.

A ComfyUI Manager or manual plugin update can replace the patched loader.py. After updating ComfyUI-GGUF, rerun the forward and reverse git apply --check commands above before launching.

The encoder does not appear in CLIPLoaderGGUF

Put it in ComfyUI/models/text_encoders/, not models/diffusion_models/. Fully restart ComfyUI after moving it. models/clip/ is a backward-compatible alias, not the canonical location used here.

The transformer does not appear in UnetLoaderGGUF

Put it in ComfyUI/models/diffusion_models/, verify the exact filename and checksum, then restart ComfyUI.

Value not in list: ckpt_name or a GemmaAPITextEncode error

That workflow is using an API-only or regular-checkpoint node. Use the supplied workflows. The transformer must enter through UnetLoaderGGUF; the encoder must enter through CLIPLoaderGGUF with type ltxv. Neither GGUF is a ckpt_name for GemmaAPITextEncode.

Missing LTX nodes

Check that ComfyUI is at the tested core revision and that ComfyUI-GGUF loaded without import errors. The LTX conditioning, latent, sampler, VAE, audio, video, and spatial-upscale nodes used by the examples are current ComfyUI core nodes; only the two GGUF loader nodes come from ComfyUI-GGUF.

CUDA out of memory or system-memory pressure

Close other GPU applications, use the convolutional video VAE, launch with the tested low-VRAM flags, and run the single-stage 608×352×49 example before the two-stage workflow. On the tested 16 GB GPU, the two-stage path operated close to the VRAM limit and used swap. Do not raise resolution, duration, or batch size until the smoke workflow succeeds.

CUDA optimization warning

The tested PyTorch build was CUDA 12.8 and emitted a recommendation for a newer CUDA build, but it still completed inference. That warning is not the cause of the gemma4 loader rejection. Upgrade PyTorch only using a build supported by your GPU, driver, Python version, and current ComfyUI.

License and modification notice

This quantization is a modified/derivative form of LTX-2.5. Use and redistribution are subject to the full LTX-2.x Community License, including its revenue threshold, redistribution conditions, and acceptable-use restrictions. See NOTICE.md for provenance and modification details.

This repository is not affiliated with or endorsed by Lightricks. LTX and related marks belong to their respective owners.