Building Software with Homebrew Keg-Only Dependencies

A keg-only formula is installed in its own prefix but is not linked into Homebrew's common bin, lib and include directories. This prevents a Homebrew package from shadowing software provided by macOS or conflicting with another formula. See the FAQ explanation of keg-only formulae.

• Do not replace macOS tools or libraries with manual symlinks.
• Avoid brew link --force because it makes unrelated builds and system commands resolve a different dependency globally.
• Pass the required location only to the build that needs it.

Discover the prefix

Use brew --prefix <formula> rather than embedding /opt/homebrew, /usr/local or a Cellar version:

brew --prefix openssl@3

The returned opt path remains stable when the formula is upgraded.

Compiler and linker flags

For a build system that accepts compiler and linker flags:

CPPFLAGS="-I$(brew --prefix openssl@3)/include" \
  LDFLAGS="-L$(brew --prefix openssl@3)/lib" \
  ./configure

Use CPPFLAGS for C or C++ preprocessor include paths unless upstream explicitly documents CFLAGS or CXXFLAGS. These flags affect only that command.

Executable lookup

Temporarily prepend a keg-only formula's executable directory when a build requires its tools:

PATH="$(brew --prefix FORMULA)/bin:$PATH" make

Do not add a keg-only dependency to a global shell PATH unless you want it to override the platform command in every future shell.

pkg-config

When the dependency installs .pc metadata, point pkg-config to it for one command:

PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig" pkg-config --cflags --libs openssl

Some formulae use lib/pkgconfig, some use share/pkgconfig and some provide no pkg-config metadata. Inspect the formula prefix rather than assuming a file exists.

CMake

Add the formula prefix to CMAKE_PREFIX_PATH when a CMake project uses package configuration or Common Package Specification files:

CMAKE_PREFIX_PATH="$(brew --prefix openssl@3)" cmake -S . -B build

If more than one prefix is required, separate them with the platform's normal path separator and preserve any intentional existing value.

Language packages

Build Python and other language extensions inside an isolated project environment. Pass the same include, library or package-discovery settings to that environment's build command. Do not change ownership of Homebrew or macOS directories to make a language package install succeed.