FlakeHubConceptsSemantic versioning

Semantic versioning for Nix

FlakeHub enables you to use a subset of Semantic Versioning (SemVer) with your Nix flakes. The diagram below provides a quick refresher on the structure of versions in SemVer:

major.minor.patch

Backwardsincompatiblecompatible

  • Major versions represent backwards-incompatible API changes.
  • Minor versions represent additions of backwards-compatible functionality.
  • Patch versions represent backwards-compatible bug fixes.

Here’s an example SemVer-compatible version:

21.3.12

A breaking API change would entail a bump to major version 22 while a bug fix would entail a patch version bump to 13.

For things like pre-releases you can add extra information to the patch.

21.3.12-pre

Supported operators

FlakeHub’s subset of SemVer supports the = operator.

Exact version (=)

The = operator signals that you want to resolve to an exact version. Here’s an example:

Resolve to an exact version with =
nix flake show "https://flakehub.com/f/DeterminateSystems/fh/=0.1.15"

Here, =0.1.15 could only resolve to 0.1.15 and this operation would fail if that version didn’t exist.

Wildcard operator (*)

The wildcard (*) operator allows for any version in that position.

  • The version range * always uses the highest published version.
  • 1.* allows any version with the major version of 1.
  • 1.2.* allows any version with the major and minor version 1.2.
Resolve to an open-ended version with *
nix flake show "https://flakehub.com/f/DeterminateSystems/flake-checker/*"

Here, * would resolve to the most recent version of the flake-checker flake.

Tagged vs. rolling flake releases

FlakeHub supports two methods of versioning your flake releases, both of which are consistent with SemVer: tagged and rolling.

Consult the Publishing guide to see how to set the release type.

Tagged

Tagged releases are better suited for projects that follow SemVer and have a defined release cadence. The versioning scheme of tagged flakes is up to the author, as long as it conforms to SemVer. An example of this kind of flake is the fh flake.

Here’s a visual representation:

https://flakehub.com/f/:org/:project/:tag

The 0.1.26 tag for fh corresponds to this landing page…

https://flakehub.com/flake/DeterminateSystems/fh/0.1.26

…and looks like this as a flake input:

flake.nix
{
  inputs.fh.url = "https://flakehub.com/f/DeterminateSystems/fh/=0.1.26";
}

Rolling

Rolling versions are ideal for projects that see a constant stream of commits and releases. The versioning scheme of rolling flakes has:

  • A SemVer major version of 0
  • A SemVer minor version of 1 (for the NixOS unstable rolling release train)
  • A SemVer patch version of the number of commits that were on that branch at that time

Here’s a visual representation:

https://flakehub.com/f/:org/:project/0.1.${number of commits}

As an example, the 0.1.6953 release for the helix flake corresponds to this landing page…

https://flakehub.com/flake/helix-editor/helix/0.1.6953+rev-d79cce4e4bfc24dd204f1b294c899ed73f7e9453

…and looks like this as a flake input:

flake.nix
{
  inputs.helix.url = "https://flakehub.com/f/helix-editor/helix/=0.1.6953";
}

Nixpkgs versions

Nixpkgs follows the versioning scheme in the table below.

Version constraintMeaning
0The most recently published stable Nixpkgs
*The most recently published stable Nixpkgs (equivalent to the above)
0.{YYMM}The most recently published bi-yearly release from the nixos-{YY}.{MM} branch (such as 25.05, 24.11, etc.)
0.1The most recently published unstable Nixpkgs
0.1.{commit}The latest commit that is at least the Nth commit within the unstable epoch (such as 0.1.494976 for the 494976th commit). The same as the above, assuming the most recent version surpassed the 494976th commit

Determinate Systems publishes the DeterminateSystems/nixpkgs-weekly flake, which mirrors the latest nixos-unstable Nixpkgs and only updates once every week. Using this version of Nixpkgs can be useful in scenarios, such as when using the flake registry on the command line, when you want Nixpkgs to be up to date but not updated many times a day.

Some Nixpkgs examples inside of flakes:

flake.nix
{
  inputs = {
    # Most recently published stable
    url = "https://flakehub.com/f/NixOS/nixpkgs/0";
 
    # Most recently published stable (same as above)
    url = "https://flakehub.com/f/NixOS/nixpkgs/*";
 
    # Most recently published unstable
    url = "https://flakehub.com/f/NixOS/nixpkgs/0.1";
 
    # Most recent release from the `nixos-25.05` branch
    url = "https://flakehub.com/f/NixOS/nixpkgs/0.2505";
 
    # The latest commit that is at least the 494976th commit to Nixpkgs
    url = "https://flakehub.com/f/NixOS/nixpkgs/0.1.494976";
 
    # Exactly the 494976th commit to Nixpkgs
    url = "https://flakehub.com/f/NixOS/nixpkgs/=0.1.494976";
  };
}

You can list releases for different version constraints using fh with the fh list versions command. Here are some examples:

# The 5 most recent stable releases
fh list versions --json NixOS/nixpkgs "0" | jq -r ".[-5:] | .[].version"
 
# The 5 most recent unstable releases
fh list versions --json NixOS/nixpkgs "0.1" | jq -r ".[-5:] | .[].version"
 
# The 5 most recent releases of the `nixos-24.11` branch
fh list versions --json NixOS/nixpkgs "0.2411" | jq -r ".[-5:] | .[].version"
MirroringAuthentication