运行python manage.py makemigrations报No module named 'django'问题

云上老周

2026-8-28

manage.py 代码含义

这是Django项目内置的命令行入口脚本，逐行作用如下：

#!/usr/bin/env python
import os
import sys

if __name__ == "__main__":
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "api.settings")
    from django.core.management import execute_from_command_line
    execute_from_command_line(sys.argv)

#!/usr/bin/env python：类Unix系统（Linux/macOS）的Shebang声明，指定脚本优先调用系统环境路径中匹配到的Python解释器执行，Windows系统下该行无实际作用。
import os、import sys：导入Python标准库中负责操作系统交互、运行时环境交互的两个基础模块。
if __name__ == "__main__":：执行判断逻辑，仅当该脚本被直接运行（而非被其他代码作为模块导入）时，才会执行缩进块内的后续逻辑。
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "api.settings")：设置Django专属的环境变量，指定项目加载的配置文件为api目录下的settings.py，若该环境变量已提前赋值则不会覆盖原有配置。
from django.core.management import execute_from_command_line：从Django框架的核心管理模块导入命令行执行函数，这行就是本次报错的触发位置。
execute_from_command_line(sys.argv)：读取终端输入的命令参数（比如你输入的makemigrations参数就存储在sys.argv中），调用执行函数运行对应的Django管理命令。

报错原因

抛出ModuleNotFoundError: No module named 'django'的核心原因是：当前执行命令所调用的Python解释器环境中，没有安装Django包。
即使你已经执行过依赖安装，出现该问题基本都是环境不匹配导致的，常见场景：

虚拟环境未激活：依赖安装在项目专属的虚拟环境中，但执行命令时没有激活虚拟环境，终端默认调用全局Python解释器，全局环境未安装Django。
多版本Python冲突：设备上同时存在多个Python版本/环境（比如不同版本的系统Python、conda环境、venv虚拟环境并存），安装依赖时pip对应的解释器，和执行python命令调用的解释器不是同一个。
依赖安装路径异常：安装依赖时权限不足或参数配置错误，包被安装到了其他用户目录或其他Python版本的包路径下，当前执行命令的解释器无法检索到。

解决步骤

按顺序排查操作即可：

激活项目对应的虚拟环境
- 若使用Python自带venv虚拟环境：Windows执行venv\Scripts\activate，Linux/macOS执行source venv/bin/activate，激活成功后终端提示符开头会显示虚拟环境名称。
- 若使用conda虚拟环境：执行conda activate 你的虚拟环境名称。
验证解释器和包管理工具匹配
激活环境后依次执行以下命令：
```
# Linux/macOS执行
which python
which pip
# Windows执行
where python
where pip
```
两条命令返回的路径必须属于同一个虚拟环境目录，才说明环境匹配。
重新安装依赖
确认环境匹配后执行以下命令重装所有依赖：
```
pip install -r requirements.txt
```
安装完成后可执行pip list | grep django（Windows执行pip list | findstr django），确认Django出现在当前环境的已安装包列表中。
若仍存在路径指向问题，可直接指定对应解释器执行命令，比如确认装了依赖的是python3解释器，就直接运行：
```
python3 manage.py makemigrations
```
规避python命令指向错误解释器的问题。

内容的提问来源于stack exchange，提问作者Mert kaan Çukadar