Windows虚拟环境执行pip install psycopg2-binary报错求助

错误详情 #

执行pip install psycopg2-binary时出现如下错误：

Collecting psycopg2-binary
  Downloading psycopg2-binary-2.9.10.tar.gz (385 kB)
  Preparing metadata (setup.py) ... error
  error: subprocess-exited-with-error

  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [23 lines of output]
      running egg_info
      creating C:\Users\Nafees Ahmad\AppData\Local\Temp\pip-pip-egg-info-fbk58flv\psycopg2_binary.egg-info
      writing C:\Users\Nafees Ahmad\AppData\Local\Temp\pip-pip-egg-info-fbk58flv\psycopg2_binary.egg-info\PKG-INFO
      writing dependency_links to C:\Users\Nafees Ahmad\AppData\Local\Temp\pip-pip-egg-info-fbk58flv\psycopg2_binary.egg-info\dependency_links.txt
      writing top-level names to C:\Users\Nafees Ahmad\AppData\Local\Temp\pip-pip-egg-info-fbk58flv\psycopg2_binary.egg-info\top_level.txt
      writing manifest file 'C:\Users\Nafees Ahmad\AppData\Local\Temp\pip-pip-egg-info-fbk58flv\psycopg2_binary.egg-info\SOURCES.txt'

      Error: pg_config executable not found.

      pg_config is required to build psycopg2 from source.  Please add the directory
      containing pg_config to the $PATH or specify the full executable path with the
      option:

          python setup.py build_ext --pg-config /path/to/pg_config build ...

      or with the pg_config option in 'setup.cfg'.

      If you prefer to avoid building psycopg2 from source, please install the PyPI
      'psycopg2-binary' package instead.

      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

问题原因 #

尽管你安装的是预编译版本的psycopg2-binary，但Windows环境下pip未找到匹配的预编译wheel包，自动转而尝试源码编译；而源码编译依赖PostgreSQL的pg_config工具，你的环境中缺少该工具或其路径未加入系统PATH。

解决方案 #

1. 升级pip到最新版本 #

旧版pip可能不会优先选择预编译wheel包，先执行升级：

python -m pip install --upgrade pip

升级完成后重新执行pip install psycopg2-binary。

2. 强制下载预编译包 #

通过参数强制pip只获取预编译wheel包，跳过源码编译流程：

pip install psycopg2-binary --only-binary :all:

3. 添加pg_config到系统PATH（适配源码编译场景） #

如果上述方法无效，可安装PostgreSQL客户端并配置环境变量：

• 下载安装PostgreSQL客户端（无需完整数据库服务）
• 找到安装目录下的bin文件夹，例如C:\Program Files\PostgreSQL\16\bin
• 将该路径添加到系统环境变量PATH中
• 重启CMD和虚拟环境后，再次执行安装命令

4. 改用psycopg（psycopg3） #

psycopg是psycopg2的下一代版本，安装无需依赖pg_config，兼容性更好：

pip install psycopg

内容的提问来源于stack exchange，提问作者Namaan Rana