Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

gem install pg fails because the libpq header files are missing

ErrorCan't find the 'libpq-fe.h header

Short answer

The pg gem is building from source and cannot find libpq-fe.h, the libpq C header. Install your system's libpq development package, tell the build where pg_config lives with --with-pg-config, or install the precompiled platform gem, which bundles libpq and needs no headers.

  • Applies to pg gem 1.5 and 1.6, Ruby 3.3, Ubuntu 24.04, macOS 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether pg_config exists and where it says the headers are. If the command is missing, there is no libpq development package on this machine, or it is not on PATH.

    which pg_config
    pg_config --includedir
  2. 2Match what you see, then jump to its fix

    1. 1which pg_config prints nothingThe libpq development package is not installedFix
    2. 2On macOS with Homebrew: libpq is installed, yet the build still cannot find the headerlibpq is installed but pg_config is not on PATHFix
    3. 3The gem was forced to build from source (platform ruby), or the lockfile lacks your platformA source build is not needed: use the precompiled gemFix

What does the error look like?

  • Can't find the 'libpq-fe.h header

Cause 1 of 3

The libpq development package is not installed

1Check

Compiling the source gem needs libpq with headers. On Debian and Ubuntu the package that holds the headers for compiling C programs is libpq-dev.

apt-cache policy libpq-dev

2Fix

Install it, then install the gem again.

sudo apt install libpq-dev
gem install pg

3Verify

The gem builds and loads.

ruby -e 'require "pg"; puts :loaded'

Confirmed by packages.debian.org

Did this fix it?

Cause 2 of 3

libpq is installed but pg_config is not on PATH

1Check

Homebrew lists libpq as keg-only, so it is not linked into the default prefix and pg_config is not found by name. The gem's README says to pass the path when pg_config is not on PATH.

brew info libpq

2Fix

Install libpq if needed, then give the gem the full path to pg_config. For Bundler, set the same flag once.

brew install libpq
gem install pg -- --with-pg-config=<path to pg_config>
# with Bundler
bundle config build.pg --with-pg-config=<path to pg_config>

3Verify

Install through Bundler and load the gem.

bundle install
bundle exec ruby -e 'require "pg"; puts :loaded'

Confirmed by github.com

Did this fix it?

Cause 3 of 3

A source build is not needed: use the precompiled gem

1Check

By default gem install pg installs a binary gem for the running platform, and binary gems bundle libpq. A source build happens when the platform ruby gem is chosen, for example by force_ruby_platform in the Gemfile or a lockfile without your platform.

grep -n "force_ruby_platform" Gemfile
grep -A4 PLATFORMS Gemfile.lock

2Fix

Remove the forced source build and add your platform to the lockfile so Bundler picks the binary gem. On Alpine, the x86_64-linux and aarch64-linux gems also need the gcompat package.

bundle lock --add-platform x86_64-linux
bundle lock --add-platform arm64-darwin
bundle install

3Verify

Bundler installs pg without compiling.

bundle exec ruby -e 'require "pg"; puts :loaded'

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • In Dockerfiles that must compile the gem, install the libpq development package before bundle install.
  • Commit a lockfile that lists every platform you deploy to.
  • Check pg_config --includedir in CI images so a missing package fails early.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.