Abstract

This PEP is a followup to PEP 825 that defines how variant properties are governed and how their compatibility is determined. This is primarily done via opt-in plugins that are Python packages specified in variant metadata, but can also be vendored or reimplemented by the tools. Package maintainers and users can only supply static compatibility data to avoid the need for plugins.

Motivation

PEP 825 introduced a protocol for recording additional compatibility data in binary packages, in the form of variant properties. It provided the foundations by organizing the variant properties into namespaces. However, it did not specify how variant namespaces are governed, nor how to determine which variant properties are compatible with a particular use system. This PEP aims to fill this gap.

The PEP is specifically aiming to make variant wheels suitable for satisfying three use cases:

1. 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.
2. 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 user with the ability to explicitly select a non-default variant.
3. Variants that express compatibility with different dependency versions, particularly aiming to express Application Binary Interface (ABI) compatibility. The goal is to enable matching variants against other packages, especially if they adapt new versions of common dependencies at different rates.

Specification

(root)
|
+- $schema
+- default-priorities
+- variants
+- providers
   +- {namespace}
      +- optional          : bool       = False
      +- plugin-api        : str | None = None
      +- requires          : list[str]  = []
      +- static-properties
         +- {feature}      : list[str]  = []

{API endpoint}.{callable name}({arguments}...)

{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):
    @classmethod
    @abstractmethod
    def get_supported_configs(cls) -> list[VariantFeatureConfigType]:
        """Get ordered lists of compatible features and their values"""
        raise NotImplementedError

from dataclasses import dataclass


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


# internal -- provided for illustrative purpose
_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:
    @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,
            ),
        ]

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

Rationale

The primary use case for providers is determining platform compatibility, which implies that they need to be used at install time. The specification proposes a plugin mechanism using Python packages, with the interface inspired by PEP 517. Such a mechanism has a few advantages:

• The individual plugins can be governed independently, by the stakeholders having necessary knowledge and hardware. Additional compatibility axes (new CPUs, GPUs) do not impose direct maintenance costs on tools interacting with variant wheels, nor on centrally-maintained libraries such as packaging.
• The plugins can be updated as frequently as necessary, without being tied to tool release schedules.
• The plugins provide a unified interface for testing new providers. New plugins can be developed and tested locally without having to patch multiple tools, and released to the public after proving the concept.

At the same time, it is understood that installing additional Python packages and running the code from them at install time introduces additional attack vector (as discussed in security implications). For this reason, plugin packages are entirely opt-in, and a few mechanisms are provided to improve the user experience without compromising security:

• Users can provide static compatibility lists to avoid querying the providers. This also permits deploying packages for different systems than the one running the installer.
• Tools can maintain their own lists of trusted provider plugins that are enabled by default, or they can vendor or reimplement some providers. This is entirely voluntary, as not to impose maintenance effort on tool maintainers. At the same time, the ability to reimplement providers avoids introducing a performance bottleneck on tools that aren’t written in Python.
• Variant wheels can include static lists of compatible properties, to facilitate variants that do not need querying platform capabilities, such as builds done against different BLAS/LAPACK libraries.

Furthermore, individual providers can be disabled by default (made optional), to introduce variants that can only be selected explicitly, for example debug or experimental builds of packages.

Installing provider plugins in isolated environments is recommended, as that permits tools to automatically deploy them without affecting the system packages. However, this is not a requirement to permit other options. For example, build backends may prefer reusing the isolated build environment for this.

The requires and plugin-api keys follow the precedent of build-system.requires and build-system.build-backend keys of PEP 517. However, following the criticism of that design, plugin-api has been made optional and defaults to being inferred from the package name.

The ABI Dependency Variant Provider is defined separately, as it needs to interact with the dependency resolver. To avoid adding significant complexity to the plugin API and at the same time restricting the actual implementation, it has been made a special case. It is entirely optional to avoid adding maintenance burden to tool maintainers.

Backwards Compatibility

This PEP does not introduce any new backwards compatibility considerations, compared to PEP 825.

Security Implications

This PEP introduces a plugin system for querying the platform capabilities. Tools may install these packages and execute the code within them during dependency resolution or wheel processing. This elevates the supply-chain attack potential by introducing two new points for malicious actors to inject arbitrary code payload:

1. Publishing a version of a variant provider plugin or one of its dependencies with malicious code.
2. Introducing a malicious variant provider plugin in an existing package metadata.

Admittedly, such attacks can already be done to the package’s dependencies. However, in some cases the affected tools are executed with elevated privileges (such as when installing packages for multi-user systems), while the package itself will only be run with regular user privileges. Therefore, variant provider plugins could introduce a Remote Code Execution vulnerability with elevated privileges.

A similar issue already exists in the packaging ecosystem when packages are installed from source distributions, with build backends and other build dependencies are being installed and executed. However, various tools operating purely on wheels, as well as users using tool-specific options to disable the use of source distributions, have been relying on the assumption that no such code execution will happen. To uphold this assumption, the proposal makes plugin packages opt-in.

Unfortunately, an opt-in system creates a risk of security fatigue. Users wishing to use variant wheels may start blanket-enabling all use of provider plugins, reintroducing the RCE danger. To avoid this and improve user experience, the PEP permits tool maintainers to provide opt-out experience for selected plugins. A subsequent PEP will give further recommendations for improved user experience.

How to Teach This

This PEP is focused on installing variant wheels. The primary source of information for the users will be the user interface of installers, supplemented by their documentation and installation instructions of specific packages publishing variant wheels. The documentation present on packaging.python.org will need to be updated as well.

Ideally, in the most common use cases variants will work out of the box and non-expert users will not need to be aware of them, much like they do not need to be aware of Platform compatibility tags.

Expert users will need guidance that will largely be specific to particular installer implementation, as it involves user interface decisions. The following topics may need to be covered, depending on the features implemented by the installer:

• how to enable installing untrusted variant provider packages, and what are the security implications of that
• how to enable optional providers
• how to generate and provide static compatibility data, enabling deployment for remote targets
• how to explicitly select a specific variant
• how to alter variant selection, for example by specifying preferred properties or filtering out undesirable properties

The topic of teaching package maintainers will be addressed in a subsequent PEP, along with building variant wheels.

Reference Implementation

The variantlib project contains a reference implementation of this PEP.

A client for installing variant wheels is implemented in a uv branch.

Rejected Ideas

Open Issues

This PEP is concerned with installing wheels only. A subsequent PEP will address building variant wheels.

Acknowledgements

This work would not have been possible without the contributions and feedback of many people in the Python packaging community. In particular, we would like to credit the following individuals for their help in shaping this PEP (in alphabetical order):

Alban Desmaison, Bradley Dice, Chris Gottbrath, Dmitry Rogozhkin, Emma Smith, Geoffrey Thomas, Henry Schreiner, Jeff Daily, Jeremy Tanner, Jithun Nair, Keith Kraus, Leo Fang, Mike McCarty, Nikita Shulga, Paul Ganssle, Philip Hyunsu Cho, Robert Maynard, Vyas Ramasubramani, and Zanie Blue.

Change History

• 17-Feb-2026
  • Initial version, split from PEP 817 draft.
  • Namespaces have been removed from the provider plugin API. Instead, the namespace is named by the package in variant metadata.
  • The enable-if key has been removed from provider information, as it was deemed redundant.
  • The static-properties table has been moved into provider information.

Appendices

• Appendix: JSON Schema for Variant Metadata

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.