State Version

Every NixOS host and every Home Manager user records a state version — the release it was first initialised under. It is not the version you run; it pins the release whose stateful defaults (data directories, database layouts, service formats) the system keeps honouring across upgrades, so an upgrade never migrates that state under you unexpectedly.

Because it should be the same everywhere and rarely changes, the baseline sets both sides once, through its base concept, so a consuming configuration never has to:

• system.stateVersion (NixOS) in system/state-version.nix
• home.stateVersion (Home Manager) in user/state-version.nix

Both use lib.mkDefault, so a host can still override them.

Caution

Keep it at the release a host was first installed with — don’t raise it just because a newer release exists. Bumping it opts into that release’s new stateful defaults and can require manual data migration. You can override both on a host to the release it was installed with:

system.stateVersion = "26.05";
home.stateVersion = "26.05";