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 [options] [formula | cask ...]

--prune[=<days>]
    Removes all cached downloads and old versions of formulae and casks older than <days>. If <days> is not provided, it defaults to 30 days. This is a more aggressive cleanup than the default behavior.

--dry-run, -n
    Performs a simulated cleanup operation. It shows exactly what would be removed without actually deleting any files, allowing you to review the proposed changes before committing to them.

formula | cask ...
    Specifies one or more particular formulae or casks to clean. If this argument is omitted, brew cleanup will process all installed formulae and casks.

The brew cleanup command is an essential tool for maintaining a tidy and efficient Homebrew installation on macOS and Linux. Its primary purpose is to reclaim disk space by systematically removing various types of unnecessary files.

By default, brew cleanup identifies and removes old versions of installed formulae and casks, ensuring that only the most recent (typically the last two or three) are kept. This is particularly useful as Homebrew upgrades can leave previous versions behind, which accumulate over time. Additionally, it clears out stale lock files that might be left over from interrupted Homebrew operations, and removes cached downloads of bottles and source tarballs that are no longer needed by any installed formula.

Regular use of brew cleanup helps prevent the Homebrew Cellar from becoming cluttered, improves system performance by reducing storage overhead, and ensures that your Homebrew environment remains healthy and free of potential conflicts arising from outdated components.

While brew cleanup is generally safe, using the --prune option can remove versions of formulae that might be critical if you need to revert to an older state for compatibility reasons with specific projects or development tools. Always exercise caution, especially when specifying a very short <days> value or if your workflow relies on older software versions. Note that brew cleanup does not remove unused dependencies; for that, you would typically use brew autoremove.

One of the most significant benefits of brew cleanup is its ability to free up substantial amounts of disk space over time. By regularly removing old versions and cached downloads, it helps prevent unnecessary data accumulation, which is particularly valuable on systems with limited storage.

Many Homebrew users integrate brew cleanup into their regular system maintenance routines, often running it as part of a weekly or monthly cron job or as a post-upgrade hook. This ensures that the Homebrew installation remains lean and optimized with minimal manual intervention.

Without any options or arguments, brew cleanup intelligently keeps a minimal number of recent versions (typically 2-3) of each formula and cask, which is generally a safe default for most users. This prevents accidental removal of a recently installed or updated version while still cleaning up older, truly obsolete ones.

The brew cleanup command has been a fundamental component of Homebrew's maintenance toolkit since its early days. As Homebrew evolved to manage not just formulae but also binary applications via Casks, cleanup adapted to encompass Cask-related tidying as well. Its purpose has remained consistent: to provide users with a straightforward way to maintain a clean and efficient Homebrew environment, addressing the natural accumulation of old software versions and cached data that occurs with regular package management.

brew(1), brew install(1), brew upgrade(1), brew autoremove(1), brew doctor(1)