Development workflow

A typical contribution lifecycle for transformers.

1. Fork, clone, install editable

git clone https://github.com/<you>/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git
pip install -e ".[dev]"

pip install -e ".[dev]" is heavy (it pulls every quantization, audio, and integration dependency). Most contributors prefer the slimmer pip install -e ".[torch,quality,testing]".

2. Branch from main

git fetch upstream
git checkout -b my-fix upstream/main

The default branch is main. PRs go to main; release branches (v5.7-release, etc.) are maintained by the release team.

3. Code

Follow the conventions in Patterns and conventions:

• For changes to a single model, edit the modeling_<name>.py directly unless there is a modular_<name>.py shard alongside. If a modular shard exists, edit the shard and let make fix-repo regenerate the modeling file.
• For cross-cutting changes (cache, attention, generation), edit the central file (src/transformers/cache_utils.py, src/transformers/modeling_utils.py, src/transformers/generation/utils.py).
• Never edit code inside a # Copied from ... block; either edit the source or break the link.

4. Run the auto-fixers

make fix-repo

What it does (chained from the Makefile):

ruff_check, ruff_format, init_isort, auto_mappings, sort_auto_mappings,
doc_toc, modeling_rules_doc, copies, modular_conversion, dummies,
pipeline_typing, doctest_list, docstrings, add_dates, deps_table

If you skip this, CI will fail on consistency checks. Commit any files the fixers modify.

5. Run targeted tests

# Tests for a specific model
pytest tests/models/<name>/

# Discover the tests touched by your branch
python utils/tests_fetcher.py

Most CPU-runnable tests should pass locally on a laptop. GPU-only tests are gated by @require_torch_gpu, @require_torch_multi_gpu, @require_flash_attn, etc. (see src/transformers/testing_utils.py). Slow tests require RUN_SLOW=1.

6. Open the PR

Push your branch and open a PR against huggingface/transformers:main. The PR description should include:

• A concise summary of the change.
• A link to the coordinating issue (if any).
• The exact commands you ran to verify the change (e.g., the pytest invocations).
• For agent-assisted PRs, the disclosures required by AGENTS.md (link to the issue, why this is not duplicate work, the test commands run, an explicit statement that AI assistance was used).

7. CI runs

CI consists of two layers:

• CircleCI (.circleci/config.yml) — fast PR checks: code quality, repo consistency, CPU tests, build docs, doctests for changed files.
• GitHub Actions self-hosted (.github/workflows/self-scheduled*.yml, model_jobs.yml) — GPU jobs and nightly runs (CUDA, AMD MI250/MI325/MI355, Intel Gaudi).

Repo-consistency failures usually mean you forgot to run make fix-repo. Re-run it, commit, push.

8. Review and merge

• Maintainers review and request changes.
• Squash-and-merge is the team's default merge strategy.
• After merge, the contributor closes any related issues.

Branching and releases

• main is the development branch. Stable releases are cut from vX.Y-release branches by the release engineer (see setup.py header for the procedure).
• Patch releases live on the same release branch.
• Tags are pushed to vX.Y.Z and PyPI uploads are triggered manually.

Local agent setup

If you run a local AI agent that consumes the in-tree skill assets:

make codex   # symlinks .ai/skills under .agents/
make claude  # symlinks .ai/skills under .claude/
make clean-ai

This wiring is documented in AGENTS.md and the Makefile targets codex, claude, clean-ai.