LTX2 import fails with Transformers 5.5.0 due to annotation-only Gemma4Unified dependency

[Imagineer99]

Describe the bug

With Diffusers 0.40.0 and Transformers 5.5.0, importing LTX2Pipeline fails because Gemma4UnifiedForConditionalGeneration is unavailable. This blocks Gemma3-based LTX 2.3 use before any checkpoint is loaded. We encountered this in Unsloth Desktop, but the reproduction does not import Unsloth.

The unconditional import is also present on current main. In the five affected pipeline modules in 0.40.0, the missing class is used only in the text_encoder constructor annotation.

Reproduction

In an environment with PyTorch, diffusers==0.40.0, and transformers==5.5.0:

from diffusers import LTX2Pipeline

LTX2ImageToVideoPipeline fails similarly. No model download, GPU generation, or authentication is required to trigger this error.

Logs

RuntimeError: Failed to import diffusers.pipelines.ltx2.pipeline_ltx2 because of the following error (look up to see its traceback):
cannot import name 'Gemma4UnifiedForConditionalGeneration' from 'transformers'

Proposed scope and validation

Would you accept a PR replacing the architecture-specific text_encoder annotation with transformers.PreTrainedModel and removing the unused Gemma imports across these five modules?

• pipeline_ltx2.py
• pipeline_ltx2_image2video.py
• pipeline_ltx2_condition.py
• pipeline_ltx2_ic_lora.py
• pipeline_ltx2_hdr_lora.py

An isolated candidate preserves Diffusers 0.40.0 and Transformers 5.5.0, with no changes to generation logic. Validation so far:

• Original fails with the error above on Windows and WSL; the candidate completes tiny-fixture text-to-video and image-to-video inference, including audio decoding and local save/reload, on both.
• On a separate Transformers 5.17.0 test stack, original and patched pipelines produce bit-for-bit identical video and audio tensors for those same tiny fixtures. The real Gemma4Unified class remains accepted by the annotation.
• All five affected pipeline imports/signature checks and MiniMax-H3/Music-3 modular pipeline imports pass.

The runtime checks use the upstream LTX tiny-component fixture and hf-internal-testing/tiny-gemma3. Full LTX 2.3 and MiniMax checkpoint generation have not been tested.

This investigation and candidate were AI-assisted. Following the contribution guidelines, I am opening this issue for maintainer acknowledgment before a PR, and am happy to adjust the approach or add repository-native regression coverage.

System Info

Reproduced on both:

	Windows	WSL2 Ubuntu
Diffusers	0.40.0	0.40.0
Transformers	5.5.0	5.5.0
Python	3.13.5	3.13.12
PyTorch	2.10.0+cu130	2.11.0+cu130

Additional WSL environment: huggingface_hub 1.30.0, Accelerate 1.14.0, PEFT 0.18.1, safetensors 0.8.0. NVIDIA RTX 5070 Ti is available; the reproduction is import-only and does not use distributed execution.

[L4XB]

I have a fix ready for this and, per CONTRIBUTING, I am asking for a maintainer ack on the issue before opening the PR.

Two corrections to the scope first.

1. It is seven modules, not five. grep -rn "Gemma4Unified" --include="*.py" . on main @ 759164b matches only src/diffusers/pipelines/ltx2/, and in every one the symbol appears just in the from transformers import (...) block and the text_encoder annotation/docstring:

   pipeline_ltx2.py, pipeline_ltx2_image2video.py, pipeline_ltx2_condition.py, pipeline_ltx2_ic_lora.py, pipeline_ltx2_hdr_lora.py, pipeline_ltx2_dfr.py, pipeline_ltx2_dfr_temporal_refine.py

   The last two are newer than 0.40.0, which is why the report lists five.

2. It is nine public entry points, not seven. Resolving every name in diffusers.__all__ on transformers 5.5.0:

   transformers 5.5.0, diffusers 0.41.0.dev0 @ 759164b
   before:  resolved OK: 693   failed: 9
   after:   resolved OK: 702   failed: 0
   

   The two extra are LTX2AutoBlocks and LTX25AutoBlocks, which never name the symbol themselves — modular_blocks_ltx2.py → before_denoise.py → pipeline_ltx2_ic_lora.py carries it in. Fixing the seven source modules clears all nine.

The boundary is 5.9.0 → 5.10.0. src/transformers/models/gemma4_unified is absent at tag v5.9.0 and present at v5.10.0; from transformers import Gemma4UnifiedForConditionalGeneration raises on 5.5.0 and 5.9.0 and succeeds on 5.10.0/5.10.1/5.11.0/5.17.0. (5.10.0 is yanked on PyPI, so any table below uses 5.10.1, but the guard says >= 5.10.0 because that is where the symbol appears.)

