nixos-facter and the report that describes the machine before the modules decide

The chicken-and-egg problem of configuring a machine you cannot describe yet

A NixOS configuration is a single expression that describes a machine completely, including the hardware. That is elegant until you have more than one machine, or until you are installing onto a box whose disk controller and network card you do not know yet, because the file you are about to write has to describe hardware you have not inspected.

nixos-facter is described as an alternative to projects such as NixOS Hardware and nixos-generate-config, and it solves the problem of bootstrapping NixOS configurations by deferring decisions about hardware and other aspects of the target platform to NixOS modules.

The mechanism is a two-step split. First, a report is generated, as JSON, capturing detailed information about the machine or virtual environment it was executed within. Second, that report is passed to a series of NixOS modules, which can make a variety of decisions, some simple and some more complex. The README names the outcomes those decisions enable: automatic configuration of network controllers or graphics cards, USB devices, and so on.

The audience is people building NixOS configurations across heterogeneous hardware, where writing the same file per machine is the bottleneck. It is not aimed at a single laptop.

What lives in this repository, and what lives in nixpkgs

The project structure is the first thing to understand, and it is short. This repository contains the binary for generating the report. The NixOS modules for making use of the report are included in nixpkgs, and the details are in the NixOS options documentation.

That split has real consequences. When you upgrade NixOS, the modules that read the report come from your nixpkgs channel, not from this repository. The report generator, on the other hand, is what you run on the target machine, and it is what this repository versions.

The source layout follows the Go convention. There is a go.mod at the root declaring the module as github.com/numtide/nixos-facter, with Go 1.26.4 and a single direct dependency, the testify test library, plus an indirect yaml dependency. The command line entry point is main.go with a cmd directory beside it, and pkg holds the packages. A flake.nix and flake.lock make the project buildable with Nix, mkdocs.yml with a docs directory handle the documentation, and there is a renovate.json for dependency updates.

Note the module path says numtide rather than nix-community. The project is hosted under the nix-community organisation but the Go module identifier and the maintainers listed in the description, brianmcgee and Mic92, tell a different story about who does the work.

Generating a report with nix run

The quick start runs the generator from nixpkgs, and the command has to run as root:

# you must run this as root
❯ sudo nix run --option experimental-features "nix-command flakes" nixpkgs#nixos-facter -- -o facter.json

The -o facter.json argument names the output file, and everything after the double dash goes to the generator rather than to nix run. The experimental-features option is needed because the nix-command and flakes interfaces are still behind a flag in some Nix versions.

To run the development version from the flake instead of the nixpkgs version, the command adds a binary cache. The extra-substituters and extra-trusted-public-keys options point at the Numtide binary cache so that dependencies do not have to be built locally:

# you must run this as root
❯ sudo nix run \
  --option experimental-features "nix-command flakes" \
  --option extra-substituters https://numtide.cachix.org \
  --option extra-trusted-public-keys numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE= \
  github:nix-community/nixos-facter -- -o facter.json

Trusting a public key is worth a moment of attention. The extra-trusted-public-keys option tells Nix to accept binaries from that cache, so the integrity of what you run depends on that key staying where it is. The project is supported by Clan and Numtide, and the Numtide binary cache is the same one referenced in the README's link definitions.

Why the report has to be JSON

The choice of a machine-readable report is what makes the whole arrangement work, and it is the same reason the modules live in nixpkgs rather than in this repository.

A JSON file is something a Nix module can read at evaluation time, which means a module can branch on the contents. A report that says the machine has a particular network controller or a particular graphics card can drive a conditional in the configuration, and that conditional is evaluated when the configuration is built rather than when someone edits it.

The report is generated on the machine it describes. The flow is: run the generator as root on the target, produce the JSON, and have the configuration consume it. That is why the command has to run as root, because inspecting hardware details is privileged work.

The open question this design leaves is where the report file lives and how it gets onto the machine. The README documents generation and points to the options documentation for how the modules consume it, but it does not walk through transporting a report from a freshly booted installer to the configuration source, nor does it describe how a report should be refreshed when you replace a disk controller. For a tool whose whole purpose is bootstrapping, that gap is where most of the practical work will land.

Where nixos-facter sits against the alternatives

The README names two alternatives directly, and they fail in different ways.

NixOS Hardware is the curated repository of hardware definitions, and the difference in approach is where the facts come from. A curated definition is written by someone who had the hardware, so it is accurate for that machine and absent for every machine nobody has contributed. nixos-facter instead derives the description from the machine itself, which means coverage is whatever the generator can detect rather than whatever has been contributed.

nixos-generate-config is the installer path, and the difference is timing. The generator tool produces a starting configuration from a machine, and the alternative described here defers those decisions to modules that can consult a report you provide.

The honest framing is that these are different points in the same workflow rather than rivals. A report says what the hardware is; a hardware definition says what that hardware should be configured as. The report is a way to get the first without a human writing the second by hand.

That also sets the boundary of the project. It does not configure anything by itself. The modules that consume the report are in nixpkgs, and if a module you need does not exist there, this project cannot fill the gap.

Maintenance, licence and the state of a young 0.x line

The repository is not archived and the last push was on 2026-10-20, so work is current. The tagged releases are v0.4.4 from 2026-05-12, v0.4.3 from 2025-12-30 and v0.4.2 from 2025-11-04. The version line is still 0.x, which in the usual convention means the interfaces are not promised to be stable, and the gap between the last release in May and commits in October means the repository is ahead of any tagged binary.

That matters for the deployment model. If you build the generator from a flake, as the development-version command shows, you are running unreleased code, and you should pin the flake to a specific commit if you want reproducibility.

The licence has a wrinkle. The README states that the software is provided free under GNU GPL v3, and the link definition points to a LICENSE file in the repository root. GitHub's own classification shows the licence as one it cannot categorise, which usually means the file contains wording that does not match a standard licence identifier exactly. Read the file rather than assuming.

The rest of the README is sponsorship information, describing Clan, a peer-to-peer management framework built on NixOS, and Numtide, a team of independent freelancers who support the project. Both are real dependencies of the project's continuity rather than of its code, and the cache key in the quick start command comes from Numtide's infrastructure.

Editorial conclusion

nixos-facter fits a team that provisions many NixOS machines of different shapes and currently hand-writes per-host hardware blocks, because the report moves that knowledge out of the configuration and into a file the modules can read. It does not fit a single-machine setup where one configuration file is enough, and it does not replace the hardware configuration modules in nixpkgs, because the modules are what actually read the report. Before adopting it, run the report generation command on one machine and read the JSON to confirm it captures the hardware you expected, decide how the report file travels to the target host, and check the licence file, since the project states GNU GPL v3 while GitHub lists the licence as one it cannot classify.

Frequently asked questions

Official sources

1. Issues
2. nix-community/nixos-facter on GitHub
3. Project website
4. README
5. Releases