Wheel Variant Experimental Support

[hcho3]

WheelNext & Wheel Variants

Caution

This is an an experimental feature currently being formalized as a PEP.
This is not an official feature of the Python Ecosystem & Standards.

This PR is part of the work being conducted by the WheelNext open-source initiative.

This PR introduces the feature of "Wheel Variant" into hatch & hatchling as a proof-of-concept.

Hopefully, this will give a good idea on:

• How it works
• How to use it
• How it could be implemented

How do "Wheel Variants" work ?

Wheel Variant is a proposed extension to the wheel specification designed to make platform-specific package distribution easier for package maintainers, and installation more smooth for end users. The key concepts are:

• A Provider Plugin system, allowing vendors and communities to ship small, install-time packages that can detect system capabilities (e.g., CUDA version, CPU features).

• A declarative metadata format for wheels to express their specific requirements (e.g., nvidia :: cuda_version_lower_bound :: 12.8). Yes, absolutely inspired by Python classifier format.

• A mechanism for installers to automatically run these plugins to match the user's system with the best-fitting variant wheel, simplifying the user experience to a familiar [uv] pip install torch.

We have carefully designed this system to ensure that installers unaware of variants will safely ignore them, maintaining backward compatibility with the existing ecosystem.

Links and Resources:

• PyTorch live Q&A: https://pytorch.org/event/pytorch-live-2-8-release-qa/
• PyCon 2025 - Reinventing the Wheel: A Community-Driven Roadmap for Python Packaging
• Github Monorepo: https://variant-monorepo.wheelnext.dev/
• Technical Blogs:
  • Astral: A variant-enabled build of uv
  • NVIDIA: Streamline CUDA-Accelerated Python Install and Packaging Workflows with Wheel Variants
  • PyTorch Foundation: PyTorch Wheel Variants, the Frontier of Python Packaging
  • Quansight: Python Wheels: from Tags to Variants

PR Details

• Add CLI option --variant-property to allow users to build variant wheels with a given variant specifier. Example:

hatch build -t wheel \
    --variant-property "fictional_tech :: quantum :: foam" \
    --variant-property "fictional_tech :: risk_exposure :: 1000000000" \
    --variant-property "fictional_tech :: technology :: improb_drive"

# Using build
python -m build --no-isolation --wheel \
    --config-setting 'variant-property=fictional_tech :: quantum :: foam' \
    --config-setting 'variant-property=fictional_tech :: risk_exposure :: 1000000000' \
    --config-setting 'variant-property=fictional_tech :: technology :: improb_drive'

• Hatchling now inserts variant.json into the wheel, whenever the wheel is variant-enabled.

TODOs

• Implement the PEP517 config_settings interface to allow users to build via python -m build.
• Address review comments in [WIP] Add variant support wheelnext/hatch#1 (review)

cc @DEKHTIARJonathan, @warsaw

[cjames23]

Why not just use variantlib itself to obtain these?