本地运行Heroku部署的Django+PostgreSQL应用时psycopg2模块异常

问题重现 #

本地运行python manage.py runserver时触发以下报错：

File "C:\*userdirectory*\djangenv\Lib\site-packages\django\db\backends\postgresql\base.py", line 24, in <module>
import psycopg2 as Database
File "C:\*userdirectory*\djangenv\Lib\site-packages\psycopg2\__init__.py", line 51, in 
<module> from psycopg2._psycopg import ( # noqa 
ImportError: DLL load failed while importing _psycopg: The specified module could not be found.

项目在Heroku上运行正常，本地已尝试多种psycopg2安装方式仍未解决。

一、psycopg2 DLL问题的修复步骤 #

• 安装对应版本的Visual C++ Redistributable：
  Windows环境下psycopg2的预编译包依赖微软VC++运行库，根据你的Python版本选择对应包：
  • Python 3.8-3.11 → VC++ 2019 Redistributable
  • Python 3.12+ → VC++ 2022 Redistributable
    安装后重启系统，再重新安装psycopg2。
• 强制匹配Python与psycopg2的位数：
  先确认Python位数：

  python -c "import sys; print('64位' if sys.maxsize > 2**32 else '32位')"
  

  卸载现有psycopg2包：

  pip uninstall -y psycopg2 psycopg2-binary
  

  重新安装对应位数的版本（若用conda可指定conda install psycopg2 -c conda-forge）。
• 切换到psycopg2-binary：
  执行以下命令安装预编译的二进制包，避免本地编译依赖：

  pip install psycopg2-binary
  

• 验证虚拟环境路径：
  激活虚拟环境后，确认当前Python路径：

  # Windows
  where python
  # Linux/macOS
  which python
  

  确保安装psycopg2时使用的是该路径下的pip，避免包安装到全局环境。
• 调整Python版本：
  若使用Python 3.12+，psycopg2 2.9.x及以下版本存在兼容性问题，可：
  • 降级Python到3.11
  • 升级psycopg2到最新稳定版：pip install --upgrade psycopg2-binary

二、替代后端适配器推荐 #

• psycopg3（psycopg[binary]）：
  这是psycopg的下一代版本，Django 4.2+官方支持，安装命令：

  pip install psycopg[binary]
  

  无需额外编译依赖，Windows环境下几乎不会出现DLL问题，API与psycopg2兼容，直接修改requirements.txt即可替换。
• django-postgrespool：
  基于psycopg2的连接池适配器，适合高并发场景，安装后修改数据库配置：

  DATABASES = {
      'default': {
          'ENGINE': 'django_postgrespool.backends.postgresql',
          # 其余数据库配置不变
      }
  }
  

内容的提问来源于stack exchange，提问作者Justin Romprey