The limitations of platform compatibility tags

The current wheel format encodes compatibility through three platform tags:

1. Python tag: encoding the minimum Python version and optionally restricting Python distributions (e.g., py3 for any Python 3, py313 for Python 3.13 or newer, cp313 for specifically CPython, 3.13 or newer).
2. ABI tag: encoding the Python ABI required by any extension modules (e.g., none for no requirement, abi3 for the CPython stable ABI, cp313 for extensions requiring CPython 3.13 ABI).
3. Platform tag: currently encoding the operating system, architecture and core system libraries (e.g., any for any platform, manylinux_2_34_x86_64 for x86-64 Linux system with glibc 2.34 or newer, macosx_14_0_arm64 for arm64 macOS 14.0 or newer system.

These tags are limited to expressing the most fundamental properties of the Python interpreter, operating system and the broad CPU architectures. They cannot express anything more detailed, including non-CPU hardware requirements or library ABI constraints.

This lack of flexibility has led many projects to find sub-optimal - yet necessary - workarounds, such as the manual installation command selector provided by the PyTorch team. This complexity represents a fundamental scalability issue with the current tag system that is not extensible enough to handle the combinatorial complexity of build options.

Current workarounds and their drawbacks

Separate package indexes as variants

Projects such as PyTorch and RAPIDS currently distribute packages that approximate “variants” through separate package indexes with custom URLs. We will use the example of PyTorch, while the problem, the workarounds, and the impact on users also apply to other packages.

PyTorch uses a combination of index URLs per accelerator type and local version segments as accelerator tag (such as +cu130, +rocm6.4 or +cpu) . Users need to first determine the correct index URL for their system, and add an index specifically for PyTorch.

pip install torch --index-url https://download.pytorch.org/whl/cu129

Tools need to implement special handling for the way PyTorch uses local version segments. These requirements break the pattern that packages are usually installed with. Problems with installing PyTorch are a very common point of user confusion. To quantify this, on 2025-12-05, 552 out of 8136 (6.8%), of issues on uv’s issue tracker contained the term “torch”.

Security Risk: This approach has unfortunately led to supply chain attacks - more details on the PyTorch Blog. It’s a non-trivial problem to address which has forced the PyTorch team to create a complete mirror of all their dependencies, and is one of the core motivations behind PEP 766.

The complexity of configuration often leads to projects providing ad-hoc installation instructions that do not provide for seamless package upgrades.

pip install xgboost      # NVIDIA GPU variant
pip install xgboost-cpu  # CPU-only variant

cupy
cupy-cuda70 cupy-cuda75 cupy-cuda80 cupy-cuda90 cupy-cuda91
cupy-cuda92 cupy-cuda100 cupy-cuda101 cupy-cuda102
cupy-cuda110 cupy-cuda111 cupy-cuda112 cupy-cuda113 cupy-cuda114
cupy-cuda115 cupy-cuda116 cupy-cuda117 cupy-cuda118 cupy-cuda119
cupy-cuda11x
cupy-cuda120 cupy-cuda121 cupy-cuda122 cupy-cuda123 cupy-cuda124
cupy-cuda125 cupy-cuda126 cupy-cuda127 cupy-cuda128 cupy-cuda129
cupy-cuda12x
cupy-cuda13x
cupy-rocm-4-0 cupy-rocm-4-1 cupy-rocm-4-2 cupy-rocm-4-3
cupy-rocm-4-4 cupy-rocm-4-5 cupy-rocm-5-0 cupy-rocm-5-1
cupy-rocm-5-2 cupy-rocm-5-3 cupy-rocm-5-4 cupy-rocm-5-5
cupy-rocm-5-6 cupy-rocm-5-7 cupy-rocm-5-8 cupy-rocm-5-9
cupy-rocm-6-0 cupy-rocm-6-1 cupy-rocm-6-2 cupy-rocm-6-3
cupy-rocm-7-0 cupy-rocm-7-1

Provides-Extra: minimum-jaxlib
Provides-Extra: cpu
Provides-Extra: ci
Provides-Extra: tpu
Provides-Extra: cuda
Provides-Extra: cuda12
Provides-Extra: cuda13
Provides-Extra: cuda12-local
Provides-Extra: cuda13-local
Provides-Extra: rocm
Provides-Extra: k8s
Provides-Extra: xprof

Impact on scientific computing and AI/ML workflows

The packaging limitations particularly affect scientific computing and AI/ML applications where performance optimization is critical:

The current wheel format’s lack of hardware awareness creates a suboptimal experience for hardware-dependent packages. While plugins help with smaller and well scoped packages, users must currently manually identify the correct variant (e.g., jax[cuda13]) to avoid generic defaults or incompatible combinations. We need a system where pip install jax automatically selects packages matching the user’s hardware, unless explicitly overridden.

Wheel variants are a clear step in the right direction in this regard.

—Michael Hudgins, JAX Developer Infrastructure Lead

They affect everyone from package authors to end users of all skill levels, including students, scientists and engineers:

Accessing compute to run models and process large datasets has been a pain point in scientific computing for over a decade. Today, researchers and data scientists still spend hours to days installing core tools like PyTorch before they can begin their work. This complexity is a significant barrier to entry for users who want to use Python in their daily work. The WheelNext Wheel Variants proposal offers a pathway to address persistent installation and compute-access problems within the broader packaging ecosystem without creating another, new and separate solution. Let’s focus on the big picture of enhancing user experience - it will make a real difference.

—Leah Wasser, Executive Director and Founder of pyOpenSci

Out-of-scope features

This PEP presents the minimal scope required to meet modern heterogenous system needs. It leaves aspects beyond the minimal scope to evolve via tools or future PEPs. A non-exhaustive list of these aspects include:

• The format of a static file to select variants deterministically or include variants in a pylock.toml file,
• The list of variant providers that are vendored or re-implemented by installers,
• The specific opt-in mechanisms and UX for allowing an installer to run non-vendored variant providers,
• How to instruct build backends to emit variants through the PEP 517 mechanism.

Prior art

This problem is not unique to the Python ecosystem, different groups and ecosystems have come up with various answers to that very problem. This section will focus on highlighting the strengths and weaknesses of the different approaches taken by various communities.

pytorch-2.8.0-cpu_mkl_py313_he1d8d61_100.conda      # CPU + MKL variant
pytorch-2.8.0-cuda128_mkl_py313_hf206996_300.conda  # CUDA 12.8 + MKL variant
pytorch-2.8.0-cuda129_mkl_py313_he100a2c_300.conda  # CUDA 12.9 + MKL variant

conda install pytorch mkl

Wheel variant glossary

Variant Wheels

Wheels that share the same distribution name, version, build number, and platform compatibility tags, but are distinctly identified by an arbitrary set of variant properties.

Variant Namespace

An identifier used to group related features provided by a single provider (e.g., nvidia, x86_64, arm, etc.).

Variant Feature

A specific characteristic (key) within a namespace (e.g., version, avx512_bf16, etc.) that can have one or more values.

Variant Property

A 3-tuple (namespace :: feature-name :: feature-value) describing a single specific feature and its value. If a feature has multiple values, each is represented by a separate property.

Variant Label

A string (up to 16 characters) added to the wheel filename to uniquely identify variants.

Null Variant

A special variant with zero variant properties and the reserved label null. Always considered supported but has the lowest priority among wheel variants, while being preferably chosen over non-variant wheels.

Variant Provider

A provider of supported and valid variant properties for a specific namespace, usually in the form of a Python package that implements system detection.

Install-time Provider

A provider implemented as a plugin that can be queried during wheel installation.

Ahead-of-Time Provider

A provider that features a static list of supported properties which is then embedded in the wheel metadata. Such a list can either be embedded in pyproject.toml or provided by a plugin queried at build time.

Overview

Wheel variants introduce a more fine-grained specification of built wheel characteristics beyond what existing wheel tags provide. Individual wheels carry a human-readable label defined at build time, as described in modified wheel filename, and are characterizing using variant property system. The properties are organized into a hierarchical structure of namespaces, features and feature values. When evaluating wheels to install, the installer determines whether variant properties of a given wheel are compatible with the system, and perform variant ordering based on the priority of the compatible variant properties. This is done in addition to determining the compatibility. The ordering by variant properties takes precedence over ordering by tags.

Every variant namespace is governed by a variant provider. There are two kinds of variant providers: install-time providers and ahead-of-time (AoT) providers. Install-time providers require plugins that are queried while installing wheels to determine the set of supported properties and their preference order. For AoT providers, this data is static and embedded in the wheel; it can be either provided directly by the wheel maintainer or queried at wheel build time from an AoT plugin.

Both kinds of plugins are usually implemented as Python packages which implement the provider plugin API, but they may also be vendored or reimplemented by installers to improve security, as outlined in Providers. Plugin packages may be installed in isolated or non-isolated environments. In particular, all plugins may be returned by the get_requires_for_build_wheel() hook of a PEP 517 backend, and therefore installed along with other build dependencies. For this reason, it is important that plugin packages do not narrowly pin dependencies, as that could prevent different packages from being installed simultaneously in the same environment.

Metadata governing variant support is defined in pyproject.toml file, and it is copied into variant.json file in wheels, as explored in metadata in source tree and wheels. Additionally, variant environment markers can be used to define dependencies specific to a subset of variants.

Modified wheel filename

One of the core requirements of the design is to ensure that installers predating this PEP will ignore wheel variant files. This makes it possible to publish both variant wheels and non-variant wheels on a single index, with installers that do not support variants securely ignoring the former, and falling back to the latter.

A variant label component is added to the filename for the twofold purpose of providing a unique mapping from the filename to a set of variant properties, and providing a human-readable identification for the variant. The label is kept short and lowercase to avoid issues with different filesystems. It is added as a --separated component at the end to ensure that the existing filename validation algorithms reject it:

• If both the build tag and the variant label are present, the filename contains too many components. Example:

  numpy-2.3.2-1-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
                                                 ^^^^^^^^^^
  

• If only the variant label is present, the Python tag at third position will be misinterpreted as a build number. Since the build number must start with a digit and no Python tags at the time start with digits, the filename is considered invalid. Example:

  numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
              ^^^^^
  

This behavior was confirmed for a number of existing tools: auditwheel, packaging, pdm, pip, poetry, and uv.

Variant property system

Variant properties serve the purpose of expressing the characteristics of the variant. Unlike platform compatibility tags, they are stored in the variant metadata and therefore do not affect the wheel filename length. They follow a hierarchical key-value design, with the key further broken into a namespace and a feature name. Namespaces are used to group features defined by a single provider, and to avoid conflicts should multiple providers define a feature with the same name. This permits independent governance and evolution of every namespace.

The keys are restricted to lowercase letters, digits, and underscores. Uppercase characters are disallowed to avoid different spellings of the same name. The character set for values is more relaxed, to permit values resembling versions.

Variant properties are serialized into a structured 3-tuple format inspired by Trove Classifiers in PEP 301:

{namespace} :: {feature_name} :: {feature_value}

Properties are used both to determine variant wheel compatibility, and to select the best variant to install. Provider plugins indicate which variant properties are compatible with the system, and order them by importance. This ordering can further be altered in variant wheel metadata.

Variant features can be declared as allowing multiple values to be present within a single variant wheel. If that is the case, these values are matched as a logical OR, i.e. only a single value needs to be compatible with the system for the wheel to be considered supported. On the other hand, features are treated as a logical AND, i.e. all of them need to be compatible. This provides some flexibility in designating variant compatibility while avoiding having to implement a complete boolean logic.

Typically, variant features will be single-value and indicate minimal or mutually exclusive requirements. The system may indicate multiple compatible values. For example, if the feature declares a minimum CUDA runtime version, the provider will indicate compatibility with wheels requiring a minimum version corresponding to the currently installed version or older, e.g. for CUDA 12.8, the compatible minimum versions used in wheels would be, in order of decreasing preference:

nvidia :: cuda_version_lower_bound :: 12.8
nvidia :: cuda_version_lower_bound :: 12.7
nvidia :: cuda_version_lower_bound :: 12.6
...

Similarly, a wheel could indicate its minimum required CPU version, and the provider will indicate all the compatible CPU versions.

Multi-value features are useful for “fat” packages where multiple incompatible targets are supported by a single package. A typical example are GPUs. In this case, the wheel declares a number of supported GPUs, and the provider indicates which GPUs are actually installed (usually one). The wheel is compatible if there is overlap between the two lists.

Null variant

A null variant is a variant wheel with no properties, but distinct from non-variant wheels in having the null variant label and variant metadata. During the transition period, it provides the possibility of providing a distinct fallback for systems that do not support any of the variants provided, and for systems that do support variant wheels at all.

For example, a package with optional GPU support could publish three kinds of wheels:

• Multiple GPU-enabled wheels, each built for a single CUDA version with a matching set of supported GPUs, and used only when the provider plugin indicates that the system is compatible.
• A CPU-only null variant, much smaller than the GPU variants, installed when the provider plugin indicates that no compatible GPU is installed.
• A GPU+CPU non-variant wheel, that will be installed on systems without an installer supporting variants.

Publishing a null variant is optional, and makes sense only if distinct fallbacks provide advantages to the user. If one is published, a wheel variant-enabled installer will prefer it over the non-variant wheel. If it is not, it will fall back to the non-variant wheel instead. The non-variant wheel is also used if variant support is explicitly disabled by an installer flag.

The null variant uses a reserved null label to make it clearly distinguishable from regular variants.

Install-time and Ahead-of-Time providers

The variant wheel metadata specifies what providers are used for its properties. Providers serve a twofold purpose:

1. at install time: determining which variant wheels are compatible with the user’s system, and which of them constitutes the best choice, and
2. at build time: determining which variant properties are valid for building a wheel.

The specification proposes two kinds of providers: install-time providers and Ahead-of-Time providers.

Install-time providers are implemented either as Python packages that need to be installed and run to query them, or vendored or reimplemented in the tools. They are used when user systems need to be queried to determine wheel compatibility, for example for variants utilizing GPUs or requiring CPU instruction sets beyond what platform tags provide. Installing third-party packages involves security risks highlighted in the security implications section, and the proposed mitigations incur a cost on installer implementations.

Ahead-of-Time providers are implemented as static metadata embedded in the wheel. They are used when particular variant properties are always compatible with the user’s system (provided that a wheel using them has been built successfully). However, the metadata indicates which properties are preferred. For example, AoT providers can be used to provide choice between builds against different BLAS / LAPACK providers, or to provide debug builds of packages. Since they do not require running code external to the installer, they do not pose the problems faced by install-time providers, and can be used more liberally.

AoT providers are permitted to feature plugin packages. If that is the case, these packages are only used when building wheels, and their output is used to fill in the static metadata used at install time. This way, it is easier to use consistent property names and values across multiple packages. Otherwise, the package maintainer needs to include the supported properties directly in the pyproject.toml file.

When implemented as Python packages, both kinds of provider plugins expose roughly the same API. However, an AoT provider must always consider all valid variant properties supported, and it must always return the same ordered list of supported properties irrespective of the user system. All AoT providers can technically be used as install-time providers, but not the other way around.

Plugin stability and versioning

As the specification introduces the potential necessity of installing and running provider packages to install wheels, it is recommended that these packages remain functioning correctly for the variant wheels published in the past, including very old package versions. Ideally, no properties previously supported should ever be removed.

If a breaking change needs to be performed, it is recommended to either introduce a new provider package for that, or add a new plugin API endpoint to the existing package. In both cases, it may be necessary to preserve the old endpoint in minimal maintenance mode, to ensure that old wheels can still be installed. The old endpoint can trigger deprecation warnings in the get_all_configs() hook that is used when building packages.

An alternative approach is to use semantic versioning to cut off breaking changes. However, this relies on package authors reliably using caps on dependencies, as otherwise old wheels will start using incompatible plugin versions. This is already a problem with Python build backends used today.

When vendoring or reimplementing plugins, installers need to follow their current behavior. In particular, they should recognize the relevant provider versions numbers, and possibly fall back to installing the external plugin when the package in question is incompatible with the installer’s implementation.

Metadata in source tree and wheels

Variants introduce a few new portions of metadata that are stored in the source tree and in wheels. In the source tree, it is stored in the pyproject.toml file along with other project properties, benefiting from the TOML format’s readability and strictness. Afterwards, it is converted into an equivalent JSON structure, and stored as a separate file in the .dist-info directory. The existing metadata files are unchanged to avoid unnecessary incompatibility, and to avoid serializing into the inconvenient Core Metadata format.

The metadata in pyproject.toml includes:

• information about variant providers that could be used by the wheels,
• optionally, lists overriding the default property ordering,
• static property lists for Ahead-of-Time providers that do not use plugins.

In wheel metadata, the above is amended by static property lists obtained from the plugins and variant properties for the built wheel.

When wheels are published on an index, the variant metadata from all wheels is combined into a single {name}-{version}-variants.json file that is used by clients to efficiently obtain the variant metadata without having to download it from individual wheels separately, or implement explicit variant metadata support in an API provided by the package index server.

ABI dependency variant provider

Some packages provide extension modules exposing an Application Binary Interface (ABI) that is not compatible across wide ranges of versions. The packages using this interface need to pin their wheels to the version used at build time. If ABI changes frequently, the pins are very narrow and users face problems if they need to install two packages that may happen to pin to different versions of the same dependency. Providing variants built against different dependency versions can increase the chance of a resolver being able to find a dependency version that is compatible with all the packages being installed.

Unfortunately, such a variant provider cannot be implemented within the plugin API defined by the specification. Given that a robust implementation would need to interface with the dependency resolver, rather than attempt to extend the API to cover this use case and add significant complexity as a result, the specification reserves abi_dependency as a special variant namespace that can be implemented by installers wishing the provide this feature.

Given the complexity of the problem, this extension is made entirely optional. This implies that any packages using it need to provide non-variant wheels as well.

Example use cases

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.

Extended wheel filename

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
                                                                             +++++++++++++++++++

Wheels using extensions introduced by this PEP MUST feature the variant label component. The label MUST adhere to the following rules:

• Lower case only (to prevent issues with case-sensitive vs. case-insensitive filesystems)
• Between 1-16 characters
• Using only 0-9, a-z, . or _ ASCII characters

This is equivalent to the following regular expression: ^[0-9a-z._]{1,16}$.

Every label MUST uniquely correspond to a specific set of variant properties, which MUST be the same for all wheels using the same label within a single package version. Variant labels SHOULD be specified at wheel build time, as human-readable strings. The label null is reserved for the null variant and MUST use an empty set of variant properties.

Installers that do not implement this specification MUST ignore wheels with variant label when installing from an index, and fall back to a wheel without such label if it is available. If no such wheel is available, the installer SHOULD output an appropriate diagnostic, in particular warning if it results in selecting an earlier package version or a clear error if no package version can be installed.

Examples:

• Non-variant wheel: numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64.whl
• Wheel with variant label: numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl

Variant properties

Every variant wheel MUST be described by zero or more variant properties. A variant wheel with exactly zero properties represents the null variant. The properties are specified when the variant wheel is being built, using a mechanism defined by the project’s build backend.

Each variant property is described by a 3-tuple that is serialized into the following format:

{namespace} :: {feature_name} :: {feature_value}

The namespace MUST consist only of 0-9, a-z and _ ASCII characters (^[a-z0-9_]+$). It MUST correspond to a single variant provider.

The feature name MUST consist only of 0-9, a-z and _ ASCII characters (^[a-z0-9_]+$). It MUST correspond to a valid feature name defined by the respective variant provider in the namespace.

The feature value MUST consist only of 0-9, a-z, _ and . ASCII Characters (^[a-z0-9_.]+$). It MUST correspond to a valid value defined by the respective variant provider for the feature.

If a feature is marked as “multi-value” by the provider plugin, a single variant wheel can define multiple properties sharing the same namespace and feature name. Otherwise, there MUST NOT be more than a single value corresponding to a single pair of namespace and feature name within a variant wheel.

For a variant wheel to be considered compatible with the system, all of the features defined within it MUST be determined to be compatible. For a feature to be compatible, at least a single value corresponding to it MUST be compatible.

Examples:

# all of the following must be supported
x86_64 :: level :: v3
x86_64 :: avx512_bf16 :: on
nvidia :: cuda_version_lower_bound :: 12.8
# additionally, at least one of the following must be supported
nvidia :: sm_arch :: 120_real
nvidia :: sm_arch :: 110_real

Providers

When installing or resolving variant wheels, installers SHOULD query the variant provider to verify whether a given wheel’s properties are compatible with the system and to select the best variant through variant ordering. However, they MAY provide an option to omit the verification and install a specified variant explicitly.

Providers can be marked as install-time or ahead-of-time. For install-time providers, installers MUST use the provider package or an equivalent reimplementation to query variant property compatibility. For ahead-of-time providers, they MUST use the static metadata embedded in the wheel instead.

Providers can be marked as optional. If a provider is marked optional, then the installer MUST NOT query said provider by default, and instead assume that its properties are incompatible. It SHOULD provide an option to enable optional providers.

Providers can also be made conditional to Environment Markers. If that is the case, the installer MUST check the markers against the environment to which wheels are going to be installed. It MUST NOT use any providers whose markers do not match, and instead assume that their properties are incompatible.

All the tools that need to query variant providers and are run in a security-sensitive context, MUST NOT install or run code from any untrusted package for variant resolution without explicit user opt-in. Install-time provider packages SHOULD take measures to guard against supply chain attacks, for example by vendoring all dependencies.

It is RECOMMENDED that said tools vendor, reimplement or lock the most commonly used plugins to specific wheels. For plugins and their dependencies that are neither reimplemented, vendored nor otherwise vetted, a trust-on-first-use mechanism for every version is RECOMMENDED. In interactive sessions, the tool can explicitly ask the user for approval. In non-interactive sessions, the approval can be given using command-line interface options. It is important that the user is informed of the risk before giving such an approval.

For a consistent experience between tools, variant wheels SHOULD be supported by default. Tools MAY provide an option to only use non-variant wheels.

Variant metadata

This section describes the metadata format for the providers, variants and properties of a package and its wheels. The format is used in three locations, with slight variations:

1. in the source tree, inside the pyproject.toml file
2. in the built wheel, as a *.dist-info/variant.json file
3. on the package index, as a {name}-{version}-variants.json file.

All three variants metadata files share a common JSON-compatible structure:

(root)
|
+- providers
|  +- {namespace}
|     +- enable-if     : str | None = None
|     +- install-time  : bool       = True
|     +- optional      : bool       = False
|     +- plugin-api    : str | None = None
|     +- requires      : list[str]  = []
|
+- default-priorities
|  +- namespace        : list[str]
|  +- feature
|     +- {namespace}   : list[str]  = []
|  +- property
|     +- {namespace}
|        +- {feature}  : list[str]  = []
|
+- static-properties
|  +- {namespace}
|     +- {feature}     : list[str]  = []
|
+- variants
  +- {variant_label}
     +- {namespace}
        +- {feature}   : list[str]  = []

The top-level object is a dictionary rooted at a specific point in the containing file. Its individual keys are sub-dictionaries that are described in the subsequent sections, along with the requirements for their presence. The tools MUST ignore unknown keys in the dictionaries for forwards compatibility of updates to the PEP. However, users MUST NOT use unsupported keys to avoid potential future conflicts.

A JSON schema is included in the Appendix of this PEP, to ease comprehension and validation of the metadata format. This schema will be updated with each revision to the variant metadata specification. The schema is available in Appendix: JSON Schema for Variant Metadata.

Ultimately, the variant metadata JSON schema SHOULD be served by packaging.python.org.

[variant.default-priorities]
# prefer CPU features over BLAS/LAPACK variants
namespace = ["x86_64", "aarch64", "blas_lapack"]

# prefer aarch64 version and x86_64 level features over other features
# (specific CPU extensions like "sse4.1")
feature.aarch64 = ["version"]
feature.x86_64 = ["level"]

# prefer x86-64-v3 and then older (even if CPU is newer)
property.x86_64.level = ["v3", "v2", "v1"]

[variant.providers.aarch64]
# example using different package based on Python version
requires = [
   "provider-variant-aarch64 >=0.0.1; python_version >= '3.12'",
   "legacy-provider-variant-aarch64 >=0.0.1; python_version < '3.12'",
]
# use only on aarch64/arm machines
enable-if = "platform_machine == 'aarch64' or 'arm' in platform_machine"
plugin-api = "provider_variant_aarch64.plugin:AArch64Plugin"

[variant.providers.x86_64]
requires = ["provider-variant-x86-64 >=0.0.1"]
# use only on x86_64 machines
enable-if = "platform_machine == 'x86_64' or platform_machine == 'AMD64'"
plugin-api = "provider_variant_x86_64.plugin:X8664Plugin"

[variant.providers.blas_lapack]
# plugin-api inferred from requires
requires = ["blas-lapack-variant-provider"]
# plugin used only when building package, properties will be inlined
# into variant.json
install-time = false

{
  // The schema URL will be replaced with the final URL on packaging.python.org
  "$schema": "https://variants-schema.wheelnext.dev/v0.0.3.json",
  "default-priorities": {
     "feature": {
        "aarch64": ["version"],
        "x86_64": ["level"]
     },
     "namespace": ["x86_64", "aarch64", "blas_lapack"],
     "property": {
        "x86_64": {
           "level": ["v3", "v2", "v1"]
        }
     }
  },
  "providers": {
     "aarch64": {
        "enable-if": "platform_machine == 'aarch64' or 'arm' in platform_machine",
        "plugin-api": "provider_variant_aarch64.plugin:AArch64Plugin",
        "requires": [
           "provider-variant-aarch64 >=0.0.1; python_version >= '3.12'",
           "legacy-provider-variant-aarch64 >=0.0.1; python_version < '3.12'"
        ]
     },
     "blas_lapack": {
        "install-time": false,
        "requires": ["blas-lapack-variant-provider"]
     },
     "x86_64": {
        "enable-if": "platform_machine == 'x86_64' or platform_machine == 'AMD64'",
        "plugin-api": "provider_variant_x86_64.plugin:X8664Plugin",
        "requires": ["provider-variant-x86-64 >=0.0.1"]
     }
  },
  "static-properties": {
     "blas_lapack": {
        "provider": ["accelerate", "openblas", "mkl"]
     },
  },
  "variants": {
     // always a single entry, expressing the variant properties of the wheel
     "x8664v3_openblas": {
        "blas_lapack": {
           "provider": ["openblas"]
        },
        "x86_64": {
           "level": ["v3"]
        }
     }
  }
}

{
  // The schema URL will be replaced with the final URL on packaging.python.org
  "$schema": "https://variants-schema.wheelnext.dev/v0.0.3.json",
  "default-priorities": {
     // identical to above
  },
  "providers": {
     // identical to above
  },
  "static-properties": {
     // identical to above
  },
  "variants": {
     // all available wheel variants
     "x8664v3_openblas": {
        "blas_lapack": {
           "provider": ["openblas"]
        },
        "x86_64": {
           "level": ["v3"]
        }
     },
     "x8664v4_mkl": {
        "blas_lapack": {
           "provider": ["mkl"]
        },
        "x86_64": {
           "level": ["v4"]
        }
     }
 }
}

Variant ordering

To determine which variant wheel to install when multiple wheels are compatible, variant wheels MUST be ordered by their variant properties.

For the purpose of ordering, variant properties are grouped into features, and features into namespaces. The ordering MUST be equivalent to the following algorithm:

1. Construct the ordered list of namespaces by copying the value of the default-priorities.namespace key.
2. For every namespace:
   1. Construct the initial ordered list of feature names by copying the value of the respective default-priorities.feature.{namespace} key.
   2. Obtain the supported feature names from the provider, in order. For every feature name that is not present in the constructed list, append it to the end.

   After this step, a list of ordered feature names is available for every namespace.

3. For every feature:
   1. Construct the initial ordered list of values by copying the value of the respective default-priorities.property.{namespace}.{feature_name} key.
   2. Obtain the supported values from the provider, in order. For every value that is not present in the constructed list, append it to the end.

   After this step, a list of ordered property values is available for every feature.

4. For every variant property present in at least one of the compatible variant wheels, construct a sort key that is a 3-tuple consisting of its namespace, feature name and feature value indices in the respective ordered lists.
5. For every compatible variant wheel, order its properties by their sort keys, in ascending order.
6. To order variant wheels, compare their sorted properties. If the properties at the first position are different, the variant with the lower 3-tuple of the respective property is sorted earlier. If they are the same, compare the properties at the second position, and so on, until either a tie-breaker is found or the list of properties of one wheel is exhausted. In the latter case, the variant with more properties is sorted earlier.

After this process, the variant wheels are sorted from the most preferred to the least preferred. The null variant naturally sorts after all the other variants, and the non-variant wheel MUST be sorted after the null variant. Multiple wheels with the same variant set (and multiple non-variant wheels) MUST then be ordered according to their platform compatibility tags.

Alternatively, the sort algorithm for variant wheels could be described using the following pseudocode. For simplicity, this code does not account for non-variant wheels or tags.

from typing import Self


def get_supported_feature_names(namespace: str) -> list[str]:
    """Get feature names from plugin's get_supported_configs()"""
    ...


def get_supported_feature_values(namespace: str, feature_name: str) -> list[str]:
    """Get feature values from plugin's get_supported_configs()"""
    ...


# default-priorities dict from variant metadata
default_priorities = {
    "namespace": [...],  # : list[str]
    "feature": {...},    # : dict[str, list[str]]
    "property": {...},   # : dict[str, dict[str, list[str]]]
}


# 1. Construct the ordered list of namespaces.
namespace_order = default_priorities["namespace"]
feature_order = {}
value_order = {}

for namespace in namespace_order:
    # 2. Construct the ordered lists of feature names.
    feature_order[namespace] = default_priorities["feature"].get(namespace, [])
    for feature_name in get_supported_feature_names(namespace):
        if feature_name not in feature_order[namespace]:
            feature_order[namespace].append(feature_name)

   value_order[namespace] = {}
   for feature_name in feature_order[namespace]:
        # 3. Construct the ordered lists of feature values.
        value_order[namespace][feature_name] = (
            default_priorities["property"].get(namespace, {}).get(feature_name, [])
        )
        for feature_value in get_supported_feature_values(namespace, feature_name):
            if feature_value not in value_order[namespace][feature_name]:
                value_order[namespace][feature_name].append(feature_value)


def property_key(prop: tuple[str, str, str]) -> tuple[int, int, int]:
    """Construct a sort key for variant property (akin to step 4.)"""
    namespace, feature_name, feature_value = prop
    return (
        namespace_order.index(namespace),
        feature_order[namespace].index(feature_name),
        value_order[namespace][feature_name].index(feature_value),
    )


class VariantWheel:
    """Example class exposing properties of a variant wheel"""
    properties: list[tuple[str, str, str]]

    def __lt__(self: Self, other: Self) -> bool:
        """Variant comparison function for sorting (akin to step 6.)"""
        for self_prop, other_prop in zip(self.properties, other.properties):
            if self_prop != other_prop:
                return property_key(self_prop) < property_key(other_prop)
        return len(self.properties) > len(other.properties)


# A list of variant wheels to sort.
wheels: list[VariantWheel] = [...]


for wheel in wheels:
    # 5. Order variant wheel properties by their sort keys.
    wheel.properties.sort(key=property_key)
# 6. Order variant wheels by comparing their sorted properties
# (see VariantWheel.__lt__())
wheels.sort()

Integration with pylock.toml

The following section is added to the pylock.toml Specification:

.. _pylock-packages-variants-json:

``[packages.variants-json]``
----------------------------

- **Type**: table
- **Required?**: no; requires that :ref:`pylock-packages-wheels` is used,
 mutually-exclusive with :ref:`pylock-packages-vcs`,
 :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`.
- **Inspiration**: uv_
- The URL or path to the ``variants.json`` file.
- Only used if the project uses :ref:`wheel variants <wheel-variants>`.

.. _pylock-packages-variants-json-url:

``packages.variants-json.url``
''''''''''''''''''''''''''''''

See :ref:`pylock-packages-archive-url`.

.. _pylock-packages-variants-json-path:

``packages.variants-json.path``
'''''''''''''''''''''''''''''''

See :ref:`pylock-packages-archive-path`.

.. _pylock-packages-variants-json-hashes:

``packages.variants-json.hashes``
'''''''''''''''''''''''''''''''''

See :ref:`pylock-packages-archive-hashes`.

If there is a [packages.variants-json] section, the installer SHOULD resolve variants to select the best wheel file.

Provider plugin API

{import_path}(:{object_path})?

import {import_path}

if "{object_path}":
    plugin = {import_path}.{object_path}
else:
    plugin = {import_path}

from abc import abstractmethod
from typing import Protocol


class VariantFeatureConfigType(Protocol):
    @property
    @abstractmethod
    def name(self) -> str:
        """Feature name"""
        raise NotImplementedError

    @property
    @abstractmethod
    def multi_value(self) -> bool:
        """Does this property allow multiple values per variant?"""
        raise NotImplementedError

    @property
    @abstractmethod
    def values(self) -> list[str]:
        """List of values, possibly ordered from most preferred to least"""
        raise NotImplementedError

from abc import abstractmethod
from typing import Protocol


class PluginType(Protocol):
    # Note: properties are used here for docstring purposes, these
    # must be actually implemented as attributes.

    @property
    @abstractmethod
    def namespace(self) -> str:
        """The provider namespace"""
        raise NotImplementedError

    @property
    def is_aot_plugin(self) -> bool:
        """Is this plugin valid for `install-time = false`?"""
        return False

    @classmethod
    @abstractmethod
    def get_all_configs(cls) -> list[VariantFeatureConfigType]:
        """Get all valid configs for the plugin"""
        raise NotImplementedError

    @classmethod
    @abstractmethod
    def get_supported_configs(cls) -> list[VariantFeatureConfigType]:
        """Get supported configs for the current system"""
        raise NotImplementedError

from dataclasses import dataclass


@dataclass
class VariantFeatureConfig:
    name: str
    values: list[str]
    multi_value: bool


# internal -- provided for illustrative purpose
_MAX_VERSION = 4
_ALL_GPUS = ["narf", "poit", "zort"]


def _get_current_version() -> int:
    """Returns currently installed runtime version"""
    ...  # implementation not provided


def _is_gpu_available(codename: str) -> bool:
    """Is specified GPU installed?"""
    ...  # implementation not provided


class MyPlugin:
    namespace = "example"

    # optional, defaults to False
    is_aot_plugin = False

    # all valid properties
    @staticmethod
    def get_all_configs() -> list[VariantFeatureConfig]:
        return [
            VariantFeatureConfig(
                # example :: gpu -- multi-valued, since the package
                # can target multiple GPUs
                name="gpu",
                # [narf, poit, zort]
                values=_ALL_GPUS,
                multi_value=True,
            ),
            VariantFeatureConfig(
                # example :: min_version -- single-valued, since
                # there is always one minimum
                name="min_version",
                # [1, 2, 3, 4] (order doesn't matter)
                values=[str(x) for x in range(1, _MAX_VERSION + 1)],
                multi_value=False,
            ),
        ]

    # properties compatible with the system
    @staticmethod
    def get_supported_configs() -> list[VariantFeatureConfig]:
        current_version = _get_current_version()
        if current_version is None:
            # no runtime found, system not supported at all
            return []

        return [
            VariantFeatureConfig(
                name="min_version",
                # [current, current - 1, ..., 1]
                values=[str(x) for x in range(current_version, 0, -1)],
                multi_value=False,
            ),
            VariantFeatureConfig(
                name="gpu",
                # this may be empty if no GPUs are supported --
                # 'example :: gpu feature' is not supported then;
                # but wheels with no GPU-specific code and only
                # 'example :: min_version' could still be installed
                values=[x for x in _ALL_GPUS if _is_gpu_available(x)],
                multi_value=True,
            ),
        ]

Build backends

As a build backend can’t determine whether the frontend supports variant wheels or not, PEP 517 and PEP 660 hooks MUST build non-variant wheels by default. Build backends MAY provide ways to request variant builds. This specification does not define any specific configuration.

When building variant wheels, build backends MUST verify variant metadata for correctness, and they MUST NOT emit wheels with nonconformant variant.json files. They SHOULD also query providers to determine whether variant properties requested by the user are valid, though they MAY permit skipping this verification and therefore emitting variant wheels with potentially unknown properties.

Variant environment markers

Four new environment markers are introduced in dependency specifications:

1. variant_namespaces corresponding to the set of namespaces of all the variant properties that the wheel variant was built for.
2. variant_features corresponding to the set of namespace :: feature pairs of all the variant properties that the wheel variant was built for.
3. variant_properties corresponding to the set of namespace :: feature :: value tuples of all the variant properties that the wheel variant was built for.
4. variant_label corresponding to the exact variant label that the wheel was built with. For the non-variant wheel, it is an empty string.

The markers evaluating to sets of strings MUST be matched via the in or not in operator, e.g.:

# satisfied by any "foo :: * :: *" property
dep1; "foo" in variant_namespaces
# satisfied by any "foo :: bar :: *" property
dep2; "foo :: bar" in variant_features
# satisfied only by "foo :: bar :: baz" property
dep3; "foo :: bar :: baz" in variant_properties

The variant_label marker is a plain string:

# satisfied by the variant "foobar"
dep4; variant_label == "foobar"
# satisfied by any wheel other other than the null variant
# (including the non-variant wheel)
dep5; variant_label != "null"
# satisfied by the non-variant wheel
dep6; variant_label == ""

Implementations MUST ignore differences in whitespace while matching the features and properties.

Variant marker expressions MUST be evaluated against the variant properties stored in the wheel being installed, not against the current output of the provider plugins. If a non-variant wheel was selected or built, all variant markers evaluate to False.

ABI Dependency Variant Namespace (Optional)

This section describes an OPTIONAL extension to the wheel variant specification. Tools that choose to implement this feature MUST follow this specification. Tools that do not implement this feature MUST treat the variants using it as incompatible, and SHOULD inform users when such wheels are skipped.

The variant namespace abi_dependency is reserved for expressing that different builds of the same version of a package are compatible with different versions or version ranges of a dependency. This namespace MUST NOT be used by any variant provider plugin, it MUST NOT be listed in providers metadata, and can only appear in a built wheel variant property.

Within this namespace, zero or more properties can be used to express compatible dependency versions. For each property, the feature name MUST be the normalized name of the dependency, whereas the value MUST be a valid release segment of a public version identifier, as defined by the Version specifiers specification. It MUST contain up to three version components, that are matched against the installed version same as the =={value}.* specifier. Notably, trailing zeroes match versions with fewer components (e.g. 2.0 matches release 2 but not 2.1). This also implies that the property values have different semantics than PEP 440 versions, in particular 2, 2.0 and 2.0.0 represent different ranges.

Versions with nonzero epoch are not supported.

Multiple variant properties with the same feature name can be used to indicate wheels compatible with multiple providing package versions, e.g.:

abi_dependency :: torch :: 2.8.0
abi_dependency :: torch :: 2.9.0

This means the wheel is compatible with both PyTorch 2.8.0 and 2.9.0.

Python package users

The primary source of information for Python package users should be installer documentation, supplemented by helpful informational messages from command-line interface, and tutorials. Users without special needs should not require any special variant awareness. Advanced users would specifically need documentation on (provided the installer in question implements these features):

• enabling untrusted provider plugins and the security implications of that
• controlling provider usage, in particular enabling optional providers, disabling undesirable plugins or disabling variant usage in general
• explicitly selecting variants, as well as controlling variant selection process
• configuring variant selection for remote deployment targets, for example using a static file generated on the target

The installer documentation may also be supplemented by documentation specific to Python projects, in particular their installation instructions.

For the transition period, during which some package managers do and some do not support variant wheels, users need to be aware that certain features may only be available with certain tools.

Python package maintainers

The primary source of information for maintainers of Python packages should be build backend documentation, supplemented by tutorials. The documentation needs to indicate:

• how to declare variant support in pyproject.toml
• how to use variant environment markers to specify dependencies
• how to build variant wheels
• how to publish them and generate the *-variants.json file on local indexes

The maintainers will also need to peruse provider plugin documentation. They should also be aware which provider plugins are considered trusted by commonly used installers, and know the implications of using untrusted plugins. These materials may also be supplemented by generic documents explaining publishing variant wheels, along with specific example use cases.

For the transition period, package maintainers need to be aware that they should still publish non-variant wheels for backwards compatibility.

An approach without provider plugins

The support for additional variant properties could technically be implemented without introducing provider plugins, but rather defining the available properties and their discovery methods as part of the specification, much like how wheel tags are implemented currently. However, the existing wheel tag logic already imposes a significant complexity on packaging tools that need to maintain the logic for generating supported tags, partially amortized by the data provided by the Python interpreter itself.

Every new axis would be imposing even more effort on package manager maintainers, who would have to maintain an algorithm to determine the property compatibility. This algorithm could become quite complex, possibly needing to account for different platforms, hardware versions and requiring more frequent updates than the one for platform tags. This would also significantly increase the barrier towards adding new axes and therefore the risk of lack of feature parity between different installers, as every new axis will be imposing additional maintenance cost.

For comparison, the plugin design essentially democratizes the variant properties. Provider plugins can be maintained independently by people having the necessary knowledge and hardware. They can be updated as frequently as necessary, independently of package managers. The decision to use a particular provider falls entirely on the maintainer of package needing it, though they need to take into consideration that using plugins that are not vetted by the common installers will inconvenience their users.

Resolving variants to separate packages

An alternative proposal was to publish the variants of the package as separate projects on the index, along with the main package serving as a “resolver” directing to other variants via its metadata. For example, a torch package could indicate the conditions for using torch-cpu, torch-cu129, etc. subpackages.

Such an approach could possibly feature better backwards compatibility with existing tools. The changes would be limited to installers, and even with pre-variant installers the users could explicitly request installing a specific variant. However, it poses problems at multiple levels.

The necessity of creating a new project for every variant will lead to the proliferation of old projects, such as torch-cu123. While the use of resolver package will ensure that only the modern variants are used, users manually installing packages and cross-package dependencies may accidentally be pinning to old variant projects, or even fall victim to name squatting. For comparison, the variant wheel proposal scopes variants to each project version, and ensures that only the project maintainers can upload them.

Furthermore, it requires significant changes to the dependency resolver and package metadata formats. In particular, the dependency resolver would need to query all “resolver” packages before performing resolution. It is unclear how to account for such variants while performing universal resolution. The one-to-one mapping between dependencies and installed packages would be lost, as a torch dependency could effectively be satisfied by torch-cu129.