Rules
mlinter ships 63 rules, 61 of them enabled by default. Every rule is static: it reads the file’s syntax tree and never imports or runs the model code.
Rules whose scope names a date only apply to models contributed to Transformers on or after it — existing models are grandfathered so a new convention does not retroactively fail the whole library. Individual models can also be exempted; each rule page lists its own exemptions.
| Code | What it checks | Default | Scope |
|---|---|---|---|
| TRF002 | base_model_prefix on a PreTrainedModel, when set, should be a non-empty canonical string. | Enabled | All models |
| TRF003 | forward() should use @capture_output/@can_return_tuple, not manual return_dict branching. | Disabled | All models |
| TRF004 | Models must never override tie_weights. Use _tied_weights_keys instead. | Enabled | All models |
| TRF005 | _no_split_modules, when defined, should be a list/tuple of non-empty strings. | Enabled | All models |
| TRF006 | Cache arguments declared in a forward signature should be used in its body. | Enabled | All models |
| TRF007 | self.post_init() should stay last in a PreTrainedModel __init__. | Enabled | All models |
| TRF008 | add_start_docstrings on a model class should not be empty. | Enabled | All models |
| TRF009 | No file in a model directory may import implementation code from another model package. | Enabled | All models |
| TRF010 | Direct config definitions must use @strict(accept_kwargs=True). | Enabled | All models |
| TRF011 | forward() must not read non-nn.Module attributes off submodules: pipeline parallelism may replace them with Identity. | Enabled | All models |
| TRF012 | _init_weights must use init primitives, not in-place operations on module weights. | Enabled | All models |
| TRF013 | PreTrainedModel __init__ must call self.post_init(). | Enabled | All models |
| TRF014 | trust_remote_code should never be used in native model integrations. |
Enabled | All models |
| TRF015 | Models with non-empty _tied_weights_keys must have tie_word_embeddings in their Config. | Enabled | All models |
| TRF016 | do_* flags declared on a processor class must be referenced by overridden preprocess/_preprocess. | Enabled | All models |
| TRF017 | @auto_docstring must be placed above @dataclass on output classes. | Enabled | All models |
| TRF018 | _init_weights overrides should call super()._init_weights(module), except modular-file sentinels. | Enabled | All models |
| TRF019 | A processor TypedDict must not define _defaults; ship them on the hub in processor_config.json. |
Enabled | 2026-06-20 |
| TRF020 | MLA models must isolate the KV LoRA expansion (kv_b_proj) in a dedicated method that forward() calls. | Enabled | All models |
| TRF021 | Scalar tensors must be filled on-device with torch.full((), …) instead of torch.tensor(…, device=…). | Enabled | All models |
| TRF022 | _no_split_modules entries must name module classes that exist in the model. | Enabled | All models |
| TRF023 | Config fields must use canonical dimension names (hidden_size, intermediate_size, num_attention_heads, …). | Enabled | 2026-06-20 |
| TRF024 | Layer dimensions must come from the config, not from an integer literal in the modeling file. | Enabled | 2026-06-20 |
| TRF025 | Attention masks must be built once in the model, not rebuilt inside a layer or attention module. | Enabled | 2026-06-20 |
| TRF026 | A module whose forward only delegates to its single submodule adds nothing; inline it. | Enabled | 2026-06-20 |
| TRF027 | Model files must raise explicit errors instead of using bare assert. |
Enabled | 2026-06-20 |
| TRF028 | Model files must carry a complete license header. | Enabled | 2026-06-20 |
| TRF029 | A module taking config must not also take arguments that live on the config. |
Enabled | 2026-06-20 |
| TRF030 | Reaching more than two levels into the config means the module was handed the wrong config. | Enabled | 2026-06-20 |
| TRF031 | Output-like dataclasses in modeling files must inherit ModelOutput. | Enabled | 2026-06-20 |
| TRF032 | Masked positions must be filled with torch.finfo(dtype).min, not a magic negative number. | Enabled | 2026-06-20 |
| TRF033 | Hyperparameters must be set on the config, not mutated through a set_* method. | Enabled | 2026-06-20 |
| TRF034 | Layer classes held in an nn.ModuleList must subclass GradientCheckpointingLayer. | Enabled | 2026-06-20 |
| TRF035 | Model files must not silence the linter with # noqa. |
Enabled | 2026-06-20 |
| TRF036 | nn.Sequential hides the forward flow; declare the submodules explicitly. | Enabled | 2026-06-20 |
| TRF037 | torch.einsum is hard to read; prefer explicit matmul/transpose operations. | Disabled | 2026-06-20 |
| TRF038 | Every modeling-family source file needs a matching test file under tests/models/. | Enabled | All models |
| TRF039 | Imports guarded by is_*_available() must be removed once nothing in the file uses them. | Enabled | All models |
| TRF040 | @can_return_tuple must not be combined with @capture_outputs. | Enabled | All models |
| TRF041 | A config-gated branch must carry a # CODEPATH: note saying which checkpoints diverge. |
Enabled | 2026-06-20 |
| TRF042 | A tokenizer test must exercise the shared TokenizerTesterMixin suite. | Enabled | 2026-06-20 |
| TRF043 | Attention classes must not declare position_ids in their forward signature; it flows via **kwargs. | Enabled | All models |
| TRF044 | cache_position must not appear as a parameter in modeling code; it is removed framework surface. | Enabled | All models |
| TRF045 | forward must not declare output_attentions/output_hidden_states/return_dict; decorators own them. | Enabled | 2026-06-20 |
| TRF046 | forward must not write module attributes; modules are stateless in forward. | Enabled | All models |
| TRF047 | Image/video processors are stateless: preprocess/_preprocess/post_process_* must not write self attributes. | Enabled | All models |
| TRF048 | _tied_weights_keys must be a dict mapping target to source, not the pre-v5 list form. | Enabled | All models |
| TRF049 | Weight initialization belongs in _init_weights, never in __init__ (meta-device init discards it). | Enabled | All models |
| TRF050 | One rotary module per model: attention classes must not instantiate their own rotary embedding. | Enabled | All models |
| TRF051 | Modeling code must not branch on _attn_implementation; the attention interface owns dispatch. | Enabled | All models |
| TRF052 | No *_ATTENTION_CLASSES dispatch dicts; attention backends route through the attention interface. | Enabled | All models |
| TRF053 | No manual label shifting in modeling code; self.loss_function owns it. | Enabled | All models |
| TRF055 | PreTrainedModel config must be an annotation (config: SomeConfig) matched by __init__(config: SomeConfig); config_class is never used. |
Enabled | All models |
| TRF056 | forward() must not materialize tensors with .item() or .tolist(). | Enabled | 2026-06-20 |
| TRF057 | Public model, config, output and processor classes and their public methods must carry @auto_docstring. | Enabled | 2026-06-20 |
| TRF058 | Buffers must be declared as nn.Buffer attributes, not registered with register_buffer(). | Enabled | All models |
| TRF059 | Routed Experts modules tagged with moe_tp_experts must take hidden states, top-k indices and top-k weights in that order. |
Enabled | All models |
| TRF060 | Files in a model directory must import from transformers with relative imports, not from transformers.... |
Enabled | 2026-06-20 |
| TRF061 | A class in a modular_*.py file must not subclass another class defined in the same file: the generated modeling file keeps that inheritance. | Enabled | 2026-06-20 |
| TRF062 | _init_weights must initialize tensors with the transformers initialization module, not torch.nn.init. |
Enabled | All models |
| TRF063 | Model-local imports must not need backends beyond those the importing module’s exported objects declare. | Enabled | All models |
| TRF064 | <Model>ProcessorKwargs must not override _defaults, text_kwargs, images_kwargs, videos_kwargs or audio_kwargs. Set defaults as class attributes of the processor instead. |
Enabled | All models |
| TRF065 | Processors must not subclass ImagesKwargs, TextKwargs, AudioKwargs or VideosKwargs. Declare model-specific kwargs at the top level of <Model>ProcessorKwargs. |
Enabled | All models |
Removed rules
2 rules have been retired. They no longer run, they are not included in the count above, and their numbers are never reused. A leftover # trf-ignore comment naming one is harmless.
| Code | Why it was removed |
|---|---|
| TRF001 | Removed in 0.1.6: checked that config_class on <Model>PreTrainedModel was named <Model>Config. config_class is no longer written by hand; TRF055 now requires a config: <Model>Config annotation instead and flags any config_class. |
| TRF054 | Removed in 0.1.4: flagged self.<media>_token_id assignments in processor __init__, too noisy on legitimate processor code. |