调试启动Django站点时遭遇ImproperlyConfigured配置错误

问题重现 #

尝试以调试模式启动Django站点时触发ImproperlyConfigured错误，报错信息：

django.core.exceptions.ImproperlyConfigured: Requested settings, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

使用的manage.py代码如下：

#!/usr/bin/env python
"""Django's command-line utility for administrative tasks."""
import os
import sys


def main():
    """Run administrative tasks."""
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'webstore.settings')  # webstore is project name
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


if __name__ == '__main__':
    main()

解决步骤 #

• 确保虚拟环境已激活
  若使用虚拟环境，必须先激活再执行启动命令：

  • Linux/macOS：source venv/bin/activate
  • Windows：venv\Scripts\activate

• 验证settings模块路径正确性
  确认项目结构中webstore目录下存在settings.py，且该目录包含__init__.py文件（Django默认生成，若误删需重新创建空文件）。

• 启动时显式指定settings模块
  跳过环境变量依赖，直接在启动命令中指定：

  python manage.py runserver --settings=webstore.settings
  

• 将项目根目录加入PYTHONPATH
  若项目根目录不在Python的搜索路径中，Django无法找到webstore模块：

  • Linux/macOS终端临时设置：export PYTHONPATH=/path/to/your/project
  • Windows终端临时设置：set PYTHONPATH=C:\path\to\your\project
  • 或在manage.py开头添加代码永久生效：

    import os
    import sys
    sys.path.append(os.path.dirname(os.path.abspath(__file__)))
    

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