PEP 825: Wheel Variants: Package Format by mgorny · Pull Request #4819 · python/peps

mgorny · 2026-02-17T19:05:47Z

Basic requirements (all PEP Types)

Standards Track requirements

Following the suggestions given in the previous PEP 817 thread [1], we have decided to split PEP 817 into a series of smaller PEPs, with the hope that this will make it easier to comprehend the concept and discuss it.

This is the first split PEP, that specifically focuses on the low-level details necessary for variants wheels to work, that is:

adding variant label to the filename
storing variant properties in the file
exposing variants on the index
ordering/selecting variants
introducing variant-conditional dependencies via environment markers
exposing variant wheels in pylock.toml

The PEP keeps variant properties abstract, deferring their governance and determining their compatibility to a subsequent PEP, along with building wheels. We've also significantly cut motivation down (the original is kept in PEP 817 for reference). We've tried to make the "specification" part easier to comprehend, and removed the duplicate "rationale-overview", in favor of a more focused "rationale" section.

Compared to the previous iteration of PEP 817, we've also corrected the variant ordering algorithm to handle corner cases better.

[1] https://discuss.python.org/t/pep-817-wheel-variants-beyond-platform-tags/105860

📚 Documentation preview 📚: https://pep-previews--4819.org.readthedocs.build/pep-0825/

Following the suggestions given in the previous PEP 817 thread [1], we have decided to split PEP 817 into a series of smaller PEPs, with the hope that this will make it easier to comprehend the concept and discuss it. This is the first split PEP, that specifically focuses on the low-level details necessary for variants wheels to work, that is: - adding variant label to the filename - storing variant properties in the file - exposing variants on the index - ordering/selecting variants - introducing variant-conditional dependencies via environment markers - exposing variant wheels in `pylock.toml` The PEP keeps variant properties abstract, deferring their governance and determining their compatibility to a subsequent PEP, along with building wheels. We've also significantly cut motivation down (the original is kept in PEP 817 for reference). We've tried to make the "specification" part easier to comprehend, and removed the duplicate "rationale-overview", in favor of a more focused "rationale" section. Compared to the previous iteration of PEP 817, we've also corrected the variant ordering algorithm to handle corner cases better. [1] https://discuss.python.org/t/pep-817-wheel-variants-beyond-platform-tags/105860 Signed-off-by: Michał Górny <mgorny@quansight.com> Co-authored-by: Jonathan Dekhtiar <jonathan@dekhtiar.com> Co-authored-by: Konstantin Schütze <konstin@mailbox.org> Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>

Signed-off-by: Michał Górny <mgorny@quansight.com>

hugovk · 2026-02-17T19:16:50Z

@warsaw or @dstufft Please can one of you confirm co-authorship?

@DEKHTIARJonathan Note: we assign PEP number after core team co-authorship/sponsorship is confirmed :)

@mgorny There's a checklist at https://github.com/python/peps/blob/main/.github/PULL_REQUEST_TEMPLATE/Add%20a%20new%20PEP.md you might find useful to paste into the top message and check off as relevant.

DEKHTIARJonathan · 2026-02-17T19:18:00Z

@hugovk thanks Hugo with the help :)

@dstufft just told me to grab the next number available: link

PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header

dstufft · 2026-02-17T19:20:11Z

