Public version identifiers¶

The canonical public version identifiers MUST comply with the followingscheme:

[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 withthis scheme but MUST also include the normalizations specified below.Installation tools MAY warn the user when non-compliant or ambiguous versionsare detected.

See alsoAppendix: Parsing version strings with regular expressions which provides a regularexpression to check strict conformance with the canonical format, aswell as a more permissive regular expression accepting inputs that mayrequire 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 sequencesof ASCII digits.

All numeric components MUST be interpreted and ordered according to theirnumeric value, not as text strings.

All numeric components MAY be zero. Except as described below for therelease segment, a numeric component of zero has no special significanceaside 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 theprevious section), along with an arbitrary “local version label”, separatedfrom the public version identifier by a plus. Local version labels haveno 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, thesemay be created by application developers and system integrators by applyingspecific backported bug fixes when upgrading to a new upstream release wouldbe too disruptive to the application or other integrated system (such as aLinux distribution).

The inclusion of the local version label makes it possible to differentiateupstream releases from potentially altered rebuilds by downstreamintegrators. The use of a local version identifier does not affect the kindof a release but, when applied to a source distribution, does indicate thatit may not contain the exact same code as the corresponding upstream release.

To ensure local version identifiers can be readily incorporated as part offilenames and URLs, and to avoid formatting inconsistencies in hexadecimalhash representations, local version labels MUST be limited to the followingset 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 localversion (divided by a.) separately. If a segment consists entirely ofASCII digits then that section should be considered an integer for comparisonpurposes and if a segment contains any ASCII letters then that segment iscompared lexicographically with case insensitivity. When comparing a numericand lexicographic segment, the numeric section always compares as greater thanthe lexicographic segment. Additionally a local version with a great number ofsegments will always compare as greater than a local version with fewersegments, as long as the shorter local version’s segments match the beginningof 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 theupstream project.

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

Source distributions using a local version identifier SHOULD provide thepython.integrator extension metadata (as defined inPEP 459).

Final releases¶

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

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

N(.N)*

Final releases within a project MUST be numbered in a consistentlyincreasing fashion, otherwise automated tools will not be able to upgradethem correctly.

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

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

For example:

0.90.9.10.9.2...0.9.100.9.111.01.0.11.12.02.0.1...

A release series is any set of final release numbers that start with acommon prefix. For example,3.3.1,3.3.5 and3.3.9.45 are allpart of the3.3 release series.

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

2012.42012.72012.102013.12013.6...

Pre-releases¶

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

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

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

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

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

Installation tools MAY accept bothc andrc releases for a commonrelease segment in order to handle some existing legacy distributions.

Installation tools SHOULD interpretc versions as being equivalent torc versions (that is,c1 indicates the same version asrc1).

Build tools, publication tools and index servers SHOULD disallow the creationof bothrc andc releases for a common release segment.

Post-releases¶

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

If used as part of a project’s development cycle, these post-releases areindicated 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 adevelopmental release segment is termed a “post-release”.

The post-release segment consists of the string.post, followed by anon-negative integer value. Post-releases are ordered by theirnumerical 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 releaseX.YbN.postM   # Post-release of a beta releaseX.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 releasesdirectly from source control which do not conflict with later projectreleases.

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

X.Y.devN    # Developmental release

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

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

Developmental releases are also permitted for pre-releases andpost-releases:

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

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

Version epochs¶

If included in a version identifier, the epoch appears before all othercomponents, 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 is0.

Most version identifiers will not include an epoch, as an explicit epoch isonly needed if a projectchanges the way it handles version numbering ina way that means the normal version ordering rules will give the wronganswer. For example, if a project is using date based versions like2014.04 and would like to switch to semantic versions like1.0, thenthe new releases would be identified asolder than the date based releaseswhen using the normal sorting scheme:

1.01.12.02013.102014.04

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

2013.102014.041!1.01!1.11!2.0

Normalization¶

In order to maintain better compatibility with existing versions there are anumber of “alternative” syntaxes that MUST be taken into account when parsingversions. These syntaxes MUST be considered when parsing a version, howeverthey 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 ofidentification practices across public and private Python projects. Inpractice, a single project attempting to use the full flexibility offeredby the scheme would create a situation where human users had difficultyfiguring out the relative order of versions, even though the rules aboveensure all compliant tools will order them consistently.

The following examples illustrate a small selection of the differentapproaches projects may choose to identify their releases, while stillensuring that the “latest release” and the “latest stable release” canbe easily determined, both by human users and automated tools.

Simple “major.minor” versioning:

0.10.20.31.01.1...

Simple “major.minor.micro” versioning:

1.1.01.1.11.1.21.2.0...

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

0.91.0a11.0a21.0b11.0rc11.01.1a1...

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

0.91.0.dev11.0.dev21.0.dev31.0.dev41.0c11.0c21.01.0.post11.1.dev1...

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

2012.12012.22012.3...2012.152013.12013.2...

Summary of permitted suffixes and relative ordering¶

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

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

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

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

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

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

Note thatc is considered to be semantically equivalent torc and mustbe sorted as if it wererc. Tools MAY reject the case of having the sameN for both ac and arc in the same release segment as ambiguousand 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 beordered as shown:

