Nix Flake Checker

Nix Flake Checker is a tool from Determinate Systems that performs "health" checks on the flake.lock files in your flake-powered Nix projects. Its goal is to help your Nix projects stay on recent and supported versions of Nixpkgs.

To run the checker in the root of a Nix project:

nix run github:DeterminateSystems/flake-checker

# Or point to an explicit path for flake.lock
nix run github:DeterminateSystems/flake-checker /path/to/flake.lock

Nix Flake Checker looks at your flake.lock's root-level Nixpkgs inputs. There are two ways to express flake policies:

• Via config parameters.
• Via policy conditions using Common Expression Language (CEL).

If you're running it locally, Nix Flake Checker reports any issues via text output in your terminal. But you can also use Nix Flake Checker in CI.

Supported branches

At any given time, Nixpkgs has a bounded set of branches that are considered supported. The current list:

• nixos-23.11
• nixos-23.11-small
• nixos-24.05
• nixos-24.05-small
• nixos-unstable
• nixos-unstable-small
• nixpkgs-23.11-darwin
• nixpkgs-24.05-darwin
• nixpkgs-unstable

Parameters

By default, Flake Checker verifies that:

• Any explicit Nixpkgs Git refs are in the supported list.
• Any Nixpkgs dependencies are less than 30 days old.
• Any Nixpkgs dependencies have the NixOS org as the GitHub owner (and thus that the dependency isn't a fork or non-upstream variant).

You can adjust this behavior via configuration (all are enabled by default but you can disable them):

Policy conditions

You can apply a CEL condition to your flake using the --condition flag. Here's an example:

flake-checker --condition "has(numDaysOld) && numDaysOld < 365"

This would check that each Nixpkgs input in your flake.lock is less than 365 days old. These variables are available in each condition:

We recommend a condition at least this stringent:

supportedRefs.contains(gitRef) && (has(numDaysOld) && numDaysOld < 30) && owner == 'NixOS'

Note that not all Nixpkgs inputs have a numDaysOld field, so make sure to ensure that that field exists when checking for the number of days.

Here are some other example conditions:

# Updated in the last two weeks
supportedRefs.contains(gitRef) && (has(numDaysOld) && numDaysOld < 14) && owner == 'NixOS'

# Check for most recent stable Nixpkgs
gitRef.contains("24.05")

The Nix Flake Checker Action

You can automate Nix Flake Checker by adding Determinate Systems' Nix Flake Checker Action to your GitHub Actions workflows:

checks:
  steps:
    - uses: actions/checkout@v4
    - name: Check Nix flake Nixpkgs inputs
      uses: DeterminateSystems/flake-checker-action@main

When run in GitHub Actions, Nix Flake Checker always exits with a status code of 0 by default—and thus never fails your workflows—and reports its findings as a Markdown summary.

Telemetry

The goal of Nix Flake Checker is to help teams stay on recent and supported versions of Nixpkgs. The flake checker collects a little bit of telemetry information to help us make that true.

Here is a table of the telemetry data we collect:

To disable diagnostic reporting, set the diagnostics URL to an empty string by passing --no-telemetry or setting FLAKE_CHECKER_NO_TELEMETRY=true.

You can read the full privacy policy for Determinate Systems, the creators of this tool and the Determinate Nix Installer, here.

Rust library

The Nix Flake Checker is written in Rust. This repo exposes a parse-flake-lock crate that you can use to parse flake.lock files in your own Rust projects. To add that dependency:

[dependencies]
parse-flake-lock = { git = "https://github.com/DeterminateSystems/flake-checker", branch = "main" }

Here's an example usage:

use std::path::Path;

use parse_flake_lock::{FlakeLock, FlakeLockParseError};

fn main() -> Result<(), FlakeLockParseError> {
    let flake_lock = FlakeLock::new(Path::new("flake.lock"))?;
    println!("flake.lock info:");
    println!("version: {version}", version=flake_lock.version);
    println!("root node: {root:?}", root=flake_lock.root);
    println!("all nodes: {nodes:?}", nodes=flake_lock.nodes);

    Ok(())
}

The parse-flake-lock crate doesn't yet exhaustively parse all input node types, instead using a "fallthrough" mechanism that parses input types that don't yet have explicit struct definitions to a serde_json::value::Value. If you'd like to help make the parser more exhaustive, pull requests are quite welcome.