docs/FAQ.md
The Formula Cookbook has a list of Homebrew terminology.
First update all package definitions (formulae) and Homebrew itself:
brew update
You can now list which of your installed packages (kegs) are outdated with:
brew outdated
Upgrade everything with:
brew upgrade
Or upgrade a specific formula with:
brew upgrade <formula>
To stop something from being updated/upgraded:
brew pin <formula_or_cask>
If you also do not want Homebrew to automatically learn about newer versions until you choose to, disable auto-updating entirely:
export HOMEBREW_NO_AUTO_UPDATE=1
For the tradeoffs and alternatives, see Locking installed formulae at specific versions.
To allow that package to update again:
brew unpin <formula_or_cask>
Note that pinned, outdated formulae that another formula depends on need to be upgraded when required, as we do not allow formulae to be built against outdated versions. If this is not desired, see Locking installed formulae at specific versions instead.
Pinned casks are skipped by brew upgrade, but an app’s own updater may still update it outside Homebrew.
To uninstall Homebrew, run the uninstall script from the Homebrew/install repository.
Homebrew automatically uninstalls old versions of each formula that is upgraded with brew upgrade, and periodically performs additional cleanup every 30 days.
To disable automatic brew cleanup:
export HOMEBREW_NO_INSTALL_CLEANUP=1
To disable automatic brew cleanup only for formulae foo and bar:
export HOMEBREW_NO_CLEANUP_FORMULAE=foo,bar
When automatic brew cleanup is disabled, if you uninstall a formula, it will only remove the latest version you have installed. It will not remove all versions of the formula that you may have installed in the past. Homebrew will continue to attempt to install the newest version it knows about when you run brew upgrade. This can be surprising.
In this case, to remove a formula entirely, you may run brew uninstall --force <formula>. Be careful as this is a destructive operation.
brew upgrade <formula> or brew install <formula> also upgrade a bunch of other stuff?Homebrew doesn't support arbitrary mixing and matching of formula versions, so everything a formula depends on, and everything that depends on it in turn, needs to be upgraded to the latest version as that's the only combination of formulae we test. As a consequence any given upgrade or install command can upgrade many other (seemingly unrelated) formulae, especially if something important like python or openssl also needed an upgrade.
brew --cache
Which is usually: ~/Library/Caches/Homebrew
.apps don’t find Homebrew utilitiesGUI apps on macOS don't have Homebrew's prefix in their PATH by default. You can fix this by running sudo launchctl config user path "$(brew --prefix)/bin:${PATH}" and then rebooting, as documented in man launchctl. Note that this sets the launchctl PATH for all users.
Running a developer command (e.g. brew edit, brew create) enables Homebrew's developer mode. This means:
brew update before some commands every hour instead of every 24 hours.main instead of the latest stable tag.To switch back to the default behaviour, run brew developer off. If you only want to switch back to stable tags, set HOMEBREW_UPDATE_TO_TAG=1 in your shell environment. To control auto-update frequency, use HOMEBREW_AUTO_UPDATE_SECS; to disable auto-updates entirely, set HOMEBREW_NO_AUTO_UPDATE=1.
Read our contribution guidelines.
Homebrew provides pre-built binary packages for many formulae. These are referred to as bottles and are available at https://github.com/Homebrew/homebrew-core/packages.
If available, bottled binaries will be used by default except under the following conditions:
--build-from-source option is invoked.brew install <formula> will try to find a bottled binary, but brew install --with-foo <formula> will trigger a source build.We aim to bottle everything.
Homebrew's pre-built binary packages (known as bottles) of many formulae can only be used if you install in the default installation prefix, otherwise they have to be built from source. Building from source takes a long time, is prone to failure, and is not supported. The default prefix is:
/opt/homebrew for macOS on Apple Silicon,/usr/local for macOS on Intel, and/home/linuxbrew/.linuxbrew for Linux.Do yourself a favour and install to the default prefix so that you can use our pre-built binary packages. Pick another prefix at your peril!
/opt/homebrew on Apple Silicon?The prefix /opt/homebrew was chosen to allow installations in /opt/homebrew for Apple Silicon and /usr/local for Rosetta 2 to coexist and use bottles.
/home/linuxbrew/.linuxbrew on Linux?The prefix /home/linuxbrew/.linuxbrew was chosen to avoid writing to system-owned directories after installation while still allowing most precompiled binaries (bottles) to be used. Homebrew is designed for single-user installations rather than shared role accounts. See Support Tiers for unsupported multi-user environments.
tl;dr Sudo is dangerous, and you installed TextMate.app without sudo anyway.
Homebrew refuses to work using sudo.
Use sudo only with software that you trust.
Even when you trust Homebrew itself, a source build can run large upstream build scripts that have not received a security review from Homebrew.
Running those scripts as root would allow them to modify or upload files anywhere permitted by the operating system.
Some build scripts have attempted to modify /usr even when configured with another installation prefix.
We use the macOS sandbox to stop this but this doesn't work when run as the root user (which also has read and write access to almost everything on the system).
The sandbox is part of Homebrew's wider Software Supply Chain Security measures.
Did you chown root /Applications/TextMate.app? Probably not. So is it that important to chown root wget?
Note: Homebrew is primarily designed for single-user use and does not work well in multi-user configurations.
First, see previous question regarding sudo.
Ownership on macOS, all subdirectories and files use a forced default of admin user group (instead of lower default user group staff) and the current user that executed the installation.
Ownership on Linux, all subdirectories and files default to the current user and the user group that executed the installation.
By default, permissions for Homebrew-managed directories and files are 0755 (u=rwx,g=rx,o=rx) on both macOS and Linux. This means that only the owning user (typically the installing user) can modify or replace files within the Homebrew prefix, while all users are allowed to read and execute installed binaries.
When a Homebrew-installed binary is executed, it runs with the privileges of the user who launched it.
Note: Homebrew is primarily designed for single-user use and does not work well in multi-user configurations.
If it’s not in man brew, it’s probably an external command with documentation available using --help.
If all maintainer feedback has been addressed and all tests are passing, bump it with a “bump” comment. Sometimes we miss requests and there are plenty of them. In the meantime, rebase your pull request so that it can be more easily merged.
Yes! It’s easy! If brew tap doesn't show homebrew/core, set yourself up to edit a local copy:
HOMEBREW_NO_INSTALL_FROM_API=1 in your shell environment,brew tap --force homebrew/core and wait for the clone to complete, thenbrew edit <formula> to open the formula in EDITOR.You don’t have to submit modifications back to homebrew/core, just edit the formula to what you personally need and brew install <formula>. As a bonus, brew update will merge your changes with upstream so you can still keep the formula up-to-date with your personal modifications!
Note that if you are editing a core formula or cask you must set HOMEBREW_NO_INSTALL_FROM_API=1 before using brew install or brew update otherwise they will ignore your local changes and default to the API.
To undo all changes you have made to any of Homebrew's repositories, run brew update-reset. It will revert to the upstream state on all Homebrew's repositories.
Yes! It’s easy! If you already have a local copy of homebrew/core (see above), just use the brew create command. Homebrew will then open the formula in EDITOR so you can edit it, but it probably already installs; try it: brew install <formula>. If you encounter any issues, run the command with the --debug switch like so: brew install --debug <formula>, which drops you into a debugging shell.
If you want your new formula to be part of homebrew/core or want to learn more about writing formulae, then please read the Formula Cookbook.
Ensure you have a local copy of homebrew/core, then:
brew update
brew install gh
cd "$(brew --repository homebrew/core)"
gh pr checkout pull_request_number
Use brew log <formula> to find out! Likely because it had unresolved issues and/or our analytics indicated it was not widely used.
For disabled and deprecated formulae, running brew info <formula> will also provide an explanation.
Homebrew's creator @mxcl wasn't too concerned with the beer theme and didn't consider that the project may actually prove popular. By the time Max realised that it was popular, it was too late. However, today, the first Google hit for "homebrew" is not beer related 😉
It means the formula is installed only into the Cellar and is not linked into the default prefix. This means most tools will not find it. You can see why a formula was installed as keg-only, and instructions for including it in your PATH, by running brew info <formula>.
You can modify a tool's build configuration to find keg-only dependencies. Or, you can link in the formula if you need to with brew link <formula>, though this can cause unexpected behaviour if you are shadowing macOS software.
brew edit <formula> and edit the formula directly. Currently there is no other way to do this.
<a data-proofer-ignore name="why-arent-some-apps-included-during-brew-upgrade"></a>
brew upgrade handle apps that update themselves?Many apps can update themselves without Homebrew:
An app’s own updater can make Homebrew’s installation record older than the app that is actually installed. Blindly replacing the app based on that record could downgrade it.
Casks for self-updating apps declare auto_updates true.
For a versioned cask that installs a single readable app bundle, Homebrew compares the bundle’s version metadata with the cask's current version.
The default brew upgrade includes the cask when the installed app appears older and skips it when the installed app appears to be the same version or newer.
This comparison is not available for every artifact or versioning scheme.
When Homebrew cannot make a reliable comparison, it normally skips the self-updating cask instead of guessing.
To persistently opt out of automatic upgrades for all auto_updates true casks, add export HOMEBREW_NO_UPGRADE_AUTO_UPDATES_CASKS=1 to your shell configuration.
This does not affect upgrades requested with --greedy or --greedy-auto-updates.
Casks that use version :latest have no version number to compare and are excluded from an ordinary brew upgrade.
When such a cask is named explicitly or included with --greedy-latest, Homebrew downloads the current artifact and, when possible, compares its SHA-256 checksum with the checksum recorded during installation.
It skips reinstalling the cask when the artifact has not changed.
Naming a cask explicitly, using --greedy-auto-updates or using the broader --greedy option can include casks that the default checks skip.
Set HOMEBREW_UPGRADE_GREEDY=1 to apply --greedy persistently to all cask upgrades, or list selected casks in the space-separated HOMEBREW_UPGRADE_GREEDY_CASKS variable.
Refer to the upgrade section of the brew manual page for the full option details.
We tried.
We built brew-rs, a Rust frontend, and benchmarked it against Ruby with zero delegation back to Ruby and cold-cache I/O included.
Rust did win some narrow operations: it was faster at fetching batches of bottles, especially with a warm archive cache.
But fetching is not where users spend their time.
For brew install, the operation people actually care about, Ruby was faster on representative comparisons.
A real install does far more than fetch a file: it resolves metadata, pours bottles, links files, writes tabs, runs postinstall and preserves Homebrew's existing semantics.
The Rust frontend only looked faster when it skipped that work or delegated it back to Ruby, and delegating defeats the point.
So a rewrite would mean reimplementing the Cellar layout, tabs, links, caveats, postinstall, cask behaviour, source fallback and tap logic in another language for little or no gain on the path that matters. The performance work that does help is happening in Ruby: starting useful network and disk I/O sooner, using API-backed bottle metadata earlier and trimming overhead in simple bottle fetch paths without duplicating install semantics in a second frontend.
brew upgrade?Homebrew has two possible strategies to update cask apps: uninstalling the old version and reinstalling the new one, or replacing the contents of the app with the new contents. With the uninstall/reinstall strategy, macOS thinks the app is being deleted without any intent to reinstall it, and so it removes some internal metadata for the old app, including where it appears in the Dock and Launchpad and which permissions it's been granted. The content replacement strategy works around this by treating the upgrade as an in-place upgrade. However, starting in macOS Ventura, these in-place upgrades are only allowed when the updater application (in this case, the terminal running Homebrew) has certain permissions granted. Either the "App Management" or "Full Disk Access" permission will suffice.
Homebrew defaults to in-place upgrades when it has the necessary permissions. Otherwise, it will use the uninstall/reinstall strategy.