When do PEP 735 dependency groups replace optional-dependencies extras in a project?

## Two tables that look alike and are not A `pyproject.toml` can name optional requirements in two places, and the distinction is about **audience**, not syntax. The **optional-dependencies** table under `[project]` defines *extras*. It is PEP 621 metadata, so it is baked into the built distribution: a consumer installs your project and names the extra to pull the feature in. Extras are a public API. Rename one and you break somebody's install line. **Dependency groups** come from PEP 735 and live in a top-level `[dependency-groups]` table. Each key is a group name and each value is a list of requirement strings, plus optionally an `include-group` inline table that pulls another group in wholesale. Groups are *not* part of the distribution's metadata. They are never published, a consumer cannot install one, and they exist purely for people working in the repository. ## Why extras were the wrong tool for dev dependencies Before PEP 735, the community convention was a `dev` or `test` extra, and it had four real problems. **It leaks.** The extra is in the published metadata for everyone to see and install, and it becomes part of your compatibility surface even though it is an internal detail. **It requires the project to be a distribution.** Installing an extra means installing your project, which means your project must be buildable and installable. A repository that is a service, a set of scripts or a monorepo leaf with no distribution to build cannot express its tooling as an extra at all. **It cannot say "not for consumers".** There is no way to mark an extra as private, so tooling that audits published metadata cannot tell a real optional feature from a development bucket. **Composition is awkward.** Making a `dev` extra include a `test` extra requires the project to depend on itself with an extra — a self-referential requirement that works but reads like a trick. Dependency groups answer all four: not published, no project required, obviously internal, and composed with a first-class `include-group`. ## Choosing between them The test is a single question: **could an installer of your distribution ever want this?** - A feature that needs an extra library — an optional metrics exporter, an optional async backend, an optional compression codec — is an **extra**. The consumer opts in. - A test runner, a type checker, a formatter, a docs builder, a benchmark harness, a release script — nobody installing your package wants these. They are **groups**. Applications blur the line less than you would think. An application publishes nothing, so it has no consumers and therefore essentially no legitimate extras; everything optional in an application repository is a group. ## What the tooling does with them All-in-one project managers read `[dependency-groups]` natively and typically install a default group into the project environment on sync, so a fresh checkout comes up with the test tooling already present. pip added support for installing a named group directly in its 25.1 release. Because the table is a standard rather than one tool's invention, moving a repository between managers keeps the groups intact — which is the same portability argument that makes the `[project]` table valuable. One subtlety: a group's contents are still *abstract* requirements, exactly like `dependencies`. Groups describe what the repository needs, not which versions were chosen. The chosen versions live in the lock file, and a manager's lock normally records the groups separately so it can install production dependencies only, or production plus one group, from the same lock. ## Migration in practice Moving an existing project is mechanical: delete the `dev` and `test` extras, add the same requirement lists as groups, and replace the self-referential extra chain with `include-group` entries. The one thing to check is anything outside the repository that installed your dev extra — a CI job, a downstream image, a contributor's script. Because extras are published metadata, removing one is a visible change; because groups are not, adding them is not. That asymmetry is the whole point, and it is worth saying out loud in an interview: extras are a contract with your users, groups are a note to yourself.