VS Code调试Django项目时出现psycopg模块加载配置错误

问题描述 #

我有一个Django 4.2.2项目，在VS Code终端里用python3 manage.py runserver启动一切正常，但用调试功能启动时就报错。

我的launch.json配置如下：

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger django",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/manage.py",
            "console": "integratedTerminal",
            "django": true,
            "args": [
                "runserver",
            ]
        }
    ]
}

启动调试后出现错误：

django.core.exceptions.ImproperlyConfigured: Error loading psycopg2 or psycopg module

我的requirements.txt里已经安装了psycopg相关包：

psycopg==3.2.4
psycopg-binary==3.2.4

错误在models.py的User模型定义处触发，完整错误栈如下：

Exception in thread django-main-thread:
Traceback (most recent call last):
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/backends/postgresql/base.py", line 25, in <module>
    import psycopg as Database
ModuleNotFoundError: No module named 'psycopg'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/backends/postgresql/base.py", line 27, 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 "/usr/lib/python3.10/threading.py", line 1016, in _bootstrap_inner
    self.run()
  File "/usr/lib/python3.10/threading.py", line 953, in run
    self._target(*self._args, **self._kwargs)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/utils/autoreload.py", line 64, in wrapper
    fn(*args, **kwargs)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/core/management/commands/runserver.py", line 126, in inner_run
    autoreload.raise_last_exception()
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/utils/autoreload.py", line 87, in raise_last_exception
    raise _exception[1]
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/core/management/__init__.py", line 394, in execute
    autoreload.check_errors(django.setup)()
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/utils/autoreload.py", line 64, in wrapper
    fn(*args, **kwargs)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/__init__.py", line 24, in setup
    apps.populate(settings.INSTALLED_APPS)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/apps/registry.py", line 116, in populate
    app_config.import_models()
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/apps/config.py", line 269, in import_models
    self.models_module = import_module(models_module_name)
  File "/usr/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/home/louis/zero/backend/ztm_app/models.py", line 3, in <module>
    class User(models.Model):
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/models/base.py", line 143, in __new__
    new_class.add_to_class("_meta", Options(meta, app_label))
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/models/base.py", line 371, in add_to_class
    value.contribute_to_class(cls, name)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/models/options.py", line 231, in contribute_to_class
    self.db_table, connection.ops.max_name_length()
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/utils/connection.py", line 15, in __getattr__
    return getattr(self._connections[self._alias], item)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/utils/connection.py", line 62, in __getitem__
    conn = self.create_connection(alias)
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/utils.py", line 193, in create_connection
    backend = load_backend(db["ENGINE"])
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/utils.py", line 113, in load_backend
    return import_module("%s.base" % backend_name)
  File "/usr/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/home/louis/zero/backend/venv/lib/python3.10/site-packages/django/db/backends/postgresql/base.py", line 29, in <module>
    raise ImproperlyConfigured("Error loading psycopg2 or psycopg module")
django.core.exceptions.ImproperlyConfigured: Error loading psycopg2 or psycopg module

问题分析与解决方案 #

这个问题的核心是VS Code调试器没有使用你项目的虚拟环境——虽然终端启动时自动激活了虚拟环境能找到psycopg包，但调试器可能默认调用了全局Python解释器或其他不匹配的环境。以下是分步解决方法：

1. 手动指定VS Code使用的Python解释器 #

• 点击VS Code左下角状态栏的Python版本标识（比如3.10.x）
• 在弹出的列表中，选择你项目虚拟环境的Python路径，比如/home/louis/zero/backend/venv/bin/python
• 重新启动调试功能

2. 直接在launch.json中指定虚拟环境路径 #

如果自动选择环境不生效，可以在调试配置里硬编码虚拟环境的Python路径：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger django",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/manage.py",
            "console": "integratedTerminal",
            "django": true,
            "args": [
                "runserver"
            ],
            "python": "/home/louis/zero/backend/venv/bin/python" // 替换为你的虚拟环境Python路径
        }
    ]
}

3. 重新安装依赖包（排除缓存问题） #

有时候虚拟环境的依赖可能存在缓存异常，激活环境后重新安装：

source /home/louis/zero/backend/venv/bin/activate
pip install -r requirements.txt --force-reinstall

4. 确认DATABASE引擎配置正确性 #

确保settings.py中的数据库引擎是Django 4.2+支持的官方值（适配psycopg3）：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        # 其余数据库配置（NAME, USER, PASSWORD等）
    }
}

一般来说，前两步即可解决问题，这也是这类调试环境依赖问题最常见的修复方式。

备注：内容来源于stack exchange，提问作者El Pandario