Add prototype implementation of wheel variant specification by charliermarsh · Pull Request #12203 · astral-sh/uv

charliermarsh · 2025-03-16T16:35:56Z

(Branch taken over by @konstin)

This branch contains the prototype implementation of wheel variants proposal. It support uv pip install and uv sync for basic test cases and torch. Included are:

Installing and running providers
Variant ordering
Basic lockfile support
Static providers, with a custom format
Variant markers markers
Basic universal resolution

It does not implement abi_dependency yet, nor does it consider whether features are multi-value or single value.

Naturally, it is not ready for any serious usage yet. Expect that things break, please report problems.

release Installing the latest release, potentially a bit behind this branch:

Unix:

curl -LsSf https://astral.sh/uv/install.sh | INSTALLER_DOWNLOAD_URL=https://wheelnext.astral.sh/v0.0.2 sh

Windows:

powershell -c { $env:INSTALLER_DOWNLOAD_URL = 'https://wheelnext.astral.sh/v0.0.3'; irm https://astral.sh/uv/install.ps1 | iex }

latest The best way to test is to clone the repo, checkout the branch (charlie/wheel-variant) and run:

export RUST_LOG=uv_distribution_types=debug,uv_distribution::distribution_database=debug
cargo run pip install torch --index https://wheelnext.github.io/variants-index/v0.0.3/ --refresh

If you don’t have Rust installed, there's a bootstrapping process from current uv, though it's slow:

export RUST_LOG=uv_distribution_types=debug,uv_distribution::distribution_database=debug
uvx --from "uv @ git+https://github.com/astral-sh/uv@charlie/wheel-variant" uv pip install torch --index https://wheelnext.github.io/variants-index/v0.0.3/ --refresh

To use a static variant declaration, i.e. not query any providers, you pass a JSON file by settings its path in UV_VARIANT_LOCK. It assumes that you don't want to run any additional providers with it, i.e. no third party code execution, unless you set UV_VARIANT_LOCK_INCOMPLETE=1. The file format has to follow the schema below:

[metadata]
created-by = "tool-that-created-the-file" # Freeform string
version = "0.1" # PEP 440 version

[[provider]]
resolved = ["cpu_level_provider==0.1"]
plugin-api = "cpu_level_provider"
namespace = "cpu_level"

[provider.properties]
x86_64_level = ["v1", "v2"]

[[provider]]
resolved = ["nvidia-variant-provider==0.0.1"]
plugin-api = "nvidia_variant_provider.plugin:NvidiaVariantPlugin"
namespace = "nvidia"

[provider.properties]
cuda_version_lower_bound = ["12.8"]
sm_arch = ["100_real", "120_real", "70_real", "75_real", "80_real", "86_real", "90_real"]

warsawnv · 2025-03-17T22:30:06Z

The build-wheels.sh step gives:

Successfully built wheels/provider_fictional_hw-1.0.0-py3-none-any.whl
+ uv build --out-dir ./wheels --project ./vendor/variantlib
warning: Failed to parse `pyproject.toml` during settings discovery:
  TOML parse error at line 101, column 11
      |
  101 | [[tool.uv.variant]]
      |           ^^^^^^^
  unknown field `variant`, expected one of `required-version`, `native-tls`, `offline`, `no-cache`, `cache-dir`, `preview`, `python-preference`, `python-downloads`, `concurrent-downloads`, `concurrent-builds`, `concurrent-installs`, `index`, `index-url`, `extra-index-url`, `no-index`, `find-links`, `index-strategy`, `keyring-provider`, `allow-insecure-host`, `resolution`, `prerelease`, `fork-strategy`, `dependency-metadata`, `config-settings`, `no-build-isolation`, `no-build-isolation-package`, `exclude-newer`, `link-mode`, `compile-bytecode`, `no-sources`, `upgrade`, `upgrade-package`, `reinstall`, `reinstall-package`, `no-build`, `no-build-package`, `no-binary`, `no-binary-package`, `python-install-mirror`, `pypy-install-mirror`, `publish-url`, `trusted-publishing`, `check-url`, `pip`, `cache-keys`, `override-dependencies`, `constraint-dependencies`, `build-constraint-dependencies`, `environments`, `required-environments`, `conflicts`, `workspace`, `sources`, `managed`, `package`, `default-groups`, `dev-dependencies`, `build-backend`

But then it seems to succeed.

charliermarsh · 2025-03-17T22:36:01Z

Ah sorry. I’ll update the instructions. You can either remove that section from the pyproject.toml, then run the build script, then re-add it. Or run cargo build, then point the build script to ./target/debug/uv instead of your global uv.

warsawnv · 2025-03-17T22:36:13Z

And the cargo run step fails with:

     Running `target/debug/uv pip install dummy_project --find-links ./wheels --extra-index-url 'https://mockhouse.wheelnext.dev/pep-xxx-variants/' --no-cache --reinstall`
error: No virtual environment found; run `uv venv` to create an environment, or pass `--system` to install into a non-virtual environment

warsawnv · 2025-03-17T22:36:58Z

Or run cargo build, then point the build script to ./target/debug/uv instead of your global uv

I had a feeling about that!

charliermarsh · 2025-03-17T22:38:35Z

You can run uv venv prior to the cargo run command to create a virtual environment in the current working directory. cargo run will then install into that virtual environment by default.

warsawnv · 2025-03-17T22:43:09Z

% git diff 
diff --git a/build-wheels.sh b/build-wheels.sh
index 96d89524d..193eed495 100755
--- a/build-wheels.sh
+++ b/build-wheels.sh
@@ -13,12 +13,14 @@
 
 set -euxo pipefail
 
+UV=./target/debug/uv
+
 # Create the destination directory if it doesn't exist.
 rm -rf wheels
 mkdir wheels
 
 # Build the wheels for the fictional hardware provider package.
-uv build --out-dir ./wheels --project ./vendor/provider_fictional_hw
+$UV build --out-dir ./wheels --project ./vendor/provider_fictional_hw
 
 # Build the wheels for the variant library.
-uv build --out-dir ./wheels --project ./vendor/variantlib
+$UV build --out-dir ./wheels --project ./vendor/variantlib

seemethere · 2025-03-17T23:06:41Z

[[tool.uv.variant]]
backend = "provider_fictional_hw.plugin:build"
requires = ["provider_fictional_hw"]

For this configuration I'm curious if this would be end-user facing or would this be package maintainer facing?

From my POV I feel like this would be best served at the package maintainer side where a potential PyTorch packaging config might look like:

[[tool.uv.variant]]
backend = "torch.build.variants:detect_variants"
requires = ["cuda_variants", "rocm_variants", "xpu_variants", "your_fav_hardware_variants"]

fwiw I don't know if requiring people to install variant plugins themselves is necessarily going to be a way to adopt this heavily since this should be something that reduces the friction towards someone installing the correct package for their machine instead of them having to remember which variant plugins they're installing vs. not.

charliermarsh · 2025-03-17T23:11:52Z

I was thinking it would be declared by the package maintainer, but possibly overridable by the end user (so, like, if they don't care about your_fav_hardware_variants, they can "skip" that variant provider).

charliermarsh · 2025-03-17T23:15:38Z

(Applied your changes, thanks @warsawnv.)

crates/uv-distribution-filename/src/lib.rs

crates/uv-resolver/Cargo.toml

crates/uv-resolver/src/candidate_selector.rs

charliermarsh added no-build Disable building binaries in CI test:skip Disable running tests for a pull request labels Mar 16, 2025

charliermarsh force-pushed the charlie/wheel-variant branch 3 times, most recently from 6ca5626 to f598b60 Compare March 16, 2025 17:38

charliermarsh force-pushed the charlie/wheel-variant branch from f598b60 to 189dd02 Compare March 17, 2025 23:14

charliermarsh mentioned this pull request Mar 19, 2025

[WheelVariants - Discussion] Detaching specification from variantlib internals wheelnext/pep_817_wheel_variants#11

Closed

konstin force-pushed the charlie/wheel-variant branch 2 times, most recently from bd7d6d2 to 9146f46 Compare July 8, 2025 08:52

konstin force-pushed the charlie/wheel-variant branch 5 times, most recently from 18dfd1e to 5ac01b8 Compare July 21, 2025 16:51

charliermarsh commented Jul 23, 2025

View reviewed changes

crates/uv-distribution-filename/src/lib.rs Outdated Show resolved Hide resolved

charliermarsh commented Jul 23, 2025

View reviewed changes

crates/uv-resolver/Cargo.toml Outdated Show resolved Hide resolved

charliermarsh commented Jul 23, 2025

View reviewed changes

crates/uv-resolver/src/candidate_selector.rs Outdated Show resolved Hide resolved

konstin force-pushed the charlie/wheel-variant branch 4 times, most recently from 5ae7861 to f168655 Compare July 29, 2025 14:38

charliermarsh force-pushed the charlie/wheel-variant branch 4 times, most recently from 531619a to 3f33934 Compare August 1, 2025 17:52

konstin force-pushed the charlie/wheel-variant branch from 0009f18 to baea3ac Compare August 5, 2025 12:12

konstin force-pushed the charlie/wheel-variant branch 3 times, most recently from b389852 to d53cca9 Compare September 16, 2025 12:26

dvrogozh mentioned this pull request Sep 23, 2025

configs: torch-2.9 xpu configs wheelnext/variant-repack#4

Closed

konstin force-pushed the charlie/wheel-variant branch from 5131d07 to 96182b3 Compare September 25, 2025 08:38

konstin force-pushed the charlie/wheel-variant branch 2 times, most recently from d3df356 to 2918fc7 Compare October 13, 2025 11:09

charliermarsh force-pushed the charlie/wheel-variant branch from b2b513f to de2d1ed Compare October 16, 2025 23:44

konstin force-pushed the charlie/wheel-variant branch 4 times, most recently from dc6757b to cc81ee9 Compare December 2, 2025 17:21

Add wheel variant support

81f0ecc

konstin force-pushed the charlie/wheel-variant branch from cc81ee9 to 81f0ecc Compare January 24, 2026 20:50

Prettier and ruff

dd4562a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add prototype implementation of wheel variant specification#12203

Add prototype implementation of wheel variant specification#12203
charliermarsh wants to merge 2 commits intomainfrom
charlie/wheel-variant

charliermarsh commented Mar 16, 2025 •

edited by konstin

Loading

Uh oh!

warsawnv commented Mar 17, 2025 •

edited

Loading

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

warsawnv commented Mar 17, 2025

Uh oh!

warsawnv commented Mar 17, 2025

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

warsawnv commented Mar 17, 2025

Uh oh!

seemethere commented Mar 17, 2025 •

edited

Loading

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

charliermarsh commented Mar 16, 2025 • edited by konstin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

warsawnv commented Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

warsawnv commented Mar 17, 2025

Uh oh!

warsawnv commented Mar 17, 2025

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

warsawnv commented Mar 17, 2025

Uh oh!

seemethere commented Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

charliermarsh commented Mar 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

charliermarsh commented Mar 16, 2025 •

edited by konstin

Loading

warsawnv commented Mar 17, 2025 •

edited

Loading

seemethere commented Mar 17, 2025 •

edited

Loading