Repository navigation
🚨 Fix gemma4 cross imports resulting in import failing without torch but with PIL - #49748
Conversation
torch but with PILtorch when we have PIL installed
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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 ImageSuppress with # trf-ignore: TRF039 if intentional.
| if is_vision_available(): | ||
| from .image_processing_gemma4_unified import ( # noqa: F401 | ||
| Gemma4UnifiedImageProcessorKwargs, | ||
| get_aspect_ratio_preserving_size, |
There was a problem hiding this comment.
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 ImageSuppress with # trf-ignore: TRF039 if intentional.
|
But yea there is a deeper issue potentially, because gemma4 alone should also potentially fail no? |
|
Thanks for the fix! The root cause analysis is correct and both fixes make sense. One thing worth flagging: the |
|
But shouldnt we have a sanity ci somewhere that tests |
|
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. |
|
run-slow: gemma4, gemma4_unified |
torch when we have PIL installedtorch but with PIL
|
@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) |
CI (Nvidia + AMD)Nvidia · ✅ No new failures 🎉👏 · ⚙️ Workflow · 📊 Dashboard AMD · ❌ 1 new failing tests 😭 · ⚙️ Workflow · 📊 Dashboard Failure details
|
Thanks for checking on this, works for me 👍 |
| # 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]: |
There was a problem hiding this comment.
LOOOL no, pls, lets stop copying same fn around and now in 3 files 😭
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
yeah these will be deleted anyway soon in Guarin's PR and we dont do proper typing anyway in majority models
There was a problem hiding this comment.
OK, good you comment this
|
|
||
|
|
||
| @auto_docstring | ||
| @requires(backends=("torch", "torchvision")) |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
wait i dont see torchvision used anywhere in auto-gen file 👁️
There was a problem hiding this comment.
Removing the requires, the cross imports are probably at fault tbh
|
[For maintainers] Suggested jobs to run (before merge) run-slow: embedding_gemma2, gemma4, gemma4_unified |
zucchini-nlp
left a comment
There was a problem hiding this comment.
Should we merge, CI is green and it looks fine to me, as we decided to enforce modular for new models
## 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>
What does this PR do?
from transformers import *is failing if we havepillowlibrary but nottorchin our env. Beacuse couple of Gemma4 processors are declared with@requires(backends=("vision",))but they import from files which requiretorch/torchvision.Updating the import in
src/transformers/models/gemma4/processing_gemma4.pyto PIL processing file fixes this but gemma4_unified still fails with this 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.Before submitting
Pull Request checks?
to it if that's the case.
Who can review?
@vasqu
🤖 mlinter review state
7823519b0a7d93eatorchbut withPIL#49748 (review)