136136 {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}(-{variant label})?.whl
137137 +++++++++++++++++++
138138
139+ The Python tag component MUST NOT start with a digit.
140+
139141Variant wheels MUST include the variant label component. Conversely,
140142wheels without variant label are non-variant wheels. The variant label
141143MUST be non-empty and consist only of ``0-9 ``, ``a-z ``, ``_ `` and ``. ``
@@ -846,11 +848,8 @@ Backwards Compatibility
846848=======================
847849
848850Variant wheels add an additional `variant label `_ component to the wheel
849- filename, causing them to be rejected while verifying the filename. This
850- permits publishing them on an index alongside non-variant wheels,
851- without risking previous installer versions accidentally installing
852- them. It was confirmed that the filename validation algorithms in tools
853- commonly used today reject it:
851+ filename. A complete filename verification step should reject such
852+ wheels:
854853
855854- If both the build tag and the variant label are present, the filename
856855 contains too many components. Example:
@@ -862,14 +861,31 @@ commonly used today reject it:
862861
863862 - If only the variant label is present, the Python tag at third position
864863 will be misinterpreted as a build number. Since the build number must
865- start with a digit and Python tags do not start with digits,
866- the filename is considered invalid. Example:
864+ start with a digit, the filename is considered invalid. Example:
867865
868866 .. code-block :: text
869867
870868 numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
871869 ^^^^^
872870
871+ Currently, no Python tags start with a digit. To guarantee unambiguity,
872+ the specification enforces that going forward. Tools commonly used to
873+ install wheels at the time of writing implemented a verification
874+ algorithm of that kind, making it possible to publish variant wheels on
875+ an index alongside non-variant wheels without risk of them being
876+ installed accidentally.
877+
878+ Tools that do not perform full filename verification will consume some
879+ or all variant wheels as regular wheels. This may cause unexpected
880+ behavior or breakage if the tool in question needs to specially account
881+ for variant wheels.
882+
883+ The libraries for processing wheel files and their consumers will need
884+ to be updated to handle the new filename component and possibly the new
885+ metadata. For example, there is an `open discussion in packaging project
886+ how to adapt the parse_wheel_filename() function
887+ <https://github.com/pypa/packaging/issues/1148> `__.
888+
873889The addition of the variant label increases the filename length. On platforms
874890with a low total path length limit such as Windows, long filenames are a
875891concern. However, given that the name and version components are already
@@ -993,6 +1009,13 @@ and Zanie Blue.
9931009Change History
9941010==============
9951011
1012+ - 06-Apr-2026
1013+
1014+ - Added a formal requirement that Python tags must not start with
1015+ a digit.
1016+ - Expanded backwards compatibility concerns regarding tools that do
1017+ not perform full filename verification.
1018+
9961019- 09-Mar-2026
9971020
9981021 - Clarified that feature values in ``variants `` dictionary are sets,
0 commit comments