Files
2026-10-28 08:00:16 +05:30

5.5 KiB

i-am-gcroot

List, filter and delete Nix garbage collector roots from a TUI, an optional web UI, or the command line.

nix run github:illustris/i-am-gcroot          # TUI
nix run . -- --web                            # TUI + web UI on 127.0.0.1:8377
nix run . -- list -q 'under:/tmp older:7d' --sizes

What it finds

Kind What it is Delete does
indirect a link outside the gcroots tree (./result, .gcroots/foo) registered via /nix/var/nix/gcroots/auto removes the link (and the auto/ entry if writable; nix-store --gc prunes it otherwise)
dangling an auto/ entry whose link is already gone removes the auto/ entry (needs root)
profile a profile generation, <profile>-<N>-link, system or user nix-env --profile <p> --delete-generations N
direct any other symlink in /nix/var/nix/gcroots removes the link
runtime store paths held by running processes (/proc/...), grouped per PID never deletable; hidden unless asked for

Protected roots (marked !) are refused unless --force is given: the current generation of every profile, and gcroots/current-system / gcroots/booted-system.

Only symlinks are ever removed. Nothing in /nix/store is touched until you run GC: either a full nix-store --gc (g in the TUI, the "run gc" button, i-am-gcroot gc) or a targeted collect right after deleting (X in the TUI, "delete + collect", rm -c).

Targeted collect takes the closures of the roots just deleted, subtracts everything still reachable from any GC root (including runtime roots), and runs nix-store --delete on the rest. Nix re-checks liveness itself, so a path that turns out to be alive (for example through keep-derivations) is kept and reported. It takes tens of seconds rather than a walk of the whole store.

Roots that nix creates for its own caches (anything under .cache/nix/, like ~/.cache/nix/flake-registry.json) are hidden by default. Show them with h in the TUI, the "hidden" checkbox, --all, or the is:hidden query term.

Closure sizes come from nix path-info -S and load in the background. The "up to" figure for a selection is the sum of closures; shared paths may stay alive through other roots, so the real amount freed is usually less.

Filter syntax

Terms are whitespace separated and ANDed. Prefix any term with - to negate it.

Term Matches
foo case-insensitive substring of link, target, via or command
/re/ regex over the same fields (no spaces, use \s; terms with more than two / are substrings)
kind:indirect,dangling kinds (prefixes like kind:prof work)
owner:me, owner:alice, owner:1000 owner of the link
under:/tmp/claude- link starts with this prefix
older:30d, newer:2h link mtime (s m h d w y)
size>1G, size<10M closure size (K M G T)
is:protected, is:current, is:dangling, is:hidden flags (is:hidden also makes hidden roots visible)

TUI keys

Key Action
j/k, arrows, pgup/pgdn, home/end move
space / x mark / unmark
a / A mark all shown (non-protected) / clear marks
d delete marked roots (or the one under the cursor), with confirmation
X delete, then garbage collect only the store paths those roots kept alive
D dry run
g run nix-store --gc
/ edit filter (enter/esc to leave, esc again clears it)
1-5, 0 toggle kinds, reset kinds
h show/hide nix cache roots
s / S cycle sort key (age, size, target, kind, link) / reverse
enter details
R full results of the last delete or dry run
r rescan
? help

Below the key hints, an activity line shows the running operation with a timer, then a one-line outcome (failures included); R shows the per-root details. The list is rescanned from disk after every delete.

CLI

i-am-gcroot [tui] [-q QUERY] [--web] [--addr ADDR] [--no-auth] [--runtime] [--force]
i-am-gcroot list  [-q QUERY] [--kind K,..] [--sort KEY] [--desc] [--sizes] [--json] [--runtime] [--all]
i-am-gcroot rm    [-n] [-y] [-c] [--force] [--all] (-q QUERY | LINK...)
i-am-gcroot gc
i-am-gcroot web   [--addr ADDR] [--no-auth] [--force] [--runtime]

rm asks for confirmation unless -y; -n is a dry run; -c runs the targeted collect afterwards; --all lets -q match hidden roots (explicit link arguments always work).

Web UI

i-am-gcroot web (headless) or --web alongside the TUI. It binds to 127.0.0.1:8377 and generates a random token at startup; open the printed URL (?token=...), which sets a cookie. POST requests additionally require the token in an X-Token or Authorization: Bearer header (the page sends it), so a cross-site form cannot trigger deletes. --no-auth disables this; only use it on a trusted socket.

JSON API (with Authorization: Bearer <token>):

  • GET /api/roots?q=...&kind=indirect&kind=profile&sort=size&desc=1&hidden=1
  • POST /api/delete with {"links": ["/home/me/result"], "dryRun": false, "collect": true}, returns {"results": [...], "collected": {...}}
  • POST /api/gc

Permissions

Run as your user to manage your own roots. Root-owned roots (system profile generations, auto/ entries of dangling roots, other users' links) fail with a hint to rerun under sudo. Runtime roots of other users' processes show as {censored} unless run as root.

NixOS

{
	inputs.i-am-gcroot.url = "github:illustris/i-am-gcroot";
	# ...
	imports = [ inputs.i-am-gcroot.nixosModules.default ];
	programs.i-am-gcroot.enable = true;
}