安装psycopg2-binary构建wheel失败，提示找不到io.h文件

问题描述 #

安装psycopg2-binary（版本2.9.10）时出现构建wheel失败，执行python setup.py bdist_wheel退出码为1，核心错误为：C:\Program Files\Python313\include\pyconfig.h(59)处发生致命错误C1083，无法打开包含文件'io.h'。完整错误日志如下：

使用缓存的psycopg2-binary-2.9.10.tar.gz (385 kB)
  准备元数据(setup.py)...完成
为收集到的包构建wheels: psycopg2-binary
  为psycopg2-binary构建wheel(setup.py)...错误
  error: subprocess-exited-with-error
  
  × python setup.py bdist_wheel运行失败。
  │ 退出码: 1
  ╰─> [32行输出]
      running bdist_wheel
      running build
      running build_py
      创建build\lib.win-amd64-cpython-313\psycopg2
      复制lib\errorcodes.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\errors.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\extensions.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\extras.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\pool.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\sql.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\tz.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\_ipaddress.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\_json.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\_range.py -> build\lib.win-amd64-cpython-313\psycopg2
      复制lib\__init__.py -> build\lib.win-amd64-cpython-313\psycopg2
      running build_ext
      构建'psycopg2._psycopg'扩展
      创建build\temp.win-amd64-cpython-313\Release\psycopg
      "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.42.34433\bin\HostX86\x64\cl.exe" /c /nologo /O2 /W3 /GL /DNDEBUG /MD "-DPSYCOPG_VERSION=2.9.10 (dt dec pq3 ext lo64)" -DPSYCOPG_DEBUG=1 -DPG_VERSION_NUM=170002 -DHAVE_LO64=1 -DPSYCOPG_DEBUG=1 -IC:\Users\hello\memesite\myenv\include "-IC:\Program Files\Python313\include" "-IC:\Program Files\Python313\Include" -I. -IC:/PROGRA~1/POSTGR~1/17/include -IC:/PROGRA~1/POSTGR~1/17/include/server "-IC:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.42.34433\include" "-IC:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\VS\include" /Tcpsycopg\adapter_asis.c /Fobuild\temp.win-amd64-cpython-313\Release\psycopg\adapter_asis.obj
      adapter_asis.c
      C:\Program Files\Python313\include\pyconfig.h(59): 致命错误C1083: 无法打开包含文件: 'io.h': 系统找不到指定文件

      看起来您缺少从源代码构建包的某些先决条件。

      您可以通过从PyPI安装'psycopg2-binary'来安装二进制包。
      如果您想从源代码安装psycopg2，请安装构建所需的包并重试。

      更多信息请查看'doc/src/install.rst'文件(也可访问<https://www.psycopg.org/docs/install.html>)。

      error: 命令'C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\VC\\Tools\\MSVC\\14.42.34433\\bin\\HostX86\\x64\\cl.exe'以退出码2失败
      [输出结束]

  note: 此错误源自子进程，可能与pip无关。
  ERROR: Failed building wheel for psycopg2-binary
  为psycopg2-binary运行setup.py clean
构建psycopg2-binary失败
ERROR: ERROR: 无法为部分基于pyproject.toml的项目(psycopg2-binary)构建可安装的wheels

解决方案 #

• 补全Windows SDK组件：打开Visual Studio Installer，找到已安装的"Visual Studio Build Tools 2022"，点击「修改」，进入「单个组件」页面，勾选对应系统版本的Windows SDK（如Windows 11 SDK），确保选中「Windows SDK头文件和库」相关组件，完成安装后重试。

• 降级Python版本：Python 3.13属于较新版本，psycopg2-binary 2.9.10对其兼容性不足。降级到Python 3.12及以下版本后，执行pip install psycopg2-binary==2.9.10，此时会自动使用预编译wheel，无需源码构建。

• 手动安装预编译wheel：若坚持使用Python 3.13，可直接下载对应平台的预编译wheel文件（如psycopg2_binary-2.9.10-cp313-cp313-win_amd64.whl），然后执行pip install 下载的文件名.whl，跳过源码构建步骤。

• 使用正确的命令行环境：打开「x64 Native Tools Command Prompt for VS 2022」，在该环境下执行pip安装命令，确保构建工具能正确识别所有系统头文件路径。

内容的提问来源于stack exchange，提问作者Ojas Mutreja