Managing Binary Conflicts with Homebrew Keg-Only Formulae

The Conflict Between System Binaries and Custom Tooling

Installing a new library often creates a dilemma: you need a specific version of a tool for development, but installing it globally might overwrite a critical system binary or conflict with a version required by macOS. When two versions of the same library exist, the system typically defaults to the one found first in the $PATH. If a package manager blindly links every installation into /usr/local/bin, it risks breaking system stability.

Homebrew solves this using Keg-only formulae. A Keg-only package is installed into the Cellar (Homebrew's isolated storage area) but is not symlinked into the global path. This allows the software to be available for other packages to use as a dependency without exposing it to the user's shell or the system's default environment.

How the Ruby DSL Controls Installation

Homebrew defines packages using a Ruby-based Domain Specific Language (DSL). This allows the maintainers to script specific logic for how a package behaves. In a formula file (the .rb file), the keg_only attribute tells Homebrew to skip the linking phase for that specific package.

When a formula is marked as keg-only, Homebrew performs the following:

• Downloads and installs the package into /usr/local/Cellar/package_name/version (or /opt/homebrew/Cellar on Apple Silicon).
• Omits the creation of symbolic links in /usr/local/bin or /usr/local/lib.
• Ensures that other formulae that depend on this package can still find it via absolute paths during their own build processes.

Practical Example: Using a Keg-Only Library

Consider a scenario where you install openssl. Because macOS provides its own version of OpenSSL, Homebrew often treats the latest version as keg-only to avoid breaking system tools that rely on the Apple-provided version.

To verify if a package is keg-only, run this command in your terminal:

brew info openssl

If the output contains the phrase "Keg-only", the binary is not in your path. To use it for a specific task—such as compiling a different project from source—you must manually point your compiler to the Homebrew location.

Configuration for a Compiler:
Run these commands in your shell (assuming Intel Mac paths; replace /usr/local with /opt/homebrew for Apple Silicon) to make the keg-only library visible to your current session:

export LDFLAGS="-L/usr/local/opt/openssl@3/lib"
export CPPFLAGS="-I/usr/local/opt/openssl@3/include"
export PKG_CONFIG_PATH="/usr/local/opt/openssl@3/lib/pkgconfig"

Risk: Adding these to your .zshrc or .bash_profile permanently can lead to "version mismatch" errors if you switch between different versions of the same library.

Trade-offs: Isolation vs. Convenience

The primary trade-off of the keg-only system is the shift from automatic discovery to manual configuration. While it prevents system breakage, it introduces friction for developers who expect a tool to "just work" after running brew install.

Approach	Benefit	Drawback
Linked Formula	Instant access via terminal.	Potential to override system binaries.
Keg-Only Formula	System stability and isolation.	Requires manual PATH/Flag exports.

Verifying the Result

To confirm whether a package is actually isolated or linked, use the which command. If the package is keg-only, the command should return no path or point to the system version, not the Homebrew version.

which openssl

If the output is empty or points to /usr/bin/openssl, the Homebrew version is successfully isolated. If it points to /usr/local/bin/openssl, it has been linked.

Forcing a Link

If you have determined that the system risk is low and you prefer the convenience of a global binary, you can override the keg-only status. Run this command with standard user permissions:

brew link --force openssl@3

Rollback: To undo this and return the package to its isolated state, run:

brew unlink openssl@3