Django+PostgreSQL配置报错：已装psycopg2仍提示找不到

问题详情 #

首次使用Django（有PostgreSQL使用经验），按官方教程完成数据库配置后，执行python manage.py migrate报错，提示找不到psycopg2模块，但已确认该模块已安装。

错误回溯 #

installed.Traceback (most recent call last):
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/backends/postgresql/base.py", line 24, in <module>
    import psycopg2 as Database
ModuleNotFoundError: No module named 'psycopg2'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/alexanderverheecke/Documents/GitHub/mysite/manage.py", line 22, in <module>
    main()
  File "/Users/alexanderverheecke/Documents/GitHub/mysite/manage.py", line 18, in main
    execute_from_command_line(sys.argv)
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/core/management/__init__.py", line 446, in execute_from_command_line
    utility.execute()
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/core/management/__init__.py", line 420, in execute
    django.setup()
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/__init__.py", line 24, in setup
    apps.populate(settings.INSTALLED_APPS)
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/apps/registry.py", line 116, in populate
    app_config.import_models()
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/apps/config.py", line 269, in import_models
    self.models_module = import_module(models_module_name)
  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 850, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/contrib/auth/models.py", line 3, in <module>
    from django.contrib.auth.base_user import AbstractBaseUser, BaseUserManager
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/contrib/auth/base_user.py", line 49, in <module>
    class AbstractBaseUser(models.Model):
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/models/base.py", line 141, in __new__
    new_class.add_to_class("_meta", Options(meta, app_label))
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/models/base.py", line 369, in add_to_class
    value.contribute_to_class(cls, name)
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/models/options.py", line 231, in contribute_to_class
    self.db_table, connection.ops.max_name_length()
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/utils/connection.py", line 15, in __getattr__
    return getattr(self._connections[self._alias], item)
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/utils/connection.py", line 62, in __getitem__
    conn = self.create_connection(alias)
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/utils.py", line 193, in create_connection
    backend = load_backend(db["ENGINE"])
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/utils.py", line 113, in load_backend
    return import_module("%s.base" % backend_name)
  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "/Users/alexanderverheecke/Library/Python/3.9/lib/python/site-packages/django/db/backends/postgresql/base.py", line 28, in <module>
    raise ImproperlyConfigured("Error loading psycopg2 module: %s" % e)
django.core.exceptions.ImproperlyConfigured: Error loading psycopg2 module: No module named 'psycopg2'

数据库配置 #

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'DatabaseName',
        'USER': 'UserName',
        'PASSWORD': 'Userpassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

已安装包信息 #

pip freeze:

Django==4.1.3
psycopg2==2.9.5
psycopg2-binary==2.9.5

pip show Django/psycopg2/psycopg2-binary:

Django : Location: /opt/homebrew/lib/python3.10/site-packages
Psycopg2: Location: /opt/homebrew/lib/python3.10/site-packages
psycopg2-binary: Location: /opt/homebrew/lib/python3.10/site-packages

问题原因 #

从错误日志和包安装路径可以看出：

• 运行manage.py的是Python 3.9（错误路径中显示Python3.9）
• 但你安装的Django、psycopg2都在Python 3.10的site-packages目录下
  两个版本的Python环境不统一，导致运行时找不到对应模块。

解决方案 #

1. 统一Python版本 #

• 先确认当前终端使用的Python版本：

  python --version
  python3 --version
  

• 找到对应Python 3.10的命令（通常是python3），用该版本的pip重新安装依赖：

  python3 -m pip install django psycopg2-binary
  

• 使用对应版本的Python执行迁移命令：

  python3 manage.py migrate
  

2. 推荐：使用虚拟环境隔离依赖 #

虚拟环境可以避免不同项目或Python版本之间的依赖冲突，步骤如下：

• 创建虚拟环境（基于Python 3.10）：

  python3 -m venv myenv
  

• 激活虚拟环境：
  • macOS/Linux：

    source myenv/bin/activate
    

  • Windows：

    myenv\Scripts\activate
    

• 激活后安装依赖：

  pip install django psycopg2-binary
  

• 执行迁移命令：

  python manage.py migrate
  

内容的提问来源于stack exchange，提问作者Alexander Veheecke