---
title: "Specification — Semantic Versions 1.0.0 · semver.xyz"
description: "The Semantic Versions specification: versions, sets, ranges, comparators, operators and precedence."
url: "https://semver.xyz/spec/"
lang: "en"
---

Specification

# Semantic Versions 1.0.0

Rendered from [`spec/SPEC.md`](https://github.com/vltpkg/semantic-versions/blob/main/spec/SPEC.md) · [Markdown](https://www.semver.xyz/spec/SPEC.md) · [Suggest an edit](https://github.com/vltpkg/semantic-versions/edit/main/spec/SPEC.md)

Contents

[Introduction](https://www.semver.xyz/spec#introduction) [Versions](https://www.semver.xyz/spec#versions) [Precedence](https://www.semver.xyz/spec#precedence) [Sets](https://www.semver.xyz/spec#sets) [Ranges](https://www.semver.xyz/spec#ranges) [Operators](https://www.semver.xyz/spec#operators) [Comparators](https://www.semver.xyz/spec#comparators) [Advanced range syntax](https://www.semver.xyz/spec#advanced-range-syntax) [Approximate ranges](https://www.semver.xyz/spec#approximate-ranges) [Pre-release channels](https://www.semver.xyz/spec#pre-release-channels) [Build channels](https://www.semver.xyz/spec#build-channels)

## 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](https://www.rfc-editor.org/rfc/rfc2119), [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)) 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](https://www.semver.xyz/spec#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](https://www.semver.xyz/spec#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](https://www.semver.xyz/spec#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](https://www.semver.xyz/spec#sets) or [range](https://www.semver.xyz/spec#ranges) 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](https://www.semver.xyz/spec#precedence). Versions that differ in their build are distinct versions with distinct precedence ([Versions](https://www.semver.xyz/spec#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](https://www.semver.xyz/extensions.md) 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](https://www.semver.xyz/spec#ranges) 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](https://www.semver.xyz/spec#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.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](https://www.semver.xyz/spec#context) the same way a version does (`npm:react@^18.0.0`). A context-scoped range selects from the [contextual set](https://www.semver.xyz/spec#contextual-sets) 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`](https://github.com/npm/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](https://github.com/semver/semver/pull/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](https://www.semver.xyz/spec#x-ranges-12x-1x-12-))

## 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](https://www.semver.xyz/spec#pre-release-channels), 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](https://www.semver.xyz/spec#pre-release-channels); `*-*` 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](https://www.semver.xyz/spec#pre-release-channels) 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](https://www.semver.xyz/spec#pre-release-channels) 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](https://www.semver.xyz/spec#tilde-ranges-123-12-1); 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](https://www.semver.xyz/spec#pre-release-channels) 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](https://www.semver.xyz/spec#build-channels). 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](https://www.semver.xyz/selector.md).

### 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](https://www.semver.xyz/spec#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](https://www.semver.xyz/spec#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](https://www.semver.xyz/extensions/variants.md) for os/arch/abi channels and [Package Integrity](https://www.semver.xyz/extensions/integrity.md) for a channel built on content digests.

---

This specification is licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). The BNF grammars are at [semver.xyz/grammar](https://www.semver.xyz/grammar.md), implementations at [semver.xyz/libraries](https://www.semver.xyz/libraries.md), and answers to common questions, including interoperability with Python's PEP 440, in the [FAQ](https://www.semver.xyz/faq.md).
