CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 771 – Default Extras for Python Software Packages | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0771/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 771 – Default Extras for Python Software Packages | peps.python.org'> <meta property="og:description" content="PEP 508 specifies a mini-language for declaring package dependencies. One feature of this language is the ability to specify extras, which are optional components of a distribution that, when used, install additional dependencies. This PEP proposes a me..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0771/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="PEP 508 specifies a mini-language for declaring package dependencies. One feature of this language is the ability to specify extras, which are optional components of a distribution that, when used, install additional dependencies. This PEP proposes a me..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 771</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 771 – Default Extras for Python Software Packages</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Thomas Robitaille <thomas.robitaille at gmail.com>, Jonathan Dekhtiar <jonathan at dekhtiar.com></dd> <dt class="field-even">Sponsor<span class="colon">:</span></dt> <dd class="field-even">Pradyun Gedam <pradyunsg at gmail.com></dd> <dt class="field-odd">Discussions-To<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/79706/">Discourse thread</a></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Proposal under active discussion and revision">Draft</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Created<span class="colon">:</span></dt> <dd class="field-odd">13-Jan-2025</dd> <dt class="field-even">Post-History<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/77892/" title="Discourse thread">15-Jan-2025</a>, <a class="reference external" href="https://discuss.python.org/t/79706/" title="Discourse thread">06-Feb-2025</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#recommended-but-not-required-dependencies">Recommended but not required dependencies</a></li> <li><a class="reference internal" href="#packages-supporting-multiple-backends-or-frontends">Packages supporting multiple backends or frontends</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#default-extra-metadata-field"><code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> Metadata Field</a></li> <li><a class="reference internal" href="#new-key-in-project-metadata-table">New key in <code class="docutils literal notranslate"><span class="pre">[project]</span></code> metadata table</a></li> <li><a class="reference internal" href="#overriding-default-extras">Overriding default extras</a></li> <li><a class="reference internal" href="#installing-without-default-extras">Installing without default extras</a></li> <li><a class="reference internal" href="#examples">Examples</a><ul> <li><a class="reference internal" href="#recommended-dependencies-and-minimal-installations">Recommended dependencies and minimal installations</a></li> <li><a class="reference internal" href="#packages-requiring-at-least-one-backend-or-frontend">Packages requiring at least one backend or frontend</a></li> <li><a class="reference internal" href="#supporting-minimal-installations-while-not-always-removing-default-extras">Supporting minimal installations while not always removing default extras</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#backward-compatibility">Backward Compatibility</a><ul> <li><a class="reference internal" href="#packages-not-using-default-extras">Packages not using default extras</a></li> <li><a class="reference internal" href="#packages-using-default-extras">Packages using default extras</a></li> <li><a class="reference internal" href="#packaging-related-tools">Packaging-related tools</a></li> </ul> </li> <li><a class="reference internal" href="#security-implications">Security Implications</a></li> <li><a class="reference internal" href="#how-to-teach-this">How to teach this</a><ul> <li><a class="reference internal" href="#package-end-users">Package end users</a></li> <li><a class="reference internal" href="#package-authors">Package authors</a><ul> <li><a class="reference internal" href="#supporting-older-versions-of-package-installers">Supporting older versions of package installers</a></li> <li><a class="reference internal" href="#avoiding-the-addition-of-many-default-dependencies">Avoiding the addition of many default dependencies</a></li> <li><a class="reference internal" href="#inheriting-from-default-extras">Inheriting from default extras</a></li> <li><a class="reference internal" href="#incompatible-extras">Incompatible extras</a></li> <li><a class="reference internal" href="#circular-dependencies">Circular dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#packaging-repository-maintainers">Packaging repository maintainers</a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#syntax-for-deselecting-extras">Syntax for deselecting extras</a></li> <li><a class="reference internal" href="#adding-a-special-entry-in-extras-require">Adding a special entry in <code class="docutils literal notranslate"><span class="pre">extras_require</span></code></a></li> <li><a class="reference internal" href="#relying-on-tooling-to-deselect-any-default-extras">Relying on tooling to deselect any default extras</a></li> <li><a class="reference internal" href="#package-disables-default-extras"><code class="docutils literal notranslate"><span class="pre">package[]</span></code> disables default extras</a></li> </ul> </li> <li><a class="reference internal" href="#open-issues">Open issues</a><ul> <li><a class="reference internal" href="#should-package-disable-default-extras">Should <code class="docutils literal notranslate"><span class="pre">package[]</span></code> disable default extras?</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p><a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> specifies a mini-language for declaring package dependencies. One feature of this language is the ability to specify <em>extras</em>, which are optional components of a distribution that, when used, install additional dependencies. This PEP proposes a mechanism to allow one or more extras to be installed by default if none are provided explicitly.</p> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <p>Various use cases for default extras and possible solutions in this PEP were discussed extensively on <a class="reference external" href="https://discuss.python.org/t/adding-a-default-extra-require-environment/4898">this DPO thread</a>. These fall into two broad cases that that provide the motivation for the present PEP.</p> <section id="recommended-but-not-required-dependencies"> <h3><a class="toc-backref" href="#recommended-but-not-required-dependencies" role="doc-backlink">Recommended but not required dependencies</a></h3> <p>Package maintainers often use extras to declare optional dependencies that extend the functionality or performance of a package. In some cases, it can be difficult to determine which dependencies should be required and which should be categorized as extras. A balance must be struck between the needs of typical users (who may prefer most features to be available ‘by default’) and users who want minimal installations without large, optional dependencies. One solution with existing Python packaging infrastructure is for package maintainers to define an extra called, for example, <code class="docutils literal notranslate"><span class="pre">recommended</span></code>, which includes all non-essential but suggested dependencies. Users are then instructed to install the package using <code class="docutils literal notranslate"><span class="pre">package[recommended]</span></code>, while those who prefer more control can use <code class="docutils literal notranslate"><span class="pre">package</span></code>. However, in practice, many users are unaware of the <code class="docutils literal notranslate"><span class="pre">[recommended]</span></code> syntax, placing the burden on them to know this for a typical installation. Having a way to have recommended dependencies be installed by default while providing a way for users to request a more minimal installation would satisfy this use case, and this PEP describes a solution to this.</p> <p>Examples of packages that demonstrate this pattern by encouraging users to include extra dependencies by default include:</p> <ul class="simple"> <li><a class="reference external" href="https://www.astropy.org/">astropy</a>: <code class="docutils literal notranslate"><span class="pre">astropy[recommended]</span></code></li> <li><a class="reference external" href="https://fastapi.tiangolo.com/">fastapi</a>: <code class="docutils literal notranslate"><span class="pre">fastapi[standard]</span></code></li> <li><a class="reference external" href="https://www.tensorflow.org">tensorflow</a>: <code class="docutils literal notranslate"><span class="pre">tensorflow[and-cuda]</span></code></li> </ul> </section> <section id="packages-supporting-multiple-backends-or-frontends"> <h3><a class="toc-backref" href="#packages-supporting-multiple-backends-or-frontends" role="doc-backlink">Packages supporting multiple backends or frontends</a></h3> <p>Another common use case for using extras is to define different backends or frontends and dependencies that need to be installed for each backend or frontend. A package might need at least one backend or frontend to be installed in order to be functional, but may be flexible on which backend or frontend this is. Concrete examples of such frontends or backends include:</p> <ul class="simple"> <li>The Qt frontend library, which can be provided by <a class="reference external" href="https://pypi.org/project/PyQt5/">PyQt5</a>, <a class="reference external" href="https://pypi.org/project/PyQt6/">PyQt6</a>, <a class="reference external" href="https://pypi.org/project/PySide2/">PySide2</a>, or <a class="reference external" href="https://pypi.org/project/PySide6/">PySide6</a></li> <li>BLAS/LAPACK, which have different possible implementations (e.g. OpenBLAS, and MKL)</li> <li>FFT libraries, which also have different implementations (e.g. <code class="docutils literal notranslate"><span class="pre">scipy.fft</span></code> and pyFFTW)</li> </ul> <p>With current packaging standards, maintainers have to either require one of the backends or frontends, or require users to always specify extras, e.g. <code class="docutils literal notranslate"><span class="pre">package[backend]</span></code> and therefore risk users having an unusable installation if they only install <code class="docutils literal notranslate"><span class="pre">package</span></code>. Having a way to specify one or more default backend or frontend and providing a way to override these defaults would provide a much better experience for users, and the approach described in this PEP will allow this.</p> <p>Note that this PEP does not aim to address the issue of disallowing conflicting or incompatible extras - for example if a package requires exactly one frontend or backend package. There is currently no mechanism in Python packaging infrastructure to disallow conflicting or incompatible extras to be installed, and this PEP does not change that.</p> <p>Examples of packages that require at least one backend or frontend to work and recommend a default extra to install a backend or frontend include:</p> <ul class="simple"> <li><a class="reference external" href="https://kivy.org/">kivy</a>: <code class="docutils literal notranslate"><span class="pre">kivy[base]</span></code></li> <li><a class="reference external" href="https://napari.org">napari</a>: <code class="docutils literal notranslate"><span class="pre">napari[all]</span></code></li> <li><a class="reference external" href="https://www.glueviz.org">glueviz</a>: <code class="docutils literal notranslate"><span class="pre">glueviz[qt]</span></code></li> </ul> <p>In all three cases, installing the package without any extras results in a broken installation (and this is a commonly reported issue for some of these packages).</p> </section> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p>A number of possible solutions have been extensively and vigorously discussed by the community for several years, including in <a class="reference external" href="https://discuss.python.org/t/adding-a-default-extra-require-environment/4898">this DPO thread</a> as well as in numerous issues and pull requests. The solution that is presented below:</p> <ul class="simple"> <li>is an opt-in solution which means that package maintainers can choose whether or not to use it</li> <li>is flexible enough to accommodate both of the major use cases described in <a class="reference internal" href="#motivation">Motivation</a></li> <li>re-uses the syntax from <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a></li> </ul> <p>It is the only solution out of all those discussed that meets all three criteria.</p> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="default-extra-metadata-field"> <h3><a class="toc-backref" href="#default-extra-metadata-field" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> Metadata Field</a></h3> <p>A new multiple-use metadata field, <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code>, will be added to the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata">core package metadata</a>. For this field, each entry must be a string specifying an extra that will be automatically included when the package is installed without any extras specified explicitly.</p> <p>Only entries already specified in a <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#provides-extra-multiple-use">Provides-Extra</a> entry can be used in a <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> entry.</p> <p>Examples:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Default</span><span class="o">-</span><span class="n">Extra</span><span class="p">:</span> <span class="n">recommended</span> <span class="n">Default</span><span class="o">-</span><span class="n">Extra</span><span class="p">:</span> <span class="n">backend1</span> <span class="n">Default</span><span class="o">-</span><span class="n">Extra</span><span class="p">:</span> <span class="n">backend2</span> <span class="n">Default</span><span class="o">-</span><span class="n">Extra</span><span class="p">:</span> <span class="n">backend3</span> </pre></div> </div> <p>Since this introduces a new field in the core package metadata, this will require <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#metadata-version">Metadata-Version</a> to be bumped to the next minor version (2.5 at the time of writing).</p> </section> <section id="new-key-in-project-metadata-table"> <h3><a class="toc-backref" href="#new-key-in-project-metadata-table" role="doc-backlink">New key in <code class="docutils literal notranslate"><span class="pre">[project]</span></code> metadata table</a></h3> <p>A new key will be added to the <code class="docutils literal notranslate"><span class="pre">[project]</span></code> table in project metadata as originally defined in <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a> and now defined in the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/pyproject-toml/">PyPA specifications</a>. This key will be named <code class="docutils literal notranslate"><span class="pre">default-optional-dependency-keys</span></code> with the following description:</p> <ul class="simple"> <li><a class="reference external" href="https://toml.io/">TOML</a> type: Array of strings</li> <li>Corresponding core metadata field: <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code></li> </ul> <p>Each string in <code class="docutils literal notranslate"><span class="pre">default-optional-dependency-keys</span></code> must be the name of an extra defined in <a class="reference external" href="https://packaging.python.org/en/latest/specifications/pyproject-toml/#dependencies-optional-dependencies">optional-dependencies</a>, and each extra in this array will be converted to a matching <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> entry in the core package metadata. Examples of valid usage which would produce the example <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> entries presented in the previous section are:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"recommended"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> <p>and:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"backend1"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"backend2"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"backend3"</span> <span class="p">]</span> </pre></div> </div> </section> <section id="overriding-default-extras"> <h3><a class="toc-backref" href="#overriding-default-extras" role="doc-backlink">Overriding default extras</a></h3> <p>If extras are explicitly given in a dependency specification, the default extras are ignored. Otherwise, the default extras are installed.</p> <p>For example, if a package defines an <code class="docutils literal notranslate"><span class="pre">extra1</span></code> default extra as well as a non-default <code class="docutils literal notranslate"><span class="pre">extra2</span></code> extra, then if a user were to install the package with:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package </pre></div> </div> <p>the default <code class="docutils literal notranslate"><span class="pre">extra1</span></code> dependency would be included. If the user instead installs the package with:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package<span class="o">[</span>extra2<span class="o">]</span> </pre></div> </div> <p>then the <code class="docutils literal notranslate"><span class="pre">extra2</span></code> extra would be installed but the default <code class="docutils literal notranslate"><span class="pre">extra1</span></code> extra would be ignored.</p> <p>If the same package is specified multiple times in an installation command or dependency tree, the default extras must be installed if any of the instances of the package are specified without extras. For instance, if one installs a package <code class="docutils literal notranslate"><span class="pre">spam</span></code> where <code class="docutils literal notranslate"><span class="pre">package</span></code> appears several times in the dependency tree:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>spam ├── tomato │ ├── package[extra2] └── egg └── package </pre></div> </div> <p>then the default extra should be installed because <code class="docutils literal notranslate"><span class="pre">package</span></code> appears at least once with no extras specified.</p> <p>Note that <code class="docutils literal notranslate"><span class="pre">package[]</span></code> would continue to be equivalent to <code class="docutils literal notranslate"><span class="pre">package</span></code> and would not be provided as a way to install without default extras (see the <a class="reference internal" href="#rejected-ideas">Rejected Ideas</a> section for the rationale).</p> <p>We also note that some tools such as <a class="reference external" href="https://github.com/wheel-next/pip/tree/pep_771">pip</a> currently ignore unrecognized extras, and emit a warning to the user to indicate that the extra has not been recognized, e.g:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package<span class="o">[</span>non-existent-extra<span class="o">]</span> <span class="go">WARNING: package 3.0.0 does not provide the extra 'non-existent-extra'</span> <span class="go">...</span> </pre></div> </div> <p>For tools that behave like this (rather than raising an error), if an extra is recognized as invalid in a dependency specification, it should be ignored and treated as if the user has not passed an explicit extra. If none of the provided extras are valid, default extras should be installed.</p> </section> <section id="installing-without-default-extras"> <h3><a class="toc-backref" href="#installing-without-default-extras" role="doc-backlink">Installing without default extras</a></h3> <p>In some cases, package maintainers may want to facilitate installing packages without any default extras. In this case, as will be shown in more detail in <a class="reference internal" href="#examples">Examples</a>, the best approach is to define an extra which could be called e.g. <code class="docutils literal notranslate"><span class="pre">minimal</span></code> or <code class="docutils literal notranslate"><span class="pre">nodefault</span></code> (the naming would be up to the package maintainer) which would be an empty set of dependencies. If this extra is specified, no default extras will be included, so that e.g. <code class="docutils literal notranslate"><span class="pre">package[minimal]</span></code> would include only required dependencies and no extras. Note that this requires no additional specification and is a natural consequence of the rule described in <a class="reference internal" href="#overriding-default-extras">Overriding default extras</a>.</p> <p>There are however valid use cases where package maintainers may not want to provide this. For example, in the case of the multiple possible frontends or backends, it may be that the package would not be functional without any of the options. To take a specific example, a package may need either PyQt or PySide to be installed but will not work if none are provided, so a package maintainer may therefore not want to provide an option to install the package without any extras.</p> </section> <section id="examples"> <h3><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h3> <p>In this section we take a look at the use cases described in the <a class="reference internal" href="#motivation">Motivation</a> section and how these can now be addressed by using the specification outlined above.</p> <section id="recommended-dependencies-and-minimal-installations"> <h4><a class="toc-backref" href="#recommended-dependencies-and-minimal-installations" role="doc-backlink">Recommended dependencies and minimal installations</a></h4> <p>First, we consider the case of packages that want recommended but not strictly required dependencies installed by default, while also providing a way to only install the required dependencies.</p> <p>In order to do this, a package maintainer would define an extra called <code class="docutils literal notranslate"><span class="pre">recommended</span></code> containing the recommended but not required dependencies, and would choose to have this be included as a default extra:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"recommended"</span> <span class="p">]</span> <span class="k">[project.optional-dependencies]</span> <span class="n">recommended</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"package1"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"package2"</span> <span class="p">]</span> </pre></div> </div> <p>In this specific case, a package maintainer may want to allow users to also install the package without the recommended dependencies, in which case they could define an empty extra:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project.optional-dependencies]</span> <span class="n">minimal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[]</span> <span class="n">recommended</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"package1"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"package2"</span> <span class="p">]</span> </pre></div> </div> <p>This would then allow users to install <code class="docutils literal notranslate"><span class="pre">package[minimal]</span></code> which, since there would be an extra explicitly specified, would mean the default extra does not get installed, and since the <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extra is empty, no additional dependencies would be installed.</p> <p>Maintainers would have the choice as to whether to offer the capability to do a minimal installation or not - in some cases, such as highlighted in the next section, this might not be desirable.</p> <p>To take a one of the concrete examples of package from the <a class="reference internal" href="#motivation">Motivation</a> section, the <a class="reference external" href="https://www.astropy.org/">astropy</a> package defines a <code class="docutils literal notranslate"><span class="pre">recommended</span></code> extra that users are currently instructed to install in the default installation instructions. With this PEP, the <code class="docutils literal notranslate"><span class="pre">recommended</span></code> extra could be declared as being a default extra, and a new <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extra could be provided for users wishing to retain the ability to install only the strictly required dependencies:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"recommended"</span> <span class="p">]</span> <span class="k">[project.optional-dependencies]</span> <span class="n">minimal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[]</span> <span class="n">recommended</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"scipy"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> </pre></div> </div> <p>meaning that installing:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>astropy </pre></div> </div> <p>would then also install optional but important optional dependencies such as <a class="reference external" href="https://www.scipy.org">scipy</a>. Advanced users who want a minimal install could then use:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>astropy<span class="o">[</span>minimal<span class="o">]</span> </pre></div> </div> </section> <section id="packages-requiring-at-least-one-backend-or-frontend"> <h4><a class="toc-backref" href="#packages-requiring-at-least-one-backend-or-frontend" role="doc-backlink">Packages requiring at least one backend or frontend</a></h4> <p>As described in <a class="reference internal" href="#motivation">Motivation</a>, some packages may support multiple backends and/or frontends, and in some cases it may be desirable to ensure that there is always at least one backend or frontend package installed, as the package would be unusable otherwise. Concrete examples of this might include a GUI application that needs a GUI library to be present to be usable but is able to support different ones, or a package that can rely on different computational backends but needs at least one to be installed.</p> <p>In this case, package maintainers could make the choice to define an extra for each backend or frontend, and provide a default, e.g.:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"backend1"</span> <span class="p">]</span> <span class="k">[project.optional-dependencies]</span> <span class="n">backend1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"package1"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"package2"</span> <span class="p">]</span> <span class="n">backend2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"package3"</span> <span class="p">]</span> </pre></div> </div> <p>Unlike the previous example however, maintainers would not necessarily provide a way to do an installation without any extras since it might leave the package in an unusable state.</p> <p>If packages can support e.g. multiple backends at the same time, and some of the backends should always be installed, then the dependencies for these must be given as required dependencies rather than using the default extras mechanism.</p> <p>To take one of the concrete examples mentioned in <a class="reference internal" href="#motivation">Motivation</a>, the <a class="reference external" href="https://napari.org">napari</a> package can make use of one of <a class="reference external" href="https://pypi.org/project/PyQt5/">PyQt5</a>, <a class="reference external" href="https://pypi.org/project/PyQt6/">PyQt6</a>, <a class="reference external" href="https://pypi.org/project/PySide2/">PySide2</a>, or <a class="reference external" href="https://pypi.org/project/PySide6/">PySide6</a>, and users currently need to explicitly specify <code class="docutils literal notranslate"><span class="pre">napari[all]</span></code> in order to have one of these be installed, or e.g., <code class="docutils literal notranslate"><span class="pre">napari[pyqt5]</span></code> to explicitly specify one of the frontend packages. Installing <code class="docutils literal notranslate"><span class="pre">napari</span></code> with no extras results in a non-functional package. With this PEP, <code class="docutils literal notranslate"><span class="pre">napari</span></code> could define the following configuration:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pyqt5"</span> <span class="p">]</span> <span class="k">[project.optional-dependencies]</span> <span class="n">pyqt5</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"PyQt5"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> <span class="n">pyside2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"PySide2"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> <span class="n">pyqt6</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"PyQt6"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> <span class="n">pyside6</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"PySide6"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> </pre></div> </div> <p>meaning that:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>napari </pre></div> </div> <p>would work out-of-the-box, but there would still be a mechanism for users to explicitly specify a frontend, e.g.:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>napari<span class="o">[</span>pyside6<span class="o">]</span> </pre></div> </div> </section> <section id="supporting-minimal-installations-while-not-always-removing-default-extras"> <h4><a class="toc-backref" href="#supporting-minimal-installations-while-not-always-removing-default-extras" role="doc-backlink">Supporting minimal installations while not always removing default extras</a></h4> <p>An additional case we consider here is where a package maintainer wants to support minimal installations without any extras, but also wants to support having users specify additional extras without removing the default one. Essentially, they would want:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">package[minimal]</span></code> to give an installation without any extras</li> <li><code class="docutils literal notranslate"><span class="pre">package</span></code> to install recommended dependencies (in a <code class="docutils literal notranslate"><span class="pre">recommended</span></code> extras)</li> <li><code class="docutils literal notranslate"><span class="pre">package[additional]</span></code> to install both recommended and additional dependencies (in an <code class="docutils literal notranslate"><span class="pre">additional</span></code> extras)</li> </ul> <p>This could be achieved with e.g:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"recommended"</span> <span class="p">]</span> <span class="k">[project.optional-dependencies]</span> <span class="n">minimal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[]</span> <span class="n">recommended</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"package1"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"package2"</span> <span class="p">]</span> <span class="n">additional</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"package[recommended]"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"package3"</span> <span class="p">]</span> </pre></div> </div> <p>The ability for a package to reference itself in the extras is supported by existing Python packaging tools.</p> <p>Once again considering a concrete example, <a class="reference external" href="https://www.astropy.org/">astropy</a> could with this PEP define a <code class="docutils literal notranslate"><span class="pre">recommended</span></code> extra (as described in <a class="reference internal" href="#recommended-dependencies-and-minimal-installations">Recommended dependencies and minimal installations</a>). However, it also defines other extras, including for example <code class="docutils literal notranslate"><span class="pre">jupyter</span></code>, which adds packages that enhance the user experience inside <a class="reference external" href="https://jupyter.org/">Jupyter</a>-based environments. It is possible that users opting in to this extra would still want recommended dependencies to be installed. In this case, the following configuration would solve this case:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project]</span> <span class="n">default-optional-dependency-keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"recommended"</span> <span class="p">]</span> <span class="k">[project.optional-dependencies]</span> <span class="n">minimal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[]</span> <span class="n">recommended</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"scipy"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> <span class="n">jupyter</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"astropy[recommended]"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"ipywidgets"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"..."</span> <span class="p">]</span> </pre></div> </div> <p>Users installing:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>astropy<span class="o">[</span>jupyter<span class="o">]</span> </pre></div> </div> <p>would then get the same as:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>astropy<span class="o">[</span>recommended,<span class="w"> </span>jupyter<span class="o">]</span> </pre></div> </div> </section> </section> </section> <section id="backward-compatibility"> <h2><a class="toc-backref" href="#backward-compatibility" role="doc-backlink">Backward Compatibility</a></h2> <section id="packages-not-using-default-extras"> <h3><a class="toc-backref" href="#packages-not-using-default-extras" role="doc-backlink">Packages not using default extras</a></h3> <p>Once support for this PEP is added to tools in the packaging ecosystem, packages that do not make use of default extras will continue to work as-is and there should be no break in compatibility.</p> </section> <section id="packages-using-default-extras"> <h3><a class="toc-backref" href="#packages-using-default-extras" role="doc-backlink">Packages using default extras</a></h3> <p>Once packages start defining default extras, those defaults will only be honored with recent versions of packaging tools which implement this PEP, but those packages will remain installable with older packaging tools – with the main difference being that the default extras will not be installed automatically when older packaging tools are used.</p> <p>As described in <a class="reference internal" href="#how-to-teach-this">How to teach this</a>, package authors need to carefully evaluate when and how they adopt the default extra feature depending on their user base, as some actions (such as moving a required dependency to a default extra) will likely result in breakage for users if a significant fraction of them are still using older package installers that do not support default extras. In this sense, package authors should be aware that this feature, if used in certain ways, can cause backward-compatibility issues for users, and they are thus responsible for ensuring that they minimize the impact to users.</p> </section> <section id="packaging-related-tools"> <h3><a class="toc-backref" href="#packaging-related-tools" role="doc-backlink">Packaging-related tools</a></h3> <p>The most significant backward-compatibility aspect is related to assumptions packaging tools make about extras – specifically, this PEP changes the assumption that extras are no longer exclusively additive in terms of adding dependencies to the dependency tree, and specifying some extras can result in fewer dependencies being installed.</p> <p>A specific example of change in behavior can be seen with <a class="reference external" href="https://github.com/wheel-next/pip/tree/pep_771">pip</a>: consider a package <code class="docutils literal notranslate"><span class="pre">package</span></code> which has a required dependency of <code class="docutils literal notranslate"><span class="pre">numpy</span></code>, a (default) extra called <code class="docutils literal notranslate"><span class="pre">recommended</span></code> which includes <code class="docutils literal notranslate"><span class="pre">scipy</span></code>, and a <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extra which does not contain any dependencies. If a user installs <code class="docutils literal notranslate"><span class="pre">package[minimal]</span></code>, only <code class="docutils literal notranslate"><span class="pre">package</span></code> and <code class="docutils literal notranslate"><span class="pre">numpy</span></code> will be installed. If a user then does:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>freeze<span class="w"> </span>><span class="w"> </span>requirements.txt </pre></div> </div> <p>then <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code> will contain e.g.:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">package</span><span class="o">==</span><span class="mf">1.0.2</span> <span class="n">numpy</span><span class="o">==</span><span class="mf">2.1.0</span> </pre></div> </div> <p>However, if the user then installs the requirements from this file using:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt </pre></div> </div> <p>then pip will install <code class="docutils literal notranslate"><span class="pre">package</span></code> (which will include the default extra) as well as <code class="docutils literal notranslate"><span class="pre">numpy</span></code>, so the final environment will contain <code class="docutils literal notranslate"><span class="pre">scipy</span></code>. A solution in this specific case is for the user to pass <code class="docutils literal notranslate"><span class="pre">--no-deps</span></code> to <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> to avoid resolving the dependency tree, but the point here is to illustrate that there may be changes in behavior in packaging tools due to the change in the assumption about what impact an extra can have.</p> </section> </section> <section id="security-implications"> <h2><a class="toc-backref" href="#security-implications" role="doc-backlink">Security Implications</a></h2> <p>There are no known security implications for this PEP.</p> </section> <section id="how-to-teach-this"> <h2><a class="toc-backref" href="#how-to-teach-this" role="doc-backlink">How to teach this</a></h2> <p>This section outlines information that should be made available to people in different groups in the community in relation to the implementation of this PEP. Some aspects described below will be relevant even before the PEP is fully implemented in packaging tools as there are some preparations that can be done in advance of this implementation to facilitate any potential transition later on. The groups covered below are:</p> <ul class="simple"> <li><a class="reference internal" href="#package-end-users">Package end users</a></li> <li><a class="reference internal" href="#package-authors">Package authors</a></li> <li><a class="reference internal" href="#packaging-repository-maintainers">Packaging repository maintainers</a></li> </ul> <section id="package-end-users"> <h3><a class="toc-backref" href="#package-end-users" role="doc-backlink">Package end users</a></h3> <p>Package users should be provided with clear installation instructions that show what extras are available for packages and how they behave, for example explaining that by default some recommended dependencies or a given frontend or backend will be installed, and how to opt out of this or override defaults, depending what is available.</p> </section> <section id="package-authors"> <h3><a class="toc-backref" href="#package-authors" role="doc-backlink">Package authors</a></h3> <p>While the mechanism used to define extras and the associated rule about when to use it are clear, package authors need to carefully consider several points before adopting this capability in their packages, to avoid inadvertently breaking backward-compatibility.</p> <section id="supporting-older-versions-of-package-installers"> <h4><a class="toc-backref" href="#supporting-older-versions-of-package-installers" role="doc-backlink">Supporting older versions of package installers</a></h4> <p>Package installers such as <a class="reference external" href="https://github.com/wheel-next/pip/tree/pep_771">pip</a> or <a class="reference external" href="https://docs.astral.sh/uv/">uv</a> will not necessarily implement support for default extras at the same time, and once they do it is likely that package authors will want to keep supporting users who do not have the most recent version of a package installer. In this case, the following recommendations would apply:</p> <ul> <li>Moving a package from being a required dependency to a default extra would be a breaking change, because older versions of package installers would not recognise the concept of default extras, and would then install the package with fewer dependencies, which could affect users that would have been relying on these. Therefore, changing dependencies from required to a default extra in an established package should only be done in future once the developers only want to support users with installers that implement this PEP.</li> <li>Making an existing extra become a default should be safer, such as making <code class="docutils literal notranslate"><span class="pre">recommended</span></code> in <a class="reference external" href="https://www.astropy.org/">astropy</a> be a default extra, but in order to support users with older versions of package installers, the documentation should still mention the extra explicitly as long as possible (until it is clear that most/all users are using package installers that implement this PEP). There is no downside to keeping the extra be explicitly mentioned, but this will ensure that users with modern tooling who do not read documentation (which may be a non-negligeable fraction of the user community) will start getting the recommended dependencies by default.</li> <li>Adding a new extra, whether it be <code class="docutils literal notranslate"><span class="pre">minimal</span></code> or another new extra that is to be the default, comes with the same caveats that it does prior to this PEP, which is that users will only be able to use this extra for releases that define this extra. This might seem obvious, but consider a package that has a version 1.0 prior to using default extras. Suppose that package now defines <code class="docutils literal notranslate"><span class="pre">minimal</span></code> in 2.0, then downstream users and packages that want to depend on a minimal version of the package cannot declare the following dependency:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">package</span><span class="p">[</span><span class="n">minimal</span><span class="p">]</span><span class="o">>=</span><span class="mf">1.0</span> </pre></div> </div> <p>because <code class="docutils literal notranslate"><span class="pre">package[minimal]==1.0</span></code> does not exist (in practice, pip ignores unknown extras, so it might be possible to do this, but there is no guarantee that other tools won’t error on an unrecognized extra).</p> <p>The easiest solution to this problem is for package authors to define a no-op <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extra as soon as possible, even if only planning to adopt default extras further down the road, as it will allow <code class="docutils literal notranslate"><span class="pre">package[minimal]</span></code> to work for versions prior to when defaults were adopted.</p> </li> </ul> </section> <section id="avoiding-the-addition-of-many-default-dependencies"> <h4><a class="toc-backref" href="#avoiding-the-addition-of-many-default-dependencies" role="doc-backlink">Avoiding the addition of many default dependencies</a></h4> <p>One temptation for authors might be to include many dependencies by default since they can provide a way to opt out from these. We recommend however that authors carefully consider what is included by default to avoid unecessarily bloating installations and complicating dependency trees. Using default extras does not mean that all extras need to be defaults, and there is still scope for users to explicitly opt in to non-default extras.</p> </section> <section id="inheriting-from-default-extras"> <h4><a class="toc-backref" href="#inheriting-from-default-extras" role="doc-backlink">Inheriting from default extras</a></h4> <p>If package authors choose to make an extra be installed by default, it is important that they are aware that if users explicitly specify another extra, the default may not be installed, unless they use the approach described in <a class="reference internal" href="#supporting-minimal-installations-while-not-always-removing-default-extras">Supporting minimal installations while not always removing default extras</a>.</p> <p>There are cases, such as the interchangeable backends, or the <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extras, where ignoring the default if an extra is explicitly specified is the right thing to do. However, for other cases, such as using default extras to include recommended dependencies while still providing a way to do minimal installs, it may be that many of the other extras <em>should</em> explicitly ‘inherit’ the default extra(s), so package authors should carefully consider in which cases they want the default extras to be installed.</p> </section> <section id="incompatible-extras"> <h4><a class="toc-backref" href="#incompatible-extras" role="doc-backlink">Incompatible extras</a></h4> <p>In some cases, it may be that packages have extras that are mutually incompatible. In this case, we recommend against using the default extra feature for any extra that contains a dependency that could be incompatible with another.</p> <p>Consider a package that has extras <code class="docutils literal notranslate"><span class="pre">package[A]</span></code> and <code class="docutils literal notranslate"><span class="pre">package[B]</span></code>. Users could already currently try and install <code class="docutils literal notranslate"><span class="pre">package[A]</span></code> and <code class="docutils literal notranslate"><span class="pre">package[B]</span></code> or <code class="docutils literal notranslate"><span class="pre">package[A,B]</span></code> which would result in a broken installation, however it would at least be explicit that both extras were being installed. Making <code class="docutils literal notranslate"><span class="pre">A</span></code> into a default extra however could lead to unintuitive issues. A user could do:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package<span class="w"> </span><span class="c1"># this installs package[A]</span> <span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package<span class="o">[</span>B<span class="o">]</span> </pre></div> </div> <p>and end up with a broken installation, even though A and B were never explicitly both installed. For this reason, we recommend against using default extras for dependencies where this is likely to be an issue.</p> </section> <section id="circular-dependencies"> <h4><a class="toc-backref" href="#circular-dependencies" role="doc-backlink">Circular dependencies</a></h4> <p>Authors need to take special care when circular dependencies are present. For instance, consider the following dependency tree:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>package1 └── package2 └── package1 </pre></div> </div> <p>If <code class="docutils literal notranslate"><span class="pre">package1</span></code> has a default extra named <code class="docutils literal notranslate"><span class="pre">recommended</span></code> and a <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extra which is empty, then:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package1<span class="o">[</span>minimal<span class="o">]</span> </pre></div> </div> <p>will still result in the <code class="docutils literal notranslate"><span class="pre">recommended</span></code> extra being installed if <code class="docutils literal notranslate"><span class="pre">package2</span></code> continues to depend on <code class="docutils literal notranslate"><span class="pre">package1</span></code> (with no extras specified). If the dependency tree was updated to instead be:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>package1 └── package2 └── package1[minimal] </pre></div> </div> <p>Then <code class="docutils literal notranslate"><span class="pre">package1</span></code> would no longer be installable with tools that do not yet implement this PEP (if those tools would fail on unrecognized extras). Authors therefore need to carefully consider a migration plan, coordinating with the authors of <code class="docutils literal notranslate"><span class="pre">package2</span></code>.</p> </section> </section> <section id="packaging-repository-maintainers"> <h3><a class="toc-backref" href="#packaging-repository-maintainers" role="doc-backlink">Packaging repository maintainers</a></h3> <p>The impact on individuals who repackage Python libraries for different distributions, such as <a class="reference external" href="https://docs.conda.io">conda</a>, <a class="reference external" href="https://brew.sh/">Homebrew</a>, linux package installers (such as <code class="docutils literal notranslate"><span class="pre">apt</span></code> and <code class="docutils literal notranslate"><span class="pre">yum</span></code>) and so on, needs to be considered. Not all package distributions have mechanisms that would line up with the approach described. In fact, some distributions such as conda, do not even have the concept of extras.</p> <p>There are two cases to consider here:</p> <ul class="simple"> <li>In cases where the repackaging is done by hand, such as for a number of conda-forge recipes, and especially where there is no equivalent to extras, the introduction of default extras should not have a large impact since manual decisions already have to be made as to which dependencies to include (for example, the conda-forge recipe for the <a class="reference external" href="https://www.astropy.org/">astropy</a> package mentioned in the <a class="reference internal" href="#motivation">Motivation</a> includes all the <code class="docutils literal notranslate"><span class="pre">recommended</span></code> dependencies by default since there is no way for users to explicitly request them otherwise).</li> <li>In cases where the repackaging is done in an automated, way, distribution maintainers will need to carefully consider how to treat default extras, and this may imply a non-negligible amount of work and discussion.</li> </ul> <p>It is impossible for a PEP such as this to exhaustively consider each of the different package distributions. However, ultimately, default extras should be understood as how package authors would like their package to be installed for the majority of users, and this should inform decisions about how default extras should be handled, whether manually or automatically.</p> </section> </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> <p>The following repository contains a fully functional demo package that makes use of default extras:</p> <p><a class="reference external" href="https://github.com/wheel-next/pep_771">https://github.com/wheel-next/pep_771</a></p> <p>This makes use of modified branches of several packages, and the following links are to these branches:</p> <ul class="simple"> <li><a class="reference external" href="https://github.com/wheel-next/setuptools/tree/pep_771">Setuptools</a></li> <li><a class="reference external" href="https://github.com/wheel-next/pip/tree/pep_771">pip</a></li> <li><a class="reference external" href="https://github.com/wheel-next/importlib_metadata/tree/pep_771">importlib_metadata</a></li> </ul> <p>In addition, <a class="reference external" href="https://github.com/astrofrog/flit/tree/default-extras-pep">this branch</a> contains a modified version of the <a class="reference external" href="https://flit.pypa.io/en/stable/">Flit</a> package.</p> <p>The implementations above are proofs-of-concept at this time and the existing changes have not yet been reviewed by the relevant maintainers. Nevertheless, they are functional enough to allow for interested maintainers to try these out.</p> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="syntax-for-deselecting-extras"> <h3><a class="toc-backref" href="#syntax-for-deselecting-extras" role="doc-backlink">Syntax for deselecting extras</a></h3> <p>One of the main competing approaches was as follows: instead of having defaults be unselected if any extras were explicitly provided, default extras would need to be explicitly unselected.</p> <p>In this picture, a new syntax for unselecting extras would be introduced as an extension of the mini-language defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>. If a package defined default extras, users could opt out of these defaults by using a minus sign (<code class="docutils literal notranslate"><span class="pre">-</span></code>) before the extra name. The proposed syntax update would have been as follows:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>extras_list = (-)?identifier (wsp* ',' wsp* (-)?identifier)* </pre></div> </div> <p>Valid examples of this new syntax would have included, e.g.:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">package[-recommended]</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">package[-backend1,</span> <span class="pre">backend2]</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">package[pdf,</span> <span class="pre">-svg]</span></code></li> </ul> <p>However, there are two main issues with this approach:</p> <ul class="simple"> <li>One would need to define a number of rules for how to interpret corner cases such as if an extra and its negated version were both present in the same dependency specification (e.g. <code class="docutils literal notranslate"><span class="pre">package[pdf,</span> <span class="pre">-pdf]</span></code>) or if a dependency tree included both <code class="docutils literal notranslate"><span class="pre">package[pdf]</span></code> and <code class="docutils literal notranslate"><span class="pre">package[-pdf]</span></code>, and the rules would not be intuitive to users.</li> <li>More critically, this would introduce new syntax into dependency specification, which means that if any package defined a dependency using the new syntax, it and any other package depending on it would no longer be installable by existing packaging tools, so this would be a major backward compatibility break.</li> </ul> <p>For these reasons, this alternative was not included in the final proposal.</p> </section> <section id="adding-a-special-entry-in-extras-require"> <h3><a class="toc-backref" href="#adding-a-special-entry-in-extras-require" role="doc-backlink">Adding a special entry in <code class="docutils literal notranslate"><span class="pre">extras_require</span></code></a></h3> <p>A potential solution that has been explored as an alternative to introducing the new <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> metadata field would be to make use of an extra with a ‘special’ name.</p> <p>One example would be to use an empty string:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Provides</span><span class="o">-</span><span class="n">Extra</span><span class="p">:</span> <span class="n">Requires</span><span class="o">-</span><span class="n">Dist</span><span class="p">:</span> <span class="n">numpy</span> <span class="p">;</span> <span class="n">extra</span> <span class="o">==</span> <span class="s1">''</span> </pre></div> </div> <p>The idea would be that dependencies installed as part of the ‘empty’ extras would only get installed if another extra was not specified. An implementation of this was proposed in <a class="reference external" href="https://github.com/pypa/setuptools/pull/1503">https://github.com/pypa/setuptools/pull/1503</a>, but it was found that there would be no way to make this work without breaking compatibility with existing usage. For example, packages using Setuptools via a <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> file can do:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span> <span class="o">...</span> <span class="n">extras_require</span><span class="o">=</span><span class="p">{</span><span class="s1">''</span><span class="p">:</span> <span class="p">[</span><span class="s1">'package_a'</span><span class="p">]},</span> <span class="p">)</span> </pre></div> </div> <p>which is valid and equivalent to having <code class="docutils literal notranslate"><span class="pre">package_a</span></code> being defined in <code class="docutils literal notranslate"><span class="pre">install_requires</span></code>, so changing the meaning of the empty string would break compatibility.</p> <p>In addition, no other string (such as <code class="docutils literal notranslate"><span class="pre">'default'</span></code>) can be used as a special string since all strings that would be a backward-compatible valid extras name may already be used in existing packages.</p> <p>There have been suggestions of using the special <code class="docutils literal notranslate"><span class="pre">None</span></code> Python variable, but again this is not possible, because even though one can use <code class="docutils literal notranslate"><span class="pre">None</span></code> in a <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> file, this is not possible in declarative files such as <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> or <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>, and furthermore ultimately extras names have to be converted to strings in the package metadata. Having:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Provides</span><span class="o">-</span><span class="n">Extra</span><span class="p">:</span> <span class="kc">None</span> </pre></div> </div> <p>would be indistinguishable from the string ‘None’ which may already be used as an extra name in a Python package. If we were to modify the core metadata syntax to allow non-string ‘special’ extras names, then we would be back to modifying the core metadata specification, which is no better than introducing <code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code>.</p> </section> <section id="relying-on-tooling-to-deselect-any-default-extras"> <h3><a class="toc-backref" href="#relying-on-tooling-to-deselect-any-default-extras" role="doc-backlink">Relying on tooling to deselect any default extras</a></h3> <p>Another option to unselect extras would be to implement this at the level of packaging tools. For instance, pip could include an option such as:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package<span class="w"> </span>--no-default-extras </pre></div> </div> <p>This option could apply to all or specific packages, similar to the <code class="docutils literal notranslate"><span class="pre">--no-binary</span></code> option, e.g.,:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>package<span class="w"> </span>--no-default-extras<span class="w"> </span>:all: </pre></div> </div> <p>The advantage of this approach is that tools supporting default extras could also support unselecting them. This approach would be similar to the <code class="docutils literal notranslate"><span class="pre">--no-install-recommends</span></code> option for the <code class="docutils literal notranslate"><span class="pre">apt</span></code> tool.</p> <p>However, this solution is not ideal because it would not allow packages to specify themselves that they do not need some of the default extras of a dependency. It would also carry risks for users who might disable all default extras in a big dependency tree, potentially breaking packages in the tree that rely on default extras at any point. Nevertheless, this PEP does not disallow this approach and it is up to the maintainers of different packaging tools to decide if they want to support this kind of option.</p> </section> <section id="package-disables-default-extras"> <h3><a class="toc-backref" href="#package-disables-default-extras" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">package[]</span></code> disables default extras</a></h3> <p>Another way to specify not to install any extras, including default extras, would be to use <code class="docutils literal notranslate"><span class="pre">package[]</span></code>. However, this would break the current assumption in packaging tools that <code class="docutils literal notranslate"><span class="pre">package[]</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">package</span></code>, and may also result in developers overusing <code class="docutils literal notranslate"><span class="pre">[]</span></code> by default even when it is not needed. As highlighted in <a class="reference internal" href="#how-to-teach-this">How to teach this</a>, there may also be cases where package maintainers do not actually want to support an installation without any extras, for example in cases where at least one backend or frontend must be installed.</p> </section> </section> <section id="open-issues"> <h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open issues</a></h2> <section id="should-package-disable-default-extras"> <h3><a class="toc-backref" href="#should-package-disable-default-extras" role="doc-backlink">Should <code class="docutils literal notranslate"><span class="pre">package[]</span></code> disable default extras?</a></h3> <p>Currently, the PEP as written above does not allow <code class="docutils literal notranslate"><span class="pre">package[]</span></code> to be equivalent to installing the package with no extras, but there would be some benefits to allowing this:</p> <ul class="simple"> <li>It would avoid different packages using different names for a ‘no default’ extras (e.g. <code class="docutils literal notranslate"><span class="pre">minimal</span></code>, <code class="docutils literal notranslate"><span class="pre">no-default</span></code>, <code class="docutils literal notranslate"><span class="pre">no-defaults</span></code>) and reduce the burden for people who don’t want to have to scan through source code or documentation to figure out whether there is the equivalent of a <code class="docutils literal notranslate"><span class="pre">minimal</span></code> extra.</li> <li>It would allow people who want to use existing packages as-is and future versions of those packages with no default extras to use <code class="docutils literal notranslate"><span class="pre">package[]</span></code> because that syntax works right now, so it would provide a consistent way over time to get a minimal install.</li> </ul> <p>On the other hand, it is not clear at this point whether any tools are currently relying on <code class="docutils literal notranslate"><span class="pre">package[]</span></code> being identical to <code class="docutils literal notranslate"><span class="pre">package</span></code> in a way that would break compatibility if this was done, so this needs to be investigated.</p> </section> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0771.rst">https://github.com/python/peps/blob/main/peps/pep-0771.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0771.rst">2025-02-06 17:02:06 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#recommended-but-not-required-dependencies">Recommended but not required dependencies</a></li> <li><a class="reference internal" href="#packages-supporting-multiple-backends-or-frontends">Packages supporting multiple backends or frontends</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#default-extra-metadata-field"><code class="docutils literal notranslate"><span class="pre">Default-Extra</span></code> Metadata Field</a></li> <li><a class="reference internal" href="#new-key-in-project-metadata-table">New key in <code class="docutils literal notranslate"><span class="pre">[project]</span></code> metadata table</a></li> <li><a class="reference internal" href="#overriding-default-extras">Overriding default extras</a></li> <li><a class="reference internal" href="#installing-without-default-extras">Installing without default extras</a></li> <li><a class="reference internal" href="#examples">Examples</a><ul> <li><a class="reference internal" href="#recommended-dependencies-and-minimal-installations">Recommended dependencies and minimal installations</a></li> <li><a class="reference internal" href="#packages-requiring-at-least-one-backend-or-frontend">Packages requiring at least one backend or frontend</a></li> <li><a class="reference internal" href="#supporting-minimal-installations-while-not-always-removing-default-extras">Supporting minimal installations while not always removing default extras</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#backward-compatibility">Backward Compatibility</a><ul> <li><a class="reference internal" href="#packages-not-using-default-extras">Packages not using default extras</a></li> <li><a class="reference internal" href="#packages-using-default-extras">Packages using default extras</a></li> <li><a class="reference internal" href="#packaging-related-tools">Packaging-related tools</a></li> </ul> </li> <li><a class="reference internal" href="#security-implications">Security Implications</a></li> <li><a class="reference internal" href="#how-to-teach-this">How to teach this</a><ul> <li><a class="reference internal" href="#package-end-users">Package end users</a></li> <li><a class="reference internal" href="#package-authors">Package authors</a><ul> <li><a class="reference internal" href="#supporting-older-versions-of-package-installers">Supporting older versions of package installers</a></li> <li><a class="reference internal" href="#avoiding-the-addition-of-many-default-dependencies">Avoiding the addition of many default dependencies</a></li> <li><a class="reference internal" href="#inheriting-from-default-extras">Inheriting from default extras</a></li> <li><a class="reference internal" href="#incompatible-extras">Incompatible extras</a></li> <li><a class="reference internal" href="#circular-dependencies">Circular dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#packaging-repository-maintainers">Packaging repository maintainers</a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#syntax-for-deselecting-extras">Syntax for deselecting extras</a></li> <li><a class="reference internal" href="#adding-a-special-entry-in-extras-require">Adding a special entry in <code class="docutils literal notranslate"><span class="pre">extras_require</span></code></a></li> <li><a class="reference internal" href="#relying-on-tooling-to-deselect-any-default-extras">Relying on tooling to deselect any default extras</a></li> <li><a class="reference internal" href="#package-disables-default-extras"><code class="docutils literal notranslate"><span class="pre">package[]</span></code> disables default extras</a></li> </ul> </li> <li><a class="reference internal" href="#open-issues">Open issues</a><ul> <li><a class="reference internal" href="#should-package-disable-default-extras">Should <code class="docutils literal notranslate"><span class="pre">package[]</span></code> disable default extras?</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0771.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>