Glossary

Binary Distribution

A specific kind of Built Distribution that contains compiled extensions.

Build Frontend

A tool that users interact with directly to trigger a build of a Project, which in turn invokes the project’s Build Backend in a suitable environment to generate a Built Distribution (i.e. a Wheel), from a Source Tree or Source Distribution. Examples include build, as well as pip (when running a command such as pip wheel some-directory/). Compare to Integration Frontend. For more details, see the Build frontend-backend interface specification.

Build Backend

A tool directly responsible for transforming a Source Tree or Source Distribution into a Built Distribution (i.e. a Wheel). Typically invoked by a Build Frontend rather than directly. Examples include flit, hatch and setuptools. For more details, see the Build frontend-backend interface specification.

Built Distribution

A Distribution format containing files and metadata that only need to be moved to the correct location on the target system to be installed. Wheel is such a format, whereas a Sdist is not, in that it requires processing by the Project’s Build Backend before it can be installed. This format does not imply that Python files have to be precompiled (Wheel intentionally does not include compiled Python files).

Distribution Package

Distribution

Package

A versioned archive file that contains Python packages, modules, and other resource files that are used to distribute a Release. The archive file is what an end-user will download from the internet and install.

A distribution package is more commonly referred to with the single words “package” or “distribution”, but this guide may use the expanded term when more clarity is needed to prevent confusion with an Import Package (which is also commonly called a “package”) or another kind of distribution (e.g. a Linux distribution or the Python language distribution), which are often referred to with the single term “distribution”.

Editable Installation

Editable Mode

An installation mode implying that the Source Tree of the project being installed is available in a local directory, in which users expect that changes to its Python code become effective without the need of a new installation step.

When a project is installed in “editable mode”, users expect it to behave as identically as practical to a non-editable installation (though some minor differences might be visible). In particular, the code must be importable by other code, and metadata must be available by standard mechanisms such as importlib.metadata.

Formally specified in PEP 660 and now defined in the Build frontend-backend interface specification.

Egg

A Built Distribution format introduced by setuptools, which is being replaced by Wheel. For details, see ` The Internal Structure of Python Eggs and Python Eggs

Extension Module

A Module written in the low-level language of the Python implementation: C/C++ for Python, Java for Jython. Typically contained in a single dynamically loadable pre-compiled file, e.g. a shared object (.so) file for Python extensions on Unix, a DLL (given the .pyd extension) for Python extensions on Windows, or a Java class file for Jython extensions.

Known Good Set (KGS)

A set of distributions at specified versions which are compatible with each other. Typically a test suite will be run which passes all tests before a specific set of packages is declared a known good set. This term is commonly used by frameworks and toolkits which are comprised of multiple individual distributions.

Import Package

A Python module which can contain other modules or recursively, other packages.

An import package is more commonly referred to with the single word “package”, but this guide will use the expanded term when more clarity is needed to prevent confusion with a Distribution Package which is also commonly called a “package”.

Integration Frontend

A tool that users run directly that takes a set of Requirements, such as from a Project’s Core metadata specifications, a Requirements File or specified manually, and attempts to update a working environment to satisfy them. This may require locating, building and installing a combination of Built Distributions and Source Distributions, including acting as a Build Frontend in the latter case. In a command like pip install lxml==2.4.0, pip is acting as an integration frontend.

Module

The basic unit of code reusability in Python, existing in one of two types: Pure Module, or Extension Module.

Package Index

A repository of distributions with a web interface to automate package discovery and consumption.

Per Project Index

A private or other non-canonical Package Index indicated by a specific Project as the index preferred or required to resolve dependencies of that project.

Project

A library, framework, script, plugin, application, collection of data or other resources, or some combination thereof that is intended to be packaged into a Distribution.

Since most projects create Distributions using a Build Backend declared within a pyproject.toml file, (or else implicitly use setuptools), another practical way to define a project is something that contains a pyproject.toml (or setup.py/setup.cfg) file at the root of the project Source Tree.

Python projects must have unique names, which are registered on a Package Index such as PyPI. Each project will contain one or more Releases, and each release may comprise one or more Distributions.

Note that there is a strong convention to name a project after the name of the package that is imported to use that project. However, this doesn’t have to hold true. It’s possible to install a distribution from the project foo and have it provide a package importable only as bar.

Pure Module

A Module written in Python and contained in a single .py file (and possibly associated .pyc and/or .pyo files).

Python Packaging Authority (PyPA)

PyPA is a working group that maintains many of the relevant projects in Python packaging. They maintain a site at pypa.io, host projects on GitHub and Bitbucket, and discuss issues on the distutils-sig mailing list and the Python Discourse forum.

Python Package Index (PyPI)

PyPI is the default Package Index for the Python community. It is open to all Python developers to consume and distribute their distributions.

pypi.org

pypi.org is the domain name for the Python Package Index (PyPI). It replaced the legacy index domain name, pypi.python.org, in 2017. It is powered by Warehouse.

pyproject.toml

The tool-agnostic Project configuration file. Originally introduced in PEP 518 and now defined in the The pyproject.toml configuration file specification.

Release

A snapshot of a Project at a particular point in time, denoted by a version identifier.

Making a release may entail the publishing of multiple Distributions. For example, if version 1.0 of a project was released, it could be available in both a source distribution format and a Windows installer distribution format.

Requirement

A specification for a Package to be installed by an Integration Frontend. pip, the PyPA recommended installer, allows various forms of specification that can all be considered a “requirement”. For more information, see the pip install reference.

Requirement Specifier

A syntax used to declare the name and version of a Package that an Integration Frontend such as pip should install from a Package Index. For example, foo>=1.3 is a requirement specifier, where foo is the project name and >=1.3 is the Version Specifier. The format was initially specified in PEP 508, and is now defined in the Dependency specifiers specification.

Requirements File

A file containing a list of Requirements that can be installed using an Integration Frontend, such as pip. For more information, see the pip docs on Requirements Files.

setup.py

setup.cfg

The project specification files for distutils and setuptools. See also pyproject.toml.

Source Archive

An archive containing the Source Tree for a Release, prior to creation of a Source Distribution or Built Distribution.

Source Distribution

Sdist

A Distribution format (generated using, e.g., python -m build --sdist) that provides metadata and the essential source files needed by a Build Backend to generate a Built Distribution for installation by an installer like pip.

Source Tree

A collection of files and directories (typically from a VCS checkout) containing the raw source code of a project that is used for development. Can be stored in a Source Archive and is used by a Build Backend to generate a Source Distribution and in turn a Built Distribution, as well as directly in an Editable Installation. Typically contains a The pyproject.toml configuration file at its root.

System Package

A package provided in a format native to the operating system, e.g. an rpm or dpkg file.

Version Specifier

The version component of a Requirement Specifier. For example, the “>=1.3” portion of “foo>=1.3”. PEP 440 contains a full specification of the specifiers that Python packaging currently supports. Support for PEP440 was implemented in setuptools v8.0 and pip v6.0.

Virtual Environment

An isolated Python environment that allows packages to be installed for use by a particular application, rather than being installed system wide. For more information, see the section on Creating Virtual Environments.

Wheel

A Built Distribution format, introduced by PEP 427 and now defined in the Binary distribution format specification, which replaces the legacy Egg format. Wheel is supported by pip and other installation tools, and is the primary output of Build Backends.

Working Set

A collection of distributions available for importing. These are the distributions that are on the sys.path variable. At most, one Distribution for a project is possible in a working set.