Merge pull request #2087 from Trenza1ore/main

Document self-referential extras now that pip officially supports it

Author: webknjaz

source/guides/writing-pyproject-toml.rst

@@ -175,6 +175,33 @@ Each of the keys defines a "packaging extra". In the example above, one
 could use, e.g., ``pip install your-project-name[gui]`` to install your
 project with GUI support, adding the PyQt5 dependency.
 
+.. _self-referential-extras:
+
+You can also define an extra that refers back to the current project with
+other extras. This is useful for convenience extras that combine several
+optional features (such as an ``all`` extra hosting dependencies from both
+``gui`` and ``cli``):
+
+.. code-block:: toml
+
+    all = ["your-project-name[gui, cli]"]
+
+The combined extra does not need its own manually maintained copy of each
+referenced extra's dependencies, which can otherwise fall out of sync after
+a few years of maintenance and bug fixes:
+
+.. code-block:: toml
+
+    gui = ["PyQt5"]
+    cli = [
+      "rich>=14.2",   # version range is added after last "all" extra update
+      "textual",      # dependency newly added since last "all" extra update
+      "click",
+    ]
+    all = ["PyQt5", "rich", "click"]
+
+Most package managers now support this kind of extra, including
+:ref:`pip`, :ref:`uv`, :ref:`poetry`, :ref:`hatch`, :ref:`pdm` and :ref:`pipenv`.
 
 .. _requires-python:
 .. _python_requires:
@@ -555,6 +582,7 @@ A full example
      "rich",
      "click",
    ]
+   all = ["spam-eggs[gui, cli]"]
 
    [project.urls]
    Homepage = "https://example.com"

source/specifications/pyproject-toml.rst

@@ -505,6 +505,11 @@ marker clause on the related ``Requires-Dist`` entries to check the extra name.
 Optional dependencies are thus only considered for installation if installation
 if the associated extra name is requested.
 
+Dependency specifiers in an extra may self-reference other extras from the
+current project (e.g. ``all = ["your-project-name[gui, cli]"]``). See
+:ref:`self-referential extras <self-referential-extras>` for an example.
+Most package managers now support this kind of extra, including
+:ref:`pip`, :ref:`uv`, :ref:`poetry`, :ref:`hatch`, :ref:`pdm` and :ref:`pipenv`.
 
 .. _pyproject-toml-import-names:
 
@@ -714,4 +719,7 @@ History
   as listed in ``dynamic``, with build back-ends only able to append
   entries, through :pep:`808`.
 
+- August 2026: Document self-referential extra as a supported feature by many
+  modern package managers of Python.
+
 .. _TOML: https://toml.io