linux-cleanup
linux-cleanup shows the paths before it removes regenerable caches on Linux. It covers package-manager, browser and build-tool caches, with separate modes for system work and personal-file candidates. Start with a read-only scan or a dry run before choosing a real cleanup.
Get linux-cleanup: on npm · the website · all places
It is a destructive tool. Every deletion is permanent, and there is no undo. Its safety comes from refusing to touch the wrong things in the first place, not from being able to put them back.
There is no undo, Trash or backup step. A real cleanup permanently removes the selected files. Use
--dry-run to preview the chosen mode before you confirm it.
Read What it deletes and run the read-only preview before you let it remove anything.
| Package version | 2.1.0 in the current source; check linux-cleanup --version for the installed copy |
| Platform | Linux only — bash ≥ 4 and GNU coreutils |
| License | MIT — since 1.4.0 |
| Network access | One public release-record request on start when online; installing or updating also uses npm or GitHub |
| Author | Ahsan Mahmood · aoneahsan@gmail.com |
Read this in order
This documentation is deliberately sequenced for a tool that erases data. The first three pages are the ones that keep you out of trouble.
| Step | Page | Why |
|---|---|---|
| 1 | What it deletes | The complete target list, by category |
| 2 | Preview before deleting | Read-only scan, then a dry run of the selected mode |
| 3 | Safety guards | The four gates a path must clear before deletion |
| 4 | Deletion is permanent | What "no undo" means in practice |
| 5 | Installation | npx, global npm, or git clone |
| 6 | Quick start | Your first real cleanup |
What it is good at
- Showing the candidates. A scan names cache roots and their current size. A dry run walks the selected cleanup and names proposed actions.
- Not deleting the wrong thing. A path allowlist hard-refuses
~/Documents,~/.ssh,~/.config,/etcand friends, after symlink resolution. - Leaving recently-used files alone. Since 1.2.0 the default is to prune, not wipe: within a cache, only files untouched for 100+ days are removed. See the staleness gate.
- Recording the run. The CLI keeps a local log. Guided walkthroughs write a JSON session report unless disabled; dry runs do not.
- Checking updates. On start, the CLI reads a public release record over HTTPS when available.
What it is not
Being clear about the boundaries is more useful than a feature list.
- Not a backup tool. It deletes; it never archives. Nothing it removes is recoverable from within the tool.
- Not an undo tool.
--scanreads only;--dry-runpreviews the selected cleanup; neither can recover files after a real run. - Not a security scanner. It will not find secrets, malware, or vulnerabilities.
- Not cross-platform. Linux only. The npm package declares
"os": ["linux"]. - Not fully cross-distro. Cache cleanup inside
$HOMEworks anywhere, but the--systemmode is Debian/Ubuntu only — it callsaptanddpkgdirectly. - Not a substitute for your judgement. Read what it proposes before you confirm it.
The 30-second version
# 1. See what could be reclaimed. Deletes nothing.
npx linux-cleanup --scan
# 2. Preview the selected cleanup without deleting.
npx linux-cleanup --all-safe --dry-run
# 3. Run the guided walkthrough. Review each choice before deletion.
npx linux-cleanup
Step 3 is the default mode. It walks ten categories, asks before each one, shows a running total of bytes reclaimed, and writes a report at the end. See Walkthrough.
Where to go next
- Want the space back fastest? → Reclaim the most space
- Something went wrong? → Recovery then Troubleshooting
- Want every flag? → CLI flags
- Wondering what changed? → Changelog