How to Clear the Homebrew Cache and Old Versions on Mac
AskClean Team · Updated 2026-08-05
Use brew --cache to locate Homebrew's download cache, then run brew cleanup -n before making changes. A normal brew cleanup removes stale locks, outdated downloads, and old installed formula versions; brew cleanup --prune=all removes cached files regardless of age. Keep current installations, configuration, and project files outside the cleanup target.
Homebrew storage is more than one cache folder
Homebrew uses a download cache for bottles, source archives, and cask downloads. On macOS the default is ~/Library/Caches/Homebrew, but HOMEBREW_CACHE can change it. The reliable way to find the active location is brew --cache. A cached archive is normally reproducible: Homebrew can download it again if a future install or reinstall needs it.
Installed software lives elsewhere. Formulae are installed as versioned kegs in the Homebrew Cellar, and the active version is normally reached through links under the Homebrew prefix. Casks have a Caskroom and may also place an application or other artifact in its configured destination. Use brew --cellar, brew --caskroom, and brew --prefix to discover these locations instead of assuming /opt/homebrew or /usr/local.
This distinction matters because brew cleanup is not merely a command that empties the download directory. Homebrew's current manpage says it removes stale lock files, outdated downloads, and old versions of installed formulae. Old kegs may be unnecessary, but they are installed versions rather than cache. A cleanup guide must account for both the redownload cost of cached files and the rollback cost of removing an older installed version.
Start with a read-only audit
First ask Homebrew where it keeps downloads: run brew --cache. If you want a size without opening or changing the directory, run du -sh "$(brew --cache)". The quoted command substitution handles spaces in a custom cache path. Do not copy a hard-coded cache path from another Mac, because an environment override may point your installation somewhere else.
Next run brew cleanup -n. The -n flag is the same as --dry-run: it shows what Homebrew would remove without actually removing it. Read the output for both cached downloads and versioned kegs. If a familiar tool appears, confirm which version is active with brew list --versions and whether your work depends on the older version before proceeding.
The preview is more useful than a raw Finder sort because Homebrew understands which versions are current, which downloads are outdated, and which files belong to its own layout. Finder can show size, but size alone cannot tell whether a directory is a disposable bottle, an active keg, a cask installation, or user-created configuration.
- Run brew --cache and record the active download-cache path.
- Run du -sh "$(brew --cache)" to measure that path without modifying it.
- Run brew cleanup -n and review every proposed download and old formula version.
- Use brew list --versions to confirm the current installed versions of tools you rely on.
- Decide whether you need a normal age-based cleanup or the broader --prune=all cache cleanup.
A dry run is a preview, not a backup. Once Homebrew removes an old keg or cached artifact, do not assume it will appear in the macOS Trash or remain available upstream in the same version.
Use brew cleanup for the normal, conservative pass
After reviewing brew cleanup -n, run brew cleanup for the ordinary maintenance pass. According to Homebrew's manpage, the command removes stale lock files and outdated downloads for formulae and casks, and removes old versions of installed formulae. If you supply formula or cask names, cleanup is limited to those named items; without names it reviews all formulae and casks.
The current default treats downloads older than 120 days as cleanup candidates. Homebrew exposes HOMEBREW_CLEANUP_MAX_AGE_DAYS for users who intentionally maintain a different age policy, but changing an environment variable merely to force a one-time purge is harder to audit than using the documented command options. Keep the default unless you have a repeatable retention reason.
A normal cleanup should leave the current installed formula version in place. It can still remove an older version you were informally keeping for rollback, so the preview remains important. If a production script depends on a versioned executable inside a specific old keg rather than the supported opt link or PATH, fix or document that dependency before cleanup.
Homebrew may also perform periodic cleanup after install, upgrade, or reinstall activity, depending on configuration and elapsed time. Therefore brew cleanup can report little or nothing even when you use Homebrew frequently. Trust the preview and measured cache size rather than expecting a fixed number of gigabytes from every run.
Use --prune=all only when you accept the redownload cost
Run brew cleanup --prune=all when you intentionally want Homebrew to remove cached files regardless of age. Homebrew documents all as the value for removing everything covered by the prune cache policy. This is broader than the standard age-based cleanup, so repeat the preview with brew cleanup -n --prune=all before executing it.
The main consequence is future network and time cost. A formula reinstall may need to download its bottle again; a source build may need to fetch its archive again; and a cask reinstall may need to retrieve a large installer again. On a metered, slow, offline, or tightly controlled network, a recent cache can be worth more than the local space it occupies.
The command does not mean 'uninstall every current Homebrew package.' The current Cellar and Caskroom are distinct from the download cache. However, cleanup still includes its normal old-version work, so inspect the dry run for old kegs as well as cache files. Do not treat --prune=all as reversible merely because downloads are usually reproducible.
Avoid turning an aggressive prune into a scheduled reflex. Caches are valuable when they prevent repeated downloads, and Homebrew already has age-based maintenance. Reserve the all policy for real storage pressure, cache troubleshooting, an image-preparation workflow that intentionally excludes installers, or a machine whose packages can be fetched again immediately.
- Run brew cleanup -n --prune=all and save the preview.
- Check that your network, proxy, credentials, and upstream availability allow required downloads to be fetched again.
- Confirm that any listed old formula version is no longer required for rollback or a pinned workflow.
- Run brew cleanup --prune=all only after accepting those consequences.
- Measure the cache again with du -sh "$(brew --cache)" and test one important Homebrew-installed command.
Clean one formula or cask when the global scope is too broad
The cleanup command accepts formula and cask arguments. If one package has accumulated a large installer or several old kegs, a targeted preview such as brew cleanup -n <name> is easier to reason about than a global cleanup. Replace <name> with the actual formula or cask token; do not paste angle brackets literally.
Then run brew cleanup <name> only if its preview matches your intent. Targeting limits the package scope, but it does not change the meaning of cleanup: Homebrew may remove outdated downloads and old installed formula versions associated with that name. An old version can have a higher recovery cost than a cached bottle.
If you are trying to repair one failed download, first confirm that the suspect artifact is actually in the location reported by brew --cache <name>. A targeted Homebrew command preserves package-manager context. Manually deleting unrelated files by pattern can catch other packages that share a name fragment or leave Homebrew with a partial directory.
brew autoremove is not cache cleanup
Homebrew's autoremove command uninstalls formulae that were installed only as dependencies and are no longer needed. That is installed software removal, not deletion of cached downloads. It can reclaim space from the Cellar, but it also removes executable code and libraries that ad hoc scripts may call even if Homebrew no longer sees a declared dependency relationship.
If you are considering it, start with brew autoremove --dry-run. Review every formula and ask whether you installed or use it indirectly outside Homebrew's dependency graph. A shell script, build system, local service, or manual PATH reference can depend on a formula without making it a dependency of another installed formula.
Only run brew autoremove after that separate review. Do not append it automatically to brew cleanup, and do not describe it as a stronger cache flag. Reinstalling an autoremoved formula may be simple when the package remains available, but it is still a change to the machine's installed toolchain and can interrupt work immediately.
brew autoremove --dry-run is optional and read-only. The actual brew autoremove command uninstalls dependencies; skip it when your goal is only to clear Homebrew's download cache.
Never treat the prefix, Cellar, Caskroom, or configuration as cache
Do not run a broad rm -rf against the output of brew --prefix, brew --cellar, or brew --caskroom. Those locations hold Homebrew itself, current formula installations, and cask records. Removing them behind Homebrew's back can break links, services, upgrades, and uninstall bookkeeping while offering no reliable preview or package-level recovery plan.
Do not delete a whole ~/Library/Caches directory to reach Homebrew either. That parent contains caches owned by many applications, each with different shutdown and recovery behavior. Even when the Homebrew cache itself is reproducible, the neighboring directories are outside Homebrew's cleanup contract.
User configuration is also not download cache. Shell startup files, Brewfiles, service definitions, database data, package-specific dotfiles, certificates, and project directories can determine how installed software behaves or contain irreplaceable work. Homebrew cleanup does not need you to erase them. If a formula stores state outside the Cellar, use that software's own backup and retention documentation before changing it.
If the goal is to uninstall Homebrew completely, this cache procedure is the wrong workflow. Cleanup keeps the package manager and current installations. A full uninstall requires Homebrew's supported uninstall process plus a separate review of user data and configuration; it should never be improvised by deleting whatever looks Homebrew-related in Finder.
Verify the result and plan for recovery
After cleanup, run brew cleanup -n again. A shorter or empty preview confirms that Homebrew no longer sees the same candidates. Re-run du -sh "$(brew --cache)" to measure the download cache and brew list --versions to confirm expected current formulae remain installed. Finally, launch or invoke the few tools that matter to your current work.
A removed cached download is normally recovered when Homebrew downloads it again during install or reinstall. That recovery requires a working network and an artifact that is still available. A removed old keg has a different recovery path: you may have to install a currently supported version, use a versioned formula if one exists, or rebuild your environment from a maintained Brewfile. None of those guarantees the exact removed bits.
For reproducible machines, keep a Brewfile in version control and document deliberate version constraints. The Brewfile records intended packages; it is not a copy of their binaries or user data. Pair it with backups for configuration, databases, certificates, and project files. This gives you a restoration plan without retaining every stale download forever.
How AskClean fits into a Homebrew cleanup
AskClean scans application-cache folders under ~/Library/Caches and can surface a Homebrew cache that crosses its size threshold. It labels the cache for review and does not run a Homebrew cleanup command on your behalf. That boundary is important: only Homebrew can provide the package-aware preview that distinguishes outdated downloads from old formula versions.
If you approve the Homebrew cache item in AskClean, the app moves the selected cache directory to the macOS Trash rather than immediately deleting it permanently. That offers a recovery window for the files AskClean handled, but it is broader than Homebrew's normal 120-day policy and does not clean old kegs in the Cellar. Use brew cleanup -n when you want Homebrew's own decision model.
A practical workflow is to use AskClean to discover whether the Homebrew cache is materially contributing to disk pressure, then choose the executor that matches your intent. Use brew cleanup for package-aware maintenance. Use AskClean's reviewed Trash workflow only when you intentionally accept clearing the surfaced cache as a whole and want short-term local recoverability.
Homebrew storage and deletion boundaries
Use Homebrew's own path and preview commands to separate reproducible downloads from installed tools and user-owned state.
| Item | Inspect with | Cleanup consequence |
|---|---|---|
| Download cache | brew --cache | Reproducible in principle, but future installs and reinstalls must download artifacts again. |
| Outdated download or stale lock | brew cleanup -n | Normal cleanup removes it under Homebrew's current age and package rules. |
| Old formula keg | brew cleanup -n / brew list --versions | Cleanup removes an installed old version; exact rollback may not remain available. |
| Current formula or cask | brew --cellar / brew --caskroom | Installed software, not cache; do not delete its directory manually. |
| Unused dependency formula | brew autoremove --dry-run | The real autoremove command uninstalls it and can break an undeclared script dependency. |
| Brewfile, dotfiles, service state, or project data | Your configuration and backup inventory | User-owned state; it is outside cache cleanup and may be irreplaceable. |
brew cleanup --prune=all broadens cache pruning by age; it does not turn current installations or user configuration into disposable cache.
FAQ
Is brew cleanup safe to run on a Mac?
It is a supported Homebrew maintenance command, but preview it with brew cleanup -n first. It removes outdated downloads and old versions of installed formulae, so confirm that no workflow relies on an older keg before running the real command.
What does brew cleanup --prune=all delete?
It applies cleanup with a prune policy that removes cached files regardless of age, while cleanup can also remove stale locks and old formula versions. Preview the exact result with brew cleanup -n --prune=all and expect later installs or reinstalls to download artifacts again.
Where is the Homebrew cache on Apple Silicon and Intel Macs?
Run brew --cache. The macOS default is ~/Library/Caches/Homebrew, but HOMEBREW_CACHE can override it, so the command is safer than assuming a location from the Mac's processor or Homebrew prefix.
Does brew cleanup uninstall my current packages?
Its cleanup target includes old versions of installed formulae, not the current version as a blanket rule. It is still important to inspect brew cleanup -n because an old keg may be part of your rollback or a hard-coded local workflow.
Should I run brew autoremove after brew cleanup?
Only as a separate, optional decision. Start with brew autoremove --dry-run. Autoremove uninstalls formulae that Homebrew considers no longer-needed dependencies; it does not clear download cache and may remove a tool used directly by your scripts.
Can I delete ~/Library/Caches/Homebrew manually?
Prefer Homebrew's preview and cleanup commands because they understand package state. Avoid blind rm -rf commands. If you choose a whole-cache removal workflow, confirm the exact path with brew --cache, accept the redownload cost, and preserve a recovery window where possible.
Sources