brew-cleanup

Remove stale lock files and outdated downloads for all formulas/casks

$ brew cleanup

$ brew cleanup [formula|cask]

$ brew cleanup [[-n|--dry-run]]

$ brew cleanup [[-h|--help]]

brew cleanup [-n|--dry-run] [-s[=all]|--scrub[=all]] [formula|cask …]

-n, --dry-run
    Preview what would be removed, without deleting anything.

-s, --scrub[=all]
    Aggressively scrub all downloads and symlinks (dangerous; use =all for everything).

formula|cask …
    Limit cleanup to specific formulae or casks.

The brew cleanup command is a Homebrew utility designed to reclaim disk space by removing outdated versions of installed formulae (packages), cached downloads, and broken symlinks. Homebrew, a popular package manager originally for macOS but available on Linux via Linuxbrew or Homebrew-on-Linux, stores multiple versions of formulae during upgrades. Over time, these accumulate, consuming significant storage.

By default, brew cleanup retains the most recent version of each formula and deletes others older than 120 days (configurable via BREW_CLEANUP_MAX_AGE_DAYS or HOMEBREW_CLEANUP_MAX_AGE_DAYS). It also prunes unused downloads from the cache directory ($HOMEBREW_CACHE) and fixes broken links. Running it periodically is recommended, especially after upgrades.

On Linux, where Homebrew is less mature than on macOS, it performs similarly but may interact differently with system paths. Always preview with --dry-run before scrubbing. This command enhances Homebrew hygiene without uninstalling current versions, making it essential for long-term usage.

The --scrub option permanently deletes files without confirmation—use cautiously. On Linux, Homebrew is experimental; test in a safe environment. Ignores kegs newer than max age (default 120 days).

HOMEBREW_CLEANUP_MAX_AGE_DAYS: Days before auto-cleanup (default 120).
HOMEBREW_NO_CLEANUP: Disable automatic cleanup after installs.

brew cleanup
Standard cleanup of old versions.
brew cleanup -n
Dry-run preview.
brew cleanup --scrub git
Clean specific formula aggressively.

Introduced in early Homebrew releases (~2010) by Max Howell for macOS disk management. Enhanced with --scrub in 2012; env var support added ~2015. Linux support via Linuxbrew (2014) by Michka Popov, merged into Homebrew in 2020.

brew(1), brew uninstall(1), brew autoremove(1)