RubyGems "Failed to build gem native extension" (pg / libpq) in CI

The pg gem compiles a C extension against libpq, and the build failed because the PostgreSQL client library or pg_config is missing on the runner. The mkmf check for libpq fails before make even runs.

What this error means

bundle install fails building pg with "Can't find the PostgreSQL client library (libpq)" or "checking for pg_config... no", ending in a Gem::Ext::BuildError.

checking for pg_config... no
checking for libpq-fe.h... no
Can't find the PostgreSQL client library (libpq)
Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

Common causes

libpq development headers are not installed

The runner lacks libpq-dev (or postgresql client dev), so the pg extension cannot find libpq-fe.h.

pg_config is not on PATH

Without pg_config the build cannot locate the PostgreSQL client library to link against.

How to fix it

Install the PostgreSQL client dev package

1. Install libpq-dev so headers and pg_config are present.
2. Re-run bundle install to compile pg.
3. Confirm the database client is on PATH for runtime too.

sudo apt-get update
sudo apt-get install -y libpq-dev

Point the build at pg_config explicitly

If PostgreSQL is installed in a nonstandard prefix, tell the gem where pg_config lives.

bundle config set --local build.pg --with-pg-config=/usr/pgsql-16/bin/pg_config
bundle install

How to prevent it

• Install libpq-dev before bundle install when pg builds from source.
• Ensure pg_config is on PATH in the build step.
• Bake the PostgreSQL client into a custom runner image.

Related guides