Tooling

What runs when you type make fix-repo, what each utils/check_*.py script does, and how CI is wired.

The Makefile

Makefile is short. Key targets:

Target	Calls
style	python utils/checkers.py ruff_check,ruff_format,init_isort,sort_auto_mappings --fix
typing	python utils/checkers.py types,modeling_structure
check-code-quality	typing + style checks (no auto-fix)
check-repository-consistency	All the consistency checks (copies, modular, doc TOC, docstrings, dummies, repo, inits, …)
check-repo	Quality + repo consistency, all read-only, with --keep-going
fix-repo	All the auto-fixers, with --fix --keep-going
test	python -m pytest -p random_order -n auto --dist=loadfile -s -v --random-order-bucket=module ./tests/
test-examples	Same against ./examples/pytorch/
benchmark	Generation throughput sweep via benchmark/benchmark.py
codex, claude, clean-ai	Wire .ai/skills into the local agent's expected directory
pre-release, pre-patch, post-release, post-patch, build-release	Release engineer workflow

The checker orchestrator

utils/checkers.py (22K LOC) is a thin harness that runs each named check in subprocesses and aggregates the exit codes. Check names map to specific scripts:

Check name	Script	Purpose
ruff_check, ruff_format	ruff	Lint + format
init_isort	utils/custom_init_isort.py	Sort imports inside __init__.py files
auto_mappings, sort_auto_mappings	utils/check_auto.py, utils/sort_auto_mappings.py	Auto-class registries are correct & sorted
imports, import_complexity	utils/check_inits.py, utils/check_import_complexity.py	Lazy import structure is consistent
copies	utils/check_copies.py (46K LOC)	Sync # Copied from blocks
modular_conversion	utils/check_modular_conversion.py	Re-expand modular_*.py and confirm output matches
doc_toc	utils/check_doc_toc.py	docs/source/en/_toctree.yml is consistent
modeling_rules_doc	utils/check_modeling_rules_doc.py	Rules documented in docs/source/en/modeling_rules.md
docstrings	utils/check_docstrings.py (90K LOC)	Auto-docstring contracts are honoured
dummies	utils/check_dummies.py	Dummy-object stubs in utils/dummy_*.py are up to date
repo	utils/check_repo.py (66K LOC)	Many repo-wide invariants (every model has tests, every model is exported in __init__.py, …)
inits	utils/check_inits.py	__init__.py exports match definitions
pipeline_typing	utils/check_pipeline_typing.py	Pipeline typing is consistent
config_docstrings, config_attributes	utils/check_config_docstrings.py, utils/check_config_attributes.py	Config classes documented
doctest_list	utils/check_doctest_list.py	Doctest opt-out list is consistent
update_metadata	utils/update_metadata.py	Metadata for the website / Hub
add_dates	utils/add_dates.py	Stamps "since" dates in docs
deps_table	regenerates src/transformers/dependency_versions_table.py from setup.py
types, modeling_structure	utils/check_modeling_structure.py	ty type checker + structural rules

The full surface is intentionally broad: passing CI is essentially equivalent to passing make check-repo locally.

Ruff and ty

pyproject.toml configures both:

• [tool.ruff] — target-version = "py310", line-length = 119, mccabe.max-complexity = 75. Rule selection includes pycodestyle, Pyflakes, isort, pyupgrade, refurb, comprehensions, and a curated subset of bandit/perf rules.
• [tool.ty] — the ty type checker is configured to ignore many false-positives the team has accepted (parameter renames, tensor slicing, optional dependency import errors, and so on).

tests_fetcher

utils/tests_fetcher.py (52K LOC) walks the import graph from changed files to compute the minimal set of test files that should be run for a branch. CI consumes its test_list.txt output; you can run it locally to scope your test runs.

CircleCI

.circleci/config.yml defines fast PR checks:

• check_code_quality — make check-code-quality.
• check_repository_consistency — make check-repository-consistency.
• tests_torch, tests_torch_and_tf, tests_pipelines_torch — CPU pytest jobs.
• tests_hub, tests_doctests, tests_examples.
• tests_torch_compile_models, tests_torch_export_models.

The orchestration script .circleci/create_circleci_config.py programmatically builds the config based on the changed files (so a tokenizer-only PR doesn't run modeling tests).

GitHub Actions (self-hosted)

.github/workflows/ has 50+ workflows. Highlights:

• model_jobs.yml, model_jobs_intel_gaudi.yml — per-model GPU tests.
• self-scheduled-caller.yml and friends — nightly NVIDIA tests.
• self-scheduled-amd-mi250-caller.yml, …-mi325-…, …-mi355-… — AMD GPUs.
• self-scheduled-intel-gaudi*.yml — Intel Gaudi 2/3.
• self-scheduled-flash-attn-caller.yml — FlashAttention regressions.
• benchmark.yml, benchmark_v2.yml, benchmark_v2_a10_caller.yml, benchmark_v2_mi325_caller.yml — perf tracking.
• extras-smoke-test.yml — install matrix for pip install transformers[<extra>].
• build-docker-images.yml, build-ci-docker-images.yml, build-nightly-ci-docker-images.yml — image builds; Dockerfiles in docker/.
• pr-repo-consistency-bot.yml — comments on PRs that fail consistency checks.
• assign-reviewers.yml — auto-assigns based on touched files.
• trufflehog.yml — secret scanner.
• codeql.yml — security analysis.
• release.yml, release-conda.yml — packaging.

Notification routing (Slack) is in utils/notification_service.py (67K LOC).

Docker images

docker/ contains Dockerfiles for CI and developer environments. Examples:

• transformers-pytorch-gpu/ — main GPU CI image.
• transformers-pytorch-amd-gpu/, transformers-pytorch-intel-gaudi-gpu/.
• transformers-quantization-latest-gpu/.
• transformers-pytorch-deepspeed-latest-gpu/.
• transformers-pytorch-tpu/.

The image catalogue is rebuilt by build-docker-images.yml and build-ci-docker-images.yml.

Release engineering

The release workflow is documented at the top of setup.py. Key steps:

1. Cut a release branch vX.Y-release from main.
2. make pre-release (or make pre-patch) — bumps versions and pins.
3. Tag and push, then have a maintainer approve the PyPI deployment.
4. make post-release (or make post-patch) on main — bumps to X.(Y+1).0.dev0.
5. make fix-repo after each version bump.