Introduction
Versions are a communication mechanism. This specification outlines a set of rules and requirements that dictate how software version numbers can be assigned, incremented, grouped, compared and matched.
For this system to work, you MUST declare a public API. This MAY consist of documentation or be enforced by the software itself. Regardless, it is important that an API is clear and precise. Changes to your public API are communicated with specific increments to your software's Semantic Version.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.
Versions
Given a semantic version MAJOR.MINOR.PATCH, increment the:
MAJORversion when you make incompatible API changes;MINORversion when you add functionality in a backward compatible manner;PATCHversion when you make changes that leave the declared public API as it is.
Optional labels for a pre-release and build extend the format:
MAJOR.MINOR.PATCH-PRERELEASE+BUILD.
-
Software using semantic versions MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.
-
A normal version number MUST take the form
X.Y.ZwhereX,YandZare non-negative integers, and MUST NOT contain leading zeroes.Xis the major version,Yis the minor version, andZis the patch version. Each element MUST increase numerically. For instance:1.9.0→1.10.0→1.11.0. -
Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
-
Major version zero (
0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. -
Version
1.0.0SHOULD be the first stable release and MUST define the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes. -
Patch version
Z(x.y.Z | x > 0) MUST be incremented when a release leaves the declared public API unchanged, unless the release takes the minor increment that rule 7 allows. That covers corrections which bring behaviour into agreement with the declaration, corrections which honour the evident intended behaviour where the declaration is silent, and changes with no bearing on the declaration at all: refactors, dependency updates, performance work. A patch MAY be externally observable, and a correction usually is. What makes it a patch is that the declared contract is the same before and after, not that nothing visible changed. -
Minor version
Y(x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to0when minor version is incremented. -
Major version
X(X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the declared public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to0when major version is incremented. -
Behaviour that the declaration does not describe and that was never intended to form part of the public API (a symbol exported by accident, an undocumented side effect, or an implementation detail a consumer can reach) is NOT covered by the compatibility guarantees above. Correcting or removing such behaviour MUST NOT require a major increment. Where it is known to be relied upon in practice, authors SHOULD announce the correction in a minor release before removing the behaviour, and SHOULD record it in release notes. Undocumented behaviour that was intended is a different case: the declaration is incomplete rather than the behaviour wrong. Correcting it toward that intent is a patch; writing it into the declaration is a minor.
-
A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens
[0-9A-Za-z-], MUST NOT be empty, and numeric identifiers MUST NOT include leading zeroes. Pre-release versions have lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples:1.0.0-alpha,1.0.0-alpha.1,1.0.0-0.3.7,1.0.0-x.7.z.92,1.0.0-x-y-z.--. -
A build MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens
[0-9A-Za-z-]and MUST NOT be empty. A build identifier MAY have leading zeroes, but then it is not numeric: it compares as text (see Precedence, 5), so+001and+1are different builds rather than the same number written twice. Unlike "build metadata" in later drafts of Semantic Versioning, a build participates in precedence; it is the antithesis of a pre-release. Two versions that differ only in the build therefore do not have the same precedence (see Precedence). Examples:1.0.0-alpha+001,1.0.0+20130313144700,1.0.0-beta+exp.sha.5114f85,1.0.0+21AF26D3----117B344092BD.
Precedence
Precedence refers to how versions are compared to each other when ordered.
-
Precedence MUST be calculated by separating the version into major, minor, patch, pre-release and build identifiers, in that order.
-
Precedence is determined by the first difference when comparing each of these identifiers from left to right. Major, minor and patch are always compared numerically.
Example:
1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 -
When major, minor and patch are equal, a pre-release version has lower precedence than a normal version.
Example:
1.0.0-alpha < 1.0.0 -
When major, minor, patch and pre-release are equal, a version with a build has higher precedence than one without it. Where Semantic Versioning 2.0.0 discards build metadata for ordering, Semantic Versions restores it: a build names a more specific artifact of that release, so it ranks above the plain release rather than below it like a pre-release.
Example:
1.0.0 < 1.0.0+build.1 < 1.0.0+build.2 -
Precedence for two pre-releases with the same major, minor and patch, or for two builds whose versions are equal up to the build, MUST be determined by comparing each dot separated identifier from left to right until a difference is found:
- Numeric identifiers are compared numerically. An identifier is numeric
when it is
0or consists of digits with no leading zero. - All other identifiers, including any with a leading zero, are compared lexically in ASCII sort order.
- Numeric identifiers always have lower precedence than non-numeric identifiers.
- A larger set of pre-release (or build) fields has higher precedence than a smaller set, if all preceding identifiers are equal.
Example:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0 < 1.0.0+build.1 - Numeric identifiers are compared numerically. An identifier is numeric
when it is
-
A context is identity, not precedence. It is not one of the identifiers above, so it never changes how two versions order; which versions may be compared or selected together is a property of the set or range that holds them.
Sets
A Set is a collection of versions. Sets are how the ecosystem actually reasons about software: "every version of this package", "the 1.x line", "what this range selects". Semantic Versions defines them directly, so tools can talk about groups of versions, not just one at a time.
- A Set MUST contain a collection of semantic versions.
- A Set MAY be scoped to a context; such a Contextual Set MUST contain only versions sharing that context.
- Fixing any single identifier (
MAJOR,MINOR,PATCH,PRE-RELEASEorBUILD) partitions a set into Subsets. - A Set MUST NOT contain two versions of equal precedence.
Versions that differ in their build are distinct versions with distinct
precedence (Versions, 11), so
3.2.1and3.2.1+build.123MAY both be members. - An Unordered Set imposes no ordering; an Ordered Set MUST be sorted by precedence.
Examples:
- Valid set:
5.6.7, 3.2.1+build.123, 3.2.1, 4.0.0, 1.16.3, 0.9.8 - Invalid set:
3.2.1, 3.2.1 - Valid set:
3.2.1, 3.2.1+build.123 - Ordered set:
0.9.8, 1.16.3, 3.2.1, 3.2.1+build.123, 4.0.0, 5.6.7 - Unordered set:
5.6.7, 3.2.1+build.123, 3.2.1, 4.0.0, 1.16.3, 0.9.8 - Normal versions only:
0.9.8, 1.16.3, 3.2.1, 4.0.0, 5.6.7 - The pre-releases of one release:
1.0.0-pre.1, 1.0.0-pre.2, 1.0.0-pre.3 - The builds of one release:
1.0.0+build.1, 1.0.0+build.2, 1.0.0+build.3
Context
A version rarely travels alone; it is understood in context. A context is
the identity a version belongs to: a package, module, image, crate, service or
any other named artifact. It scopes a version with an @ separator
(context@MAJOR.MINOR.PATCH-PRE+BUILD), so that where a bare 1.2.3 is
ambiguous, app@1.2.3-canary.1+sha.1a8c… names a specific build of a specific
thing. A version never contains @, so the context is everything before the
last one; a name may itself contain @, as an npm scope does.
Context is deliberately ecosystem-agnostic. Everything above (the version
grammar, precedence, sets and ranges) makes no assumption about where a version
lives. An ecosystem binds to the spec by qualifying a context with a source,
written source:name, which names the origin or ecosystem. The same rules then
apply identically everywhere: npm:react@18.2.0, pypi:flask@3.0.0,
gem:rails@7.1.3, cargo:serde@1.0.203, golang:golang.org/x/text@0.14.0.
A source is a lowercase token, and a name keeps whatever namespace its
ecosystem uses, such as an npm scope or a Maven group: npm:@vue/cli@5.0.8,
maven:com.google.guava/guava@33.0.0. A private origin is a source like any
other: internal:billing@2.4.0. Source-qualified contexts are what the
extensions build on.
SubSets
Fixing any one coordinate of a version yields a subset of context@*. Every
position (major, minor, patch, pre-release and build) defines its own family.
The major, minor and patch families each partition the full set <context>@*;
the pre-release and build families partition the versions that carry that
label. The table below is set notation, not range syntax: a
range fixes leading coordinates only (1.2.x), and *.0.* is not
a range.
| Major SubSet | Minor SubSet | Patch SubSet | Pre-release SubSet | Build SubSet |
|---|---|---|---|---|
0.*.* | *.0.* | *.*.0 | *.*.*-0 | *.*.*+0 |
1.*.* | *.1.* | *.*.1 | *.*.*-1 | *.*.*+1 |
2.*.* | *.2.* | *.*.2 | *.*.*-2 | *.*.*+2 |
| … | … | … | … | … |
Ordered & unordered sets
The same members, two arrangements. An unordered set lists versions as they were encountered; an ordered set sorts them by precedence. Ordering is a property of the set, not of its members.
| Unordered | Ordered |
|---|---|
react@9.3.1 | react@1.0.0 |
react@6.8.0 | react@6.8.0 |
react@7.1.2 | react@7.1.2 |
react@1.0.0 | react@9.3.1 |
Contextual sets
A set scoped to a single context (react@*, express@*) is a contextual
set: every version that shares that identity. Two contextual sets can hold
identical version numbers and still be distinct, because their context
differs.
react@* | express@* |
|---|---|
react@1.2.3 | express@1.2.3 |
react@8.9.1 | express@8.9.1 |
react@7.1.0-alpha.3 | express@7.1.0-alpha.3 |
Ranges
A range is a set of comparators which specify the versions that satisfy the
range. A range is composed of one or more comparator sets, joined by ||. A
version matches a range if and only if every comparator in at least one of the
||-separated comparator sets is satisfied by the version.
>=1.2.7 <1.3.0matches1.2.7,1.2.8and1.2.99, but not1.2.6,1.3.0or1.1.0.1.2.7 || >=1.2.9 <2.0.0matches1.2.7,1.2.9and1.4.6, but not1.2.8or2.0.0.
Ranges may be non-contiguous, so a version might be neither greater than, less
than, nor a member of a range. For example, 1.2 <1.2.9 || >2.0.0 has a hole
from 1.2.9 to 2.0.0: 1.2.10 is not greater than the range (2.0.1
satisfies, which is higher), not less than it (1.2.8 satisfies, which is
lower), and does not satisfy it. Test membership directly.
A range MAY carry a context the same way a version does
(npm:react@^18.0.0). A context-scoped range selects from the
contextual set of that context: a version of another
context, or of none, does not satisfy it, whatever its number. A range with
no context places no constraint on context, so it selects by number alone.
The range, comparator and advanced range syntax in this specification descend from
node-semver, thesemverpackage Isaac Z. Schlueter wrote for npm in 2011, which became the de facto range language of the JavaScript ecosystem. Isaac proposed bringing that grammar into Semantic Versioning in 2020 (semver/semver#584); the proposal is still open. Semantic Versions adopts it as normative text and extends it with the approximate operator~>, pre-release and build channels, explicit pre-release wildcards, and contexts.
Operators
An operator expresses how to compare a version. Supported operators are:
<Less than>Greater than=Equal to<=Less than or equal to>=Greater than or equal to
Comparators
A comparator is composed of an operator and a version. Comparators can be
joined by whitespace to form a comparator set, satisfied by the
intersection of all the comparators it includes.
>=1.2.7matches1.2.7,1.2.8,2.5.3and1.3.9, but not1.2.6or1.1.0.
The operator MAY be omitted, in which case = is implied: 1.2.3 is
=1.2.3. A partial version after an operator stands for the whole tuple it
names, so the comparator applies to all of it:
>1:=>=2.0.0; it matches2.0.0and3.1.0, but not1.0.1or1.1.0.>1.2:=>=1.3.0, and>=1.2:=>=1.2.0<1.2:=<1.2.0-0, and<=1.2:=<1.3.0-0=1.2:=>=1.2.0 <1.3.0-0(an x-range)
Advanced range syntax
Advanced ranges desugar to primitive comparators in deterministic ways, and may
be combined in the same way as primitive comparators, using whitespace or ||.
Upper bounds desugar to <X.Y.Z-0. Because 0 is the lowest possible
pre-release identifier, such a bound excludes X.Y.Z and every pre-release of
it; it does not open a pre-release channel, since
nothing on that tuple can fall below it.
Hyphen ranges X.Y.Z - A.B.C
Specifies an inclusive set.
1.2.3 - 2.3.4:=>=1.2.3 <=2.3.4
If a partial version is provided as the first version, the missing pieces are replaced with zeroes.
1.2 - 2.3.4:=>=1.2.0 <=2.3.4
If a partial version is provided as the second version, all versions that start with the supplied parts of the tuple are accepted, but nothing greater than them.
1.2.3 - 2.3:=>=1.2.3 <2.4.0-01.2.3 - 2:=>=1.2.3 <3.0.0-0
X-ranges 1.2.x 1.X 1.2.* *
Any of X, x or * may stand in for a numeric value in the
[major, minor, patch] tuple.
*:=>=0.0.0(any stable version). Pre-releases opt in through a channel;*-*is the universal channel that admits every pre-release.1.x:=>=1.0.0 <2.0.0-0(matching major version)1.2.x:=>=1.2.0 <1.3.0-0(matching major and minor versions)
A partial version range is treated as an x-range, so the special character is optional.
""(empty string) :=*:=>=0.0.01:=1.x.x:=>=1.0.0 <2.0.0-01.2:=1.2.x:=>=1.2.0 <1.3.0-0
Tilde ranges ~1.2.3 ~1.2 ~1
Allows patch-level changes if a minor version is specified on the comparator; allows minor-level changes if not.
~1.2.3:=>=1.2.3 <1.(2+1).0:=>=1.2.3 <1.3.0-0~1.2:=>=1.2.0 <1.(2+1).0:=>=1.2.0 <1.3.0-0(same as1.2.x)~1:=>=1.0.0 <(1+1).0.0:=>=1.0.0 <2.0.0-0(same as1.x)~0.2.3:=>=0.2.3 <0.(2+1).0:=>=0.2.3 <0.3.0-0~0.2:=>=0.2.0 <0.(2+1).0:=>=0.2.0 <0.3.0-0(same as0.2.x)~0:=>=0.0.0 <(0+1).0.0:=>=0.0.0 <1.0.0-0(same as0.x)~1.2.3-beta.2:=>=1.2.3-beta.2 <1.3.0-0
A pre-release on the comparator declares a
pre-release channel on the 1.2.3 tuple. The channel is
the prefix beta.2, so 1.2.3-beta.2 and 1.2.3-beta.2.1 are admitted, but
1.2.3-beta.3 (a different sibling) and 1.2.4-beta.2 (a different tuple) are
not.
Caret ranges ^1.2.3 ^0.2.5 ^0.0.4
Allows changes that do not modify the left-most non-zero element in the
[major, minor, patch] tuple. In other words, this allows patch and minor
updates for versions 1.0.0 and above, patch updates for versions
0.X >=0.1.0, and no updates for versions 0.0.X.
Many authors treat a 0.x version as if the x were the major
"breaking-change" indicator. Caret ranges are ideal when an author may make
breaking changes between 0.2.4 and 0.3.0 releases, which is a common
practice. However, they presume that there will not be breaking changes
between 0.2.4 and 0.2.5; they allow changes that are presumed to be additive
(but non-breaking), according to commonly observed practices.
^1.2.3:=>=1.2.3 <2.0.0-0^0.2.3:=>=0.2.3 <0.3.0-0^0.0.3:=>=0.0.3 <0.0.4-0^1.2.3-beta.2:=>=1.2.3-beta.2 <2.0.0-0: the pre-release declares abeta.2channel on the1.2.3tuple.1.2.3-beta.2.4is admitted;1.2.3-rc.1(a different channel) and1.2.4-beta.2(a different tuple) are not. Stable releases in range are admitted normally.^0.0.3-beta:=>=0.0.3-beta <0.0.4-0: thebetachannel on the0.0.3tuple, so0.0.3-beta.2is admitted and0.0.3-rc.1is not.
When parsing caret ranges, a missing patch value desugars to the number 0,
but allows flexibility within that value, even if the major and minor versions
are both 0.
^1.2.x:=>=1.2.0 <2.0.0-0^0.0.x:=>=0.0.0 <0.1.0-0^0.0:=>=0.0.0 <0.1.0-0
Missing minor and patch values desugar to zero, but also allow flexibility
within those values, even if the major version is zero.
^1.x:=>=1.0.0 <2.0.0-0^0.x:=>=0.0.0 <1.0.0-0
Approximate ranges
The pessimistic operator ~> is the range operator of RubyGems and Bundler,
and it keeps their meaning here: drop the last supplied part, and allow
anything up to the next value of the part before it. With one or three parts
that is the same as the tilde; with two parts it
reaches to the next major, where a tilde stops at the next minor.
~>1:=>=1.0.0 <2.0.0-0(same as~1)~>1.2:=>=1.2.0 <2.0.0-0(where~1.2is>=1.2.0 <1.3.0-0)~>0.2:=>=0.2.0 <1.0.0-0~>1.2.3:=>=1.2.3 <1.3.0-0(same as~1.2.3)~>1.2.3-alpha.1:=>=1.2.3-alpha.1 <1.3.0-0: thealpha.1channel on the1.2.3tuple (same as~1.2.3-alpha.1)
An x or * in the last position is not a supplied part, so ~>1.2.x is
~>1.2 and ~>1.x is ~>1.
Pre-release channels
A pre-release is provisional: it ranks below its eventual release
(1.0.0-rc < 1.0.0), so it is a step toward a version rather than a
refinement of it. Consequently pre-releases are excluded by default (a
range of stable comparators never admits them), and a range opts in by naming
the pre-release it wants, as in ^1.0.0-rc. That name is a channel: a
prefix filter scoped to the comparator's [major, minor, patch] tuple, exactly
mirroring a build channel. There is no global "include
pre-releases" switch; admission is always a property of the range.
- A range with no pre-release token anywhere admits stable versions only.
- A comparator, tilde, or caret carrying a pre-release declares a channel whose
prefix is its pre-release identifiers, scoped to its tuple. A pre-release
candidate is admitted if and only if it is within the numeric bounds and
its identifiers, compared left to right, begin with the prefix of some
channel declared on the same tuple.
^1.0.0-rc(prefixrc) admits1.0.0-rc,1.0.0-rc.1,1.0.0-rc.2; never1.0.0-beta(different channel) and never1.5.0-rc(different tuple).^1.0.0-rc.2(prefixrc.2) admits therc.2sub-tree only.
- Two explicit wildcards provide the opt-in that a global flag used to:
X.Y.Z-*is the empty-prefix channel for one tuple: any pre-release of that release.^1.0.0-*admits1.0.0-alpha,1.0.0-rc.1, … (plus stable in range), but not1.5.0-beta.*-*is the universal channel: admit pre-releases on every tuple. This is the in-range equivalent of the old toggle (npm'sincludePrerelease, pip's--pre).
- Stable versions are unaffected by channels: once inside the numeric bounds they are always admitted.
- A tilde or caret carrying a pre-release applies its channel to the numeric lower bound it desugars to. A hyphen range keeps each endpoint's pre-release as that endpoint's channel.
^1.0.0-rc:=>=1.0.0-rc <2.0.0-0: thercchannel of1.0.0, plus all stable up to<2.0.0.~1.2.3-beta:=>=1.2.3-beta <1.3.0-0: thebetachannel of1.2.3.^1.0.0-*:=>=1.0.0-0 <2.0.0-0+ any-pre channel on1.0.0: every pre-release of1.0.0, plus stable1.x.*-*: any version at all, stable or pre-release.
Pre-release channels are a deliberate divergence from Semantic Versioning 2.0.0 and its
node-semverimplementation, which admit any pre-release sharing a comparator's tuple (an all-or-nothing, any-prefix rule) and expose a separateincludePrereleaseflag. Scoping to a prefix makes^1.0.0-alphamean the alpha channel, not "everything from alpha onward", and folds the flag into the grammar. This precise, floating model follows NuGet's shipped behaviour (1.2.3-alpha.*prefix floats,*-*for everything). Try channels on the range selector.
Subset selection: one rule for pre-release and build
Pre-release and build are the two labels a version can carry, and a range selects among them with the same channel/prefix rule: identifiers on a comparator, matched left-to-right as a prefix, scoped to that comparator's tuple. They differ only in their default, and that difference follows directly from precedence:
| Label | Ranks vs. its release | Meaning | Default in a range | Opt in / narrow with |
|---|---|---|---|---|
| Pre-release | below (1.0.0-rc < 1.0.0) | provisional, on the way to the release | excluded | name it (-rc), -*, or *-* |
| Build | above (1.0.0 < 1.0.0+win) | a refinement, a specific artifact of the release | included | a channel narrows (+win) |
A version is in a range when it passes every comparator's numeric test and, for whichever labels it carries, the range's channels admit them. Nothing is configured out-of-band.
Build channels
Because a build carries precedence, it can also select. A build
attached to a comparator, tilde, or caret, as in ^1.0.0+win, is a channel
filter: it is orthogonal to the numeric comparison and admits only versions
whose own build begins with the channel's identifiers. This makes the build a
first-class way to range over release channels and variants: signed builds,
platform or architecture targets, content digests.
- A comparator's build MUST be treated as a channel filter, not as part of the numeric comparison.
- The numeric comparison MUST ignore the build on both the comparator and the candidate version.
- A version satisfies a channel if and only if its build identifiers, compared left to right, begin with the channel's identifiers.
- A range with no build channel matches any build (and the build-less release); a channel excludes versions that carry no build.
- A tilde or caret carrying a channel MUST apply that channel to every comparator it desugars to. A hyphen range keeps each endpoint's build as that endpoint's channel, exactly as it keeps each endpoint's pre-release.
^1.0.0+win:=>=1.0.0+win <2.0.0-0+win: thewinchannel within^1.0.0, so it matches1.4.2+win.x64, not1.4.2+linux.x64or1.4.2.>=1.1.0+linux.x64: thelinux.x64variant at or above1.1.0.1.0.0+sha.a1b2c3: pins the exact artifact (and any narrower build beneath it).1.2.3+win - 2.0.0:=>=1.2.3+win <=2.0.0: thewinchannel from1.2.3up to and including2.0.0, since a version must satisfy both comparators and the first carries the channel.^1.0.0: no channel, so every variant of every release in range matches, build or not.
Build channels are a deliberate divergence from Semantic Versioning 2.0.0, which discards build metadata during range resolution. See Build Variants for os/arch/abi channels and Package Integrity for a channel built on content digests.
This specification is licensed under CC BY 3.0. The BNF grammars are at semver.xyz/grammar, implementations at semver.xyz/libraries, and answers to common questions, including interoperability with Python's PEP 440, in the FAQ.