如何解决pip安装报错ModuleNotFoundError: No module named ‘django’问题

【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named ‘django’问题
摘要

在日常 Django 项目开发中，最常见的“拦路虎”之一就是 ModuleNotFoundError: No module named 'django'。该异常通常在以下场景出现：

1. 在 PyCharm 2025 中新建项目后，直接在 PyCharm 自带控制台 / Terminal 里执行 python manage.py migrate。
2. 在 macOS 14+ 上使用 Homebrew 安装的 Python 3.12，但 PyCharm 默认解释器却指向了 系统自带 Python 3.9。
3. 多人协作时，同事把 requirements.txt 更新到 Django 5.x，而你本地仍停留在 4.x 分支，导致虚拟环境与全局环境混用，出现“装了却找不到”的假象。

这些场景背后隐藏的技术细节包括：

• 虚拟环境未激活或解释器路径不一致
• pip 源被墙、SSL 证书校验失败
• 包名拼写错误（Django 大小写敏感）
• 自定义目录或包名与官方包冲突
• PYTHONPATH / site-packages 顺序错乱

开发环境

组件	版本	备注
操作系统	macOS 14.5	Apple Silicon (M2)
Python	3.12.3	Homebrew 安装
PyCharm	2025.1 EAP	Professional
pip	24.0	2024-07-17 更新
Django	5.0.7	官方最新 LTS
包管理源	清华 TUNA	https://pypi.tuna.tsinghua.edu.cn/simple

一、快速自检清单

在开始“大动干戈”之前，先花 30 秒跑完下面 5 个命令：

which python        # 应该指向 venv 目录
python -m pip --version
python -c "import sys, django; print(django.__version__)"
echo $PYTHONPATH    # mac 下为空或仅包含 venv
ls venv/lib/python3.12/site-packages | grep -i django

如果任何一步报错，再继续下一章对症修复。

二、常见 10 大根因与解决方案

根因编号	症状速查	解决思路	命令示例
1	未安装 Django	确认 pip install 成功	python -m pip install "Django>=5,<6"
2	包名大小写错	必须 import django 全小写	检查代码
3	虚拟环境未激活	PyCharm 解释器路径指向全局	PyCharm → Settings → Python Interpreter → 选 venv
4	网络超时	切国内源 + 信任主机	pip install -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn django
5	pip 版本旧	升级 pip	python -m pip install -U pip
6	多 Python 混用	系统 Python 与 venv 冲突	pyenv local 3.12.3
7	PYTHONPATH 污染	手动 export 覆盖了 venv	unset PYTHONPATH
8	包目录无 __init__.py	自建同名目录被识别为 namespace	改名或删除空 django/
9	相对导入错误	from .models import … 找不到	改为绝对导入
10	依赖版本冲突	Django 5 需要 asgiref>=3.7	pip install "asgiref>=3.7"

三、分场景深度排查

3.1 场景 A：PyCharm 终端提示找不到 Django，但 pip list 能看到

引用：这通常是因为 PyCharm 使用的解释器 ≠ 你在终端激活的虚拟环境。

排查流程：

graph TD
    A[PyCharm 运行按钮报错] --> B{检查解释器}
    B -->|指向系统 Python| C[Settings → Python Interpreter]
    C --> D[选择 venv/bin/python]
    D --> E[重启 Run/Debug]
    B -->|已指向 venv| F{检查 pip list}
    F -->|无 Django| G[重新 pip install]
    F -->|有 Django| H[检查 PYTHONPATH]

3.2 场景 B：pip install 报 SSL/TLS 或 ReadTimeout

常见报错：

WARNING: Retrying ... after connection broken by 'ReadTimeoutError'

解决方案：

1. 临时切国内源

   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple \
               --trusted-host pypi.tuna.tsinghua.edu.cn \
               django
   

2. 永久写入配置

   mkdir -p ~/.pip
   cat > ~/.pip/pip.conf <<EOF
   [global]
   index-url = https://pypi.tuna.tsinghua.edu.cn/simple
   trusted-host = pypi.tuna.tsinghua.edu.cn
   EOF
   

3.3 场景 C：自建项目目录叫 django，导致 import 冲突

引用：Python 的模块搜索顺序是 当前目录 > PYTHONPATH > site-packages。

复现步骤：

myproject/
├── django/          # 自建空目录
└── manage.py

运行 python manage.py migrate 会优先导入 ./django 而不是 site-packages 的 Django。

修复：

mv django django_local  # 改名
python -c "import django; print(django.__version__)"

四、进阶：使用 pipdeptree 做依赖诊断

安装：

pip install pipdeptree

查看 Django 依赖树：

pipdeptree -p django

输出示例：

django==5.0.7
├── asgiref [required: >=3.7.0,<4, installed: 3.8.1]
├── sqlparse [required: >=0.3.1, installed: 0.5.0]
└── tzdata [required: Any, installed: 2024.1]

若缺失依赖，可一键补全：

pip install "django[argon2]"  # 官方推荐额外安全依赖

五、一键自动化脚本

把日常排查写成脚本 fix_django.sh，一键运行：

#!/usr/bin/env bash
set -e
echo ">>> 1. 检查虚拟环境"
[[ "$VIRTUAL_ENV" ]] || { echo "请先激活 venv"; exit 1; }

echo ">>> 2. 升级 pip & 安装 Django"
python -m pip install -U pip
python -m pip install -U "Django>=5,<6"

echo ">>> 3. 验证"
python -c "import django; print('Django OK:', django.__version__)"

echo ">>> 4. 清理缓存"
pip cache purge

赋权并执行：

chmod +x fix_django.sh
./fix_django.sh

六、总结与最佳实践

实践要点	说明
永远使用虚拟环境	python -m venv venv
固定解释器到 PyCharm	避免系统 Python 污染
固定 requirements.txt	pip freeze > requirements.txt
定期更新 pip & 源	pip install -U pip -i https://pypi.tuna.tsinghua.edu.cn/simple
避免目录同名	项目根目录不要出现 django/

---

更多 Bug 解决方案请查看 ==> 全栈Bug解决方案专栏