mlinter

A standalone linter for Hugging Face Transformers model integration files — modeling_*.py, modular_*.py, configuration_*.py, processing_*.py, image_processing_*.py, video_processing_*.py and feature_extraction_*.py under src/transformers/models/, plus test_tokenization_*.py under tests/models/. It enforces the structural conventions that keep hundreds of model implementations consistent with each other.

📖 Documentation: https://huggingface.github.io/transformers-mlinter/

The docs site is generated from mlinter/rules.toml, so its rule reference is always in step with the installed rules.

Installation

pip install transformers-mlinter

When working on the transformers repo, mlinter is included in the quality extras:

pip install -e ".[quality]"

Quick start

Run from the root of a transformers checkout:

mlinter                                     # check every model integration file
mlinter --changed-only --base-ref origin/main   # only what you changed
mlinter --list-rules                        # list rules and their default state
mlinter --rule TRF001                       # explain one rule

Pass a path to check code that lives outside a transformers checkout — a model repository shipped on the Hub with trust_remote_code, for instance, which has to honour the same conventions:

mlinter ~/models/LLaDA-8B-Instruct          # a directory, searched recursively
mlinter path/to/modeling_llada.py           # or a single file

See the CLI reference for every flag, the Python API, and cache locations.

Documentation map

Page	What's there
Home	What mlinter checks and why, installation, how rule registration works
Rules	All rules, filterable, one page each with examples and exemptions
CLI usage	Every flag, output formats, cache, Python API
Suppressing rules	# trf-ignore, whole-file directives, cutoff dates, allowlists
Contributing a rule	Adding a rule, the add-mlinter-rule skill, constraints on a rule
Releasing	The tag-driven release process

Development

git clone https://github.com/huggingface/transformers-mlinter
cd transformers-mlinter
pip install -e ".[dev]"

make test        # pytest under tests/
make lint        # ruff check + format --check
make format      # auto-fix style
make typecheck   # ty on mlinter/

Building the docs site

The rule pages are generated and git-ignored. Building needs the Ruby toolchain once:

cd docs && bundle install && cd ..
make docs         # regenerate rule pages, build the site, check internal links
make docs-serve   # live preview on http://localhost:4000/transformers-mlinter/

License

Apache-2.0. See LICENSE.