PKG_CONFIG_PATH: Point pkg-config at Your .pc Files

PKG_CONFIG_PATH adds directories to pkg-config's search for .pc files; PKG_CONFIG_LIBDIR replaces the default set.

When a dependency is installed under a non-standard prefix (a custom build, /opt, or a sysroot), pkg-config will not find it until you point it there. These two environment variables are how you do it.

What it does

PKG_CONFIG_PATH prepends directories to the default .pc search path, so locally installed libraries are discoverable. PKG_CONFIG_LIBDIR replaces the default search path entirely, which is the correct tool for cross-compiling so only the sysroot's .pc files are seen. PKG_CONFIG_SYSROOT_DIR rewrites the prefixes inside found .pc files.

Common usage

Terminal

export PKG_CONFIG_PATH=/opt/mylib/lib/pkgconfig:$PKG_CONFIG_PATH
pkg-config --cflags mylib
# cross-compiling: see only the sysroot's .pc files
export PKG_CONFIG_LIBDIR=$SYSROOT/usr/lib/pkgconfig:$SYSROOT/usr/share/pkgconfig
export PKG_CONFIG_SYSROOT_DIR=$SYSROOT
pkg-config --debug --cflags mylib   # trace the search

Options

Variable	What it does
PKG_CONFIG_PATH	Extra directories to search (prepended)
PKG_CONFIG_LIBDIR	Replace the default search path entirely
PKG_CONFIG_SYSROOT_DIR	Prefix found paths with a sysroot
PKG_CONFIG_PATH_FOR_BUILD	Search path for build-machine tools (cross)
--debug	Trace which directories pkg-config searches

In CI

For a library you build in an earlier step, export PKG_CONFIG_PATH to its <prefix>/lib/pkgconfig before configuring the dependent build. For cross-compiles, set PKG_CONFIG_LIBDIR (not PATH) to the sysroot so the host's libraries are not picked up by mistake, and pair it with PKG_CONFIG_SYSROOT_DIR.

Common errors in CI

A library "not found" despite being installed under a custom prefix means PKG_CONFIG_PATH does not include its lib/pkgconfig directory. A cross build linking the host's libraries means you used PKG_CONFIG_PATH instead of PKG_CONFIG_LIBDIR. Wrong absolute paths in flags during a cross build mean PKG_CONFIG_SYSROOT_DIR is unset.