Text of peps.python.org › pep-0440 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 440 – Version Identification and Dependency Specification | peps.python.org

PEP 440 – Version Identification and Dependency Specification PEP 440 – Version Identification and Dependency Specification Author : Alyssa Coghlan <ncoghlan at gmail.com>, Donald Stufft <donald at stufft.io> BDFL-Delegate : Alyssa Coghlan <ncoghlan at gmail.com> Discussions-To : Distutils-SIG list Status : Final Type : Standards Track Topic : Packaging Created : 18-Mar-2013 Post-History : 30-Mar-2013, 27-May-2013, 20-Jun-2013, 21-Dec-2013, 28-Jan-2014, 08-Aug-2014, 22-Aug-2014 Replaces : 386 Resolution : Distutils-SIG message Table of Contents Abstract Definitions Version scheme Public version identifiers Local version identifiers Final releases Pre-releases Post-releases Developmental releases Version epochs Normalization Case sensitivity Integer Normalization Pre-release separators Pre-release spelling Implicit pre-release number Post release separators Post release spelling Implicit post release number Implicit post releases Development release separators Implicit development release number Local version segments Preceding v character Leading and Trailing Whitespace Examples of compliant version schemes Summary of permitted suffixes and relative ordering Version ordering across different metadata versions Compatibility with other version schemes Semantic versioning DVCS based version labels Olson database versioning Version specifiers Compatible release Version matching Version exclusion Inclusive ordered comparison Exclusive ordered comparison Arbitrary equality Handling of pre-releases Examples Direct references File URLs Updating the versioning specification Summary of differences from pkg_resources.parse_version Summary of differences from PEP 386 Changing the version scheme A more opinionated description of the versioning scheme Describing version specifiers alongside the versioning scheme Changing the interpretation of version specifiers Support for date based version identifiers Adding version epochs Adding direct references Adding arbitrary equality Adding local version identifiers Providing explicit version normalization rules Allowing Underscore in Normalization Summary of changes to PEP 440 References Appendix A Appendix B : Parsing version strings with regular expressions Copyright Important This PEP is a historical document.

The up-to-date, canonical spec, Version specifiers , is maintained on the PyPA specs page . × See the PyPA specification update process for how to propose changes. Abstract This PEP describes a scheme for identifying versions of Python software distributions, and declaring dependencies on particular versions. This document addresses several limitations of the previous attempt at a standardized approach to versioning, as described in PEP 345 and PEP 386 .

Definitions The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 . “Projects” are software components that are made available for integration. Projects include Python libraries, frameworks, scripts, plugins, applications, collections of data or other resources, and various combinations thereof.

Public Python projects are typically registered on the Python Package Index . “Releases” are uniquely identified snapshots of a project. “Distributions” are the packaged files which are used to publish and distribute a release. “Build tools” are automated tools intended to run on development systems, producing source and binary distribution archives. Build tools may also be invoked by integration tools in order to build software distributed as sdists rather than prebuilt binary 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. “Installation tools” are integration tools specifically intended to run on deployment targets, consuming source and binary distribution archives from an index server or other designated location and deploying them to the target system.

“Automated tools” is a collective term covering build tools, index servers, publication tools, integration tools and any other software that produces or consumes distribution version and dependency metadata. Version scheme Distributions are identified by a public version identifier which supports all defined version comparison operations The version scheme is used both to describe the distribution version provided by a particular distribution archive, as well as to place constraints on the version of dependencies needed in order to build or run the software.

Public version identifiers The canonical public version identifiers MUST comply with the following scheme: [N!]N(.N)*[{a|b|rc}N][.postN][.devN] Public version identifiers MUST NOT include leading or trailing whitespace. Public version identifiers MUST be unique within a given distribution. Installation tools SHOULD ignore any public versions which do not comply with this scheme but MUST also include the normalizations specified below.

Installation tools MAY warn the user when non-compliant or ambiguous versions are detected. See also Appendix B : Parsing version strings with regular expressions which provides a regular expression to check strict conformance with the canonical format, as well as a more permissive regular expression accepting inputs that may require subsequent normalization. Public version identifiers are separated into up to five segments: Epoch segment: N!

Release segment: N(.N)* Pre-release segment: {a|b|rc}N Post-release segment: .postN Development release segment: .devN Any given release will be a “final release”, “pre-release”, “post-release” or “developmental release” as defined in the following sections. All numeric components MUST be non-negative integers represented as sequences of ASCII digits. All numeric components MUST be interpreted and ordered according to their numeric value, not as text strings.

All numeric components MAY be zero. Except as described below for the release segment, a numeric component of zero has no special significance aside from always being the lowest possible value in the version ordering. Note Some hard to read version identifiers are permitted by this scheme in order to better accommodate the wide range of versioning practices across existing public and private Python projects. Accordingly, some of the versioning practices which are technically permitted by the PEP are strongly discouraged for new projects.

Where this is the case, the relevant details are noted in the following sections. Local version identifiers Local version identifiers MUST comply with the following scheme: < public version identifier > [ +< local version label > ] They consist of a normal public version identifier (as defined in the previous section), along with an arbitrary “local version label”, separated from the public version identifier by a plus.

Local version labels have no specific semantics assigned, but some syntactic restrictions are imposed. Local version identifiers are used to denote fully API (and, if applicable, ABI) compatible patched versions of upstream projects. For example, these may be created by application developers and system integrators by applying specific backported bug fixes when upgrading to a new upstream release would be too disruptive to the application or other integrated system (such as a Linux distribution).

The inclusion of the local version label makes it possible to differentiate upstream releases from potentially altered rebuilds by downstream integrators. The use of a local version identifier does not affect the kind of a release but, when applied to a source distribution, does indicate that it may not contain the e

The rest of this page is on the live site.