PEP 850 – Wheel Variants: Providers | peps.python.org
PEP 850 – Wheel Variants: Providers PEP 850 – Wheel Variants: Providers Author : Michał Górny <mgorny at quansight.com>, Jonathan Dekhtiar <jonathan at dekhtiar.com>, Konstantin Schütze <konstin at mailbox.org>, Ralf Gommers <ralf.gommers at gmail.com> Sponsor : Carol Willing <willingc at gmail.com> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Packaging Requires : 825 Created : 15-Oct-2026 Post-History : 20-Oct-2026 Table of Contents Abstract Motivation Specification Definitions Providers Variant metadata Provider information Example Provider plugin API High-level design API endpoint Variant plugin discovery Variant feature config class Plugin interface Example implementation Future extensions Builtin providers ABI Dependency Variant Provider Rationale Backwards Compatibility Security Implications How to Teach This Reference Implementation Acknowledgements Change History Appendices Copyright Abstract This PEP extends PEP 825 by defining how variant properties are governed and how their compatibility is determined.
This is done either via static feature and feature value compatibility lists specified in the variant metadata, or by querying opt-in plugins that are Python packages but can also be vendored or reimplemented by the tools. A static list can also be provided in place of querying the plugins. Additionally, an ABI Dependency Variant Provider is defined to facilitate builds of the same package against different dependency versions.
Motivation PEP 825 defines a protocol for recording additional compatibility data for binary packages, in the form of variant properties, but does not define how to obtain the matching information for the system. This PEP defines how to determine which variant properties are compatible with a particular system and how variant namespaces are governed. This PEP introduces three different ways of defining and obtaining variant properties for three different use cases: Variants that express platform compatibility, for example GPU or CPU capabilities.
In this case, the goal is to select the best wheel that is compatible with the particular system. Variants that express non-platform properties, such as different BLAS/LAPACK or OpenMP implementations, or debug builds. Here all variants that were built are compatible, and the goal is to provide users with the ability to explicitly select a non-default variant. Variants that express compatibility with different dependency versions, particularly aiming to express Application Binary Interface (ABI) compatibility between extension modules.
The goal is to enable matching variants against other packages, where one source distribution can be narrowed to specific versions of a dependency during build. Specification Definitions The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .
Providers Variant properties, as defined in PEP 825 , are organized into variant namespaces. Every variant namespace used in a variant wheel MUST be governed by a variant provider . Variant providers supply ordered lists of compatible features and feature values corresponding to their namespaces, as required by PEP 825 . The providers for all namespaces used MUST be defined in the provider information dictionary in variant metadata .
This PEP is concerned only with consuming said dictionary; the process of building variant wheels will be covered in a subsequent PEP. Each of these providers either defines a static list of compatible features and their values, specifies a list of requirements referring to Python packages or is one of the builtin providers . Builtin providers are implemented within the installer to handle checks that the plugin API cannot support.
For example, the ABI Dependency Variant Provider checks whether a wheel built against a particular version of a dependency (e.g. PyTorch) is compatible with the version selected during dependency resolution. This requires access to the installer’s dependency resolver. For Python package providers (also called provider plugins), an API endpoint is either explicitly specified or inferred from the first dependency string.
The canonical way of querying the list of compatible features and their values is then to install the specified packages and call this endpoint. The combination of dependency strings and the API endpoint is used to uniquely identify the provider, while the respective version constraints can be used to indicate the minimum versions emitting variant properties used in the package. For security reasons, none of these packages are installed or used by default.
Tools can provide a way to securely use a subset of provider packages, for example through vendoring, a reimplementation or an embedded lockfile. To aid in this, a shared list of such packages along with trusted implementations will be maintained; the details of said list and its governance will be provided in a subsequent PEP. Using provider plugins that are not trusted, such as the actual package from an index fulfilling the requirement, requires explicit user opt-in.
This ensures only trusted code is executed during installation, while still supporting the evolution of providers and establishing clear governance over each namespace. Installers and other tools that need to determine whether a variant is compatible with the system MUST follow the specified algorithm in order to obtain the list of compatible features and feature values for every namespace: The tool SHOULD implement a way for the user to provide a static list of compatible features and their values for a particular provider.
Standardizing this format is left to a future PEP. If the user provides such a list, the tool MUST use it exclusively. Otherwise, proceed to step 2. The tool MUST read the optional key from the provider information to determine whether the variant provider is disabled by default. It SHOULD provide a way to explicitly enable a provider, and MAY provide a way to disable one. If a provider is disabled, the list of compatible features is empty.
Otherwise, proceed to step 3. The tool MUST read the builtin key from the provider information dictionary. If it is present, the tool MUST use the internal provider implementation if supported, or assume that no features are compatible if not. Otherwise, proceed to step 4. The tool MUST read the static-properties key from the provider information dictionary. If it is present, the tool MUST use the static lists of properties therein exclusively.
Otherwise, proceed to step 5. If no static list of compatible features and their values is provided, the tool MUST read the requires and plugin-api keys in the provider information dictionary to determine the packages providing the compatibility information. If the tool provides a secure implementation of the specific provider, it SHOULD obtain the list from that implementation. Otherwise, proceed to step 6. The tool SHOULD provide a way for the user to permit installing specific provider packages.
It MUST NOT install or use any provider packages that are not considered trusted. It SHOULD use an isolated virtual environment while installing provider plugin packages. The tool MUST query the trusted and installed provider packages via the provider plugin API to obtain the list of compatible features and feature values. For providers that were not trusted, it MUST assume that the list of compatible features is empty.
For every unique provider, the tool MUST obtain the list of compatible features and their values only once throughout the install session and use it across all the packages being installed. Variant metadata This PEP extends the metadata introduced in PEP 825 with an additional providers key, described in the Provider information subsection. (root) | +- $schema +- default-priorities +- var
The rest of this page is on the live site.