Handle Deprecated Homebrew Formula Options (2026)

Homebrew’s deprecation system is a lot like a passive-aggressive roommate: it’ll hint at changes for a while before outright yelling at you, and by then, it might be too late to easily fix.

Let’s see what happens when a formula you’re trying to install or upgrade has deprecated options. Imagine you’re trying to install foobar with a specific, now-deprecated, feature enabled.

brew install foobar --with-baz

Suddenly, you’re hit with this:

Error: foobar: --with-baz has been deprecated and removed.
Use --with-qux instead.

This isn’t just a minor inconvenience; it means the maintainer has decided a particular configuration option for foobar is no longer supported, and they’ve actively removed it from the formula’s definition. The system is telling you, "Hey, that thing you asked for? It doesn’t exist anymore. Here’s the new thing you should probably be asking for."

Common Causes and Fixes

Direct Deprecation & Removal: The most straightforward reason is that the option was explicitly marked as deprecated and then removed. The formula maintainer likely announced this in the formula’s commit history or on the project’s issue tracker.
- Diagnosis: Check the formula’s Git history on GitHub. Look for commits where the option was added, then marked as deprecated, and finally removed. You can often find this by searching the formula file’s history directly. For example, if foobar’s formula is Formula/foobar.rb, you’d look at https://github.com/Homebrew/homebrew-core/commits/master/Formula/foobar.rb.
- Fix: As the error message suggests, replace the deprecated option with the recommended one. In our example, it’s --with-baz to --with-qux.
```
brew install foobar --with-qux
```
- Why it works: You’re now using the current, supported configuration flag that the formula maintainer has provided as a replacement.
Underlying Dependency Changes: The deprecated option might have relied on a specific version or feature of a dependency that is no longer available or supported.
- Diagnosis: Examine the formula’s depends_on clauses and patch blocks around the time the option was deprecated. Look for dependencies that were updated or removed. If the deprecated option’s logic was tied to a specific library version (e.g., --with-feature-x required libfoo >= 1.5), check if libfoo has been updated beyond that version or if libfoo itself was removed.
- Fix: If the option was removed because an underlying dependency changed, the fix is usually to remove the option entirely. The new behavior might be the default, or the functionality might have been refactored into a different option.
```
brew install foobar # Without any mention of --with-baz or --with-qux
```
- Why it works: You’re letting Homebrew install the formula with its default, current configuration, which has adapted to the changes in its dependencies.
Feature Re-architecture: The functionality provided by the deprecated option has been fundamentally changed or integrated into the main formula in a way that no longer requires a separate flag.
- Diagnosis: Read the commit messages and pull requests related to the deprecation of the option. Often, maintainers will explain why an option was removed, and it’s usually because the feature it controlled is now always on, always off, or managed differently.
- Fix: Simply remove the option from your command. The functionality it enabled is likely now the default behavior of the formula.
```
brew install foobar
```
- Why it works: The formula has been updated so that the feature is no longer controlled by a flag. Its presence or absence is now determined by the core formula logic.
Formula Renaming or Splitting: Sometimes, a formula is split into multiple, or a formula is renamed, and options are simplified or removed in the process.
- Diagnosis: Search Homebrew’s core repository for the formula name you’re trying to install. If it was renamed, you’ll find a redirect or a note in the old formula pointing to the new one. If it was split, you might need to install multiple new formulas.
- Fix: Install the new, renamed formula or the appropriate new sub-formula.
```
brew install new-foobar # If foobar was renamed to new-foobar
brew install foobar-core foobar-addon # If foobar was split
```
- Why it works: You’re now installing the correct, current formula that has a simplified or different set of options.
Outdated Homebrew Installation: While less common for formula option deprecation, an extremely old Homebrew installation might not correctly interpret the deprecation messages or might be trying to use syntax that’s no longer supported by the core.
- Diagnosis: Run brew doctor. This command checks for common issues within your Homebrew installation, including outdated versions.
- Fix: Update Homebrew itself.
```
brew update
brew upgrade brew
```
- Why it works: Ensures you’re running the latest Homebrew logic, which understands the current state of formula deprecations and removals.
User-Defined Aliases or Scripts: You might have an alias or a script that automatically appends deprecated options to brew install commands.
- Diagnosis: Check your shell’s configuration files (e.g., .bashrc, .zshrc) for any aliases or functions that modify brew commands. Also, check any custom scripts you use for package management.
- Fix: Remove or update the offending alias or script to no longer include the deprecated option.
```
# Example: Remove an alias from .zshrc
# alias brew='brew --with-baz' # Remove this line
```
- Why it works: You’re preventing the deprecated option from being passed to Homebrew in the first place.

After you’ve successfully resolved the deprecated option, the next error you’ll likely encounter is related to missing dependencies or configuration issues that were implicitly handled by the deprecated option’s functionality.