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 725 – Specifying external dependencies in pyproject.toml | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0725/"> <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 725 – Specifying external dependencies in pyproject.toml | peps.python.org'> <meta property="og:description" content="This PEP specifies how to write a project’s external, or non-PyPI, build and runtime dependencies in a pyproject.toml file for packaging-related tools to consume."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0725/"> <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="This PEP specifies how to write a project’s external, or non-PyPI, build and runtime dependencies in a pyproject.toml file for packaging-related tools to consume."> <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 725</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 725 – Specifying external dependencies in pyproject.toml</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Pradyun Gedam <pradyunsg at gmail.com>, Ralf Gommers <ralf.gommers at gmail.com></dd> <dt class="field-even">Discussions-To<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/31888">Discourse thread</a></dd> <dt class="field-odd">Status<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Proposal under active discussion and revision">Draft</abbr></dd> <dt class="field-even">Type<span class="colon">:</span></dt> <dd class="field-even"><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-odd">Topic<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">17-Aug-2023</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/31888" title="Discourse thread">18-Aug-2023</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></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#types-of-external-dependencies">Types of external dependencies</a></li> <li><a class="reference internal" href="#cross-compilation">Cross compilation</a><ul> <li><a class="reference internal" href="#terminology">Terminology</a></li> <li><a class="reference internal" href="#build-and-host-dependencies">Build and host dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#specifying-external-dependencies">Specifying external dependencies</a><ul> <li><a class="reference internal" href="#concrete-package-specification-through-purl">Concrete package specification through PURL</a></li> <li><a class="reference internal" href="#virtual-package-specification">Virtual package specification</a></li> <li><a class="reference internal" href="#versioning">Versioning</a></li> <li><a class="reference internal" href="#dependency-specifiers">Dependency specifiers</a></li> </ul> </li> <li><a class="reference internal" href="#usage-of-core-metadata-fields">Usage of core metadata fields</a><ul> <li><a class="reference internal" href="#differences-between-sdist-and-wheel-metadata">Differences between sdist and wheel metadata</a></li> <li><a class="reference internal" href="#canonical-names-of-dependencies-and-dev-el-split-packages">Canonical names of dependencies and <code class="docutils literal notranslate"><span class="pre">-dev(el)</span></code> split packages</a></li> <li><a class="reference internal" href="#python-development-headers">Python development headers</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#details">Details</a><ul> <li><a class="reference internal" href="#table-name">Table name</a></li> <li><a class="reference internal" href="#build-requires-optional-build-requires"><code class="docutils literal notranslate"><span class="pre">build-requires</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-build-requires</span></code></a></li> <li><a class="reference internal" href="#host-requires-optional-host-requires"><code class="docutils literal notranslate"><span class="pre">host-requires</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-host-requires</span></code></a></li> <li><a class="reference internal" href="#dependencies-optional-dependencies"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a></li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></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></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="#specific-syntax-for-external-dependencies-which-are-also-packaged-on-pypi">Specific syntax for external dependencies which are also packaged on PyPI</a></li> <li><a class="reference internal" href="#using-library-and-header-names-as-external-dependencies">Using library and header names as external dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#open-issues">Open Issues</a><ul> <li><a class="reference internal" href="#version-specifiers-for-purls">Version specifiers for PURLs</a></li> <li><a class="reference internal" href="#versioning-of-virtual-dependencies">Versioning of virtual dependencies</a></li> <li><a class="reference internal" href="#who-defines-canonical-names-and-canonical-package-structure">Who defines canonical names and canonical package structure?</a></li> <li><a class="reference internal" href="#syntax-for-virtual-dependencies">Syntax for virtual dependencies</a></li> <li><a class="reference internal" href="#should-a-host-requires-key-be-added-under-build-system">Should a <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> key be added under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code>?</a></li> </ul> </li> <li><a class="reference internal" href="#references">References</a></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>This PEP specifies how to write a project’s external, or non-PyPI, build and runtime dependencies in a <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file for packaging-related tools to consume.</p> <p>This PEP proposes to add an <code class="docutils literal notranslate"><span class="pre">[external]</span></code> table to <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> with three keys: “build-requires”, “host-requires” and “dependencies”. These are for specifying three types of dependencies:</p> <ol class="arabic simple"> <li><code class="docutils literal notranslate"><span class="pre">build-requires</span></code>, build tools to run on the build machine</li> <li><code class="docutils literal notranslate"><span class="pre">host-requires</span></code>, build dependencies needed for host machine but also needed at build time.</li> <li><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>, needed at runtime on the host machine but not needed at build time.</li> </ol> <p>Cross compilation is taken into account by distinguishing build and host dependencies. Optional build-time and runtime dependencies are supported too, in a manner analogies to how that is supported in the <code class="docutils literal notranslate"><span class="pre">[project]</span></code> table.</p> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <p>Python packages may have dependencies on build tools, libraries, command-line tools, or other software that is not present on PyPI. Currently there is no way to express those dependencies in standardized metadata <a class="footnote-reference brackets" href="#singular-vision-native-deps" id="id1">[1]</a>, <a class="footnote-reference brackets" href="#pypacking-native-deps" id="id2">[2]</a>. Key motivators for this PEP are to:</p> <ul class="simple"> <li>Enable tools to automatically map external dependencies to packages in other packaging repositories,</li> <li>Make it possible to include needed dependencies in error messages emitting by Python package installers and build frontends,</li> <li>Provide a canonical place for package authors to record this dependency information.</li> </ul> <p>Packaging ecosystems like Linux distros, Conda, Homebrew, Spack, and Nix need full sets of dependencies for Python packages, and have tools like <a class="reference external" href="https://github.com/befeleme/pyp2spec">pyp2spec</a> (Fedora), <a class="reference external" href="https://github.com/conda/grayskull">Grayskull</a> (Conda), and <a class="reference external" href="https://www.debian.org/doc/packaging-manuals/python-policy/index.html#dh-python">dh_python</a> (Debian) which attempt to automatically generate dependency metadata for their own package managers from the metadata in upstream Python packages. External dependencies are currently handled manually, because there is no metadata for this in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> or any other standard location. Enabling automating this conversion is a key benefit of this PEP, making packaging Python packages for distros easier and more reliable. In addition, the authors envision other types of tools making use of this information, e.g., dependency analysis tools like <a class="reference external" href="https://repology.org/">Repology</a>, <a class="reference external" href="https://github.com/dependabot">Dependabot</a> and <a class="reference external" href="https://libraries.io/">libraries.io</a>. Software bill of materials (SBOM) generation tools may also be able to use this information, e.g. for flagging that external dependencies listed in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> but not contained in wheel metadata are likely vendored within the wheel.</p> <p>Packages with external dependencies are typically hard to build from source, and error messages from build failures tend to be hard to decipher for end users. Missing external dependencies on the end user’s system are the most likely cause of build failures. If installers can show the required external dependencies as part of their error message, this may save users a lot of time.</p> <p>At the moment, information on external dependencies is only captured in installation documentation of individual packages. It is hard to maintain for package authors and tends to go out of date. It’s also hard for users and distro packagers to find it. Having a canonical place to record this dependency information will improve this situation.</p> <p>This PEP is not trying to specify how the external dependencies should be used, nor a mechanism to implement a name mapping from names of individual packages that are canonical for Python projects published on PyPI to those of other packaging ecosystems. Those topics should be addressed in separate PEPs.</p> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <section id="types-of-external-dependencies"> <h3><a class="toc-backref" href="#types-of-external-dependencies" role="doc-backlink">Types of external dependencies</a></h3> <p>Multiple types of external dependencies can be distinguished:</p> <ul class="simple"> <li>Concrete packages that can be identified by name and have a canonical location in another language-specific package repository. E.g., Rust packages on <a class="reference external" href="https://crates.io/">crates.io</a>, R packages on <a class="reference external" href="https://cran.r-project.org/">CRAN</a>, JavaScript packages on the <a class="reference external" href="https://www.npmjs.com/">npm registry</a>.</li> <li>Concrete packages that can be identified by name but do not have a clear canonical location. This is typically the case for libraries and tools written in C, C++, Fortran, CUDA and other low-level languages. E.g., Boost, OpenSSL, Protobuf, Intel MKL, GCC.</li> <li>“Virtual” packages, which are names for concepts, types of tools or interfaces. These typically have multiple implementations, which <em>are</em> concrete packages. E.g., a C++ compiler, BLAS, LAPACK, OpenMP, MPI.</li> </ul> <p>Concrete packages are straightforward to understand, and are a concept present in virtually every package management system. Virtual packages are a concept also present in a number of packaging systems – but not always, and the details of their implementation varies.</p> </section> <section id="cross-compilation"> <h3><a class="toc-backref" href="#cross-compilation" role="doc-backlink">Cross compilation</a></h3> <p>Cross compilation is not yet (as of August 2023) well-supported by stdlib modules and <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> metadata. It is however important when translating external dependencies to those of other packaging systems (with tools like <code class="docutils literal notranslate"><span class="pre">pyp2spec</span></code>). Introducing support for cross compilation immediately in this PEP is much easier than extending <code class="docutils literal notranslate"><span class="pre">[external]</span></code> in the future, hence the authors choose to include this now.</p> <section id="terminology"> <h4><a class="toc-backref" href="#terminology" role="doc-backlink">Terminology</a></h4> <p>This PEP uses the following terminology:</p> <ul class="simple"> <li><em>build machine</em>: the machine on which the package build process is being executed</li> <li><em>host machine</em>: the machine on which the produced artifact will be installed and run</li> <li><em>build dependency</em>: dependency for building the package that needs to be present at build time and itself was built for the build machine’s OS and architecture</li> <li><em>host dependency</em>: dependency for building the package that needs to be present at build time and itself was built for the host machine’s OS and architecture</li> </ul> <p>Note that this terminology is not consistent across build and packaging tools, so care must be taken when comparing build/host dependencies in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> to dependencies from other package managers.</p> <p>Note that “target machine” or “target dependency” is not used in this PEP. That is typically only relevant for cross-compiling compilers or other such advanced scenarios <a class="footnote-reference brackets" href="#gcc-cross-terminology" id="id3">[3]</a>, <a class="footnote-reference brackets" href="#meson-cross" id="id4">[4]</a> - this is out of scope for this PEP.</p> <p>Finally, note that while “dependency” is the term most widely used for packages needed at build time, the existing key in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> for PyPI build-time dependencies is <code class="docutils literal notranslate"><span class="pre">build-requires</span></code>. Hence this PEP uses the keys <code class="docutils literal notranslate"><span class="pre">build-requires</span></code> and <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> under <code class="docutils literal notranslate"><span class="pre">[external]</span></code> for consistency.</p> </section> <section id="build-and-host-dependencies"> <h4><a class="toc-backref" href="#build-and-host-dependencies" role="doc-backlink">Build and host dependencies</a></h4> <p>Clear separation of metadata associated with the definition of build and target platforms, rather than assuming that build and target platform will always be the same, is important <a class="footnote-reference brackets" href="#pypackaging-native-cross" id="id5">[5]</a>.</p> <p>Build dependencies are typically run during the build process - they may be compilers, code generators, or other such tools. In case the use of a build dependency implies a runtime dependency, that runtime dependency does not have to be declared explicitly. For example, when compiling Fortran code with <code class="docutils literal notranslate"><span class="pre">gfortran</span></code> into a Python extension module, the package likely incurs a dependency on the <code class="docutils literal notranslate"><span class="pre">libgfortran</span></code> runtime library. The rationale for not explicitly listing such runtime dependencies is two-fold: (1) it may depend on compiler/linker flags or details of the build environment whether the dependency is present, and (2) these runtime dependencies can be detected and handled automatically by tools like <code class="docutils literal notranslate"><span class="pre">auditwheel</span></code>.</p> <p>Host dependencies are typically not run during the build process, but only used for linking against. This is not a rule though – it may be possible or necessary to run a host dependency under an emulator, or through a custom tool like <a class="reference external" href="https://github.com/benfogle/crossenv">crossenv</a>. When host dependencies imply a runtime dependency, that runtime dependency also does not have to be declared, just like for build dependencies.</p> <p>When host dependencies are declared and a tool is not cross-compilation aware and has to do something with external dependencies, the tool MAY merge the <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> list into <code class="docutils literal notranslate"><span class="pre">build-requires</span></code>. This may for example happen if an installer like <code class="docutils literal notranslate"><span class="pre">pip</span></code> starts reporting external dependencies as a likely cause of a build failure when a package fails to build from an sdist.</p> </section> </section> <section id="specifying-external-dependencies"> <h3><a class="toc-backref" href="#specifying-external-dependencies" role="doc-backlink">Specifying external dependencies</a></h3> <section id="concrete-package-specification-through-purl"> <h4><a class="toc-backref" href="#concrete-package-specification-through-purl" role="doc-backlink">Concrete package specification through PURL</a></h4> <p>The two types of concrete packages are supported by <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> (Package URL), which implements a scheme for identifying packages that is meant to be portable across packaging ecosystems. Its design is:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>scheme:type/namespace/name@version?qualifiers#subpath </pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">scheme</span></code> component is a fixed string, <code class="docutils literal notranslate"><span class="pre">pkg</span></code>, and of the other components only <code class="docutils literal notranslate"><span class="pre">type</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> are required. As an example, a package URL for the <code class="docutils literal notranslate"><span class="pre">requests</span></code> package on PyPI would be:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkg</span><span class="p">:</span><span class="n">pypi</span><span class="o">/</span><span class="n">requests</span> </pre></div> </div> <p>Adopting PURL to specify external dependencies in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> solves a number of problems at once - and there are already implementations of the specification in Python and multiple languages. PURL is also already supported by dependency-related tooling like SPDX (see <a class="reference external" href="https://spdx.github.io/spdx-spec/v2.3/external-repository-identifiers/#f35-purl">External Repository Identifiers in the SPDX 2.3 spec</a>), the <a class="reference external" href="https://ossf.github.io/osv-schema/#affectedpackage-field">Open Source Vulnerability format</a>, and the <a class="reference external" href="https://ossindex.sonatype.org/doc/coordinates">Sonatype OSS Index</a>; not having to wait years before support in such tooling arrives is valuable.</p> <p>For concrete packages without a canonical package manager to refer to, either <code class="docutils literal notranslate"><span class="pre">pkg:generic/pkg-name</span></code> can be used, or a direct reference to the VCS system that the package is maintained in (e.g., <code class="docutils literal notranslate"><span class="pre">pkg:github/user-or-org-name/pkg-name</span></code>). Which of these is more appropriate is situation-dependent. This PEP recommends using <code class="docutils literal notranslate"><span class="pre">pkg:generic</span></code> when the package name is unambiguous and well-known (e.g., <code class="docutils literal notranslate"><span class="pre">pkg:generic/git</span></code> or <code class="docutils literal notranslate"><span class="pre">pkg:generic/openblas</span></code>), and using the VCS as the PURL type otherwise.</p> </section> <section id="virtual-package-specification"> <h4><a class="toc-backref" href="#virtual-package-specification" role="doc-backlink">Virtual package specification</a></h4> <p>There is no ready-made support for virtual packages in PURL or another standard. There are a relatively limited number of such dependencies though, and adopting a scheme similar to PURL but with the <code class="docutils literal notranslate"><span class="pre">virtual:</span></code> rather than <code class="docutils literal notranslate"><span class="pre">pkg:</span></code> scheme seems like it will be understandable and map well to Linux distros with virtual packages and to the likes of Conda and Spack.</p> <p>The two known virtual package types are <code class="docutils literal notranslate"><span class="pre">compiler</span></code> and <code class="docutils literal notranslate"><span class="pre">interface</span></code>.</p> </section> <section id="versioning"> <h4><a class="toc-backref" href="#versioning" role="doc-backlink">Versioning</a></h4> <p>Support in PURL for version expressions and ranges beyond a fixed version is still pending, see the Open Issues section.</p> </section> <section id="dependency-specifiers"> <h4><a class="toc-backref" href="#dependency-specifiers" role="doc-backlink">Dependency specifiers</a></h4> <p>Regular Python dependency specifiers (as originally defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>) may be used behind PURLs. PURL qualifiers, which use <code class="docutils literal notranslate"><span class="pre">?</span></code> followed by a package type-specific dependency specifier component, must not be used. The reason for this is pragmatic: dependency specifiers are already used for other metadata in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>, any tooling that is used with <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> is likely to already have a robust implementation to parse it. And we do not expect to need the extra possibilities that PURL qualifiers provide (e.g. to specify a Conan or Conda channel, or a RubyGems platform).</p> </section> </section> <section id="usage-of-core-metadata-fields"> <h3><a class="toc-backref" href="#usage-of-core-metadata-fields" role="doc-backlink">Usage of core metadata fields</a></h3> <p>The <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> specification contains one relevant field, namely <code class="docutils literal notranslate"><span class="pre">Requires-External</span></code>. This has no well-defined semantics in core metadata 2.1; this PEP chooses to reuse the field for external runtime dependencies. The core metadata specification does not contain fields for any metadata in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>’s <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code> table. Therefore the <code class="docutils literal notranslate"><span class="pre">build-requires</span></code> and <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> content also does not need to be reflected in core metadata fields. The <code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code> content from <code class="docutils literal notranslate"><span class="pre">[external]</span></code> would need to either reuse <code class="docutils literal notranslate"><span class="pre">Provides-Extra</span></code> or require a new <code class="docutils literal notranslate"><span class="pre">Provides-External-Extra</span></code> field. Neither seems desirable.</p> <section id="differences-between-sdist-and-wheel-metadata"> <h4><a class="toc-backref" href="#differences-between-sdist-and-wheel-metadata" role="doc-backlink">Differences between sdist and wheel metadata</a></h4> <p>A wheel may vendor its external dependencies. This happens in particular when distributing wheels on PyPI or other Python package indexes - and tools like <a class="reference external" href="https://github.com/pypa/auditwheel">auditwheel</a>, <a class="reference external" href="https://github.com/adang1345/delvewheel">delvewheel</a> and <a class="reference external" href="https://github.com/matthew-brett/delocate">delocate</a> automate this process. As a result, a <code class="docutils literal notranslate"><span class="pre">Requires-External</span></code> entry in an sdist may disappear from a wheel built from that sdist. It is also possible that a <code class="docutils literal notranslate"><span class="pre">Requires-External</span></code> entry remains in a wheel, either unchanged or with narrower constraints. <code class="docutils literal notranslate"><span class="pre">auditwheel</span></code> does not vendor certain allow-listed dependencies, such as OpenGL, by default. In addition, <code class="docutils literal notranslate"><span class="pre">auditwheel</span></code> and <code class="docutils literal notranslate"><span class="pre">delvewheel</span></code> allow a user to manually exclude dependencies via a <code class="docutils literal notranslate"><span class="pre">--exclude</span></code> or <code class="docutils literal notranslate"><span class="pre">--no-dll</span></code> command-line flag. This is used to avoid vendoring large shared libraries, for example those from CUDA.</p> <p><code class="docutils literal notranslate"><span class="pre">Requires-External</span></code> entries generated from external dependencies in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> in a wheel are therefore allowed to be narrower than those for the corresponding sdist. They must not be wider, i.e. constraints must not allow a version of a dependency for a wheel that isn’t allowed for an sdist, nor contain new dependencies that are not listed in the sdist’s metadata at all.</p> </section> <section id="canonical-names-of-dependencies-and-dev-el-split-packages"> <h4><a class="toc-backref" href="#canonical-names-of-dependencies-and-dev-el-split-packages" role="doc-backlink">Canonical names of dependencies and <code class="docutils literal notranslate"><span class="pre">-dev(el)</span></code> split packages</a></h4> <p>It is fairly common for distros to split a package into two or more packages. In particular, runtime components are often separately installable from development components (headers, pkg-config and CMake files, etc.). The latter then typically has a name with <code class="docutils literal notranslate"><span class="pre">-dev</span></code> or <code class="docutils literal notranslate"><span class="pre">-devel</span></code> appended to the project/library name. This split is the responsibility of each distro to maintain, and should not be reflected in the <code class="docutils literal notranslate"><span class="pre">[external]</span></code> table. It is not possible to specify this in a reasonable way that works across distros, hence only the canonical name should be used in <code class="docutils literal notranslate"><span class="pre">[external]</span></code>.</p> <p>The intended meaning of using a PURL or virtual dependency is “the full package with the name specified”. It will depend on the context in which the metadata is used whether the split is relevant. For example, if <code class="docutils literal notranslate"><span class="pre">libffi</span></code> is a host dependency and a tool wants to prepare an environment for building a wheel, then if a distro has split off the headers for <code class="docutils literal notranslate"><span class="pre">libffi</span></code> into a <code class="docutils literal notranslate"><span class="pre">libffi-devel</span></code> package then the tool has to install both <code class="docutils literal notranslate"><span class="pre">libffi</span></code> and <code class="docutils literal notranslate"><span class="pre">libffi-devel</span></code>.</p> </section> <section id="python-development-headers"> <h4><a class="toc-backref" href="#python-development-headers" role="doc-backlink">Python development headers</a></h4> <p>Python headers and other build support files may also be split. This is the same situation as in the section above (because Python is simply a regular package in distros). <em>However</em>, a <code class="docutils literal notranslate"><span class="pre">python-dev|devel</span></code> dependency is special because in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> Python itself is an implicit rather than an explicit dependency. Hence a choice needs to be made here - add <code class="docutils literal notranslate"><span class="pre">python-dev</span></code> implicitly, or make each package author add it explicitly under <code class="docutils literal notranslate"><span class="pre">[external]</span></code>. For consistency between Python dependencies and external dependencies, we choose to add it implicitly. Python development headers must be assumed to be necessary when an <code class="docutils literal notranslate"><span class="pre">[external]</span></code> table contains one or more compiler packages.</p> </section> </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <p>If metadata is improperly specified then tools MUST raise an error to notify the user about their mistake.</p> <section id="details"> <h3><a class="toc-backref" href="#details" role="doc-backlink">Details</a></h3> <p>Note that <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> content is in the same format as in <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a>.</p> <section id="table-name"> <h4><a class="toc-backref" href="#table-name" role="doc-backlink">Table name</a></h4> <p>Tools MUST specify fields defined by this PEP in a table named <code class="docutils literal notranslate"><span class="pre">[external]</span></code>. No tools may add fields to this table which are not defined by this PEP or subsequent PEPs. The lack of an <code class="docutils literal notranslate"><span class="pre">[external]</span></code> table means the package either does not have any external dependencies, or the ones it does have are assumed to be present on the system already.</p> </section> <section id="build-requires-optional-build-requires"> <h4><a class="toc-backref" href="#build-requires-optional-build-requires" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">build-requires</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-build-requires</span></code></a></h4> <ul class="simple"> <li>Format: Array of <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings (<code class="docutils literal notranslate"><span class="pre">build-requires</span></code>) and a table with values of arrays of <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings (<code class="docutils literal notranslate"><span class="pre">optional-build-requires</span></code>)</li> <li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: N/A</li> </ul> <p>The (optional) external build requirements needed to build the project.</p> <p>For <code class="docutils literal notranslate"><span class="pre">build-requires</span></code>, it is a key whose value is an array of strings. Each string represents a build requirement of the project and MUST be formatted as either a valid <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> string or a <code class="docutils literal notranslate"><span class="pre">virtual:</span></code> string.</p> <p>For <code class="docutils literal notranslate"><span class="pre">optional-build-requires</span></code>, it is a table where each key specifies an extra set of build requirements and whose value is an array of strings. The strings of the arrays MUST be valid <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings.</p> </section> <section id="host-requires-optional-host-requires"> <h4><a class="toc-backref" href="#host-requires-optional-host-requires" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">host-requires</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-host-requires</span></code></a></h4> <ul class="simple"> <li>Format: Array of <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings (<code class="docutils literal notranslate"><span class="pre">host-requires</span></code>) and a table with values of arrays of <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings (<code class="docutils literal notranslate"><span class="pre">optional-host-requires</span></code>)</li> <li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: N/A</li> </ul> <p>The (optional) external host requirements needed to build the project.</p> <p>For <code class="docutils literal notranslate"><span class="pre">host-requires</span></code>, it is a key whose value is an array of strings. Each string represents a host requirement of the project and MUST be formatted as either a valid <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> string or a <code class="docutils literal notranslate"><span class="pre">virtual:</span></code> string.</p> <p>For <code class="docutils literal notranslate"><span class="pre">optional-host-requires</span></code>, it is a table where each key specifies an extra set of host requirements and whose value is an array of strings. The strings of the arrays MUST be valid <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings.</p> </section> <section id="dependencies-optional-dependencies"> <h4><a class="toc-backref" href="#dependencies-optional-dependencies" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></h4> <ul class="simple"> <li>Format: Array of <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings (<code class="docutils literal notranslate"><span class="pre">dependencies</span></code>) and a table with values of arrays of <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings (<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code>)</li> <li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Requires-External</span></code>, N/A</li> </ul> <p>The (optional) runtime dependencies of the project.</p> <p>For <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>, it is a key whose value is an array of strings. Each string represents a dependency of the project and MUST be formatted as either a valid <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> string or a <code class="docutils literal notranslate"><span class="pre">virtual:</span></code> string. Each string maps directly to a <code class="docutils literal notranslate"><span class="pre">Requires-External</span></code> entry in the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>.</p> <p>For <code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code>, it is a table where each key specifies an extra and whose value is an array of strings. The strings of the arrays MUST be valid <a class="reference external" href="https://github.com/package-url/purl-spec/">PURL</a> strings. Optional dependencies do not map to a core metadata field.</p> </section> </section> <section id="examples"> <h3><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h3> <p>These examples show what the <code class="docutils literal notranslate"><span class="pre">[external]</span></code> content for a number of packages is expected to be.</p> <p>cryptography 39.0:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[external]</span> <span class="n">build-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"virtual:compiler/c"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"virtual:compiler/rust"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/pkg-config"</span><span class="p">,</span> <span class="p">]</span> <span class="n">host-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:generic/openssl"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/libffi"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> <p>SciPy 1.10:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[external]</span> <span class="n">build-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"virtual:compiler/c"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"virtual:compiler/cpp"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"virtual:compiler/fortran"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/ninja"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/pkg-config"</span><span class="p">,</span> <span class="p">]</span> <span class="n">host-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"virtual:interface/blas"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"virtual:interface/lapack"</span><span class="p">,</span><span class="w"> </span><span class="c1"># >=3.7.1 (can't express version ranges with PURL yet)</span> <span class="p">]</span> </pre></div> </div> <p>Pillow 10.1.0:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[external]</span> <span class="n">build-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"virtual:compiler/c"</span><span class="p">,</span> <span class="p">]</span> <span class="n">host-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:generic/libjpeg"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/zlib"</span><span class="p">,</span> <span class="p">]</span> <span class="k">[external.optional-host-requires]</span> <span class="n">extra</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:generic/lcms2"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/freetype"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/libimagequant"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/libraqm"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/libtiff"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/libxcb"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/libwebp"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:generic/openjpeg"</span><span class="p">,</span><span class="w"> </span><span class="c1"># add >=2.0 once we have version specifiers</span> <span class="w"> </span><span class="s2">"pkg:generic/tk"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> <p>NAVis 1.4.0:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project.optional-dependencies]</span> <span class="n">r</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s2">"rpy2"</span><span class="p">]</span> <span class="k">[external]</span> <span class="n">build-requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:generic/XCB; platform_system=='Linux'"</span><span class="p">,</span> <span class="p">]</span> <span class="k">[external.optional-dependencies]</span> <span class="n">nat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:cran/nat"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:cran/nat.nblast"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> <p>Spyder 6.0:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[external]</span> <span class="n">dependencies</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:cargo/ripgrep"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:cargo/tree-sitter-cli"</span><span class="p">,</span> <span class="w"> </span><span class="s2">"pkg:golang/github.com/junegunn/fzf"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> <p>jupyterlab-git 0.41.0:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[external]</span> <span class="n">dependencies</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:generic/git"</span><span class="p">,</span> <span class="p">]</span> <span class="k">[external.optional-build-requires]</span> <span class="n">dev</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="s2">"pkg:generic/nodejs"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> <p>PyEnchant 3.2.2:</p> <div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[external]</span> <span class="n">dependencies</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="c1"># libenchant is needed on all platforms but only vendored into wheels on</span> <span class="w"> </span><span class="c1"># Windows, so on Windows the build backend should remove this external</span> <span class="w"> </span><span class="c1"># dependency from wheel metadata.</span> <span class="w"> </span><span class="s2">"pkg:github/AbiWord/enchant"</span><span class="p">,</span> <span class="p">]</span> </pre></div> </div> </section> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> <p>There is no impact on backwards compatibility, as this PEP only adds new, optional metadata. In the absence of such metadata, nothing changes for package authors or packaging tooling.</p> </section> <section id="security-implications"> <h2><a class="toc-backref" href="#security-implications" role="doc-backlink">Security Implications</a></h2> <p>There are no direct security concerns as this PEP covers how to statically define metadata for external dependencies. Any security issues would stem from how tools consume the metadata and choose to act upon it.</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>External dependencies and if and how those external dependencies are vendored are topics that are typically not understood in detail by Python package authors. We intend to start from how an external dependency is defined, the different ways it can be depended on—from runtime-only with <code class="docutils literal notranslate"><span class="pre">ctypes</span></code> or a <code class="docutils literal notranslate"><span class="pre">subprocess</span></code> call to it being a build dependency that’s linked against— before going into how to declare external dependencies in metadata. The documentation should make explicit what is relevant for package authors, and what for distro packagers.</p> <p>Material on this topic will be added to the most relevant packaging tutorials, primarily the <a class="reference external" href="https://packaging.python.org">Python Packaging User Guide</a>. In addition, we expect that any build backend that adds support for external dependencies metadata will include information about that in its documentation, as will tools like <code class="docutils literal notranslate"><span class="pre">auditwheel</span></code>.</p> </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> <p>This PEP contains a metadata specification, rather that a code feature - hence there will not be code implementing the metadata spec as a whole. However, there are parts that do have a reference implementation:</p> <ol class="arabic simple"> <li>The <code class="docutils literal notranslate"><span class="pre">[external]</span></code> table has to be valid TOML and therefore can be loaded with <code class="docutils literal notranslate"><span class="pre">tomllib</span></code>.</li> <li>The PURL specification, as a key part of this spec, has a Python package with a reference implementation for constructing and parsing PURLs: <a class="reference external" href="https://pypi.org/project/packageurl-python/">packageurl-python</a>.</li> </ol> <p>There are multiple possible consumers and use cases of this metadata, once that metadata gets added to Python packages. Tested metadata for all of the top 150 most-downloaded packages from PyPI with published platform-specific wheels can be found in <a class="reference external" href="https://github.com/rgommers/external-deps-build">rgommers/external-deps-build</a>. This metadata has been validated by using it to build wheels from sdists patched with that metadata in clean Docker containers.</p> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="specific-syntax-for-external-dependencies-which-are-also-packaged-on-pypi"> <h3><a class="toc-backref" href="#specific-syntax-for-external-dependencies-which-are-also-packaged-on-pypi" role="doc-backlink">Specific syntax for external dependencies which are also packaged on PyPI</a></h3> <p>There are non-Python packages which are packaged on PyPI, such as Ninja, patchelf and CMake. What is typically desired is to use the system version of those, and if it’s not present on the system then install the PyPI package for it. The authors believe that specific support for this scenario is not necessary (or too complex to justify such support); a dependency provider for external dependencies can treat PyPI as one possible source for obtaining the package.</p> </section> <section id="using-library-and-header-names-as-external-dependencies"> <h3><a class="toc-backref" href="#using-library-and-header-names-as-external-dependencies" role="doc-backlink">Using library and header names as external dependencies</a></h3> <p>A previous draft PEP (<a class="reference external" href="https://github.com/pypa/interoperability-peps/pull/30">“External dependencies” (2015)</a>) proposed using specific library and header names as external dependencies. This is too granular; using package names is a well-established pattern across packaging ecosystems and should be preferred.</p> </section> </section> <section id="open-issues"> <h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2> <section id="version-specifiers-for-purls"> <h3><a class="toc-backref" href="#version-specifiers-for-purls" role="doc-backlink">Version specifiers for PURLs</a></h3> <p>Support in PURL for version expressions and ranges is still pending. The pull request at <a class="reference external" href="https://github.com/package-url/purl-spec/pull/139">vers implementation for PURL</a> seems close to being merged, at which point this PEP could adopt it.</p> </section> <section id="versioning-of-virtual-dependencies"> <h3><a class="toc-backref" href="#versioning-of-virtual-dependencies" role="doc-backlink">Versioning of virtual dependencies</a></h3> <p>Once PURL supports version expressions, virtual dependencies can be versioned with the same syntax. It must be better specified however what the version scheme is, because this is not as clear for virtual dependencies as it is for PURLs (e.g., there can be multiple implementations, and abstract interfaces may not be unambiguously versioned). E.g.:</p> <ul class="simple"> <li>OpenMP: has regular <code class="docutils literal notranslate"><span class="pre">MAJOR.MINOR</span></code> versions of its standard, so would look like <code class="docutils literal notranslate"><span class="pre">>=4.5</span></code>.</li> <li>BLAS/LAPACK: should use the versioning used by <a class="reference external" href="https://github.com/Reference-LAPACK/lapack">Reference LAPACK</a>, which defines what the standard APIs are. Uses <code class="docutils literal notranslate"><span class="pre">MAJOR.MINOR.MICRO</span></code>, so would look like <code class="docutils literal notranslate"><span class="pre">>=3.10.0</span></code>.</li> <li>Compilers: these implement language standards. For C, C++ and Fortran these are versioned by year. In order for versions to sort correctly, we choose to use the full year (four digits). So “at least C99” would be <code class="docutils literal notranslate"><span class="pre">>=1999</span></code>, and selecting C++14 or Fortran 77 would be <code class="docutils literal notranslate"><span class="pre">==2014</span></code> or <code class="docutils literal notranslate"><span class="pre">==1977</span></code> respectively. Other languages may use different versioning schemes. These should be described somewhere before they are used in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>.</li> </ul> <p>A logistical challenge is where to describe the versioning - given that this will evolve over time, this PEP itself is not the right location for it. Instead, this PEP should point at that (to be created) location.</p> </section> <section id="who-defines-canonical-names-and-canonical-package-structure"> <h3><a class="toc-backref" href="#who-defines-canonical-names-and-canonical-package-structure" role="doc-backlink">Who defines canonical names and canonical package structure?</a></h3> <p>Similarly to the logistics around versioning is the question about what names are allowed and where they are described. And then who is in control of that description and responsible for maintaining it. Our tentative answer is: there should be a central list for virtual dependencies and <code class="docutils literal notranslate"><span class="pre">pkg:generic</span></code> PURLs, maintained as a PyPA project. See <a class="reference external" href="https://discuss.python.org/t/pep-725-specifying-external-dependencies-in-pyproject-toml/31888/62">https://discuss.python.org/t/pep-725-specifying-external-dependencies-in-pyproject-toml/31888/62</a>. TODO: once that list/project is prototyped, include it in the PEP and close this open issue.</p> </section> <section id="syntax-for-virtual-dependencies"> <h3><a class="toc-backref" href="#syntax-for-virtual-dependencies" role="doc-backlink">Syntax for virtual dependencies</a></h3> <p>The current syntax this PEP uses for virtual dependencies is <code class="docutils literal notranslate"><span class="pre">virtual:type/name</span></code>, which is analogous to but not part of the PURL spec. This open issue discusses supporting virtual dependencies within PURL: <a class="reference external" href="https://github.com/package-url/purl-spec/issues/222">purl-spec#222</a>.</p> </section> <section id="should-a-host-requires-key-be-added-under-build-system"> <h3><a class="toc-backref" href="#should-a-host-requires-key-be-added-under-build-system" role="doc-backlink">Should a <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> key be added under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code>?</a></h3> <p>Adding <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> for host dependencies that are on PyPI in order to better support name mapping to other packaging systems with support for cross-compiling may make sense. <a class="reference external" href="https://github.com/rgommers/peps/issues/6">This issue</a> tracks this topic and has arguments in favor and against adding <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code> as part of this PEP.</p> </section> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="singular-vision-native-deps" role="doc-footnote"> <dt class="label" id="singular-vision-native-deps">[<a href="#id1">1</a>]</dt> <dd>The “define native requirements metadata” part of the “Wanting a singular packaging vision” thread (2022, Discourse): <a class="reference external" href="https://discuss.python.org/t/wanting-a-singular-packaging-tool-vision/21141/92">https://discuss.python.org/t/wanting-a-singular-packaging-tool-vision/21141/92</a></aside> <aside class="footnote brackets" id="pypacking-native-deps" role="doc-footnote"> <dt class="label" id="pypacking-native-deps">[<a href="#id2">2</a>]</dt> <dd>pypackaging-native: “Native dependencies” <a class="reference external" href="https://pypackaging-native.github.io/key-issues/native-dependencies/">https://pypackaging-native.github.io/key-issues/native-dependencies/</a></aside> <aside class="footnote brackets" id="gcc-cross-terminology" role="doc-footnote"> <dt class="label" id="gcc-cross-terminology">[<a href="#id3">3</a>]</dt> <dd>GCC documentation - Configure Terms and History, <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html</a></aside> <aside class="footnote brackets" id="meson-cross" role="doc-footnote"> <dt class="label" id="meson-cross">[<a href="#id4">4</a>]</dt> <dd>Meson documentation - Cross compilation <a class="reference external" href="https://mesonbuild.com/Cross-compilation.html">https://mesonbuild.com/Cross-compilation.html</a></aside> <aside class="footnote brackets" id="pypackaging-native-cross" role="doc-footnote"> <dt class="label" id="pypackaging-native-cross">[<a href="#id5">5</a>]</dt> <dd>pypackaging-native: “Cross compilation” <a class="reference external" href="https://pypackaging-native.github.io/key-issues/cross_compilation/">https://pypackaging-native.github.io/key-issues/cross_compilation/</a></aside> <aside class="footnote brackets" id="pkgconfig-and-ctypes-findlibrary" role="doc-footnote"> <dt class="label" id="pkgconfig-and-ctypes-findlibrary">[6]</dt> <dd>The “<code class="docutils literal notranslate"><span class="pre">pkgconfig</span></code> specification as an alternative to <code class="docutils literal notranslate"><span class="pre">ctypes.util.find_library</span></code>” thread (2023, Discourse): <a class="reference external" href="https://discuss.python.org/t/pkgconfig-specification-as-an-alternative-to-ctypes-util-find-library/31379">https://discuss.python.org/t/pkgconfig-specification-as-an-alternative-to-ctypes-util-find-library/31379</a></aside> </aside> </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-0725.rst">https://github.com/python/peps/blob/main/peps/pep-0725.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0725.rst">2025-02-01 08:55:40 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></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#types-of-external-dependencies">Types of external dependencies</a></li> <li><a class="reference internal" href="#cross-compilation">Cross compilation</a><ul> <li><a class="reference internal" href="#terminology">Terminology</a></li> <li><a class="reference internal" href="#build-and-host-dependencies">Build and host dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#specifying-external-dependencies">Specifying external dependencies</a><ul> <li><a class="reference internal" href="#concrete-package-specification-through-purl">Concrete package specification through PURL</a></li> <li><a class="reference internal" href="#virtual-package-specification">Virtual package specification</a></li> <li><a class="reference internal" href="#versioning">Versioning</a></li> <li><a class="reference internal" href="#dependency-specifiers">Dependency specifiers</a></li> </ul> </li> <li><a class="reference internal" href="#usage-of-core-metadata-fields">Usage of core metadata fields</a><ul> <li><a class="reference internal" href="#differences-between-sdist-and-wheel-metadata">Differences between sdist and wheel metadata</a></li> <li><a class="reference internal" href="#canonical-names-of-dependencies-and-dev-el-split-packages">Canonical names of dependencies and <code class="docutils literal notranslate"><span class="pre">-dev(el)</span></code> split packages</a></li> <li><a class="reference internal" href="#python-development-headers">Python development headers</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#details">Details</a><ul> <li><a class="reference internal" href="#table-name">Table name</a></li> <li><a class="reference internal" href="#build-requires-optional-build-requires"><code class="docutils literal notranslate"><span class="pre">build-requires</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-build-requires</span></code></a></li> <li><a class="reference internal" href="#host-requires-optional-host-requires"><code class="docutils literal notranslate"><span class="pre">host-requires</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-host-requires</span></code></a></li> <li><a class="reference internal" href="#dependencies-optional-dependencies"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a></li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></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></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="#specific-syntax-for-external-dependencies-which-are-also-packaged-on-pypi">Specific syntax for external dependencies which are also packaged on PyPI</a></li> <li><a class="reference internal" href="#using-library-and-header-names-as-external-dependencies">Using library and header names as external dependencies</a></li> </ul> </li> <li><a class="reference internal" href="#open-issues">Open Issues</a><ul> <li><a class="reference internal" href="#version-specifiers-for-purls">Version specifiers for PURLs</a></li> <li><a class="reference internal" href="#versioning-of-virtual-dependencies">Versioning of virtual dependencies</a></li> <li><a class="reference internal" href="#who-defines-canonical-names-and-canonical-package-structure">Who defines canonical names and canonical package structure?</a></li> <li><a class="reference internal" href="#syntax-for-virtual-dependencies">Syntax for virtual dependencies</a></li> <li><a class="reference internal" href="#should-a-host-requires-key-be-added-under-build-system">Should a <code class="docutils literal notranslate"><span class="pre">host-requires</span></code> key be added under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code>?</a></li> </ul> </li> <li><a class="reference internal" href="#references">References</a></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-0725.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>