---
title: "Build Variants: platform and arch subsets in a version · semver.xyz"
description: "Build Variants is a Semantic Versions extension that encodes os/arch/abi/feature coordinates as build metadata, e.g. npm:esbuild@0.21.0+darwin.arm64, so ranges can select a coherent subset of platform builds."
url: "https://semver.xyz/extensions/variants/"
lang: "en"
---

Extension · Build Variants

# One version, every target.

_Build Variants_ encodes deployment-target coordinates (os, arch, abi and features) as build metadata, so a single release addresses a whole family of artifacts. Because Semantic Versions restores build precedence, each variant is a real, orderable version, and a [build channel](https://www.semver.xyz/spec.md#build-channels) can select a coherent **subset** that no numeric range can express.

variant specifier

```
napi:sharp@0.33.0+linux.x64.musl
```

`napi:sharp@0.33.0` is the release. `+linux.x64.musl` is the target, an os·arch·abi coordinate, ordered coarse→fine so ranges can drill down.

[Select a subset](https://www.semver.xyz/extensions/variants#matrix) [Read the format](https://www.semver.xyz/extensions/variants#coordinates)

Why build metadata

## A target isn't a pre-release, or a new package.

A platform build is a _finished sibling_ of a release, not a step toward it, so it [ranks above](https://www.semver.xyz/spec.md#precedence) the plain release, never below it like a pre-release. And it needn't fork the identity: instead of scattering software across `pkg-linux-x64`, `pkg-darwin-arm64`, … wired together with `optionalDependencies` and `os`/`cpu`/`libc` filters, Build Variants keeps **one name, one version**, and moves target selection back into the range grammar.

Live

## Range over a variant subset.

Every cell is a concrete artifact: a release built for one target. Type a **build channel** and watch the selected subset light up. Shorter channels are broader subsets; the plain release column has no build, so a channel excludes it. This runs entirely in your browser on the reference `semantic-versions` parser.

Build channel

Contents

[Coordinates](https://www.semver.xyz/extensions/variants#f-coords) [Selection](https://www.semver.xyz/extensions/variants#f-select) [Target matching](https://www.semver.xyz/extensions/variants#f-target) [Other schemes](https://www.semver.xyz/extensions/variants#f-relationship) [Composability](https://www.semver.xyz/extensions/variants#f-compose) [Grammar](https://www.semver.xyz/extensions/variants#f-grammar)

## Coordinates

A Build Variant is build metadata whose identifiers name target axes, ordered coarse→fine:

`<version>+<os>[.<arch>[.<abi>[.<floor>]]][.<qualifier>]* <version>+wasm32[.<qualifier>]*`

- The **fixed axes** appear in order (**os**, then **arch**, then **abi**) and each **MAY** be omitted only if every later fixed axis is too. A variant is therefore always a _prefix_ of the axis sequence: `linux`, `linux.x64`, `linux.x64.musl` are valid; `x64` alone (arch without os) is not. An omitted axis is no constraint: `linux.x64` with no abi runs on glibc and musl alike.
- An abi of `glibc` or `musl` **MAY** carry a **version floor**, the lowest version of that C library the build runs on: `linux.x64.glibc.2.28` runs on glibc 2.28 or later (the `manylinux` rule).
- **Qualifiers** follow the fixed axes, in any order: **floors** (`osv.11.0` for the OS version on `darwin` and `win32`, `napi.8` for the N-API version an addon needs), **exact tags** (`node.127`, `electron.123`: the `NODE_MODULE_VERSION` an addon was built against; a variant carries `napi` or one of these, not both), and **feature tags** (`avx2`, `cuda`, `neon`), which **SHOULD** be sorted for a canonical form.
- `wasm32` stands alone as the whole platform: a WebAssembly build is not tied to an operating system.
- Each value is its own dot-separated build identifier, so a variant slots straight into the existing [`<build>`](https://www.semver.xyz/spec/VERSION.bnf) grammar, and floors are numeric identifiers that compare numerically under the core precedence rules with nothing added.

Registered vocabularies (extensible; aligned with runtime values like Node's `process.platform` / `process.arch`, and with the platform fields of pnpm and npm's `variants` proposal):

| Axis or key | Values                                                                               |
| ----------- | ------------------------------------------------------------------------------------ |
| `os`        | `linux` · `darwin` · `win32` · `freebsd` · `openbsd` · `android` · `sunos` · `aix`   |
| `arch`      | `x64` · `arm64` · `arm` (ARMv7) · `ia32` · `ppc64` · `s390x` · `riscv64` · `loong64` |
| `abi`       | `glibc[.M.m]` · `musl[.M.m]` · `msvc`                                                |
| platform    | `wasm32`, in place of the fixed axes                                                 |
| floors      | `osv.M[.m]` · `napi.N`                                                               |
| exact tags  | `node.N` · `electron.N`                                                              |
| features    | any other lowercase identifier                                                       |

Consumers **MUST** ignore axis, key or feature identifiers they don't recognise and **MUST NOT** treat that as a match failure on its own; an unknown coordinate simply doesn't narrow selection.

## Selection

Selection is just the core [Build Channels](https://www.semver.xyz/spec.md#build-channels) rule applied to coordinates: a `+`-channel is orthogonal to the numeric comparison and admits only versions whose build coordinates _begin with_ the channel's. Because coordinates are ordered coarse→fine, a shorter channel is a broader subset.

- `^1.0.0+linux`: every linux variant in the 1.x line.
- `^1.0.0+linux.x64`: narrows to linux/x64, both glibc and musl.
- `^1.0.0+linux.x64.musl`: just the musl build.
- `>=1.1.0+darwin.arm64`: the Apple-silicon build at or above 1.1.0.
- `1.2.0+win32.x64`: one exact artifact.
- `^1.0.0`: no channel, so every variant _and_ the plain release.

A channel narrows a range to the variants a _specifier_ asks for. Members of a subset still order by precedence, so “the latest linux/x64 build of 1.x” is well-defined: the highest release, and within it the highest build. Precedence among siblings of one release is lexical, though, and says nothing about which sibling suits a machine. That is the job of target matching, below.

> Prefix matching means a coarse channel also admits deeper refinements: `+linux.x64` matches `linux.x64.musl`. To distinguish siblings that share a prefix, make the distinguishing axis explicit: model libc as `linux.x64.glibc` vs `linux.x64.musl` rather than leaving glibc implicit.

## Target matching

A **target** is what a client installs for: by default the host, described in the same vocabulary as a coordinate (`process.platform`, `process.arch`, the C library and its version, the OS version, the N-API version and `NODE_MODULE_VERSION`, and whatever features the client can detect). A target can also be configured, for a container image or a cross-compile; any value it does not state is **unknown**.

A variant **applies to** a target when every coordinate it states is satisfied:

1. Each fixed axis it states equals the target's. An omitted axis is no constraint. `wasm32` applies to every target.
2. Each floor it states (a C-library version, `osv`, `napi`) is at or below the target's value for that key, compared numerically. A floor on a key the target leaves unknown is **not** satisfied: linking a build the host may not run is worse than falling through to a broader variant.
3. Each exact tag it states (`node`, `electron`) equals the target's.
4. Each feature tag the client recognises is one the target has; a feature tag the client does not recognise is ignored.

The build-less release applies to every target, as the fallback.

To **resolve** a range for a target, a client takes the highest release in the range that has at least one applicable member, then the most **specific** applicable member of that release:

1. a variant that states more fixed axes before one that states fewer;
2. then a higher floor before a lower one, and any floor before none;
3. then an exact `node`/`electron` tag before a `napi` floor before neither;
4. then a variant that states more matched feature tags;
5. then a native variant (one with an `os`) before `wasm32`, and `wasm32` before the build-less release.

So for a glibc 2.31 host with N-API 9, `1.4.0+linux.x64.glibc.2.28.napi.8` wins over `1.4.0+linux.x64.glibc.2.17.napi.8`, which wins over `1.4.0+linux.x64`, which wins over `1.4.0+wasm32` and `1.4.0`. Specificity is computed from the coordinates, so a publisher never has to order anything by hand, and two clients given the same target select the same artifact.

## Relationship to other schemes

- **npm `os`/`cpu`/`libc` + optional-dependency fanout.** The same target matrix, expressed in one version instead of across many packages, and now rangeable. A resolver can still map a selected variant onto whatever artifact layout a registry uses.

- **pnpm's platform variants.** pnpm describes a platform build with `os`, `cpu`, `libc`, `libcVersion`, `osVersion`, `napi` and `nodeAbi`, ranks the archives of one version by how specific their platform is, and writes the result into its lockfile. That is the same vocabulary as the coordinates above, and the specificity order in [target matching](https://www.semver.xyz/extensions/variants#f-target) is pnpm's rank computed from the coordinate. Build Variants differs in putting the coordinate in the version, where it survives outside a lockfile.

- **npm's `variants` field ([npm/rfcs#928](https://github.com/npm/rfcs/pull/928)).** The RFC lists, on a package, the separate packages that replace it per target, using pnpm's fields; it is the projection of this extension onto registries that hold one artifact per version, and the RFC itself names _several archives per version_ as its future shape. An entry maps onto a coordinate and back:

  | `variants` entry                                          | Coordinate                                                                                                              |
  | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
  | `os`, `cpu`, `libc` (one value each)                      | the fixed axes, in order                                                                                                |
  | `libcVersion: "2.28"`                                     | `glibc.2.28` on the abi axis (the RFC's floor implies glibc)                                                            |
  | `osVersion: "11.0"`                                       | `osv.11.0`                                                                                                              |
  | `napi: 8`                                                 | `napi.8`                                                                                                                |
  | `nodeAbi: "node-127"` / `"electron-123"`                  | `node.127` / `electron.123`                                                                                             |
  | an omitted `libc`                                         | an omitted abi                                                                                                          |
  | a cross product (`os: ["darwin"], cpu: ["arm64", "x64"]`) | one coordinate per cell, or the common prefix (`darwin`) when one artifact serves them all                              |
  | a `!value` exclusion                                      | no counterpart: a coordinate says what an artifact _is_, so an exclusion becomes an omitted axis or several coordinates |
  | `engines.node`                                            | no counterpart: a requirement on the consumer, which stays a manifest field                                             |
  | the unconditional fallback entry                          | `wasm32`, or the build-less release                                                                                     |

  The RFC's author order (“narrower first, higher floors first, `nodeAbi` before `napi`, native before the fallback”) is the specificity order here, so a tool can generate a correctly ordered `variants` list from a set of coordinates.

- **OCI / Docker multi-arch manifests.** A manifest list selects by `os`/`architecture`/`variant`; Build Variants lifts that tuple into the version grammar, so the same selection works in a specifier or lockfile, not only at pull time.

- **[Package-URL](https://github.com/package-url/purl-spec) qualifiers.** PURL carries target facts in `?arch=…&os=…` qualifiers, outside the version and outside precedence. Build Variants keeps them _in_ the version, where they order and where ranges select them, while staying round-trippable to PURL qualifiers for interchange.

## Composability

Variant coordinates are ordinary build identifiers, so they compose with other build-metadata extensions. Build Variants is the _first_ of the three extensions for a reason: it answers _which artifact_, and the other two build on that answer. A variant precedes an integrity digest — `1.0.0+linux.x64.musl.sha512.…` pins the exact bytes of one target — and a [Dependency Lock](https://www.semver.xyz/extensions/dependency-locks.md) pins a whole graph whose every node is an identity of exactly that shape. See [Package Integrity](https://www.semver.xyz/extensions/integrity.md) for the digest half.

## Grammar (BNF)

Building on [VERSION.bnf](https://www.semver.xyz/spec/VERSION.bnf)'s `<build>`:

[Download VARIANTS.bnf](https://www.semver.xyz/spec/VARIANTS.bnf)

```
Copy<variant build> ::= <platform> ( "." <qualifier> )*
<platform>      ::= <os> ( "." <arch> ( "." <abi> )? )?
                  | "wasm32"
<os>            ::= "linux" | "darwin" | "win32" | "freebsd" | "openbsd"
                  | "android" | "sunos" | "aix"
<arch>          ::= "x64" | "arm64" | "arm" | "ia32" | "ppc64" | "s390x"
                  | "riscv64" | "loong64"
<abi>           ::= "glibc" <floor version>? | "musl" <floor version>? | "msvc"
<qualifier>     ::= <floor> | <exact tag> | <feature>
<floor>         ::= ( "osv" | "napi" ) <floor version>
<floor version> ::= "." <numeric identifier> ( "." <numeric identifier> )?
<exact tag>     ::= ( "node" | "electron" ) "." <numeric identifier>
<feature>       ::= <build identifier>
```
