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: 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.

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 exact same code as the corresponding upstream release.

To ensure local version identifiers can be readily incorporated as part of filenames and URLs, and to avoid formatting inconsistencies in hexadecimal hash representations, local version labels MUST be limited to the following set of permitted characters:

• ASCII letters ([a-zA-Z])

• ASCII digits ([0-9])

• periods (.)

Local version labels MUST start and end with an ASCII letter or digit.

Comparison and ordering of local versions considers each segment of the local version (divided by a .) separately. If a segment consists entirely of ASCII digits then that section should be considered an integer for comparison purposes and if a segment contains any ASCII letters then that segment is compared lexicographically with case insensitivity. When comparing a numeric and lexicographic segment, the numeric section always compares as greater than the lexicographic segment. Additionally a local version with a great number of segments will always compare as greater than a local version with fewer segments, as long as the shorter local version’s segments match the beginning of the longer local version’s segments exactly.

An “upstream project” is a project that defines its own public versions. A “downstream project” is one which tracks and redistributes an upstream project, potentially backporting security and bug fixes from later versions of the upstream project.

Local version identifiers SHOULD NOT be used when publishing upstream projects to a public index server, but MAY be used to identify private builds created directly from the project source. Local version identifiers SHOULD be used by downstream projects when releasing a version that is API compatible with the version of the upstream project identified by the public version identifier, but contains additional changes (such as bug fixes). As the Python Package Index is intended solely for indexing and hosting upstream projects, it MUST NOT allow the use of local version identifiers.

Final releases¶

A version identifier that consists solely of a release segment and optionally an epoch identifier is termed a “final release”.

The release segment consists of one or more non-negative integer values, separated by dots:

N(.N)*

Final releases within a project MUST be numbered in a consistently increasing fashion, otherwise automated tools will not be able to upgrade them correctly.

Comparison and ordering of release segments considers the numeric value of each component of the release segment in turn. When comparing release segments with different numbers of components, the shorter segment is padded out with additional zeros as necessary.

While any number of additional components after the first are permitted under this scheme, the most common variants are to use two components (“major.minor”) or three components (“major.minor.micro”).

For example:

0.9
0.9.1
0.9.2
...
0.9.10
0.9.11
1.0
1.0.1
1.1
2.0
2.0.1
...

A release series is any set of final release numbers that start with a common prefix. For example, 3.3.1, 3.3.5 and 3.3.9.45 are all part of the 3.3 release series.

Date-based release segments are also permitted. An example of a date-based release scheme using the year and month of the release:

2012.4
2012.7
2012.10
2013.1
2013.6
...

Pre-releases¶

Some projects use an “alpha, beta, release candidate” pre-release cycle to support testing by their users prior to a final release.

If used as part of a project’s development cycle, these pre-releases are indicated by including a pre-release segment in the version identifier:

X.YaN   # Alpha release
X.YbN   # Beta release
X.YrcN  # Release Candidate
X.Y     # Final release

A version identifier that consists solely of a release segment and a pre-release segment is termed a “pre-release”.

The pre-release segment consists of an alphabetical identifier for the pre-release phase, along with a non-negative integer value. Pre-releases for a given release are ordered first by phase (alpha, beta, release candidate) and then by the numerical component within that phase.

Installation tools MAY accept both c and rc releases for a common release segment in order to handle some existing legacy distributions.

Installation tools SHOULD interpret c versions as being equivalent to rc versions (that is, c1 indicates the same version as rc1).

Build tools, publication tools and index servers SHOULD disallow the creation of both rc and c releases for a common release segment.

Post-releases¶

Some projects use post-releases to address minor errors in a final release that do not affect the distributed software (for example, correcting an error in the release notes).

If used as part of a project’s development cycle, these post-releases are indicated by including a post-release segment in the version identifier:

X.Y.postN    # Post-release

A version identifier that includes a post-release segment without a developmental release segment is termed a “post-release”.

