Specification

Semantic Versions 1.0.0

Rendered from spec/SPEC.md · Markdown · Suggest an edit

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:

  • MAJOR version when you make incompatible API changes;
  • MINOR version when you add functionality in a backward compatible manner;
  • PATCH version 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.

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

  2. A normal version number MUST take the form X.Y.Z where X, Y and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 → 1.10.0 → 1.11.0.

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

  4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

  5. Version 1.0.0 SHOULD 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.

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

  7. 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 to 0 when minor version is incremented.

  8. 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 to 0 when major version is incremented.

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

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

  11. 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 +001 and +1 are 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.

  1. Precedence MUST be calculated by separating the version into major, minor, patch, pre-release and build identifiers, in that order.

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

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

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

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

    1. Numeric identifiers are compared numerically. An identifier is numeric when it is 0 or consists of digits with no leading zero.
    2. All other identifiers, including any with a leading zero, are compared lexically in ASCII sort order.
    3. Numeric identifiers always have lower precedence than non-numeric identifiers.
    4. 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

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

  1. A Set MUST contain a collection of semantic versions.
  2. A Set MAY be scoped to a context; such a Contextual Set MUST contain only versions sharing that context.
  3. Fixing any single identifier (MAJOR, MINOR, PATCH, PRE-RELEASE or BUILD) partitions a set into Subsets.
  4. 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.1 and 3.2.1+build.123 MAY both be members.
  5. 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 SubSetMinor SubSetPatch SubSetPre-release SubSetBuild 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.

UnorderedOrdered
react@9.3.1react@1.0.0
react@6.8.0react@6.8.0
react@7.1.2react@7.1.2
react@1.0.0react@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.3express@1.2.3
react@8.9.1express@8.9.1
react@7.1.0-alpha.3express@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.0 matches 1.2.7, 1.2.8 and 1.2.99, but not 1.2.6, 1.3.0 or 1.1.0.
  • 1.2.7 || >=1.2.9 <2.0.0 matches 1.2.7, 1.2.9 and 1.4.6, but not 1.2.8 or 2.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, the semver package 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.7 matches 1.2.7, 1.2.8, 2.5.3 and 1.3.9, but not 1.2.6 or 1.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 matches 2.0.0 and 3.1.0, but not 1.0.1 or 1.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-0
  • 1.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.0
  • 1 := 1.x.x := >=1.0.0 <2.0.0-0
  • 1.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 as 1.2.x)
  • ~1 := >=1.0.0 <(1+1).0.0 := >=1.0.0 <2.0.0-0 (same as 1.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 as 0.2.x)
  • ~0 := >=0.0.0 <(0+1).0.0 := >=0.0.0 <1.0.0-0 (same as 0.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 a beta.2 channel on the 1.2.3 tuple. 1.2.3-beta.2.4 is admitted; 1.2.3-rc.1 (a different channel) and 1.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: the beta channel on the 0.0.3 tuple, so 0.0.3-beta.2 is admitted and 0.0.3-rc.1 is 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.2 is >=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: the alpha.1 channel on the 1.2.3 tuple (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.

  1. A range with no pre-release token anywhere admits stable versions only.
  2. 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 (prefix rc) admits 1.0.0-rc, 1.0.0-rc.1, 1.0.0-rc.2; never 1.0.0-beta (different channel) and never 1.5.0-rc (different tuple).
    • ^1.0.0-rc.2 (prefix rc.2) admits the rc.2 sub-tree only.
  3. 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-* admits 1.0.0-alpha, 1.0.0-rc.1, … (plus stable in range), but not 1.5.0-beta.
    • *-* is the universal channel: admit pre-releases on every tuple. This is the in-range equivalent of the old toggle (npm's includePrerelease, pip's --pre).
  4. Stable versions are unaffected by channels: once inside the numeric bounds they are always admitted.
  5. 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: the rc channel of 1.0.0, plus all stable up to <2.0.0.
  • ~1.2.3-beta := >=1.2.3-beta <1.3.0-0: the beta channel of 1.2.3.
  • ^1.0.0-* := >=1.0.0-0 <2.0.0-0 + any-pre channel on 1.0.0: every pre-release of 1.0.0, plus stable 1.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-semver implementation, which admit any pre-release sharing a comparator's tuple (an all-or-nothing, any-prefix rule) and expose a separate includePrerelease flag. Scoping to a prefix makes ^1.0.0-alpha mean 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:

LabelRanks vs. its releaseMeaningDefault in a rangeOpt in / narrow with
Pre-releasebelow (1.0.0-rc < 1.0.0)provisional, on the way to the releaseexcludedname it (-rc), -*, or *-*
Buildabove (1.0.0 < 1.0.0+win)a refinement, a specific artifact of the releaseincludeda 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.

  1. A comparator's build MUST be treated as a channel filter, not as part of the numeric comparison.
  2. The numeric comparison MUST ignore the build on both the comparator and the candidate version.
  3. A version satisfies a channel if and only if its build identifiers, compared left to right, begin with the channel's identifiers.
  4. A range with no build channel matches any build (and the build-less release); a channel excludes versions that carry no build.
  5. 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: the win channel within ^1.0.0, so it matches 1.4.2+win.x64, not 1.4.2+linux.x64 or 1.4.2.
  • >=1.1.0+linux.x64: the linux.x64 variant at or above 1.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: the win channel from 1.2.3 up to and including 2.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.