The shape I would like to confirm before writing it up. Bind the name to transformers.PreTrainedModel and re-import it behind is_transformers_version(">=", "5.10.0") in each affected module — the same pattern pipelines/glm_image/pipeline_glm_image.py already uses for GlmImageForConditionalGeneration. Repeated per file rather than factored into a shared helper, per the single-file policy in PHILOSOPHY.md.

I did consider the option floated in the issue — drop the import and annotate text_encoder as PreTrainedModel — but it is a behaviour change, not a cosmetic one. DiffusionPipeline._get_signature_types() reads that annotation, and loaders/single_file.py::_map_component_types_to_config_dict uses component_value[0].__name__ to build the inferred model_index.json entry. Collapsing the union would turn ["transformers", "Gemma3ForConditionalGeneration"] into ["transformers", "PreTrainedModel"] for pipelines that carry FromSingleFileMixin. A TYPE_CHECKING block has the same problem unless every module also gets from __future__ import annotations, since the annotation is evaluated at class-definition time.

With the guard, introspection is byte-identical wherever the symbol exists (checked on 5.17.0, all seven pipelines, both _get_signature_types()["text_encoder"] and the single-file inferred config); on 5.5.0 the union becomes (Gemma3ForConditionalGeneration, PreTrainedModel) and the single-file entry is unchanged.

Test. tests/others/test_dependencies.py::test_ltx2_pipelines_import_without_gemma4_unified hides the symbol and reports an older transformers in a subprocess, then resolves all nine entry points. It sits next to test_pipeline_module_imports, which exists for the same class of bug but can only catch it on an environment that actually has the older dependency. Run on transformers 5.17.0 so it discriminates on the version CI installs:

merge base 759164b : 1 failed, 4 deselected in 3.29s
this branch        : 1 passed, 4 deselected in 3.65s

pytest tests/modular_pipelines/ltx2 is unchanged: 16 failed / 140 passed / 18 skipped on both sides, the same CPU-offload tests.

Happy to open the PR if this shape is what you want, or to switch to the annotation change if you would rather take the model_index.json consequence.

[L4XB]

Correcting my own comment above: the scope is bigger than I said, in a way that matters for the ack.

I had swept diffusers.__all__ only at transformers 5.5.0, the version in the report. Sweeping the
rest of the 5.x range turns up a second class imported exactly the same way:
Gemma4ForConditionalGeneration (no "Unified"), added in transformers 5.5.0, imported
unconditionally by five of the seven modules to annotate the optional prompt_enhancer. It raises
first in the same import tuple, so on transformers 5.0.0–5.4.x guarding only Gemma4Unified would
have left this issue's symptom exactly where it is.

                                    main @ 759164b        branch
transformers 5.0.0    691 ok / 11 failed        700 ok /  2 failed
transformers 5.4.0    693 ok /  9 failed        702 ok /  0 failed
transformers 5.5.0    693 ok /  9 failed        702 ok /  0 failed
transformers 5.9.0    693 ok /  9 failed        702 ok /  0 failed

Both boundaries are measured: src/transformers/models/gemma4 is absent at tag v5.4.0 and present
at v5.5.0; gemma4_unified is absent at v5.9.0 and present at v5.10.0. The branch now guards
both, and introspection stays byte-identical on 5.17.0 — _get_signature_types() for both
text_encoder and prompt_enhancer, and the full _infer_pipeline_config_dict() mapping, for all
seven pipelines.

The 2 that remain at 5.0.0 are the same pattern outside LTX2, and I would like your call on them.
pipelines/motif_video/pipeline_motif_video.py and pipeline_motif_video_image2video.py import
T5Gemma2Encoder (transformers 5.1.0) the same way, and already carry a comment saying so:

# NOTE: This pipeline requires transformers>=5.1.0 for T5Gemma2Encoder support.

Same one-line fix, but a different pipeline family whose authors clearly knew, and unlike LTX2 that
pipeline is genuinely unusable without the class rather than merely un-importable — so I did not
widen someone else's report into their code on my own. Happy to fold it into the same PR so the sweep
comes back clean at 5.0.0, or to leave it out.

Test is unchanged in shape, just widened to hide both symbols and report transformers 5.4.0:

tests/others/test_dependencies.py::…::test_ltx2_pipelines_import_on_older_transformers
  main @ 759164b (test file only) : 1 failed — cannot import name 'Gemma4ForConditionalGeneration'
  branch                          : 5 passed  (whole file)

Still asking before opening: is the two-symbol scope what you want, and does motif_video go in it?