The post-release segment consists of the string .post, followed by a non-negative integer value. Post-releases are ordered by their numerical component, immediately following the corresponding release, and ahead of any subsequent release.

Post-releases are also permitted for pre-releases:

X.YaN.postM   # Post-release of an alpha release
X.YbN.postM   # Post-release of a beta release
X.YrcN.postM  # Post-release of a release candidate

Developmental releases¶

Some projects make regular developmental releases, and system packagers (especially for Linux distributions) may wish to create early releases directly from source control which do not conflict with later project releases.

If used as part of a project’s development cycle, these developmental releases are indicated by including a developmental release segment in the version identifier:

X.Y.devN    # Developmental release

A version identifier that includes a developmental release segment is termed a “developmental release”.

The developmental release segment consists of the string .dev, followed by a non-negative integer value. Developmental releases are ordered by their numerical component, immediately before the corresponding release (and before any pre-releases with the same release segment), and following any previous release (including any post-releases).

Developmental releases are also permitted for pre-releases and post-releases:

X.YaN.devM       # Developmental release of an alpha release
X.YbN.devM       # Developmental release of a beta release
X.YrcN.devM      # Developmental release of a release candidate
X.Y.postN.devM   # Developmental release of a post-release

Do note that development releases are considered a type of pre-release when handling them.

Version epochs¶

If included in a version identifier, the epoch appears before all other components, separated from the release segment by an exclamation mark:

E!X.Y  # Version identifier with epoch

If no explicit epoch is given, the implicit epoch is 0.

Most version identifiers will not include an epoch, as an explicit epoch is only needed if a project changes the way it handles version numbering in a way that means the normal version ordering rules will give the wrong answer. For example, if a project is using date based versions like 2014.04 and would like to switch to semantic versions like 1.0, then the new releases would be identified as older than the date based releases when using the normal sorting scheme:

1.0
1.1
2.0
2013.10
2014.04

However, by specifying an explicit epoch, the sort order can be changed appropriately, as all versions from a later epoch are sorted after versions from an earlier epoch:

2013.10
2014.04
1!1.0
1!1.1
1!2.0

Normalization¶

In order to maintain better compatibility with existing versions there are a number of “alternative” syntaxes that MUST be taken into account when parsing versions. These syntaxes MUST be considered when parsing a version, however they should be “normalized” to the standard syntax defined above.

Examples of compliant version schemes¶

The standard version scheme is designed to encompass a wide range of identification practices across public and private Python projects. In practice, a single project attempting to use the full flexibility offered by the scheme would create a situation where human users had difficulty figuring out the relative order of versions, even though the rules above ensure all compliant tools will order them consistently.

The following examples illustrate a small selection of the different approaches projects may choose to identify their releases, while still ensuring that the “latest release” and the “latest stable release” can be easily determined, both by human users and automated tools.

Simple “major.minor” versioning:

0.1
0.2
0.3
1.0
1.1
...

Simple “major.minor.micro” versioning:

1.1.0
1.1.1
1.1.2
1.2.0
...

“major.minor” versioning with alpha, beta and candidate pre-releases:

0.9
1.0a1
1.0a2
1.0b1
1.0rc1
1.0
1.1a1
...

“major.minor” versioning with developmental releases, release candidates and post-releases for minor corrections:

0.9
1.0.dev1
1.0.dev2
1.0.dev3
1.0.dev4
1.0rc1
1.0rc2
1.0
1.0.post1
1.1.dev1
...

Date based releases, using an incrementing serial within each year, skipping zero:

2012.1
2012.2
2012.3
...
2012.15
2013.1
2013.2
...

Summary of permitted suffixes and relative ordering¶

The epoch segment of version identifiers MUST be sorted according to the numeric value of the given epoch. If no epoch segment is present, the implicit numeric value is 0.

The release segment of version identifiers MUST be sorted in the same order as Python’s tuple sorting when the normalized release segment is parsed as follows:

tuple(map(int, release_segment.split(".")))

All release segments involved in the comparison MUST be converted to a consistent length by padding shorter segments with zeros as needed.