.devN, <no suffix>, .postN

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

.devN, <no suffix>

Note thatdevN andpostN MUST always be preceded by a dot, evenwhen 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 ashared prefix, ordering MUST be by the value of the numeric component.

The following example covers many of the possible combinations:

1.dev01.0.dev4561.0a11.0a2.dev4561.0a12.dev4561.0a121.0b1.dev4561.0b21.0b2.post345.dev4561.0b2.post3451.0rc1.dev4561.0rc11.01.0+abc.51.0+abc.71.0+51.0.post456.dev341.0.post4561.0.151.1.dev1

Version ordering across different metadata versions¶

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

Due to the nature of the simple installer API it is not possible for aninstaller to be aware of which metadata version a particular distribution wasusing. Additionally installers required the ability to create a reasonablyprioritized list that includes all, or as many as possible, versions ofa project to determine which versions it should install. These requirementsnecessitate a standardization across one parsing mechanism to be used for allversions of a project.

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

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

Compatibility with other version schemes¶

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

This allows automated distribution tools to provide consistently correctordering of published releases, while still allowing developers to usethe 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 expectedto be compatible with the specified version.

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

For a given release identifierV.N, the compatible release clause isapproximately 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 acompatible release clause asV.N.suffix, then the suffix is ignoredwhen 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 assumeddegree of forward compatibility in a compatible release clause can becontrolled 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 inVersion scheme, but a trailing.* is permitted on public versionidentifiers as described below.

By default, the version matching operator is based on a strict equalitycomparison: the specified version must be exactly the same as the requestedversion. Theonly substitution performed is the zero padding of therelease segment to ensure the release segments are compared with the samelength.

Whether or not strict version matching is appropriate depends on the specificuse case for the version specifier. Automated tools SHOULD at least issuewarnings and MAY reject them entirely when strict version matches are usedinappropriately.

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

For example, given the version1.1.post1, the following clauses wouldmatch 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 tohave an implied preceding., so given the version1.1a1, thefollowing 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 isimplied by the usual zero padding rules for the release segment of versionidentifiers). Given the version1.1, the following clauses wouldmatch 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 releasesuch as1.0.dev1.* or1.0+foo1.*. If present, the development releasesegment is always the final segment in the public version, and the local versionis ignored for comparison purposes, so using either in a prefix match wouldn’tmake any sense.

The use of== (without at least the wildcard suffix) when definingdependencies for published distributions is strongly discouraged as itgreatly complicates the deployment of security fixes. The strict versioncomparison operator is intended primarily for use when definingdependencies for repeatabledeployments of applications while usinga shared distribution index.

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

If the specified version identifier is a local version identifier, then thelocal version labels of candidate versions MUST be considered when matchingversions, with the public version identifier being matched as describedabove, and the local version label being checked for equivalence using astrict 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 asthose of theVersion matching operator, except that the sense of anymatch is inverted.

For example, given the version1.1.post1, the following clauses wouldmatch 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 aversion identifier, and will match any version where the comparison is correctbased on the relative position of the candidate version and the specifiedversion given the consistent ordering defined by the standardVersion scheme.

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

As with version matching, the release segment is zero padded as necessary toensure 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 inclusiveordered comparisons in that they rely on the relative position of the candidateversion and the specified version given the consistent ordering defined by thestandardVersion scheme. However, they specifically exclude pre-releases,post-releases, and local versions of the specified version.

The exclusive ordered comparison>VMUST NOT allow a post-releaseof the given version unlessV itself is a post release. You may mandatethat releases are later than a particular post release, including additionalpost releases, by using>V.postN. For example,>1.7 will allow1.7.1 but not1.7.0.post1 and>1.7.post2 will allow1.7.1and1.7.0.post3 but not1.7.0.

The exclusive ordered comparison>VMUST NOT match a local version ofthe specified version.

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

As with version matching, the release segment is zero padded as necessary toensure 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 donot take into account any of the semantic information such as zero padding orlocal versions. The comparison MUST treat ASCII letters case-insensitively, e.g.by lowercasing, and is unspecified for non-ASCII text. This operator also doesnot support prefix matching as the== operator does.

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

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

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

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

Handling of pre-releases¶

Pre-releases of any kind, including developmental releases, are implicitlyexcluded from all version specifiers,unless they are already presenton the system, explicitly requested by the user, or if the only availableversion 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 wherethere 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 neededto satisfy a version specifier.

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

• accepting pre-releases for all version specifiers

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

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

Post-releases and final releases receive no special treatment in versionspecifiers - 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 andnot version 3.2.0 or later.

File URLs¶

File URLs take the form offile://<host>/<path>. If the<host> isomitted it is assumed to belocalhost and even if the<host> is omittedthe third slash MUST still exist. The<path> defines what the file path onthe 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 currentmachine believes matches its own host. In other words, on *nix thefile://scheme can only be used to access paths on the local machine.

On Windows the file format should include the drive letter if applicable aspart of the<path> (e.g.file:///c:/path/to/a/file). Unlike *nix onWindows the<host> parameter may be used to specify a file residing on anetwork share. In other words, in order to translate\\machine\volume\fileto afile:// url, it would end up asfile://machine/volume/file. Formore information onfile:// URLs on Windows seeMSDN.