执行python manage.py makemigrations报Django导入错误如何解决

问题背景 #

项目此前可正常运行，中断开发返回后，在终端执行python manage.py makemigrations命令时抛出如下错误：

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?

排查解决步骤 #

• 优先排查虚拟环境是否激活
  终端关闭、会话中断后虚拟环境会自动退出，这是该报错最高发的原因。venv虚拟环境激活命令：Windows系统执行项目根目录下venv\Scripts\activate，macOS/Linux系统执行source venv/bin/activate，激活成功后终端输入行开头会显示(venv)前缀，此时再重试迁移命令即可。如果是conda虚拟环境，执行conda activate 你的环境名，看到前缀出现对应环境名再操作。
• 校验当前环境的Django安装状态
  虚拟环境激活后执行pip list | grep Django（Windows系统执行pip list | findstr Django），如果返回结果里没有Django，说明当前环境依赖丢失，直接执行pip install django安装对应版本即可；如果项目根目录有requirements.txt依赖清单，执行pip install -r requirements.txt一次性补全所有依赖，避免后续出现其他包缺失问题。
• 确认Python解释器路径匹配
  本地装了多版本Python时，很容易出现激活虚拟环境后仍然调用全局Python的问题。执行which python（Windows系统执行where python），查看返回的可执行文件路径是否在当前项目的虚拟环境目录下，如果路径不对，直接指定虚拟环境内的Python解释器执行命令即可，比如macOS/Linux下执行./venv/bin/python manage.py makemigrations，Windows下执行venv\Scripts\python.exe manage.py makemigrations。
• 检查PYTHONPATH环境变量配置
  前面步骤都无效的话，执行echo $PYTHONPATH（Windows系统执行echo %PYTHONPATH%），确认项目根目录、Django安装所在的site-packages目录在环境变量列表中。临时修复可以在执行命令前手动指定路径，比如macOS/Linux下执行PYTHONPATH=你的项目绝对根路径 python manage.py makemigrations，要永久生效就把对应路径添加到系统环境变量的PYTHONPATH条目中。
• IDE内置终端场景额外检查
  如果用的是VS Code、PyCharm这类IDE的内置终端，先看IDE底部状态栏选中的Python解释器是不是项目对应的虚拟环境解释器，IDE重启后经常会自动切回全局Python解释器，手动切回对应环境解释器，重启内置终端后再重试命令。

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