Rust "could not find system library" via pkg-config in CI

A -sys crate’s build script used pkg-config to locate a system library and found nothing. The library’s development package (with its .pc file and headers) isn’t installed, or pkg-config itself is missing.

What this error means

A build pulling in a -sys crate fails in the build script with could not find system library X required by the X-sys crate, listing the pkg-config probe it ran. The Rust toolchain is fine - only the OS library is absent.

cargo output

error: failed to run custom build command for `libgit2-sys v0.16.2`

  --- stderr
  pkg-config exited with status code 1
  > PKG_CONFIG_PATH=... pkg-config --libs --cflags libgit2

  The system library `libgit2` required by crate `libgit2-sys` was not found.

Common causes

The library’s -dev package is missing

pkg-config locates a library via its .pc file, which ships in the -dev/-devel package. Without it (e.g. libgit2-dev), the probe returns nothing.

pkg-config not installed or wrong PKG_CONFIG_PATH

If pkg-config itself is absent, or the library lives in a prefix not on PKG_CONFIG_PATH, the build script can’t discover it.

How to fix it

Install pkg-config and the -dev package

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y pkg-config libgit2-dev
# Alpine
apk add --no-cache pkgconf libgit2-dev

Point pkg-config at a non-standard prefix

When the library is installed in an unusual location, tell pkg-config where its .pc files are.