Building wheel variants

Added in version 1.0.

Warning

This is an early preview of PEP 817 wheel variant support. The interface may change, and it must be opted into with experimental = true.

Scikit-build-core can attach variant metadata to a wheel, producing a variant-labeled filename (the label becomes the final field of the wheel name) and a variant.json file inside *.dist-info. This lets you ship several wheels for the same version that differ by hardware or library features (CPU ABI, CUDA version, BLAS implementation, etc.).

Declaring providers

Every namespace you provide must have a provider declared in the [variant] table of pyproject.toml, and must be listed in default-priorities. The table is required for the null variant too, since PEP 825 requires at least one namespace in every variant wheel:

[variant]
"$schema" = "https://variants-schema.wheelnext.dev/v0.2.0.json"

[variant.default-priorities]
namespace = ["x86_64"]

[variant.providers.x86_64]
requires = ["x86-64-variant-provider>=0.2.3"]
plugin-api = "x86_64_variant_provider"

Selecting a variant

Declare each variant you can build in [variant.variants], keyed by its label:

[variant.variants.x86_64_v3]
x86_64.level = ["v3"]

Then select one with the variant-label setting, as PEP 817 describes. It is only allowed in config-settings or [[tool.scikit-build.overrides]]; it cannot be set at the top level of [tool.scikit-build]. When it is set, variantlib is added as a build requirement, and the experimental flag must be enabled. For example, with pip:

pip wheel . -Cexperimental=true -Cvariant-label=x86_64_v3

This produces a wheel ending in -x86_64_v3.whl. Labels may only contain lowercase letters, digits, _, and .. The label null is reserved by PEP 825 for the null variant, which has no properties; build it with -Cvariant-label=null. It does not need a [variant.variants] entry.

The provider plugins for the namespaces you select are added to the build requirements, and the properties are checked against them before the wheel is written. A property the plugin does not list is an error. Providers declared with build-requires are ahead-of-time plugins; their supported values are also embedded into variant.json as static-properties, so installers do not need the plugin. Providers declared with requires are queried again at install time.

You can also set experimental = true under [tool.scikit-build] instead of passing it every time.

For more information you can see the available PEPs:

  • PEP 817: the overview of the wheel variant proposal

  • PEP 825: the wheel variant format

  • PEP 850: variant providers and the [variant] table