Skip to main content

Walkthrough (default)

Running linux-cleanup with no flags starts the guided walkthrough: ten steps through every cleanup category, each asking before it does anything. It is the recommended way to use the tool interactively.

linux-cleanup # or: linux-cleanup -w / --walkthrough

The ten steps​

#StepDeletesNotes
1Package-manager cachesRegenerableyarn, npm, npx, pnpm, pip, composer, bun, deno
2Application cachesRegenerableBrowsers, Gradle, Cypress, Playwright, Zoom, editor VSIX
3Developer-tool dataStale onlyAndroid AVDs, pub-cache, Dart analysis, flatpak
4Editor old extensionsStale + supersededVS Code / Cursor
5Stale node_modulesInteractiveProjects idle past the threshold
6Partial / orphan downloadsInteractive.crdownload, .part, .fdmdownload
7Personal stale filesInteractiveLarge idle files in ~/Downloads, ~/Desktop
8System cleanup (sudo)Systemapt, journal, snap, /tmp, page cache
9Final size auditNothingRead-only summary
10Generate readable reportNothingMarkdown / HTML export — needs jq

Steps 5, 6 and 7 are the interactive-only ones. They cannot be auto-confirmed, and step 7 is the only step in the whole tool that can remove something genuinely irreplaceable.

How the prompts work​

Two levels of confirmation.

Per step, you choose what to do with the whole category:

KeyEffect
aRun this step. This is the default — Enter selects it
sSkip this step entirely
qQuit the walkthrough now, keeping progress so far

Per target, inside a step that you chose to run, each individual item gets a [Y/n] or [y/N] confirmation. The capitalised letter is the default.

So a at the step level does not commit you to deleting everything in it — you still see and answer each target.

Running totals​

After each step that ran, the tool prints its measured change and the session total so far.

The final summary reports disk free before and after. That figure is measured from df, so it reflects everything happening on the machine — if a build ran during your session, the reported recovery can be lower than the sum of the steps, or even negative. That is not a bug; see Troubleshooting.

Quitting early​

q at any step prompt, or Ctrl-C at any point, ends the session cleanly:

  • Earlier deletions remain permanent; inspect the log for the steps attempted before interruption
  • Ctrl-C exits with code 130, which the crash trap deliberately ignores, so no crash bundle is written
  • Steps not reached are recorded as skipped in the report

The session report​

The walkthrough writes a JSON report to ~/.linux-cleanup/reports/report-<timestamp>.json unless --no-report or --dry-run is set. It contains per-step status and bytes freed, disk and memory before/after, and session totals. Full field list: Report schema.

Step 10 optionally converts it to Markdown and HTML. That step needs jq; without it the step is recorded as skipped (jq missing) and the JSON is still written.

linux-cleanup --no-report # skip JSON generation; logs still written

Options worth combining​

linux-cleanup -d 30 # 30-day staleness threshold instead of 100
linux-cleanup --purge-all # disable the staleness gate entirely
linux-cleanup --no-color # plain output
linux-cleanup --cleanup-logs # delete this run's log at the end
--purge-all changes what step 1–4 delete

With the staleness gate off, cache steps wipe their targets in full rather than pruning idle files. That includes Gradle wrapper distributions, Playwright browsers and Cypress binaries you may still want. The pre-run banner states which strategy is active.

When to use something else​

SituationBetter mode
You only want one categoryMenu or TUI
Unattended or cronAll-safe with -y
You want to look, not deleteScan
You want the visual version of thisTUI

Next​

  • Scan — run this first
  • All-safe — the unattended equivalent
  • Reports — reading the output