Skip to main content

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.

This tool deletes files permanently

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 version2.1.0 in the current source; check linux-cleanup --version for the installed copy
PlatformLinux only — bash ≥ 4 and GNU coreutils
LicenseMIT — since 1.4.0
Network accessOne public release-record request on start when online; installing or updating also uses npm or GitHub
AuthorAhsan 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.

StepPageWhy
1What it deletesThe complete target list, by category
2Preview before deletingRead-only scan, then a dry run of the selected mode
3Safety guardsThe four gates a path must clear before deletion
4Deletion is permanentWhat "no undo" means in practice
5Installationnpx, global npm, or git clone
6Quick startYour 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, /etc and 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. --scan reads only; --dry-run previews 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 $HOME works anywhere, but the --system mode is Debian/Ubuntu only — it calls apt and dpkg directly.
  • 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​