Yes. Sent from my iPhoneOn Feb 17, 2026, at 14:18, Jonathan DEKHTIAR ***@***.***> wrote:DEKHTIARJonathan left a comment (python/peps#4819) @hugovk @dstufft just told me to grab the next number available. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

hugovk · 2026-02-17T19:21:02Z

Thanks, please go ahead with 825! Remember the CODEOWNERS file.

DEKHTIARJonathan · 2026-02-17T19:24:05Z

Done. Thanks Hugo

mgorny · 2026-02-17T19:30:38Z

@mgorny There's a checklist at https://github.com/python/peps/blob/main/.github/PULL_REQUEST_TEMPLATE/Add%20a%20new%20PEP.md you might find useful to paste into the top message and check off as relevant.

Ah, sorry, I wonder why GH didn't include it in the box.

peps/pep-0825/appendix-core-metadata-json-schema.rst

peps/pep-0825.rst

hugovk · 2026-02-17T19:30:10Z

peps/pep-0825.rst

@@ -0,0 +1,962 @@
+PEP: 825


General suggestion for all this PEP splitting work, there are some optional headers that might be useful for cross linking:

Requires: *[NNN] Replaces: *[NNN] Superseded-By: *[NNN]

https://peps.python.org/pep-0012/#how-to-use-this-template

These headers do not apply to this specific PEP. We will probably update very soon 817 to include Requires: [817, and_others_not_yet_published]

If that works for you, we can close this one

hugovk · 2026-02-17T19:34:13Z

Ah, sorry, I wonder why GH didn't include it in the box.

Not your fault, GitHub has only partially implemented the feature: the option to use a template only shows up when you click to open the PR via the website UI, and not for example via the link you get when pushing from the CLI (which is my usual route of opening a PR). 🤷

MegaIng · 2026-02-17T22:27:52Z

peps/pep-0825.rst

+        # {namespace: {feature_name: [feature_values]}}, as in variant.json
+        properties: dict[str, dict[str, list[str]]]
+
+        def best_value_properties(self) -> tuple[str, str, str]:


Suggested change

def best_value_properties(self) -> tuple[str, str, str]:

def best_value_properties(self) -> list[tuple[str, str, str]]:

warsaw · 2026-02-17T22:50:06Z

@warsaw or @dstufft Please can one of you confirm co-authorship?

Confirmed

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

h-vetinari · 2026-02-17T23:22:48Z

peps/pep-0825.rst

+
+      "variants": {
+        // REQUIRED: in variant.json, always a single entry, with the key
+        // matching the variant label ("x8664v3_openblas") and the value


the lack of separators here is a bit jarring. The numpy example for the introduction of variant labels has x86_64_v3; is there any reason this couldn't be:

Suggested change

// matching the variant label ("x8664v3_openblas") and the value

// matching the variant label ("x86_64_v3_openblas") and the value

This occurs in the same way in several example further down, so I must assume it's intentional, but I don't understand why that cramped style was chosen. Plus it's not consistent with also using x86_64_v3 in other places.

Label can be up to 16 characters long, and anyway it's just an example.

If the PEP itself already runs into this limitation (without a contrived example)

>>> len("x8664v3_openblas") 16

it sounds like 16 is too short? The Variant Label section does not provide a rationale for that length either. What constraint (aside from avoiding superlong wheel names) was this limit chosen for?

(PS. Happy to move this to discourse; I initially had thought this was just on the level of a typo fix, but it might need wider discussion)

merwok · 2026-02-18T01:34:14Z

There was a suggestion of reserving a series of PEP numbers for this work.
Is there a mecanism for this?

DEKHTIARJonathan · 2026-02-18T01:39:36Z

There was a suggestion of reserving a series of PEP numbers for this work.

Is there a mecanism for this?

One of the issues is that we are not sure how many PEPs we will end up "cutting into". It would be nice to have but realistically it's not the end of the world if we don't also.

@hugovk if we were to "reserve and block" 825-830 right now. How would we do that ? What's the criteria to make it happen ?

warsaw · 2026-02-18T02:37:18Z

Given that 817 and 825 are already somewhat disjoint, it's not the end of the world if you don't get a series. But OTOH, it's also not difficult, since it's Just Numbers 😄. I think if you had a clearer sense of wanting X PEPs you could reserve a block of those X numbers. It also wouldn't be terrible if you end up using X-N because those extras could be "released" for other proposals. Harder is if you need X+N because those will already be assigned and renumbering isn't going to work.

merwok · 2026-02-18T02:41:31Z

peps/pep-0825.rst

+   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 ``VariantWheel.__lt__()``.


The class name is Variant

merwok · 2026-02-18T02:41:39Z

peps/pep-0825.rst

+
+
+    # 7. Order variants by comparing their sorted properties
+    # (see VariantWheel.__lt__())


Here as well

mgorny requested a review from a team as a code owner February 17, 2026 19:05

Update Discussions-To and Post-History

100f9fd

Signed-off-by: Michał Górny <mgorny@quansight.com>

brianschubert added the new-pep A new draft PEP submitted for initial review label Feb 17, 2026

PEP 9999 => 0825

8bd58c4

DEKHTIARJonathan force-pushed the pep-wheel-variants-acceptance branch from 96768ab to 8bd58c4 Compare February 17, 2026 19:16

hugovk changed the title ~~New PEP: Wheel Variants: Package Format~~ PEP 825: Wheel Variants: Package Format Feb 17, 2026

CODEOWNERS added

6538ba9

hugovk reviewed Feb 17, 2026

View reviewed changes

MegaIng reviewed Feb 17, 2026

View reviewed changes

warsaw and others added 4 commits February 17, 2026 14:50

Merge branch 'main' into pep-wheel-variants-acceptance

cd9731c

Update peps/pep-0825/appendix-core-metadata-json-schema.rst

240518a

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Update peps/pep-0825.rst

4a622fa

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Update peps/pep-0825.rst

af310b7

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

h-vetinari reviewed Feb 17, 2026

View reviewed changes

merwok reviewed Feb 18, 2026

View reviewed changes

peps/pep-0825.rst

# 7. Order variants by comparing their sorted properties

# (see VariantWheel.__lt__())

Copy link

Member

merwok Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here as well

	def best_value_properties(self) -> tuple[str, str, str]:
	def best_value_properties(self) -> list[tuple[str, str, str]]:

	// matching the variant label ("x8664v3_openblas") and the value
	// matching the variant label ("x86_64_v3_openblas") and the value



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

Uh oh!

Conversation

mgorny commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

hugovk commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DEKHTIARJonathan commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dstufft commented Feb 17, 2026 via email

Uh oh!

hugovk commented Feb 17, 2026

Uh oh!

DEKHTIARJonathan commented Feb 17, 2026

Uh oh!

mgorny commented Feb 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

DEKHTIARJonathan Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

hugovk commented Feb 17, 2026

Uh oh!

MegaIng Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

warsaw commented Feb 17, 2026

Uh oh!

h-vetinari Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

mgorny Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

h-vetinari Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

merwok commented Feb 18, 2026

Uh oh!

DEKHTIARJonathan commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

warsaw commented Feb 18, 2026

Uh oh!

merwok Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

merwok Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

mgorny commented Feb 17, 2026 •

edited

Loading

hugovk commented Feb 17, 2026 •

edited

Loading

DEKHTIARJonathan commented Feb 17, 2026 •

edited

Loading

h-vetinari Feb 18, 2026 •

edited

Loading

DEKHTIARJonathan commented Feb 18, 2026 •

edited

Loading