gem install pg fails because the libpq header files are missing
Can't find the 'libpq-fe.h headerShort 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.
Fix it fast
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 --includedir2Match what you see, then jump to its fix
- 1
which pg_config prints nothingThe libpq development package is not installedFix - 2
On macOS with Homebrew: libpq is installed, yet the build still cannot find the headerlibpq is installed but pg_config is not on PATHFix - 3
The gem was forced to build from source (platform ruby), or the lockfile lacks your platformA source build is not needed: use the precompiled gemFix
- 1
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-dev2Fix
Install it, then install the gem again.
sudo apt install libpq-dev
gem install pg3Verify
The gem builds and loads.
ruby -e 'require "pg"; puts :loaded'Confirmed by packages.debian.org
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 libpq2Fix
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
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.lock2Fix
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 install3Verify
Bundler installs pg without compiling.
bundle exec ruby -e 'require "pg"; puts :loaded'Confirmed by github.com
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
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
manage.py test stops with 'permission denied to create database' on PostgreSQL
django.db.utils.ProgrammingError: permission denied to create database
Django creates a separate database called test_ plus your database name, using the DATABASES USER.
2 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fix