Within a numeric release (1.0, 2.7.3), the following suffixes are permitted and MUST be ordered as shown:

.devN, aN, bN, rcN, <no suffix>, .postN

Note that c is considered to be semantically equivalent to rc and must be sorted as if it were rc. Tools MAY reject the case of having the same N for both a c and a rc in the same release segment as ambiguous and remain in compliance with the specification.

Within an alpha (1.0a1), beta (1.0b1), or release candidate (1.0rc1, 1.0c1), the following suffixes are permitted and MUST be ordered as shown:

.devN, <no suffix>, .postN

Within a post-release (1.0.post1), the following suffixes are permitted and MUST be ordered as shown:

.devN, <no suffix>

Note that devN and postN MUST always be preceded by a dot, even when used immediately following a numeric version (e.g. 1.0.dev456, 1.0.post1).

Within a pre-release, post-release or development release segment with a shared prefix, ordering MUST be by the value of the numeric component.

The following example covers many of the possible combinations:

1.dev0
1.0.dev456
1.0a1
1.0a2.dev456
1.0a12.dev456
1.0a12
1.0b1.dev456
1.0b2
1.0b2.post345.dev456
1.0b2.post345
1.0rc1.dev456
1.0rc1
1.0
1.0+abc.5
1.0+abc.7
1.0+5
1.0.post456.dev34
1.0.post456
1.0.15
1.1.dev1

Version ordering across different metadata versions¶

Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not specify a standard version identification or ordering scheme. However metadata v1.2 (PEP 345) does specify a scheme which is defined in PEP 386.

Due to the nature of the simple installer API it is not possible for an installer to be aware of which metadata version a particular distribution was using. Additionally installers required the ability to create a reasonably prioritized list that includes all, or as many as possible, versions of a project to determine which versions it should install. These requirements necessitate a standardization across one parsing mechanism to be used for all versions of a project.

Due to the above, this specification MUST be used for all versions of metadata and supersedes PEP 386 even for metadata v1.2. Tools SHOULD ignore any versions which cannot be parsed by the rules in this specification, but MAY fall back to implementation defined version parsing and ordering schemes if no versions complying with this specification are available.

Distribution users may wish to explicitly remove non-compliant versions from any private package indexes they control.

Compatibility with other version schemes¶

Some projects may choose to use a version scheme which requires translation in order to comply with the public version scheme defined in this specification. In such cases, the project specific version can be stored in the metadata while the translated public version is published in the version field.

This allows automated distribution tools to provide consistently correct ordering of published releases, while still allowing developers to use the internal versioning scheme they prefer for their projects.

Compatible release¶

A compatible release clause consists of the compatible release operator ~= and a version identifier. It matches any candidate version that is expected to be compatible with the specified version.

The specified version identifier must be in the standard format described in Version scheme. Local version identifiers are NOT permitted in this version specifier.

For a given release identifier V.N, the compatible release clause is approximately equivalent to the pair of comparison clauses:

>= V.N, == V.*

This operator MUST NOT be used with a single segment version number such as ~=1.

For example, the following groups of version clauses are equivalent:

~= 2.2
>= 2.2, == 2.*

~= 1.4.5
>= 1.4.5, == 1.4.*

If a pre-release, post-release or developmental release is named in a compatible release clause as V.N.suffix, then the suffix is ignored when determining the required prefix match:

~= 2.2.post3
>= 2.2.post3, == 2.*

~= 1.4.5a4
>= 1.4.5a4, == 1.4.*

The padding rules for release segment comparisons means that the assumed degree of forward compatibility in a compatible release clause can be controlled by appending additional zeros to the version specifier:

~= 2.2.0
>= 2.2.0, == 2.2.*

~= 1.4.5.0
>= 1.4.5.0, == 1.4.5.*

Version matching¶

A version matching clause includes the version matching operator == and a version identifier.

The specified version identifier must be in the standard format described in Version scheme, but a trailing .* is permitted on public version identifiers as described below.

