Skip to main content

Requirements

linux-cleanup runs on Linux with bash 4 or newer and GNU coreutils. Everything else is optional and degrades gracefully when missing.

Platform​

Operating systemLinux only. The npm package declares "os": ["linux"] and will refuse to install elsewhere
Shellbash ≥ 4.0
Node.js≥ 14 — only for the npx and npm install -g paths. Not needed for a git clone
PrivilegesRuns as a normal user. Only --system requests sudo

macOS and WSL are worth separating:

  • macOS is not supported. The paths, find flags and package managers differ. A sibling tool exists for it; do not point this one at a Mac.
  • WSL runs on the Linux side. Review any symlink from $HOME into /mnt/c/ before a cleanup. The allowlist resolves symlinks, but its protected Linux home paths do not imply that every Windows directory is protected.

Required commands​

These are present on essentially every mainstream distro. bash, find, du, df, rm, awk, sort, grep, sed, stat, realpath.

realpath matters more than the others: it is what resolves symlinks before the protected-path check. On a minimal container image without GNU coreutils, install them before running.

npx linux-cleanup --self-test

--self-test probes every required command and names the first one missing, with a fix hint. Run it before anything destructive.

Optional dependencies​

Each unlocks one feature. Without it, that feature is unavailable and the rest of the tool is unaffected.

DependencyUnlocksWithout it
jqMarkdown / HTML report exportJSON reports still written; conversion unavailable
whiptailThe visual TUI menu--tui falls back to the CLI menu with an install hint
dialogTUI fallback when whiptail is absentAs above
snapDisabled snap-revision cleanup in --systemThat step is skipped cleanly
crontabThe weekly cron installer--install-cron cannot run
numfmtHuman-readable byte sizesFalls back to raw byte counts
xdg-openOpening HTML reports in a browserOpen the file manually
lessPaged JSON view in the reports managerRead the file directly
lsb_releaseBetter distro detection in feedback bundlesBundle still generated

Installing the two that matter​

jq (report export) and whiptail (visual menu) are the two most people want.

# Debian / Ubuntu / Mint
sudo apt install jq whiptail

# Fedora / RHEL / Rocky
sudo dnf install jq newt

# Arch / Manjaro
sudo pacman -S jq libnewt

# openSUSE
sudo zypper install jq newt

The whiptail binary ships in the newt package on RPM-based distros and libnewt on Arch.

Distro coverage​

Cache cleanup inside $HOME — which is the large majority of what this tool reclaims — works identically on every Linux distribution.

--system is Debian/Ubuntu only

The sudo mode calls apt and dpkg directly, with no distro detection and no guard. On Fedora, Arch or openSUSE its package steps fail with "command not found".

Full breakdown of which steps work where: Distro support.

Output on disk​

Each run can write a local log. A guided walkthrough can also write a JSON report, and a debug bundle is created when requested or after an unexpected failure. Their size depends on the run. See Output paths for the layout.

Next​