Text of peps.python.org › pep-0825 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 825 – Wheel Variants: Package Format | peps.python.org

PEP 825 – Wheel Variants: Package Format PEP 825 – Wheel Variants: Package Format Author : Jonathan Dekhtiar <jonathan at dekhtiar.com>, Michał Górny <mgorny at quansight.com>, Konstantin Schütze <konstin at mailbox.org>, Ralf Gommers <ralf.gommers at gmail.com>, Andrey Talman <atalman at meta.com>, Charlie Marsh <charlie at astral.sh>, Michael Sarahan <msarahan at gmail.com>, Eli Uriegas <eliuriegas at meta.com>, Barry Warsaw <barry at python.org>, Donald Stufft <donald at stufft.io>, Andy R.

Terrel <andy.terrel at gmail.com> PEP-Delegate : Paul Moore <p.f.moore at gmail.com> Discussions-To : Discourse thread Status : Provisional Type : Standards Track Topic : Packaging Created : 17-Feb-2026 Post-History : 17-Feb-2026 Resolution : Discourse message Table of Contents Provisional Acceptance Abstract Motivation Specification Definitions Implementation requirements Variant wheel Variant properties Variant label Variant metadata Schema Default priorities Variants Example Index-level metadata Metadata consistency Variant ordering and selection High-level overview Ordering algorithm Environment markers Evaluating variant markers Example Integration with pylock.toml Proposed specification update [packages.variants-json] Example Suggested implementation logic for tools (non-normative) Installing a package from an index Installing a specific local wheel Publishing variant wheels on an index Installation example (non-normative) Installing wheels from multiple sources (non-normative) Rationale Variant metadata consistency Variant environment markers Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas Predictable variant labels Variant label as part of Platform compatibility tag Replacing Platform compatibility tags entirely Removing ordering information from wheel files Out of scope Acknowledgements Change History Appendices Copyright Provisional Acceptance This PEP has been provisionally accepted .

This PEP is part of an extended series of PEPs covering the whole wheel variant feature. Once the full suite of PEPs has been accepted, the acceptance will become final. Abstract This PEP provides the data format for variant wheels, an extension to Wheel distribution format that permits building multiple variants of the same package while embedding additional compatibility data. This data is stored inside the wheel, and expressed via a human-readable variant label in the filename.

When wheels are hosted on an index, it is additionally exposed in a separate JSON file as an optimization. It will be followed by additional PEPs defining the remaining aspects of variant wheels. The final aim of the specification is to make {tool} install {package} capable of selecting the most appropriate variant of packages where additional compatibility dimensions such as GPU support need to be accounted for. Motivation This PEP proposes a protocol to record additional compatibility data in binary packages, to allow tools to pick the correct package to use in situations where Platform compatibility tags are insufficient.

There are many cases where this is necessary, most notably in the case of scientific and machine learning (ML) libraries, where high performance requires extension code that is carefully tailored to the precise hardware available in the user’s environment. Well known examples of this include: PyTorch and other ML tools which depend on the user’s GPU hardware and driver. Scientific libraries like SciPy, which can be linked to different linear algebra libraries.

Libraries such as XGBoost that can be linked to different OpenMP runtimes. Libraries that ship performance enhanced builds which can be used when certain CPU instruction sets are available, such as AVX2 or AVX-512. The problem space has been explored in greater detail in PEP 817 . 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 .

Implementation requirements This specification is written from the perspective of tools producing the various file formats defined or changed in this specification, such as variant wheels, variant metadata files or pylock.toml files. In the context of format definitions, the word “MUST” specifically indicates that the requirement must be satisfied for the data to be considered valid according to this specification.

Tools that produce the data formats according to this specification MUST always produce files that meet the requirements of this specification. Tools that consume this specification’s data formats are not required to verify that the data meets these requirements. A tool SHOULD NOT rely on data that the tool has established does not meet the specification format. The appropriate response depends on the role of the tool, and follows the same pattern as for invalid Core Metadata in wheel files.

Tools that are in a position to reject invalid data at the point it enters the ecosystem, such as a package index accepting an upload, SHOULD do so. Tools that encounter it later, such as an installer resolving a dependency, SHOULD prefer to degrade gracefully rather than fail outright, for example by ignoring the variant wheels and selecting among the remaining ones. Variant wheel A variant wheel is an extension of the wheel format, defined in Wheel distribution format .

It MUST specify a variant label in the filename, which makes it distinct from non-variant wheels. It MUST include a variant metadata file, which maps the variant label to zero or more variant properties . Variant properties Variant properties express the compatibility of binary packages with specific platforms, in addition to Platform compatibility tags . They follow a key-value format, where a key is called a variant feature .

The keys are further grouped into independently governed variant namespaces . Hence, a variant feature consists of a namespace and a feature name, whereas a variant property consists of a namespace, a feature name and a feature value. Variant properties are serialized into a structured 3-tuple of the following format: { namespace } :: { feature_name } :: { feature_value } The properties with which the wheel was built are stored within the wheel, in the variant metadata file.

A variant wheel can specify multiple values corresponding to a variant feature. For the wheel to be considered compatible with a system, at least one value for every feature listed in its properties MUST be compatible with the system. A variant wheel with zero properties is always deemed compatible. The namespace and feature name components MUST be non-empty and consist only of 0-9 , a-z and _ ASCII characters ( ^[a-z0-9_]+$ ).

The feature value MUST be non-empty and consist only of 0-9 , a-z , _ and . ASCII Characters ( ^[a-z0-9_.]+$ ). The available properties and the rules governing their compatibility will be defined in a subsequent PEP. Examples: # the system must be compatible with all of the following x86_64 :: level :: v3 x86_64 :: avx512_bf16 :: on nvidia :: cuda_version_lower_bound :: 12.8 # it must also be compatible with at least one of the following nvidia :: sm_arch :: 120_real nvidia :: sm_arch :: 110_real Variant label The wheel filename template originally defined by PEP 427 is changed to: {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}(-{variant label})?.whl +++++++++++++++++++ The Python tag component MUST NOT start with a digit.

Variant wheels MUST include the variant label component. Conversely, wheels without variant label are non-variant wheels. The variant label MUST be non-empty and consist only of 0-9 , a-z , _ and . ASCII characters ( ^[0-9a-z_.]+$ ). Every variant label MUST uniquely correspond to a specific set of variant properties, which MUST be the same for all wheels using the same label w

The rest of this page is on the live site.