This page describes the tooling, build configuration, dependency management, test infrastructure, and CI/CD pipelines used to develop and maintain the transformers library. It covers how the package is built and distributed, how quality checks are enforced, how tests are organized and selected, and how continuous integration runs.
For information about the public Python package API and lazy import structure, see Package Structure and Build System. For details on specific test utilities and mixins used when writing model tests, see Testing Infrastructure. For the CI pipeline job orchestration in depth, see CI/CD Pipeline and Test Orchestration. For Docker image details, see Docker Images and CI Environments.
setup.pysetup.py is the central build file. It defines:
_deps, a list of versioned strings like "torch>=2.4" and "ruff==0.14.10".deps dict built from _deps for lookup by package name.extras dict grouping dependencies into named install groups.install_requires list — the minimal set needed to import transformers.DepsTableUpdateCommand, a custom distutils command invoked via python setup.py deps_table_update that regenerates src/transformers/dependency_versions_table.py.The SUPPORTED_PYTHON_VERSIONS constant at setup.py51 controls which Python minor versions get classifiers and the python_requires constraint.
Extras groups summary:
| Extra | Key contents |
|---|---|
torch | torch, accelerate |
vision | torchvision, Pillow |
audio | torchaudio, librosa, pyctcdecode, phonemizer |
video | av |
quality | datasets, ruff, GitPython, libcst, rich, ty |
testing | All quality + pytest suite + evaluate, nltk, sacrebleu, etc. |
deepspeed | deepspeed, accelerate |
serving | openai, pydantic, uvicorn, fastapi, starlette, rich + torch |
kernels | kernels |
sentencepiece | sentencepiece, protobuf |
dev | all + testing + ja + sklearn |
The entry_points key registers the transformers CLI command mapping to transformers.cli.transformers:main.
Sources: setup.py72-356
pyproject.tomlpyproject.toml hosts tool configuration that doesn't belong in setup.py:
[tool.ruff]: Sets target-version = "py310", line-length = 119. Enabled rule sets include E, F, I (isort), W, UP, FURB, SIM, and specific C4, PERF, PLC, PIE rules. E501 (line length) and E741 (ambiguous names) are explicitly ignored. __init__.py files ignore E402, F401, F403, F811.
[tool.ruff.lint.isort]: Sets lines-after-imports = 2 and known-first-party = ["transformers"].
[tool.pytest.ini_options]:
addopts = "--doctest-glob='**/*.md'" — all Markdown files are scanned for doctests by default.generate, is_training_test, flash_attn_test, flash_attn_3_test, bitsandbytes.log_cli = 1, log_cli_level = "WARNING".env = ["D:HF_HUB_DOWNLOAD_TIMEOUT=60"] — sets a 60-second Hub timeout in CI.[tool.ty]: Configures the ty type checker. Most rule categories are set to "ignore" to suppress false positives from optional dependencies and complex mixin patterns (pyproject.toml100-114).
Sources: pyproject.toml
src/transformers/dependency_versions_table.pyThis file is autogenerated — do not edit it directly. It contains a single deps dict mapping package names to their pinned specifiers. It is regenerated by:
python setup.py deps_table_update
or equivalently via make fix-repo. The CI check_repository_consistency job validates that this file matches what setup.py would generate by comparing MD5 checksums before and after running the command.
Sources: src/transformers/dependency_versions_table.py .circleci/config.yml196-199
Makefile provides the standard local developer commands.
Diagram: Makefile Targets and Their Actions
Sources: Makefile
Key targets:
| Target | Purpose |
|---|---|
make style | Apply all formatting fixes (ruff, import order, auto-mapping sort) |
make check-repo | Run all quality and consistency checks read-only, report failures |
make fix-repo | Apply all auto-fixable corrections, regenerate autogenerated files |
make test | Run full test suite with pytest-xdist parallelism |
make pre-release / make post-release | Run utils/release.py for version bump steps |
The CI system has two layers:
Diagram: CI Entry Points and Job Flow
Sources: .circleci/config.yml .circleci/create_circleci_config.py .github/workflows/doctests.yml utils/tests_fetcher.py1-83
The static jobs always run on every PR.
check_code_quality (runs on huggingface/transformers-quality image):
ruff check and ruff format --check across examples, tests, src, utils, scripts, benchmark.ty check src/transformers/utils/*.py — type checking with ty.python utils/custom_init_isort.py --check_only — validates __init__.py import order.python utils/sort_auto_mappings.py --check_only — validates auto-class mapping sort order.check_repository_consistency (runs on huggingface/transformers-consistency image):
python -c "from transformers import *".utils/check_copies.py — validates that files marked as copies of others are in sync.utils/check_modular_conversion.py — validates modular model files match their generated counterparts.utils/check_doc_toc.py, utils/check_docstrings.py, utils/check_dummies.py.utils/check_repo.py, utils/check_modeling_structure.py, utils/check_inits.py.utils/check_pipeline_typing.py, utils/check_config_docstrings.py, utils/check_config_attributes.py.utils/check_doctest_list.py, utils/update_metadata.py --check-only, utils/add_dates.py --check-only.dependency_versions_table.py against what setup.py deps_table_update would generate.Sources: .circleci/config.yml140-199
The fetch_tests job calls utils/tests_fetcher.py to determine which tests need to run for a given PR, then calls .circleci/create_circleci_config.py to produce a generated_config.yml file which is passed to the CircleCI continuation orb.
Diagram: tests_fetcher.py Logic
The CORE_FILES list (utils/tests_fetcher.py76-83) includes files like setup.py, src/transformers/modeling_utils.py, src/transformers/generation/utils.py, and .circleci/create_circleci_config.py — changes to these trigger the full test suite.
Key functions in utils/tests_fetcher.py:
| Function | Purpose |
|---|---|
get_modified_python_files() | Returns Python files changed since the branching point from main |
diff_is_docstring_only() | Returns True if a diff is only in docstrings or comments (uses clean_code()) |
extract_imports() | Parses relative and absolute imports from a module file |
get_module_dependencies() | Recursively resolves imports through __init__.py files |
create_reverse_dependency_map() | Builds a map from each file to everything that depends on it |
infer_tests_to_run() | Combines the above to produce a final list of test paths |
get_doctest_files() | Returns Markdown and Python files with changed doc examples |
get_all_doctest_files() | Returns the full set of doctested files excluding utils/not_doctested.txt |
Sources: utils/tests_fetcher.py60-540
.circleci/create_circleci_config.py defines each test job as a CircleCIJob dataclass instance and generates the generated_config.yml.
Diagram: CircleCIJob Structure and Job Registry
Job to Docker Image Mapping:
| Job name | Docker image | Marker |
|---|---|---|
torch_job | transformers-torch-light | not generate |
generate_job | transformers-torch-light | generate |
tokenization_job | transformers-torch-light | — |
processor_job | transformers-torch-light | — |
pipelines_torch_job | transformers-torch-light | is_pipeline_test |
custom_tokenizers_job | transformers-custom-tokenizers | — |
examples_torch_job | transformers-examples-torch | — |
hub_job | transformers-torch-light | is_staging_test |
exotic_models_job | transformers-exotic-models | — |
repo_utils_job | transformers-consistency | — |
non_model_job | transformers-torch-light | not generate |
training_ci_job | transformers-torch-light | is_training_test |
doc_test_job | transformers-consistency | doctest |
Each CircleCIJob.to_dict() method (.circleci/create_circleci_config.py132-224) generates a CircleCI job dict with steps covering:
uv pip install .).circleci tests split --split-by=timings.pytest with --reruns 5 for flaky test patterns.The COMMON_ENV_VARIABLES (.circleci/create_circleci_config.py25-33) set for all jobs include TRANSFORMERS_IS_CI=True, PYTEST_TIMEOUT=120, and DISABLE_SAFETENSORS_CONVERSION=True.
The FLAKY_TEST_FAILURE_PATTERNS list (.circleci/create_circleci_config.py40-55) controls which error strings trigger automatic reruns via pytest-rerunfailures.
Sources: .circleci/create_circleci_config.py
conftest.pyconftest.py is the top-level pytest configuration file. Its responsibilities:
src/ into sys.path so the local checkout is always used in tests, not the installed package.FutureWarning globally during tests.is_pipeline_test, is_staging_test, accelerate_tests, not_device_test, torch_compile_test, torch_export_test, flash_attn_test, flash_attn_3_test, training_ci.NOT_DEVICE_TESTS: A set of test name substrings identifying tests that should always run on CPU (e.g., tokenization, processing, configuration, optimization). Items in this set are automatically tagged not_device_test (conftest.py37-72)._pytest.doctest.DoctestModule with HfDoctestModule and doctest.DocTestParser with HfDocTestParser (from transformers.testing_utils). Registers a custom IGNORE_RESULT doctest optionflag.pytest_terminal_summary calls pytest_terminal_summary_main to write per-job report files when --make-reports=<name> is passed.enable_tf32(False) in CI to ensure deterministic CUDA behavior.patch_torch_compile_force_graph() to support TORCH_COMPILE_FORCE_FULLGRAPH=1.Sources: conftest.py
The library tracks which files are not yet covered by doctests in utils/not_doctested.txt. Files listed there are excluded from doctest runs. To add doctest coverage to a file, remove it from not_doctested.txt and ensure examples in the file are syntactically runnable.
Slow doctest examples that should not run on CircleCI are tracked in utils/slow_documentation_tests.txt.
The GitHub Actions workflow .github/workflows/doctests.yml runs the full doctest suite nightly (and on branches matching run_doctest*) on GPU runners, using utils/split_doctest_jobs.py to split files across multiple parallel jobs. Results are reported to Slack via utils/notification_service_doc_tests.py.
Sources: utils/not_doctested.txt1-10 .github/workflows/doctests.yml .github/workflows/doctest_job.yml
The release workflow follows these steps (documented in setup.py20-40):
v<VERSION>-release.make pre-release (or make pre-patch for patch releases) and commit with message "Release: <VERSION>".main and run make post-release then make fix-repo, commit with "v<NEXT_VERSION>.dev0".git tag v<VERSION>.The build-release Makefile target uses python setup.py bdist_wheel and python setup.py sdist to build distribution artifacts.
Sources: setup.py20-40 Makefile82-98
Diagram: Dependency Definition and Propagation
The hard runtime dependencies declared in install_requires are:
huggingface-hub>=1.3.0,<2.0numpy>=1.17packaging>=20.0pyyaml>=5.1regex!=2019.12.17tokenizers>=0.22.0,<=0.23.0typersafetensors>=0.4.3tqdm>=4.27Sources: setup.py262-273 src/transformers/dependency_versions_table.py
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.