Gunicorn 启动 Django 项目提示 ModuleNotFoundError 怎么办？

Gunicorn 启动 Django 报错 ModuleNotFoundError，绝大多数情况是因为 Gunicorn 运行的 Python 环境里没有安装 Django，或者虚拟环境未激活。最稳妥的办法是进入项目虚拟环境，确认依赖安装完整后再启动。

先说结论：核心是环境不一致，Gunicorn 调用的 Python 解释器找不到 Django 包。

先确认：当前 shell 是否已激活项目虚拟环境，且 pip 与 python 版本对应。
先处理：在激活的环境中重新安装 Django 和 Gunicorn，避免全局环境与虚拟环境混用。
再验证：使用 python -c 命令确认模块可导入，再启动 Gunicorn 观察日志。

快速修复命令

# 1. 激活虚拟环境 (Linux/Mac)
source venv/bin/activate
# 2. 激活虚拟环境 (Windows)
venv\Scripts\activate

# 3. 安装依赖
pip install django gunicorn
# 或从文件安装
pip install -r requirements.txt

# 4. 冻结依赖 (建议定期执行)
pip freeze > requirements.txt

# 5. 启动服务 (替换 project_name 为实际项目包名)
gunicorn `--bind` 127.0.0.1:8000 project_name.wsgi:application

核心原因分析

Python 的模块导入机制依赖于 sys.path 路径列表。Gunicorn 启动时会加载当前环境的 Python 解释器，如果该解释器的 site-packages 中没有 Django，就会报 ModuleNotFoundError。常见情况是你在全局环境安装了 Django，但 Gunicorn 运行在虚拟环境中；或者虚拟环境未激活，导致 pip 安装包到了全局，而 Gunicorn 却在虚拟环境里找。

此外，Gunicorn 依赖 Unix 特有模块（如 pwd），在 Windows 上直接运行可能会遇到兼容性错误，导致模块加载失败。

详细排查步骤

第一步：检查虚拟环境状态

在终端输入 which python (Linux/Mac) 或 where python (Windows)，确认显示的路径是否包含虚拟环境目录（如 venv）。如果指向系统目录（如 /usr/bin/python），说明环境未激活。

第二步：确认依赖安装

Gunicorn 启动 Django 项目提示 ModuleNotFoundError 怎么办？

激活环境后，运行 pip list | grep django 查看是否已安装。如果没有，执行 pip install django gunicorn。建议使用 requirements.txt 统一管理依赖，避免遗漏。

第三步：环境变量路径调试

如果依赖已安装但仍报错，可能是 Python 无法找到项目模块。尝试显式设置 PYTHONPATH：

# Linux/Mac
export PYTHONPATH=$(pwd):$PYTHONPATH
# Windows (PowerShell)
$env:PYTHONPATH = ".;$env:PYTHONPATH"

设置后再次尝试启动 Gunicorn。

第四步：核对 WSGI 模块路径

Gunicorn 启动命令末尾需要指定 WSGI 入口，格式为项目包名.wsgi:application。确保项目包名与目录结构一致，且该目录下存在 wsgi.py 文件。如果项目结构变动，需同步修改 manage.py 中的 DJANGO_SETTINGS_MODULE 环境变量。

第五步：Windows 用户特别注意

如果在 Windows 上遇到 pwd 模块缺失或 socket.AF_UNIX 属性错误，说明 Gunicorn 不兼容当前系统。建议转用 Unix 环境部署，或在 Windows 开发时使用 Django 自带服务器 runserver，生产环境使用 WSL 或 Docker。

验证与日志分析

1. 模块导入测试

在激活的虚拟环境中运行 python -c "import django; print(django.__version__)"，若能输出版本号则说明 Django 已就绪。

2. 典型错误日志对照

启动 Gunicorn 后，观察终端输出。若出现以下错误，说明环境确实缺失模块：

ModuleNotFoundError: No module named 'django'
Traceback (most recent call last):
  File ".../site-packages/gunicorn/util.py", line ..., in import_app
    __import__(app)
ModuleNotFoundError: No module named 'django'

若出现 Starting gunicorn 字样且无 ImportError traceback，说明启动成功。若有错误，检查 errorlog 配置路径或终端输出。

常见坑与注意事项

1. 文件名冲突

项目中不要创建名为 gunicorn.py 的文件，这会干扰 Python 导入机制，导致系统找不到真正的 gunicorn 包。若已创建，请重命名该文件。

2. 路径优先级问题

某些 IDE（如 PyCharm）运行时可能未正确继承 sys.path，导致依赖环境路径排在项目路径之后。确保 IDE 配置的解释器与终端一致，必要时调整路径优先级。

3. 版本兼容性

Gunicorn 新版本支持 Python 3.7 及以上，旧版本可能不支持新特性。确保 Python 版本与 Gunicorn 版本匹配，避免语法错误导致加载失败。