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.

Variant wheel

A variant wheel is an extension of the wheel format, defined in Binary 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
                                                                             +++++++++++++++++++

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 within a single package version.

The label null is reserved and always corresponds to the variant with zero properties, called a null variant. This variant acts as a fallback variant that is always compatible.

Examples:

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

Variant metadata

The additional metadata specific to variant wheels is stored inside the wheel, in *.dist-info/variant.json file, using the JSON format. This PEP defines the following structure:

+- $schema
+- default-priorities
|  +- namespace        : list[str]
|  +- feature
|     +- {namespace}   : list[str]  = []
|  +- property
|     +- {namespace}
|        +- {feature}  : list[str]  = []
+- variants
  +- {variant_label}
     +- {namespace}
        +- {feature}   : list[str]  = []

This structure corresponds to the version 0.0.1 of the format. The version number is stored as part of the schema URL. Whenever the format changes, the version number must be incremented. Tools MUST assume that all variant wheels using an unknown format version are unsupported.

The version numbers starting with zero are reserved for drafts and MUST NOT be used in production. Once the proposal is complete, the latest draft will be promoted to version 1.0.0.

The top-level keys are described in the subsequent sections.

{
  // 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": {
    // REQUIRED: specifies that x86_64 CPU properties are more important than
    // aarch64 CPU properties (both are mutually exclusive, so the exact order
    // does not matter), and both are more important than specific BLAS/LAPACK
    // library:
    "namespace": ["x86_64", "aarch64", "blas_lapack"],

    // OPTIONAL: makes "library" the most important feature in "blas_lapack"
    // namespace
    "feature": {
      "blas_lapack": ["library"]
    },

    // OPTIONAL: makes ["mkl", "openblas"] the most important values of
    // "blas_lapack :: library" feature
    "property": {
      "blas_lapack": {
        "library": ["mkl", "openblas"]
      }
    }
  },

  "variants": {
    // REQUIRED: in variant.json, always a single entry, with the key
    // matching the variant label ("x8664v3_openblas") and the value
    // specifying its properties (the system must be compatible with both):
    // - blas_lapack :: library :: openblas
    // - x86_64 :: level :: v3
    "x8664v3_openblas": {
      "blas_lapack": {
        "library": ["openblas"]
      },
      "x86_64": {
        "level": ["v3"]
      }
    }
  }
}

Index-level metadata

For every package version that includes at least one variant wheel, there MUST exist a corresponding {name}-{version}-variants.json file, hosted and served by the package index. The {name} and {version} placeholders correspond to the package name and version, normalized according to the same rules as wheel files, as found in the File name convention of the Binary Distribution Format specification. The link to this file MUST be present on all index pages where the variant wheels are linked. It is presented in the same simple repository format as source distribution and wheel links in the index, including an (OPTIONAL) hash.

This file uses the same structure as variant metadata, except that the variants object MUST list all variants available on the package index for the package version in question. The tools MUST ensure that the variant metadata across multiple variant wheels of the same package version and the index-level metadata file is consistent. They MAY require that keys other than variants have exactly the same values, or they may carefully merge their values, provided that no conflicting information is introduced, and the resolution results within a subset of variants do not change.

Variant indexes MAY elect to either auto-generate the file from the uploaded variant wheels or allow the user to manually generate it themselves and upload it to the index.

The foo-1.2.3-variants.json corresponding to the package with two wheel variants, one of them listed in the previous example, would look like:

{
  // 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
  },
  "variants": {
    // REQUIRED: entries for all wheel variants for the package version

    // if a null variant is present
    "null": {},

    // "x8664v3_openblas" label corresponds to:
    // - blas_lapack :: library :: openblas
    // - x86_64 :: level :: v3
    "x8664v3_openblas": {
      "blas_lapack": {
        "library": ["openblas"]
      },
      "x86_64": {
        "level": ["v3"]
      }
    },

    // "x8664v4_mkl" label corresponds to:
    // - blas_lapack :: library :: mkl
    // - x86_64 :: level :: v4
    "x8664v4_mkl": {
      "blas_lapack": {
        "library": ["mkl"]
      },
      "x86_64": {
        "level": ["v4"]
      }
    }
  }
}

Variant ordering

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

For the purpose of ordering, variant properties are grouped into features, and features into namespaces. For every namespace, the tool MUST obtain an ordered list of compatible features, and for every feature, an ordered list of compatible values. The method of obtaining these lists will be defined in a subsequent PEP.

The default ordering MUST be performed equivalent to the following algorithm:

1. Construct the ordered list of namespaces by copying the value of the default-priorities.namespace key from index-level metadata. This is namespace_order in the example.
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 compatible feature names, 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. This is feature_order in the example.

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 compatible feature values, 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. This is value_order in the example.

