Skip to content

🚨 Fix gemma4 cross imports resulting in import failing without torch but with PIL - #49748

Merged
ydshieh merged 9 commits into
huggingface:mainfrom
Sai-Suraj-27:fix_transformers_import
Oct 23, 2026
Merged

ydshieh merged 9 commits into
huggingface:mainfrom
Sai-Suraj-27:fix_transformers_import

Conversation

@Sai-Suraj-27

@Sai-Suraj-27 Sai-Suraj-27 commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

🤗 Transformers CI

What does this PR do?

from transformers import * is failing if we have pillow library but not torch in our env. Beacuse couple of Gemma4 processors are declared with @requires(backends=("vision",)) but they import from files which require torch/torchvision.

  File "/home/suraj/repos/transformers/src/transformers/models/gemma4/processing_gemma4.py", line 28, in <module>
    from .image_processing_gemma4 import Gemma4ImageProcessorKwargs, get_aspect_ratio_preserving_size
  File "/home/suraj/repos/transformers/src/transformers/models/gemma4/image_processing_gemma4.py", line 16, in <module>
    import torch
ModuleNotFoundError: No module named 'torch'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/suraj/repos/transformers/src/transformers/utils/import_utils.py", line 2707, in __getattr__
    raise ModuleNotFoundError(import_error_message) from e
ModuleNotFoundError: Could not import module 'models.gemma4.processing_gemma4'. Are this object's requirements defined correctly? Set the logging verbosity to DEBUG for the original import error.

Updating the import in src/transformers/models/gemma4/processing_gemma4.py to PIL processing file fixes this but gemma4_unified still fails with this error:

  File "/home/suraj/repos/transformers/src/transformers/models/gemma4_unified/image_processing_gemma4_unified.py", line 22, in <module>
    import torch
ModuleNotFoundError: No module named 'torch'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/suraj/repos/transformers/src/transformers/utils/import_utils.py", line 2700, in __getattr__
    raise ModuleNotFoundError(import_error_message) from e
ModuleNotFoundError: Could not import module 'Gemma4UnifiedProcessor'. Are this object's requirements defined correctly? Set the logging verbosity to DEBUG for the original import error.

Looks like this issue is existing from #46385, Keeping the PR as a Draft for now until further review/comments.

Code Agent Policy

The Transformers repo is currently being overwhelmed by a large number of PRs and issue comments written by
code agents. These often are low-quality, or fix extremely minor issues that occur rarely or never in practice.
As a result, we're instituting a rule that first-time contributors should not use code agents to submit PRs or issues.
We'd also ask autonomous "OpenClaw"-like agents not to open any PRs or issues.

Issues/PRs from first-time contributors that violate this rule will probably just be closed without review, and we
might block you, especially if you open more than one or appear to be deliberately ignoring this. We especially do not
want new contributors to jump in on random issues to contribute an agent-written fix. This creates lots of noise
for reviewers and other users and will almost certainly get you blocked.

For more information, please read CONTRIBUTING.md.

  • (First-time contributors only): I confirm that this PR description and code is not written by an LLM or code agent

Before submitting

  • This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
  • Did you read the contributor guideline and the
    Pull Request checks?
  • Was this discussed/approved via a Github issue or the forum? Please add a link
    to it if that's the case.
  • Did you make sure to update the documentation with your changes according to the guidelines?
  • Did you write any new necessary tests?

Who can review?

@vasqu

🤖 mlinter review state

@Sai-Suraj-27 Sai-Suraj-27 changed the title Fix library import failing without torch but with PIL Fix library import failing without torch when we have PIL installed Oct 20, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Model linter — first pass

transformers-mlinter found 2 item(s) in the model files this PR touches. These are structural conventions a maintainer would otherwise flag by hand.

This is automated and advisory — it does not block merging.

rule count what it checks
TRF039 2 Imports guarded by is_*_available() must be removed once nothing in the file uses them.


