Skip to content

Use built distribution terminology for wheels #2169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rgommers wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Use built distribution terminology for wheels #2169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ba4ec2
Use built distribution terminology for wheels
rgommers Oct 27, 2026
ac8973a
Add new link target name alongside the old ones for backcompat
rgommers Oct 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion source/discussions/downstream-packaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Why?
~~~~

The vast majority of downstream packagers prefer to build packages from source,
rather than use the upstream-provided binary packages. In some cases, using
rather than use the upstream-provided wheels. In some cases, using
sources is actually required for the package to be included in the distribution.
This is also true of pure Python packages that provide universal wheels.
The reasons for using source distributions may include:
Expand Down
2 changes: 1 addition & 1 deletion source/guides/distributing-packages-using-setuptools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ sample project <https://github.com/pypa/sampleproject>`_ has removed its manifes
file, since all the necessary files have been included by :ref:`setuptools` 43.0.0
and newer.

.. note:: :file:`MANIFEST.in` does not affect binary distributions such as wheels.
.. note:: :file:`MANIFEST.in` does not affect built distributions such as wheels.

LICENSE.txt
~~~~~~~~~~~
Expand Down
2 changes: 1 addition & 1 deletion source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ jobs:
pip install
build
--user
- name: Build a binary wheel and a source tarball
- name: Build a wheel and a source distribution
run: python3 -m build
- name: Store the distribution packages
uses: actions/upload-artifact@v5
Expand Down
8 changes: 4 additions & 4 deletions source/key_projects.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ distlib
relate to packaging and distribution of Python software. ``distlib``
implements several relevant PEPs (Python Enhancement Proposal
standards) and is useful for developers of third-party packaging tools
to make and upload binary and source :term:`distributions
to make and upload built and source :term:`distributions
<Distribution Package>`, achieve interoperability, resolve
dependencies, manage package resources, and do other similar
functions.
Expand Down Expand Up @@ -373,9 +373,9 @@ creating :term:`wheel distributions <Wheel>`. Additionally, it offers its own
command line utility for creating and installing wheels.

See also `auditwheel <https://github.com/pypa/auditwheel>`__, a tool
that package developers use to check and fix Python packages they are
making in the binary wheel format. It provides functionality to
discover dependencies, check metadata for compliance, and repair the
that package developers use to check and fix wheels containing native code.
It provides functionality to discover dependencies, check metadata for
compliance, and repair the
wheel and metadata to properly link and include external shared
libraries in a package.

Expand Down
9 changes: 6 additions & 3 deletions source/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,8 +112,11 @@ advantages for pure-Python libraries.
a drop-in replacement for PIL, just by changing your project's
``install_requires`` or ``requirements.txt``.

Python binary distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _python-binary-distributions:
.. _python-built-distributions:

@merwok merwok Oct 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Here as well!

@rgommers rgommers Oct 27, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Oops sorry about that - got them both now, that should be all of them.

Python built distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^

So much of Python's practical power comes from its ability to
integrate with the software ecosystem, in particular libraries written
Expand All @@ -126,7 +129,7 @@ compiled artifacts. In fact, Python's package installer, ``pip``,
always prefers wheels because installation is always faster, so even
pure-Python packages work better with wheels.

Binary distributions are best when they come with source distributions
Built distributions are best when they come with source distributions
to match. Even if you don't upload wheels of your code for every
operating system, by uploading the sdist, you're enabling users of
other platforms to still build it for themselves. Default to
Expand Down
10 changes: 5 additions & 5 deletions source/specifications/binary-distribution-format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
.. highlight:: text

.. _binary-distribution-format:
.. _wheel-distribution-format:

Comment thread
rgommers marked this conversation as resolved.
==========================
Binary distribution format
==========================
=========================
Wheel distribution format
=========================

This page specifies the binary distribution format for Python packages,
also called the wheel format.
This page specifies the wheel format for Python packages.

A wheel is a ZIP-format archive with a specially formatted file name and
the ``.whl`` extension. It contains a single distribution nearly as it
Expand Down
2 changes: 1 addition & 1 deletion source/specifications/externally-managed-environments.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ distro

This document uses the short term "distro," because the term
"distribution" has another meaning in Python packaging contexts: a
source or binary distribution package of a single piece of Python
source or built distribution package of a single piece of Python
language software, that is, in the sense of
``setuptools.dist.Distribution`` or "sdist". To avoid confusion,
this document does not use the plain term "distribution" at all.
Expand Down
2 changes: 1 addition & 1 deletion source/specifications/source-distribution-format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Source distribution file name

The file name of a sdist was standardised in :pep:`625`. The file name must be in
the form ``{name}-{version}.tar.gz``, where ``{name}`` is normalised according to
the same rules as for binary distributions (see :ref:`binary-distribution-format`),
the same rules as for wheels (see :ref:`binary-distribution-format`),
and ``{version}`` is the canonicalized form of the project version (see
:ref:`version-specifiers`).

Expand Down
10 changes: 5 additions & 5 deletions source/specifications/version-specifiers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,18 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
document are to be interpreted as described in :rfc:`2119`.

"Build tools" are automated tools intended to run on development systems,
producing source and binary distribution archives. Build tools may also be
producing source and built distribution archives. Build tools may also be
invoked by integration tools in order to build software distributed as
sdists rather than prebuilt binary archives.
sdists rather than built distribution archives.

"Index servers" are active distribution registries which publish version and
dependency metadata and place constraints on the permitted metadata.

"Publication tools" are automated tools intended to run on development
systems and upload source and binary distribution archives to index servers.
systems and upload source and built distribution archives to index servers.

"Installation tools" are integration tools specifically intended to run on
deployment targets, consuming source and binary distribution archives from
deployment targets, consuming source and built distribution archives from
an index server or other designated location and deploying them to the target
system.

Expand Down Expand Up @@ -1112,7 +1112,7 @@ uploaded distributions. Direct references are intended as a tool for
software integrators rather than publishers.

Depending on the use case, some appropriate targets for a direct URL
reference may be an sdist or a wheel binary archive. The exact URLs and
reference may be an sdist or a wheel. The exact URLs and
targets supported will be tool dependent.

For example, a local source archive may be referenced directly::
Expand Down
Loading