pg_config executable not found

技术背景

在使用 Python 连接 PostgreSQL 数据库时，通常会使用 psycopg2 这个库。而在安装 psycopg2 时，有时会遇到 pg_config executable not found 的错误。这是因为安装 psycopg2 时需要 pg_config 程序来确定 PostgreSQL 库的位置和版本信息等，若系统无法找到 pg_config 可执行文件，就会抛出该错误。

实现步骤

不同系统安装 pg_config 相关依赖

1. Debian/Ubuntu 系统：安装 libpq-dev 和 python-dev （Python2）或者 libpq-dev 和 python3-dev （Python3）。

   sudo apt-get install libpq-dev python-dev
   # 或者
   sudo apt-get install libpq-dev python3-dev

2. CentOS/Fedora 系统：安装 postgresql 和 postgresql-devel 以及 python-devel。

   sudo yum install postgresql postgresql-devel python-devel

3. Mac OS X 系统
   • 使用 homebrew 安装 postgresql。

     brew install postgresql

   • 若安装了 Postgres.app，需将其 bin 目录添加到 PATH 环境变量。

     export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

   • 若使用 zsh 终端（macOS Catalina 默认），可将上述 export 语句添加到 ~/.zshrc 文件中：

     echo 'export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"' >> ~/.zshrc
     source ~/.zshrc

4. Alpine 系统：安装 postgresql-dev。

   apk add postgresql-dev

5. Arch 系统：安装 postgresql-libs。

   sudo pacman -S postgresql-libs

添加 pg_config 到 PATH 环境变量

有些情况下，虽然安装了相关依赖，但 pg_config 所在目录并未在 PATH 环境变量中，需要手动添加。例如，PostgreSQL 9.5 安装在 CentOS 系统上：

export PATH=$PATH:/usr/pgsql-9.5/bin

安装 psycopg2

pip install psycopg2
# 或者安装预编译二进制版本（适用于开发和测试环境）
pip install psycopg2-binary

核心代码

安装预编译二进制版本的 psycopg2

python -m pip install psycopg2-binary

从源码安装 psycopg2

python -m pip install psycopg2

在脚本中指定 pg_config 路径

python setup.py build_ext --pg-config /usr/pgsql-9.1/bin/pg_config build

最佳实践

• 开发和测试环境：优先使用 psycopg2-binary 进行安装，它避免了编译过程，安装速度快。
• 生产环境：建议从源码安装 psycopg2，以确保性能和稳定性。此时需确保系统具备编译所需依赖。
• 使用虚拟环境：在开发 Python 项目时，使用虚拟环境（如 venv 或 virtualenv）可以隔离项目依赖，避免不同项目间出现依赖冲突。

常见问题

pg_config 仍找不到

• 确认 pg_config 确实已安装，可以使用 which pg_config 命令检查其路径。
• 确保 PATH 环境变量已正确设置，可以使用 echo $PATH 查看。

编译错误

• 缺少 C 编译器：安装相应系统的 C 编译器，如 gcc。
• 缺少 Python 头文件：安装 python-dev 或 python3-dev。
• 缺少 libpq 头文件：安装 libpq-dev 或 postgresql-devel。

Windows 系统问题

• 添加 PostgreSQL 的 bin 目录到系统的 PATH 环境变量。

set PATH=%PATH%;C:\Program Files\PostgreSQL\11\bin

• 注意 Python 版本与 psycopg2 版本的兼容性，避免已知问题。