Why Error: pg_config executable not found Matters?
Getting hit with an error: pg_config executable not found during a pip install psycopg2 in CI? This common issue means the pg_config binary, required to compile PostgreSQL-related Python packages, is missing. In this guide, you’ll learn how to fix the pg_config executable not found error securely across local dev, Docker, and CI/CD environments.
What does the Error: pg_config executable not found Means?
The error message pg_config executable not found means Python’s build tools (like pip, setuptools, or build) can’t find the pg_config utility on your system. This binary is part of PostgreSQL development libraries and plays a crucial role during package compilation.
Specifically, pg_config tells compilers where to find PostgreSQL headers, libraries, and build flags, information required by popular Python packages with C extensions like psycopg2, pgvector, or timescaledb-python. When it’s missing, builds fail with messages like:
Building wheel for psycopg2 (setup.py) ... error
error: pg_config executable not found
This problem isn’t limited to one OS or environment; it appears in Docker containers, macOS, Linux, and even Windows setups without PostgreSQL’s dev tools installed.
Why It Happens (Across Different Environments)
The pg_config executable not found error typically occurs when PostgreSQL development tools are missing from your environment. This is especially common in minimal base setups where only the essentials are installed—omitting compilers, libraries, and build-time binaries.
| Environment | Why It Happens | Example Base Setup | Impact |
|---|---|---|---|
| Local Dev | PostgreSQL dev packages not installed | Minimal OS install or fresh VM | Install fails for Postgres-related Python packages |
| CI/CD | Build agent lacks dev tools | Default runner image with no extras | Pipeline fails before packaging |
| Docker | Slim images exclude build dependencies | python:X.Y-slim | Build stops during image creation |
| Cloud Build | Ephemeral runners drop extra packages | Managed build service | Repeated install failures |
Developer insight: Minimal images and fresh CI runners improve security but often exclude necessary build tools like pg_config. Your pipeline must account for this trade-off between minimalism and usability.
Diagnosing Error: pg_config executable not found Securely
Before installing anything, first check if pg_config is already available and functional:
# Locate pg_config in your PATH
which pg_config
# Show version if installed (confirms it's working)
pg_config --version
# Print current PATH to verify it includes expected binary directories
echo $PATH
If pg_config is not found or the version command fails, that confirms the issue.
Security Note:
- Always install pg_config via official system package managers: apt (Debian/Ubuntu), dnf/yum (RHEL/Fedora), or brew (macOS). These sources validate integrity and signatures.
- Never download precompiled binaries from unknown sources (e.g., random GitHub repos or pastebin links). These may be tampered with or include malicious payloads.
- Avoid “one-liner” install scripts unless you’ve audited their content and confirmed their origin.
Safe Diagnostic Checklist:
- Confirm binary origin and authenticity
- Check version matches project requirements
- Verify the PATH in CI/CD is not tampered with
Avoid exposing sensitive paths in logs.
Secure Fix Flow Diagram
The following diagram summarizes the secure process for resolving the error: pg_config executable not found, from initial detection to prevention:
"error: pg_config executable not found"
- Run
which pg_config - Run
pg_config --version - Check PATH in CI/CD
Yes → Continue | No → Exit
- Local:
apt-get install libpq-dev - Docker: use official base image + packages
- CI/CD: add package install step in pipeline
- Pin OS + Python package versions
- Use
--require-hashes - Scan dependencies with SCA tools
- Verified base images only
- Document dev dependencies
- Pre-check builds locally
- Enforce reproducible builds
- Integrate Xygeni for pipeline security
Secure Fixes for pg_config executable not found
1. Local Development
# Install PostgreSQL dev libraries on Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y libpq-dev
# Or on Fedora/RHEL
sudo dnf install postgresql-devel
Action = "*"
Effect = "Allow"
Resource = "*"
}
]
})
}
⚠️ Security Warning: Always install from official repositories (APT/YUM/Homebrew). Avoid downloading .deb or .rpm files from unofficial mirrors, personal blogs, or GitHub repos, as they could contain malicious binaries.
2. Docker Builds
# Use official slim Python base image
FROM python:X.Y-slim
# Install PostgreSQL dev libraries and compiler tools
RUN apt-get update \
&& apt-get install -y libpq-dev gcc \ # Required to compile psycopg2 and similar packages
&& rm -rf /var/lib/apt/lists/* # Clean up to reduce image size
⚠️ Security Warning: Always base your image on official Docker images like python:X.Y-slim to reduce the risk of compromised dependencies. Use multi-stage builds: install build tools in one stage, then copy only runtime dependencies to the final image. Never include compilers or unnecessary tools in production images to minimize the attack surface.
Security tip:
- Always start from official base images like python:X.Y-slim.
- Use multi-stage builds: install build tools in one stage, copy only the needed artifacts to the final image.
- Keep build and runtime environments separate, never ship compilers into production containers.
3. CI/CD Pipelines
yaml
steps:
- name: Install PostgreSQL dev libraries
run: |
sudo apt-get update
sudo apt-get install -y libpq-dev # Installs pg_config
- name: Install Python dependencies
run: pip install -r requirements.txt
⚠️ Security Warning: Ensure packages come from official repositories. Avoid using curl | bash style scripts from unverified sources. Run builds in ephemeral environments and pin OS versions to prevent persistent compromise or regressions.
Security tip:
- Run builds in ephemeral containers to avoid persistent compromise.
- Pin OS package versions to known-good releases.
- Avoid giving pipelines unnecessary root privileges.
4. Common Mistakes to Avoid
- Downloading precompiled pg_config binaries from random GitHub repos.
- Running curl | bash from unverified sources.
- Mixing system-installed and pip-installed PostgreSQL dependencies, causing version conflicts.
- Using outdated or unmaintained Docker images from unknown maintainers.
The AppSec Angle: Real Risks
The pg_config executable not found error might seem minor, but how you fix it can have serious security implications. A rushed install using unverified scripts or unofficial binaries can open the door to supply chain attacks.
For example, a “quick fix” shell script found on a forum might install pg_config, but it could also silently introduce a malicious payload or backdoor into your build environment. Attackers often exploit developer urgency and lack of verification to insert compromised components.
Key risks to watch for:
- Malicious install scripts that do more than they claim.
- Typosquatting, where fake packages mimic real ones (e.g., psycopg-connectorz instead of psycopg2).
- Dependency confusion, where CI/CD environments pull from public sources instead of internal registries.
Hardening Your Build Process
To make sure fixing pg_config executable not found doesn’t introduce new risks, your build process should follow secure engineering practices. Small adjustments like pinning versions and verifying sources can make a big difference in defending against supply chain threats.
Mini Security Checklist
- Pin OS and Python package versions to avoid unexpected updates.
- Use hash locking with pip install –require-hashes to ensure package integrity.
- Run SCA (Software Composition Analysis) scans in CI/CD to detect known vulnerabilities.
- Use only verified base images (e.g., official python: X.Y-slim) to reduce exposure to compromised containers.
These steps help ensure your environment stays secure and predictable, especially as dependencies evolve.
Preventing Future pg_config Errors
Fixing the issue once isn’t enough; you want to make sure it doesn’t come back the next time a teammate runs the build or you upgrade your CI image.
Recommendations to Prevent Recurrence
- Run pre-checks locally in a container that mirrors your CI/CD environment. This helps catch missing dependencies like pg_config before they break your pipeline.
- Document all development dependencies in README.md, pyproject. toml, or setup scripts. Clear docs prevent recurring errors, especially for new team members onboarding into the project.
- Enforce reproducible builds using Dockerfiles, lockfiles, and Infrastructure-as-Code. Reproducibility reduces surprises and makes debugging easier.
- Test clean builds regularly to ensure that no hidden dependencies exist on a developer’s local machine.
A consistent, documented, and testable build setup is the most reliable way to keep issues like pg_config executable not found from derailing future releases.
Integrating Xygeni for DevSecOps Safety Nets
Fixing pg_config executable not found can expose weaknesses in your pipeline. Xygeni helps identify and prevent insecure practices before they reach production by adding automated checks at key stages of the build process.
Detect Unsafe Build Steps
Xygeni analyzes changes to Dockerfiles, CI scripts, and setup files, detecting:
- Use of unverified installation sources (e.g., downloading binaries from unknown URLs).
- Inclusion of untrusted base images that may contain outdated or compromised components.
- Elevated permissions are used unnecessarily during builds.
Monitor Dependencies
Dependencies involved in the fix, like libpq-dev or psycopg2, are continuously monitored for:
- Known vulnerabilities (CVEs) in OS or Python packages.
- Unexpected changes in dependency hashes may indicate tampering.
- Signs of typosquatting or dependency confusion in package registries.
Block Risky Builds
Xygeni can enforce policies that stop builds when:
- Install scripts bypass official package managers.
- curl | bash commands are used without source verification.
- Docker images are used from unapproved sources.
By automating these controls, Xygeni ensures build-time fixes don’t silently introduce new risks, supporting secure, traceable, and policy-compliant pipelines.
Final Thoughts
The error: pg_config executable not found message is common, but how you handle it matters. Secure installations, verified sources, reproducible builds, and pipeline security controls turn a frustrating build failure into an opportunity to strengthen your DevSecOps posture.
