Homebrew’s package management is so good, most people never think about uninstalling.
Let’s say you’ve got a package installed, some-package, and you’re done with it. The basic command is brew uninstall some-package. This removes the package itself and its associated files. But Homebrew is smart about dependencies. If some-package was the only thing keeping another package, say dependency-package, installed, brew uninstall will also automatically remove dependency-package.
However, sometimes you end up with “orphaned” dependencies – packages that were installed as dependencies for something else, but are no longer required by any installed package. These can accumulate and take up disk space. To find them, you use brew autoremove. This command identifies and prompts you to remove these unneeded packages.
Here’s a common scenario: you install package-a, which requires dependency-b. Later, you uninstall package-a. brew uninstall package-a will remove package-a and, because dependency-b is no longer needed, it will also remove dependency-b. Now, imagine you had a third package, package-c, that also depended on dependency-b. If you uninstall package-a after package-c was installed, dependency-b would not be removed because package-c still needs it. Only when package-c is eventually uninstalled, or if dependency-b is no longer required by any installed package, will brew autoremove then pick it up.
Sometimes, a package might be installed but its linked files are broken, or you want to clean up old versions. brew cleanup is your friend here. It removes old, unlinked versions of installed formulae and cached downloads. Running brew cleanup without arguments cleans up everything. You can also specify a particular package: brew cleanup some-package. This is useful if you suspect a particular installation is problematic or just want to free up space from older versions.
What if you want to uninstall everything that Homebrew manages? This is a more drastic step, usually reserved for when you’re completely resetting your development environment. The official uninstall script is the way to go. You can download it with curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh and then run it with bash uninstall.sh. This script systematically removes Homebrew itself and all installed packages. It’s thorough and will prompt you for confirmation.
A common pitfall is forgetting to update Homebrew before uninstalling or cleaning. Outdated Homebrew can sometimes lead to confusing errors or incomplete removals. Always run brew update before performing uninstall or cleanup operations. This ensures you’re working with the latest definitions and logic for package management.
If you encounter issues where brew uninstall seems to hang or fail, it might be due to file permissions or a corrupted Homebrew installation. A common fix involves checking and correcting permissions in your Homebrew directories, typically located in /usr/local/ (for Intel Macs) or /opt/homebrew/ (for Apple Silicon Macs). Running sudo chown -R $(whoami) $(brew --prefix)/* can often resolve permission-related problems. This command recursively changes ownership of all Homebrew-related files and directories to your current user, ensuring Homebrew has the necessary access to modify them.
Another diagnostic step if uninstalls are failing is to check the integrity of your Homebrew installation. Running brew doctor will diagnose potential problems with your setup, including broken symlinks or missing dependencies, and offer suggestions for fixes. It’s the first step you should take if brew uninstall or brew autoremove are not behaving as expected.
After you’ve uninstalled a package and its dependencies, and perhaps run brew cleanup, you might notice that some command-line tools are no longer available. This is expected. The crucial next step to ensure your shell environment is clean is to restart your terminal session or, in some cases, re-source your shell configuration file (e.g., source ~/.zshrc or source ~/.bash_profile). This forces your shell to re-evaluate its PATH environment variable, removing the directories associated with the uninstalled Homebrew packages.