ModuleNotFoundError 的核心原因是 Python 找不到模块，需按四步排查：①检查是否安装；②确认解释器与 pip 匹配；③核对导入路径和工作目录；④识别虚拟环境干扰。
确认模块是否真的已安装
很多情况下报错只是因为模块压根没装，而不是路径或环境问题。先用 pip list 查一眼有没有，别急着改 sys.path 或 __init__.py。
- 运行
pip list | grep xxx（Linux/macOS）或pip list | findstr xxx（Windows），看输出里有没有目标模块名 - 如果没找到，直接
pip install xxx；注意有些包名和导入名不一致，比如pip install python-dotenv，但代码里是import dotenv - 虚拟环境没激活也会导致“明明装过却找不到”，检查
which python或where python输出路径是否指向你的 venv
检查当前 Python 解释器和 pip 是否匹配
常见陷阱：用系统 Python 装了包，但 VS Code / PyCharm 默认跑的是虚拟环境里的解释器，或者反过来。
- 在代码里加一句
import sys; print(sys.executable)，确认你运行脚本时用的是哪个 Python - 对应地，用这个 Python 的 pip 安装：比如
/path/to/venv/bin/python -m pip install xxx（macOS/Linux）或venv\Scripts\python.exe -m pip install xxx（Windows） - IDE 里点右下角 Python 解释器版本，别只看终端里
python --version的结果
验证模块是否在 Python 能搜到的路径里
即使装了，也可能因为路径没被识别而报错。Python 只查 sys.path 列表里的目录，不是所有子目录都自动递归扫描。
- 在报错位置前加
import sys; print('\n'.join(sys.path))，看看输出里有没有含该模块的目录 - 如果模块在项目本地（比如
./mylib/xxx/），确保该目录下有__init__.py，且你从外层运行时用了正确工作目录（cd到项目根目录再python main.py） - 临时加路径？可以，但别写死：
sys.path.insert(0, '/absolute/path/to/mylib')；更推荐用-m参数或设PYTHONPATH环境变量
区分 import 语句写法和包结构
模块名 ≠ 文件名 ≠ 包名，尤其在相对导入或嵌套包里容易搞混。
立即学习“Python免费学习笔记（深入）”；
-
import xxx要求xxx是顶层模块名；如果它在子目录里，得用from mypackage import xxx，前提是mypackage目录下有__init__.py - 执行脚本时，如果它在包内，又用了相对导入（如
from .utils import helper），必须用python -m mypackage.main启动，不能直接python mypackage/main.py - PyPI 上同名但不同作者的包可能冲突，比如
requests和某个叫requests的本地模块——删掉重名的本地文件夹再试
sys.executable 和 sys.path，一个字符都不能差。 