By default, the version matching operator is based on a strict equality comparison: the specified version must be exactly the same as the requested version. The only substitution performed is the zero padding of the release segment to ensure the release segments are compared with the same length.

Whether or not strict version matching is appropriate depends on the specific use case for the version specifier. Automated tools SHOULD at least issue warnings and MAY reject them entirely when strict version matches are used inappropriately.

Prefix matching may be requested instead of strict comparison, by appending a trailing .* to the version identifier in the version matching clause. This means that additional trailing segments will be ignored when determining whether or not a version identifier matches the clause. If the specified version includes only a release segment, then trailing components (or the lack thereof) in the release segment are also ignored.

For example, given the version 1.1.post1, the following clauses would match or not as shown:

== 1.1        # Not equal, so 1.1.post1 does not match clause
== 1.1.post1  # Equal, so 1.1.post1 matches clause
== 1.1.*      # Same prefix, so 1.1.post1 matches clause

For purposes of prefix matching, the pre-release segment is considered to have an implied preceding ., so given the version 1.1a1, the following clauses would match or not as shown:

== 1.1        # Not equal, so 1.1a1 does not match clause
== 1.1a1      # Equal, so 1.1a1 matches clause
== 1.1.*      # Same prefix, so 1.1a1 matches clause if pre-releases are requested

An exact match is also considered a prefix match (this interpretation is implied by the usual zero padding rules for the release segment of version identifiers). Given the version 1.1, the following clauses would match or not as shown:

== 1.1        # Equal, so 1.1 matches clause
== 1.1.0      # Zero padding expands 1.1 to 1.1.0, so it matches clause
== 1.1.dev1   # Not equal (dev-release), so 1.1 does not match clause
== 1.1a1      # Not equal (pre-release), so 1.1 does not match clause
== 1.1.post1  # Not equal (post-release), so 1.1 does not match clause
== 1.1.*      # Same prefix, so 1.1 matches clause

It is invalid to have a prefix match containing a development or local release such as 1.0.dev1.* or 1.0+foo1.*. If present, the development release segment is always the final segment in the public version, and the local version is ignored for comparison purposes, so using either in a prefix match wouldn’t make any sense.

The use of == (without at least the wildcard suffix) when defining dependencies for published distributions is strongly discouraged as it greatly complicates the deployment of security fixes. The strict version comparison operator is intended primarily for use when defining dependencies for repeatable deployments of applications while using a shared distribution index.

If the specified version identifier is a public version identifier (no local version label), then the local version label of any candidate versions MUST be ignored when matching versions.

If the specified version identifier is a local version identifier, then the local version labels of candidate versions MUST be considered when matching versions, with the public version identifier being matched as described above, and the local version label being checked for equivalence using a strict string equality comparison.

Version exclusion¶

A version exclusion clause includes the version exclusion operator != and a version identifier.

The allowed version identifiers and comparison semantics are the same as those of the Version matching operator, except that the sense of any match is inverted.

For example, given the version 1.1.post1, the following clauses would match or not as shown:

!= 1.1        # Not equal, so 1.1.post1 matches clause
!= 1.1.post1  # Equal, so 1.1.post1 does not match clause
!= 1.1.*      # Same prefix, so 1.1.post1 does not match clause

Inclusive ordered comparison¶

An inclusive ordered comparison clause includes a comparison operator and a version identifier, and will match any version where the comparison is correct based on the relative position of the candidate version and the specified version given the consistent ordering defined by the standard Version scheme.

The inclusive ordered comparison operators are <= and >=.

As with version matching, the release segment is zero padded as necessary to ensure the release segments are compared with the same length.

Local version identifiers are NOT permitted in this version specifier.

Exclusive ordered comparison¶

The exclusive ordered comparisons > and < are similar to the inclusive ordered comparisons in that they rely on the relative position of the candidate version and the specified version given the consistent ordering defined by the standard Version scheme. However, they specifically exclude pre-releases, post-releases, and local versions of the specified version.

