What This Script Does
The cleanup-homebrew.sh script is a maintenance utility that removes accumulated cruft from your Homebrew installation and recovers disk space. Over time, as you install and upgrade packages, Homebrew retains old versions of formulae, cached download files, and dependencies that are no longer needed by any installed package. This script systematically cleans up all of these artifacts and provides a clear report of how much disk space was recovered in the process.
Homebrew's default behavior is to keep old versions of packages around even after you upgrade to newer ones. This is actually a useful safety feature — if a new version of a package causes problems, you can switch back to the previous version quickly because it is still on disk. However, over weeks and months of regular updates, these old versions accumulate and can consume a significant amount of storage. On machines with limited SSD space, this wasted storage adds up noticeably. The cleanup script addresses this by removing all old versions, keeping only the currently installed version of each package.
In addition to old package versions, the script clears Homebrew's download cache. Every time you install or upgrade a package, Homebrew downloads the package file (a compressed archive or installer) and stores it in its cache directory. These cached files serve as a local backup — if you uninstall and reinstall a package, Homebrew can use the cached file instead of downloading it again. But for most users, these cached files just take up space without providing much practical benefit. The cleanup script removes them, and Homebrew simply re-downloads any needed files the next time you install something.
The third cleanup operation is brew autoremove, which identifies and removes packages that were originally installed as dependencies of other packages but are no longer needed. This can happen when you uninstall a package that brought in several dependencies — those dependencies may still be installed even though nothing depends on them anymore. The autoremove command finds these orphaned dependencies and removes them cleanly.
Before performing any cleanup, the script measures the current disk space used by Homebrew's cellar (where packages are stored) and cache directories. After cleanup is complete, it measures again and calculates the difference. This before-and-after comparison is displayed prominently so you can see exactly how much space was recovered. For long-running systems that have not been cleaned up in a while, it is not unusual to recover several gigabytes of space.
The --dry-run flag is particularly useful with this script. When you run ./cleanup-homebrew.sh --dry-run, the script identifies everything that would be cleaned up and shows you the list without actually deleting anything. This lets you review what is about to be removed and verify that nothing you want to keep is on the list. Once you are satisfied with the dry run output, run the script without the flag to perform the actual cleanup.
This script is completely safe to run at any time. It does not remove currently active packages, modify running applications, or touch anything outside of Homebrew's own directories. After cleanup, all your installed packages continue to work exactly as before. The only difference is that old, unused versions and cached files are gone, and you have more free disk space. You can run this script as often as you like — if there is nothing to clean up, it simply reports that everything is already tidy.