4. For every compatible variant, determine the most preferred value corresponding to every feature in that variant. This is done by finding among the values present in the variant properties the one that has the lowest position in the ordered property value list. After this step, a list of features along with their best values is available for every variant. This is done in the Variant.best_value_properties() method in the example.
5. For every item in the list constructed in the previous step, construct a sort key that is a 3-tuple consisting of its namespace, feature name and best feature value indices in the respective ordered lists. This is done by the property_key() function in the example.
6. For every compatible variant, sort the list constructed in step 4 using the sort keys constructed in step 5, in ascending order. This is done by the Variant.sorted_properties() method in the example.
7. To order variants, compare their sorted lists from step 6. If the sort keys at the first position are different, the variant with the lower key is sorted earlier. If they are the same, compare the keys at the second position, and so on, until either a tie-breaker is found or the list in one of the variants is exhausted. In the latter case, the variant with more keys is sorted earlier. As a fallback, if both variants have the same number of keys, they are ordered lexically by their variant label, ascending. This is done by the ultimate step of the example algorithm, with the comparison function being implemented as Variant.__lt__().

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

The tools MAY provide options to override the default ordering, for example by specifying a preference for specific namespaces, features or properties. The tools MAY also provide options to exclude specific variants, or to select a particular variant.

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_compatible_feature_names(namespace: str) -> list[str]:
    """Get an ordered list of compatible features"""
    ...


def get_compatible_feature_values(namespace: str, feature_name: str) -> list[str]:
    """Get an ordered list of compatible values"""
    ...


# default-priorities dict from index-level 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_compatible_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_compatible_feature_values(namespace, feature_name):
            if feature_value not in value_order[namespace][feature_name]:
                value_order[namespace][feature_name].append(feature_value)


def best_value_property(namespace: str, feature_name: str, feature_values: str) -> str:
    """Helper function to determine the best value for given feature"""
    for best_value in value_order[namespace][feature_name]:
        if best_value in feature_values:
            return best_value
    assert False, "No feature value supported, wheel should have been filtered out"


def property_key(prop: tuple[str, str, str]) -> tuple[int, int, int]:
    """Construct a sort key for variant property (akin to step 5.)"""
    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 Variant:
    """Example class exposing properties of a variant wheel"""

    label: str
    # {namespace: {feature_name: [feature_values]}}, as in variant.json
    properties: dict[str, dict[str, list[str]]]

    def best_value_properties(self: Self) -> list[tuple[str, str, str]]:
        """Determine the most preferred values for every feature, step 4."""
        return [
            (
                namespace,
                feature_name,
                best_value_property(namespace, feature_name, feature_values),
            )
            for namespace, features in self.properties.items()
            for feature_name, feature_values in features.items()
        ]

    def sorted_properties(self: Self) -> list[tuple[str, str, str]]:
        """Sort the list of features with their best values (step 6.)"""
        return sorted(self.best_value_properties(), key=property_key)

    def __lt__(self: Self, other: Self) -> bool:
        """Variant comparison function for sorting (part of step 7.)"""
        self_properties = self.sorted_properties()
        other_properties = other.sorted_properties()
        # Proceed from the first to the last common sort best-value property.
        # If any of them are different, the variant with better property wins.
        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)
        # If the best-value properties of one variant are a subset of another,
        # the one with more properties wins.
        if len(self_properties) != len(other_properties):
            return len(self_properties) > len(other_properties)
        # If two variants have exactly the same properties, fall back to
        # sorting on variant label (they must be unique).
        return self.label < other.label


# A list of variants to sort.
variants: list[Variant] = [...]


# 7. Order variants by comparing their sorted properties
# (see Variant.__lt__())
variants.sort()

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.

Integration with pylock.toml

Variant wheels can be listed in pylock.toml file in the same manner as wheels with different Platform compatibility tags: either all variant (and non-variant) wheels can be listed, or a subset of them.

A new [packages.variants-json] subtable is added to the file, to permit locking the {name}-{version}-variants.json file to a specific hash. If variant wheels are listed for a given package, the tool SHOULD lock this file as well.

If variant wheels are listed, the tool SHOULD resolve variants to select the best wheel file.

The proposed text for pylock.toml Specification follows:

.. _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`.

Suggested implementation logic for tools (non-normative)

Predictable variant labels

The specification proposes that variant labels are arbitrary, and variant properties are mapped to them via a variant metadata file rather than expressed directly in them. While it could be technically possible to create variant labels from variant properties, this would either require permitting very long filenames that will cause issues with some platforms, or imposing arbitrary limits on variant property counts, making the specification less suitable for addressing multidimensional compatibility matrices.

An alternative approach was to use a hash of variant properties. While such an approach is technically valid and can provide short unique labels for arbitrarily large variant property sets, it makes the labels opaque and therefore difficult to read or reason about.

Variant label as part of Platform compatibility tag

The specification adds the variant label as a separate component, therefore breaking compatibility with existing tools. It could be technically possible to preserve partial compatibility by appending it to one of the Platform compatibility tags instead, in which case installers would reject the wheel based on platform (or Python interpreter) incompatibility, while other tools could still use it. However, the authors decided it safer to break the backwards compatibility. Additionally, reusing tags posed a potential risk of wheel labels being incorrectly combined with compressed tag sets. For example, a manylinux_2_27_x86_64.manylinux_2_28_x86_64+x8664v3 tag would be incorrectly deemed compatible because of the manylinux_2_27_x86_64 part.