The exclusive ordered comparison >V MUST NOT allow a post-release of the given version unless V itself is a post release. You may mandate that releases are later than a particular post release, including additional post releases, by using >V.postN. For example, >1.7 will allow 1.7.1 but not 1.7.0.post1 and >1.7.post2 will allow 1.7.1 and 1.7.0.post3 but not 1.7.0.

The exclusive ordered comparison >V MUST NOT match a local version of the specified version.

The exclusive ordered comparison <V MUST NOT allow a pre-release of the specified version unless the specified version is itself a pre-release. Allowing pre-releases that are earlier than, but not equal to a specific pre-release may be accomplished by using <V.rc1 or similar.

As with version matching, the release segment is zero padded as necessary to ensure the release segments are compared with the same length.

Local version identifiers are NOT permitted in this version specifier.

Arbitrary equality¶

Arbitrary equality comparisons are simple string equality operations which do not take into account any of the semantic information such as zero padding or local versions. The comparison MUST treat ASCII letters case-insensitively, e.g. by lowercasing, and is unspecified for non-ASCII text. This operator also does not support prefix matching as the == operator does.

The primary use case for arbitrary equality is to allow for specifying a version which cannot otherwise be represented by this specification. This operator is special and acts as an escape hatch to allow someone using a tool which implements this specification to still install a legacy version which is otherwise incompatible with this specification.

An example would be ===foobar which would match a version of foobar.

This operator may also be used to explicitly require an unpatched version of a project such as ===1.0 which would not match for a version 1.0+downstream1.

Use of this operator is heavily discouraged and tooling MAY display a warning when it is used.

Handling of pre-releases¶

Pre-releases of any kind, including developmental releases, are implicitly excluded from all version specifiers, unless they are already present on the system, explicitly requested by the user, or if the only available version that satisfies the version specifier is a pre-release.

By default, dependency resolution tools SHOULD:

• accept already installed pre-releases for all version specifiers

• accept remotely available pre-releases for version specifiers where there is no final or post release that satisfies the version specifier

• exclude all other pre-releases from consideration

Dependency resolution tools MAY issue a warning if a pre-release is needed to satisfy a version specifier.

Dependency resolution tools SHOULD also allow users to request the following alternative behaviours:

• accepting pre-releases for all version specifiers

• excluding pre-releases for all version specifiers (reporting an error or warning if a pre-release is already installed locally, or if a pre-release is the only way to satisfy a particular specifier)

Dependency resolution tools MAY also allow the above behaviour to be controlled on a per-distribution basis.

Post-releases and final releases receive no special treatment in version specifiers - they are always included unless explicitly excluded.

Examples¶

• ~=3.1: version 3.1 or later, but not version 4.0 or later.

• ~=3.1.2: version 3.1.2 or later, but not version 3.2.0 or later.

• ~=3.1a1: version 3.1a1 or later, but not version 4.0 or later.

• == 3.1: specifically version 3.1 (or 3.1.0), excludes all pre-releases, post releases, developmental releases and any 3.1.x maintenance releases.

• == 3.1.*: any version that starts with 3.1. Equivalent to the ~=3.1.0 compatible release clause.

• ~=3.1.0, != 3.1.3: version 3.1.0 or later, but not version 3.1.3 and not version 3.2.0 or later.

File URLs¶

File URLs take the form of file://<host>/<path>. If the <host> is omitted it is assumed to be localhost and even if the <host> is omitted the third slash MUST still exist. The <path> defines what the file path on the filesystem that is to be accessed.

On the various *nix operating systems the only allowed values for <host> is for it to be omitted, localhost, or another FQDN that the current machine believes matches its own host. In other words, on *nix the file:// scheme can only be used to access paths on the local machine.

On Windows the file format should include the drive letter if applicable as part of the <path> (e.g. file:///c:/path/to/a/file). Unlike *nix on Windows the <host> parameter may be used to specify a file residing on a network share. In other words, in order to translate \\machine\volume\file to a file:// url, it would end up as file://machine/volume/file. For more information on file:// URLs on Windows see MSDN.