Persistence of stateful data during NixOS garbage collection

Question

NixOS maintains system immutability by storing configurations in the /nix/store. While system generations are atomic and easily reversible, stateful data—such as database directories, log files, or persistent user configurations—typically reside outside the immutable store to survive transitions.
A challenge arises when using nix-collect-garbage to prune old generations. Because the garbage collector only tracks paths referenced by the store, there is no native, declarative mechanism to ensure that external stateful directories are logically linked to a specific system generation or to prevent cleanup of those directories if they are not explicitly managed by the collector's logic.
What are the recommended declarative methods to ensure that external stateful paths are protected from accidental deletion without manually hardcoding paths? Is there a specific NixOS module option to link external directory lifecycles to the active system generation's lifecycle?

Siddharth · Answer

Answer
NixOS garbage collection only removes paths under /nix/store that are not reachable from a GC root; it never touches directories outside the store such as /etc, /var, /home, or /run. Therefore, stateful data kept in the usual FHS locations is already protected without any extra configuration.
When data lives inside the store
If you deliberately place mutable data inside /nix/store (e.g., via a bind‑mount or a symlink), the collector will treat it like any other store path and may delete it unless a GC root references it.
Declarative ways to add a GC root

Use systemd.tmpfiles to create a persistent symlink in /nix/var/nix/gcroots/auto/ that points to the store path you want to keep.
Example snippet for configuration.nix:

systemd.tmpfiles.rules = [
  "L+ /nix/var/nix/gcroots/auto/my-data - - - - /nix/store/abc123-my-data"
];

The L+ line creates a link that is added at boot and removed only when the rule is deleted, thereby tying the lifetime of the store path to the active system generation.
Verification

List current GC roots: find /nix/var/nix/gcroots -type l -ls
Preview what would be collected: nix-store --gc --print-dead
Ensure your stateful directory is not symlinked into the store: ls -l /nix/store | grep '' should return nothing.

If you discover that your data is symlinked into /nix/store, the tmpfiles rule above is the recommended declarative fix; otherwise no extra steps are needed.

Persistence of stateful data during NixOS garbage collection

1 answer

Answer

When data lives inside the store

Declarative ways to add a GC root

Verification

Your perspective belongs here.

1 question comment

A clarification worth adding

Practical checks