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, feature_extraction_*.py, tokenization_*.py and generation_*.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

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.