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=1POST /api/deletewith{"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;
}