运行pytest触发Django ImproperlyConfigured报错如何永久解决

django.core.exceptions.ImproperlyConfigured报错的核心触发原因是运行Django相关代码时，进程未读取到DJANGO_SETTINGS_MODULE环境变量，手动执行export命令仅对当前终端会话生效，终端关闭后配置自动失效，以下是不同场景下的永久修复方案：

• 方案1：虚拟环境级配置（本地开发最推荐） #

  用venv/virtualenv等虚拟环境做开发时，可以把环境变量写入虚拟环境激活脚本，每次激活虚拟环境时自动加载配置，不会和其他Django项目产生冲突：

  • Linux/macOS：打开虚拟环境目录下的bin/activate文件，在末尾追加一行：

    export DJANGO_SETTINGS_MODULE=<你的项目名>.settings
    

  • Windows cmd环境：打开虚拟环境目录下的Scripts/activate.bat文件，在末尾追加一行：

    set DJANGO_SETTINGS_MODULE=<你的项目名>.settings
    

  • Windows PowerShell环境：打开虚拟环境目录下的Scripts/Activate.ps1文件，在末尾追加一行：

    $env:DJANGO_SETTINGS_MODULE = "<你的项目名>.settings"
    

  修改完成后重新激活虚拟环境即可永久生效。

• 方案2：测试框架/代码层面配置（不依赖环境变量） #

  运行测试时报错可以直接在测试配置里指定settings路径，不需要修改全局环境：

  • 用pytest + pytest-django跑测试：在项目根目录新建pytest.ini文件，写入以下配置：

    [pytest]
    DJANGO_SETTINGS_MODULE = <你的项目名>.settings
    python_files = test_*.py *_tests.py tests.py
    

  • 运行自定义独立测试脚本：在脚本最顶部，导入任何Django相关模块之前加入以下代码：

    import os
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "<你的项目名>.settings")
    import django
    django.setup()
    

  注意：正常通过python manage.py test运行Django自带测试时，manage.py本身已经内置了环境变量设置逻辑，如果这种场景下仍报错，优先检查manage.py中的os.environ.setdefault行是否被误修改、项目名拼写是否和实际目录一致。

• 方案3：用户全局环境变量配置（多项目场景不推荐） #

  如果当前机器只开发这一个Django项目，可以把环境变量配置到用户全局配置中，所有新打开的终端都会自动加载：

  • Linux/macOS：根据使用的shell，把export DJANGO_SETTINGS_MODULE=<你的项目名>.settings追加到~/.bashrc（bash用户）或~/.zshrc（zsh用户）文件末尾，执行source ~/.bashrc或source ~/.zshrc即可立即生效。
  • Windows：打开系统环境变量设置面板，新建一个用户变量，变量名填DJANGO_SETTINGS_MODULE，变量值填<你的项目名>.settings，保存后重启终端生效。
    该方案的缺陷是多Django项目共存时，全局变量会固定指向某一个项目的配置，容易导致其他项目加载错误配置，非单项目开发场景不要使用。

注意：所有配置里的<你的项目名>要替换成实际的Django项目包名，也就是包含settings.py文件的目录名称，路径拼写错误会触发模块找不到的衍生报错。

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