Windows安装psycopg2报错：UnicodeDecodeError与元数据生成失败

错误信息 #

执行pip install psycopg2时出现以下错误：

Collecting psycopg2
  Using cached psycopg2-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
  ╰─> [78 lines of output]
  ...
  UnicodeDecodeError: 'utf-8' codec can't decode byte 0xed in position 0: invalid continuation byte
  [end of output]

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

已尝试的解决步骤 #

• 安装psycopg2二进制版本，仍出现相同错误
• 更新Microsoft Visual Studio构建工具至最新版本
• 重新安装PostgreSQL，确保pg_config配置正确
• 检查Python和PostgreSQL的Path环境变量

pg_config输出 #

BINDIR = C:/PROGRA~1/POSTGR~1/16/bin
DOCDIR = C:/PROGRA~1/POSTGR~1/16/doc
HTMLDIR = C:/PROGRA~1/POSTGR~1/16/doc
INCLUDEDIR = C:/PROGRA~1/POSTGR~1/16/include
PKGINCLUDEDIR = C:/PROGRA~1/POSTGR~1/16/include
INCLUDEDIR-SERVER = C:/PROGRA~1/POSTGR~1/16/include/server
LIBDIR = C:/PROGRA~1/POSTGR~1/16/lib
PKGLIBDIR = C:/PROGRA~1/POSTGR~1/16/lib
LOCALEDIR = C:/PROGRA~1/POSTGR~1/16/share/locale
MANDIR = C:/Program Files/PostgreSQL/16/man
SHAREDIR = C:/PROGRA~1/POSTGR~1/16/share
SYSCONFDIR = C:/Program Files/PostgreSQL/16/etc
PGXS = C:/Program Files/PostgreSQL/16/lib/pgxs/src/makefiles/pgxs.mk
CONFIGURE = --enable-thread-safety --enable-nls --with-ldap --with-ssl=openssl --with-uuid --with-libxml --with-libxslt --with-lz4 --with-zstd --with-icu --with-tcl --with-perl --with-python
CC = не записано
CPPFLAGS = не записано
CFLAGS = не записано
CFLAGS_SL = не записано
LDFLAGS = не записано
LDFLAGS_EX = не записано
LDFLAGS_SL = не записано
LIBS = не записано
VERSION = PostgreSQL 16.4

额外细节 #

• 错误根源是pg_config输出中的非UTF-8字符（如俄文“не записано”，意为“未填写”）导致UnicodeDecodeError
• 环境：Python 3.13、PostgreSQL 16、Windows 10

问题求助 #

• 如何修复UnicodeDecodeError，成功在Windows上安装psycopg2？
• 如何确保pg_config的输出能被psycopg2安装程序正确解析？

解决方案 #

方法1：设置Python编码环境变量 #

在命令行中执行以下命令，强制Python使用UTF-8编码处理输出：

set PYTHONUTF8=1
set PYTHONIOENCODING=utf-8

然后安装psycopg2二进制版本：

pip install psycopg2-binary --upgrade

方法2：替换pg_config输出中的俄文内容 #

由于pg_config输出的俄文“не записано”无法被UTF-8正确解码，可创建一个包装脚本替换原有pg_config的输出：

1. 在任意目录创建pg_config_wrapper.bat，内容如下：

@echo off
"%PROGRAMFILES%\PostgreSQL\16\bin\pg_config.exe" %* | powershell -Command "$input -replace 'не записано', 'not set'"

2. 将该脚本所在目录添加到系统PATH的最前端（确保pip优先调用这个脚本）
3. 重新打开命令行，执行安装命令：

pip install psycopg2-binary

方法3：修改PostgreSQL的配置语言 #

重新安装PostgreSQL时，选择英文作为安装语言，这样pg_config的输出会使用英文“not set”代替俄文，从根源避免编码问题。

内容的提问来源于stack exchange，提问作者Lapin Mikhail