Text of peps.python.org › pep-0725 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 725 – Specifying external dependencies in pyproject.toml | peps.python.org

PEP 725 – Specifying external dependencies in pyproject.toml PEP 725 – Specifying external dependencies in pyproject.toml Author : Pradyun Gedam <pradyunsg at gmail.com>, Jaime Rodríguez-Guerra <jaime.rogue at gmail.com>, Ralf Gommers <ralf.gommers at gmail.com> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Packaging Created : 17-Aug-2023 Post-History : 18-Aug-2023 , 22-Sep-2025 Table of Contents Abstract Motivation Rationale Types of external dependencies Cross compilation Terminology Build and host dependencies Specifying external dependencies Concrete package specification Virtual package specification Versioning Environment markers Canonical names of dependencies and -dev(el) split packages Python development headers New Core Metadata fields Effect of vendoring shared libraries on wheel metadata Dependency groups Optional dependencies versus dependency groups Specification DepURL External dependency specifiers Changes in Core Metadata Deprecations Additions Version bump Changes in pyproject.toml Table name build-requires / optional-build-requires host-requires / optional-host-requires dependencies / optional-dependencies dependency-groups Examples cryptography 39.0 SciPy 1.10 Pillow 10.1.0 NAVis 1.4.0 Spyder 6.0 jupyterlab-git 0.41.0 PyEnchant 3.2.2 With dependency groups Backwards Compatibility Security Implications How to Teach This Reference Implementation Example Rejected Ideas Specific syntax for external dependencies which are also packaged on PyPI Using library and header names as external dependencies Splitting host dependencies with explicit -dev or -devel suffixes Identifier indirections Adding a host-requires key under [build-system] Reusing the Requires-External field in Core Metadata Allowing use of ecosystem-specific version comparison semantics Open Issues References Copyright Abstract 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.

This PEP proposes to add an [external] table to pyproject.toml with seven keys. “build-requires”, “host-requires” and “dependencies” are for specifying three types of required dependencies: build-requires , build tools to run on the build machine host-requires , build dependencies needed for the host machine but also needed at build time. dependencies , needed at runtime on the host machine but not needed at build time.

These three keys also have their optional external counterparts ( optional-build-requires , optional-host-requires , optional-dependencies ), which have the same role that project.optional-dependencies plays for project.dependencies . Finally, dependency-groups offers the same functionality as PEP 735 but for external dependencies. Cross compilation is taken into account by distinguishing between build and host dependencies.

Optional build-time and runtime dependencies are supported too, in a manner analogous to how that is supported in the [project] table. Motivation 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 [1] , [2] . Key motivators for this PEP are to: Enable tools to automatically map external dependencies to packages in other packaging repositories, Make it possible to include needed dependencies in error messages emitted by Python package installers and build frontends, Provide a canonical place for package authors to record this dependency information.

Packaging ecosystems like Linux distros, conda, Homebrew, Spack, and Nix need full sets of dependencies for Python packages, and have tools like pyp2spec (Fedora), Grayskull (conda), and dh_python (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 pyproject.toml or any other standard location.

Other tools resort to extracting dependencies from extension modules and shared libraries inside Python packages, like elfdeps (Fedora). Enabling automating this type of conversion by only using explicitly annotated metadata 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 Repology , Dependabot and libraries.io .

Software bill of materials (SBOM) generation tools may also be able to use this information, e.g. for flagging that external dependencies listed in pyproject.toml but not contained in wheel metadata are likely vendored within the wheel. PEP 770 , which standardizes how SBOMs are included in wheels, contains an instructive section on how that PEP differs from this one. 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. 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. 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. Canonical names and a name mapping mechanism are addressed in PEP 804 .

Rationale Types of external dependencies Multiple types of external dependencies can be distinguished: Concrete packages that can be identified by name and have a canonical location in another language-specific package repository. E.g., Rust packages on crates.io , R packages on CRAN , JavaScript packages on the npm registry . 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. “Virtual” packages, which are names for concepts, types of tools or interfaces. These typically have multiple implementations, which are concrete packages. E.g., a C++ compiler, BLAS, LAPACK, OpenMP, MPI. Concrete packages are straightforward to understand, and are a concept present in 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 vary. Cross compilation Cross compilation is not yet (as of September 2025) well-supported by stdlib modules and pyproject.toml metadata. It is however important when translating external dependencies to those of other packaging systems (with tools like pyp2spec ). Introducing support for cross compilation immediately in this PEP is much easier than extending [external] in the future, hence the authors choose to include this now.

Terminology This PEP uses the following terminology: build machine : the machine on which the package build process is being executed. host machine : the machine on which the produced artifact will be installed and run. build dependency : package required only during the build process. It must be available at build time and is built for the build machine’s OS and architecture. Typical examples include compilers, code generators, and build tools. host dependency : package needed durin

The rest of this page is on the live site.