Garbage Collection and Store Roots

Garbage Collection and Store Roots in the context of Nix Package Management refer to the mechanisms and concepts that manage the lifecycle of packages and their data stored in the Nix store. These mechanisms ensure that unused or obsolete packages are safely removed, preventing unnecessary disk space consumption while preserving data still referenced and necessary for existing profiles or environments.

Garbage Collection in Nix

Garbage collection (GC) in Nix is the automated or manual process of removing unused paths from the Nix store. The Nix store is a content-addressed repository where package builds, dependencies, and other derivations reside. Over time, as packages are updated or removed from user profiles, some store paths become unreferenced or "garbage." Garbage collection identifies these unreferenced paths and deletes them, freeing disk space.

Garbage collection is safe because Nix uses immutable store paths identified by cryptographic hashes. This ensures that no other package or user environment can inadvertently rely on a removed path without explicitly referencing it.

How Garbage Collection Works

Nix maintains a graph of dependencies and references between store paths. During garbage collection, Nix:

1. Identifies "roots," which are store paths explicitly referenced by profiles, system generations, or explicitly marked roots.
2. Traverses the dependency graph from these roots to mark all reachable paths.
3. Any path not reachable from the roots is considered garbage and can be safely deleted.

The garbage collector thus preserves all store paths required by current environments and removes only those that no longer have any references.

Executing Garbage Collection

Garbage collection can be performed manually or automatically:

• Manual GC is done with the command:

nix-collect-garbage

Additional flags can control the behavior:

• -d or --delete-older-than <time> deletes store paths not referenced by roots newer than the specified time.

• --print-roots shows the current roots and their references.

• --delete-older-than can be useful for cleaning up old unused generations.

• Automatic GC can be configured via system services or cron jobs to run periodically, maintaining store hygiene without manual intervention.

Store Roots in Nix

Store roots are the explicit or implicit references that prevent garbage collection from deleting certain store paths. They act as anchors in the dependency graph and represent the entry points from which all necessary store paths are reachable.

Types of Store Roots

1. User Profiles
   User profiles are directories that contain symlinks to store paths of installed packages and their dependencies. Each generation of a user profile creates a new set of references to store paths, effectively acting as a root during garbage collection.

2. System Generations
   For NixOS or system-wide installations, the system configuration generations stored in /nix/var/nix/profiles/system serve as roots. Each system generation points to the set of store paths required for a particular system state.

3. Explicit Roots
   Store paths can be explicitly registered as roots using the nix-store --add-root command. This creates a persistent reference to a path, protecting it from garbage collection until the root is removed.

4. Profiles and Channels
   Channels or other user-managed collections of packages also create roots by symlinking or referencing store paths.

Managing Store Roots

• To list current roots, use:

nix-store --gc --print-roots

• To add a root explicitly:

nix-store --add-root /path/to/root --indirect /nix/store/xyz...

• To remove an explicit root:

rm /path/to/root

Explicit roots must be managed carefully to avoid unintentionally keeping large or obsolete store paths.

Interaction Between Garbage Collection and Store Roots

The GC process relies entirely on store roots to determine which paths are live. Without roots, all store paths would be collectible, leading to the deletion of packages still needed. Conversely, overly conservative root management (e.g., many explicit roots) can lead to store growth and wasted disk space.

Nix’s design with multiple profile generations and explicit roots offers flexible control over package life cycles, allowing users and system administrators to balance retention for rollback or reproducibility against storage efficiency.

Summary of Key Concepts

Practical Considerations

• Regular garbage collection helps maintain a manageable Nix store size.
• Deleting old profile generations reduces store roots, enabling more aggressive cleanup.
• Explicit roots should be used sparingly to avoid unnecessary retention.
• Understanding roots is crucial when troubleshooting storage bloat or unexpected package removals.
• Garbage collection does not affect files outside the Nix store or profiles.

Common Commands Related to Garbage Collection and Store Roots

# Perform garbage collection of unreachable store paths
nix-collect-garbage

# Delete store paths not referenced by roots newer than 30 days
nix-collect-garbage --delete-older-than 30d

# Show current roots and their references
nix-store --gc --print-roots

# Add an explicit root to protect a store path
nix-store --add-root /path/to/root --indirect /nix/store/abc123

# Remove an explicit root by deleting its symlink
rm /path/to/root

By combining garbage collection with carefully managed store roots, Nix ensures a reliable, reproducible, and space-efficient package management environment.