Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

C compiler cannot find postgres.h when building a PostgreSQL extension

Errorfatal error: 'postgres.h' file not found

Short answer

postgres.h lives in the server header directory, which is not on the compiler's default include path. Ask pg_config --includedir-server where it is and pass that with -I, or better, build with a PGXS Makefile. If several PostgreSQL versions are installed, make sure the pg_config you call belongs to the one you target.

  • Applies to PostgreSQL 16, PostgreSQL 17, gcc, clang
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the server header directory for the PostgreSQL that pg_config belongs to, and check that postgres.h is really there.

    which pg_config
    ls "$(pg_config --includedir-server)/postgres.h"
  2. 2Match what you see, then jump to its fix

    1. 1pg_config prints a directory that holds postgres.h, but your own compile command failsThe server include directory is not passed to the compilerFix
    2. 2pg_config is not found, or its --includedir-server path does not existpg_config points at another PostgreSQL version or at noneFix

What does the error look like?

  • fatal error: 'postgres.h' file not found

Cause 1 of 2

The server include directory is not passed to the compiler

1Check

A plain cc command knows nothing about PostgreSQL. The server headers have their own directory, separate from the client headers that --includedir reports.

pg_config --includedir
pg_config --includedir-server

2Fix

Add the server directory with -I, or use a PGXS Makefile that does this for you. In your own source, include postgres.h first.

cc -fPIC -c -I"$(pg_config --includedir-server)" foo.c

# Makefile
MODULES = foo
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

3Verify

The file compiles; with the Makefile, make and make install finish.

make && sudo make install

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 2

pg_config points at another PostgreSQL version or at none

1Check

By default PGXS builds for the first pg_config found in PATH. With two versions installed, that may be the wrong one.

which -a pg_config
pg_config --version

2Fix

Point PG_CONFIG at the pg_config of the version you want, on the make command line. If that directory does not exist, the server headers are not present for that installation.

make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config

3Verify

The version printed by that pg_config matches the server you load the extension into.

/usr/lib/postgresql/17/bin/pg_config --version

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Build extensions through PGXS so the include and library paths always come from pg_config.
  • Write PG_CONFIG into your build script when more than one version is installed.
  • Include postgres.h before every other header in server-side C files.

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.