ModuleNotFoundError本质是Python在sys.path中未找到目标模块，主因包括模块未安装、环境错配（pip与python不一致）、路径缺失、导入名与包名不符、虚拟环境未激活或IDE解释器配置错误。
ModuleNotFoundError 本质是 Python 找不到你写的 import 名称对应的模块文件，不是代码写错了，而是环境或路径出了问题。
确认模块是否真的已安装
很多人以为 pip install xxx 运行完就万事大吉，其实可能装到了另一个 Python 环境里：
- 在终端运行
which python（macOS/Linux）或where python（Windows），再运行python -m pip list | grep xxx（Linux/macOS）或python -m pip list后手动搜，确认模块出现在该 Python 对应的包列表中 - 如果你用 VS Code，右下角显示的 Python 解释器路径必须和
which python一致；不一致就点它切换，否则编辑器里 import 不报错，终端运行就报ModuleNotFoundError - Jupyter Notebook 用户尤其注意：启动 notebook 的 shell 环境，和 notebook 内核（Kernel）可能是两个环境。用
!pip show xxx在 cell 里查，比本地终端更准
检查 import 语句是否匹配模块实际名称
第三方包的 import 名和 pip install 名常常不同，比如：
-
pip install python-dotenv→ 正确导入是import dotenv，不是import python-dotenv（连字符不能出现在标识符中） -
pip install Pillow→ 导入用from PIL import Image，不是import Pillow -
pip install opencv-python→ 导入用import cv2，不是import opencv或import opencv-python
最可靠的方法：安装后进 Python，执行 help('modules') 或查对应包的官方文档 “Usage” 小节。
排查 PYTHONPATH 和当前工作目录干扰
Python 会按顺序搜索 sys.path 中的路径，而当前目录（''）默认排第一。这会导致两种典型误报：
- 当前目录下有个叫
requests.py的文件，就会覆盖真正的requests包，报错可能不直接，但行为异常 - 项目结构里有
src/目录，你 cd 进src再运行脚本，但模块实际在上层，此时相对导入或路径缺失就会触发错误 - 临时加路径？别用
sys.path.append('..')—— 改PYTHONPATH环境变量或用-m方式运行更稳定，例如：python -m mypackage.main
虚拟环境没激活或混淆是最常见根源
几乎所有生产级 Python 项目都依赖虚拟环境，但错误往往藏在细节里：
- 用
python -m venv venv创建后，必须显式source venv/bin/activate（macOS/Linux）或venv\Scripts\activate（Windows），否则pip install默认装到系统 Python - PyCharm 默认为每个项目建独立 venv，但有时会“继承全局解释器”，检查设置里的 Python Interpreter 是否指向项目下的
venv/bin/python -
pip和python版本不一致：运行python -m pip install xxx比单独pip install xxx更安全，确保装到当前 Python 对应的 site-packages
真正麻烦的是嵌套环境（比如 conda env 里又建 venv），或者 IDE 自动创建的 `.idea` 下隐藏解释器路径——这种时候，python -c "import sys; print(sys.path)" 是唯一可信的诊断依据。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
