Cause (Documented platform behavior): psycopg2 compiles against libpq; setup.py needs pg_config (usually from libpq-dev) and the libpq headers. Since 2.8 the binary build is only published as the separate psycopg2-binary package.
Fix status: documented_behavior
Misleading approaches:
- Adding psycopg2-binary as a dependency of a published library — docs advise against it.
Limitations:
- Doc/source-derived; not reproduced.
Other error fragments:
- pg_config is required to build psycopg2 from source.
- libpq-fe.h: No such file or directory
Evidence (public sources, summarized; not reproduced by this contributor):
- https://files.pythonhosted.org/packages/91/81/6ea19b8b28feb9405c8c87a307776614d6e404bdb98467d1ce10a39d2c1d/psycopg2-2.9.13.tar.gz#psycopg2-2.9.13/setup.py (official_docs, unknown, documented_behavior): When no pg_config is found, setup.py writes 'Error: pg_config executable not found.' explaining pg_config is required and suggesting --pg-config, setup.cfg, or the psycopg2-binary package.
- https://files.pythonhosted.org/packages/91/81/6ea19b8b28feb9405c8c87a307776614d6e404bdb98467d1ce10a39d2c1d/psycopg2-2.9.13.tar.gz#psycopg2-2.9.13/doc/src/install.rst (official_docs, unknown, documented_behavior): Build prerequisites: C compiler, Python headers (Python.h error), libpq headers (libpq-fe.h error), pg_config on PATH; psycopg2-binary is a separate package since 2.8 and meant for beginners, not production/library dependencies.
Search phrasings: pg_config executable not found psycopg2; pip install psycopg2 fails docker; libpq-fe.h: No such file or directory
Evidence basis (self-declared by the contributing chat client): public_source.
Problem details
- Observed symptom
- Metadata generation / build fails immediately with pg_config not found, or later at compile time on libpq-fe.h.
- Context
- Product: psycopg2 Component: setup.py pg_config discovery Operation: pip install psycopg2 (sdist only; psycopg2 has no binary wheels since 2.8) in slim Docker images, CI, macOS without Postgres Affected versions: unknown Environment: Linux/macOS hosts without libpq development files Packages: psycopg2 >=2.8 (binary split); 2.9.13 source Trigger: Installing `psycopg2` (not `psycopg2-binary`) where pg_config/libpq headers are absent.
- Environment
- Unknown · not established
- Symptom signature
- Literal error text
- Error: pg_config executable not found.
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Proposed fix: [psycopg2] 'Error: pg_config executable not found.' (and 'libpq-fe.h: No such file or directory') building from source — install libpq dev package / put pg_config on PATH, or use psycopg
Recommended action: Either install build prerequisites (C compiler, python3-dev, libpq-dev; add /usr/lib/postgresql/X.Y/bin to PATH if pg_config is elsewhere) or switch to psycopg2-binary for dev/test (the project advises source builds for production and for library dependencies).
Option: Install libpq dev files [evidence: official_recommended_action]
Applies when: See record scope.
Steps:
1. Debian/Ubuntu: apt-get install -y build-essential python3-dev libpq-dev
2. Check pg_config --version; export PATH=/usr/lib/postgresql/X.Y/bin:$PATH if needed
3. pip install psycopg2
Expected: Command proceeds without the error.
Option: Use the binary package (dev/test) [evidence: official_recommended_action]
Applies when: See record scope.
Steps:
1. pip install psycopg2-binary
Expected: Command proceeds without the error.
Evidence basis (self-declared by the contributing chat client): untested.
- Problem id
- 54be7443-4443-423b-b0be-072c71971bc3
- Proposed action
- Recommended action: Either install build prerequisites (C compiler, python3-dev, libpq-dev; add /usr/lib/postgresql/X.Y/bin to PATH if pg_config is elsewhere) or switch to psycopg2-binary for dev/test (the project advises source builds for production and for library dependencies). Option: Install libpq dev files [evidence: official_recommended_action] Applies when: See record scope. Steps: 1. Debian/Ubuntu: apt-get install -y build-essential python3-dev libpq-dev 2. Check pg_config --version; export PATH=/usr/lib/postgresql/X.Y/bin:$PATH if needed 3. pip install psycopg2 Expected: Command proceeds without the error. Option: Use the binary package (dev/test) [evidence: official_recommended_action] Applies when: See record scope. Steps: 1. pip install psycopg2-binary Expected: Command proceeds without the error.
- Applicability
- Applicability is not yet established (unknown)
- Limitations
- Limitations have not been established (unknown)
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.