ModuleNotFoundError 的核心原因是 Python 找不到模块，需按四步排查：①检查是否安装；②确认解释器与 pip 匹配；③核对导入路径和工作目录；④识别虚拟环境干扰。
遇到 ModuleNotFoundError，核心是 Python 找不到你要导入的模块。问题通常出在“模块存在，但不在 Python 的搜索路径里”，或“模块名/路径写错了”。下面从常见场景出发，给出直接有效的排查步骤。
检查模块是否已安装
很多报错其实是因为根本没装这个包。用 pip 检查：
- 运行
pip list | grep 包名（Linux/macOS）或pip list然后手动查找 - 或者直接试装一次：
pip install 包名，如果已安装会提示 “Requirement already satisfied” - 注意区分大小写和包名 vs 模块名（比如安装
requests，导入时写import requests；但安装Pillow，导入时写from PIL import Image）
确认当前 Python 解释器和 pip 是否匹配
你用 python 运行脚本，但用 pip3 安装的包可能装到了另一个环境里：
- 在 Python 中运行
import sys; print(sys.executable)，看解释器路径 - 运行
which python（macOS/Linux）或where python（Windows）对比 - 确保用对应解释器的 pip：比如
python -m pip install 包名，比单独用pip install更可靠
检查模块导入路径和当前工作目录
Python 只在 sys.path 列出的路径里找模块。本地模块（如自己写的 utils.py）容易因路径问题报错：
立即学习“Python免费学习笔记（深入）”；
- 运行脚本前，先在 Python 中执行
import sys; print(sys.path)，确认当前目录（通常是空字符串''）或目标目录在其中 - 如果模块在子目录，确保该目录下有
__init__.py（哪怕为空），才能被当作包导入 - 避免靠修改
sys.path.append(...)临时修复——这掩盖了项目结构问题；推荐用-m方式运行或配置PYTHONPATH
识别虚拟环境干扰
用 venv 或 conda 创建的环境，彼此隔离。常见错误是：在激活的环境中装了包，却用系统 Python 运行脚本：
- 终端提示符通常带环境名（如
(myenv) $），没看到说明没激活 - 运行
python -c "import sys; print(sys.prefix)"，输出路径应和你的虚拟环境路径一致 - VS Code、PyCharm 等编辑器可能默认使用系统解释器，需手动选中虚拟环境中的 Python 解释器
不复杂但容易忽略，按顺序查这四点，90% 的 ModuleNotFoundError 都能快速定位。
