【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 TDA[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解決方案專欄