if is_vision_available():
from .image_processing_gemma4_unified import ( # noqa: F401
Gemma4UnifiedImageProcessorKwargs,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TRF039 — TRF039: Gemma4UnifiedImageProcessorKwargs is imported behind an availability guard but is never used in this file. ruff does not flag or clean up imports inside if is_*_available(): blocks, so a leftover import from a refactor stays behind silently. Remove it.

Why this matters

ruff's unused-import check does not clean these up: the import is reachable, so the block looks fine on its own. Once a refactor no longer needs PIL.Image, torch, etc., the guarded import lingers as dead weight and a misleading signal about the file's real dependencies.

if is_vision_available():
-    from PIL import Image

Suppress with # trf-ignore: TRF039 if intentional.

if is_vision_available():
from .image_processing_gemma4_unified import ( # noqa: F401
Gemma4UnifiedImageProcessorKwargs,
get_aspect_ratio_preserving_size,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TRF039 — TRF039: get_aspect_ratio_preserving_size is imported behind an availability guard but is never used in this file. ruff does not flag or clean up imports inside if is_*_available(): blocks, so a leftover import from a refactor stays behind silently. Remove it.

Why this matters

ruff's unused-import check does not clean these up: the import is reachable, so the block looks fine on its own. Once a refactor no longer needs PIL.Image, torch, etc., the guarded import lingers as dead weight and a misleading signal about the file's real dependencies.

if is_vision_available():
-    from PIL import Image

Suppress with # trf-ignore: TRF039 if intentional.

@vasqu

vasqu commented Oct 20, 2026

Copy link
Copy Markdown
Collaborator

But yea there is a deeper issue potentially, because gemma4 alone should also potentially fail no?

@ydshieh

ydshieh commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator

Thanks for the fix! The root cause analysis is correct and both fixes make sense.

One thing worth flagging: the # noqa: F401 added to the import in processing_gemma4_unified.py looks incorrect — Gemma4UnifiedImageProcessorKwargs and get_aspect_ratio_preserving_size are both actively used in the same file (lines 45, 245, 272), so they are not unused imports. The noqa suppression should be removed.

@vasqu

vasqu commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator

But shouldnt we have a sanity ci somewhere that tests from transformers import * when no torch but PIL installed?

@HuggingFaceDocBuilderDev

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@vasqu

vasqu commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator

run-slow: gemma4, gemma4_unified

@vasqu vasqu changed the title Fix library import failing without torch when we have PIL installed 🚨 Fix gemma4 cross imports resulting in import failing without torch but with PIL Oct 21, 2026
@vasqu
vasqu requested a review from zucchini-nlp October 21, 2026 17:29
@vasqu

vasqu commented Oct 21, 2026

Copy link
Copy Markdown
Collaborator

@Sai-Suraj-27 I tried something different here, especially since cross imports should never happen in the library. Does that work for you?

Also cc @zucchini-nlp because this might be slightly breaking for gemma4 but i doubt anyone actually uses images_kwargs under processors kwargs (it seems to be the only ocurrence of this happening)

@github-actions

Copy link
Copy Markdown
Contributor

CI (Nvidia + AMD)

Nvidia · ✅ No new failures 🎉👏 · ⚙️ Workflow · 📊 Dashboard

AMD · ❌ 1 new failing tests 😭 · ⚙️ Workflow · 📊 Dashboard

Failure details
  • gemma4_unified:
    tests/models/gemma4_unified/test_modeling_gemma4_unified.py::Gemma4UnifiedTextModelTest::test_flash_attn_2_can_compile_with_attention_mask_None_without_graph_break (❌ ⟹ ❌)

@Sai-Suraj-27

Copy link
Copy Markdown
Contributor Author

@Sai-Suraj-27 I tried something different here, especially since cross imports should never happen in the library. Does that work for you?

Thanks for checking on this, works for me 👍

Comment on lines +31 to +38
# Copied from transformers.models.gemma4.image_processing_pil_gemma4.get_aspect_ratio_preserving_size
def get_aspect_ratio_preserving_size(
height: int,
width: int,
patch_size: int,
max_patches: int,
pooling_kernel_size: int,
) -> tuple[int, int]:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOOOL no, pls, lets stop copying same fn around and now in 3 files 😭

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed internally, more of an issue not using modular here. Otherwise we couldve defined it just once



class Gemma4ProcessorKwargs(ProcessingKwargs, total=False):
images_kwargs: Gemma4ImageProcessorKwargs

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah these will be deleted anyway soon in Guarin's PR and we dont do proper typing anyway in majority models

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, good you comment this



@auto_docstring
@requires(backends=("torch", "torchvision"))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

torch should not happen in perfect world indeed, our lib is also used by other frameworks that dont depend on torch (like the MLX i recently came to know)
I was trying to let them use existing processors rather than having to write each new processor implem from scratch

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wait i dont see torchvision used anywhere in auto-gen file 👁️

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing the requires, the cross imports are probably at fault tbh

@github-actions

Copy link
Copy Markdown
Contributor

[For maintainers] Suggested jobs to run (before merge)

run-slow: embedding_gemma2, gemma4, gemma4_unified

@zucchini-nlp zucchini-nlp left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we merge, CI is green and it looks fine to me, as we decided to enforce modular for new models

@ydshieh
ydshieh merged commit d6150ee into huggingface:main Oct 23, 2026
47 checks passed

@prosablageetpeinture-blip prosablageetpeinture-blip left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good

tarekziade added a commit to huggingface/transformers-mlinter that referenced this pull request Oct 28, 2026
## Why


[huggingface/transformers#49748](huggingface/transformers#49748):
`from transformers import *` crashes on an install with Pillow but no
torch. `Gemma4Processor` / `Gemma4UnifiedProcessor` are
`@requires(backends=("vision",))`, but under `if is_vision_available():`
they import `.image_processing_gemma4[_unified]`, which does `import
torch` / torchvision at top level. The lazy module imports the processor
file as soon as vision is installed, and the sibling import crashes.

TRF009 doesn't catch this because it only bans imports from *other*
models; imports within a model folder are fine. CI didn't catch it
either, because the runtime "PIL only" import step was running without
PIL (fixed in huggingface/transformers-ci#341). This rule catches the
pattern at lint time.

## What TRF064 checks

For every relative import that runs at module import time:

- **Declared** backends = the file's base requirements (mirror of
`BASE_FILE_REQUIREMENTS` in transformers' `import_utils.py`) ∪ the
*weakest* `@requires(backends=...)` among its `__all__` objects, since
the lazy loader imports the file as soon as any one exported object's
backends are present.
- **Needed** backends = what the imported model-local files' unguarded
top-level imports pull in (`import torch` → torch, `from PIL` → vision,
…), followed transitively, with implied backends (torchvision ⇒ torch).
- Flags when needed ⊄ declared ∪ enclosing `is_<backend>_available()`
guards.
- Skips function/class bodies, `TYPE_CHECKING`, and `try`/`except
ImportError`. Core deps (`tokenizers`, `numpy`, …) are never backends.
- `modular_*.py` files are checked through the files they generate,
since generated files aren't linted. The violation anchors on the
matching import or exported class in the modular file, so `# trf-ignore:
TRF064` works there.
- The message shows the full import chain.

The lint cache now hashes every sibling file in the model directory, so
editing an imported file re-checks its importers.

## Results on transformers

| Tree | TRF064 hits |
|---|---|
| `main` @ `fb3e4f2828` | 2: `gemma4/processing_gemma4.py:L28` and
`gemma4_unified/modular_gemma4_unified.py:L340` |
| PR #49748 head | 0 |

These are exactly the two classes that fail `from transformers import *`
at runtime in the `huggingface/transformers-consistency` image with only
Pillow installed. There are no other hits (an earlier draft treated
`tokenizers` as optional and produced 3 false positives; it is a core
dependency).

`make lint`, `make test` (454 passed) and `make typecheck` all pass.

## Limitations / follow-ups

- Base requirements and the package → backend map are hand-mirrored from
transformers and can drift.
- Direct third-party imports (e.g. top-level `import torch` in a
`processing_*.py` with only `@requires("vision")`) are not flagged yet:
the rule is scoped to model-local imports to keep this first version
precise. Worth a follow-up after a false-positive pass.
- Adopting it in transformers needs a TRF064 entry in
`utils/rules.toml`.
- TRF060–063 are taken by open PRs (#77, #79, #81, #82, #85), hence 064.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants