ModuleNotFoundError 的本质是 Python 在 sys.path 列出的路径中未找到目标模块；这些路径包括当前脚本目录、site-packages、标准库路径及 PYTHONPATH 指定目录等，且受虚拟环境、Python 版本、包名与导入名差异、pip 与 python 版本不匹配等因素影响。
ModuleNotFoundError 出现时，Python 到底在找哪些路径？
Python 报 ModuleNotFoundError 的本质，是它在自己的模块搜索路径（sys.path）里翻了一遍，没找到你要导入的包。这个路径不是固定的，而是由解释器启动时动态拼出来的：包括当前目录、site-packages、标准库路径、以及环境变量 PYTHONPATH 所指定的目录等。
最直接的验证方式是在报错环境里运行：
import sys
print('\n'.join(sys.path))
注意看输出里有没有你期望的包所在目录。如果包明明装了却不在列表中，问题就出在路径没被 Python 看到；如果路径有但包名对不上（比如大小写、下划线/中划线混用），也会触发这个错误。
-
sys.path第一项通常是执行脚本的目录，不是当前 shell 工作目录 —— 这点容易误判 - 虚拟环境激活后，
site-packages路径会指向该环境下的目录，和系统全局的互不干扰 - 通过
pip install -e .安装的本地包，会把项目根目录加进sys.path，但只对当前 shell 有效
pip install 后还是报错？检查包名和安装目标是否匹配
很多人执行了 pip install requests 却在代码里写 import request（少了个 s），或者装了 beautifulsoup4 却试图 import BeautifulSoup —— 这类“名字不一致”是 ModuleNotFoundError 最常见的非路径原因。
立即学习“Python免费学习笔记（深入）”；
包的安装名（PyPI 上的名字）和导入名（import xxx 中的 xxx）不一定相同，必须查文档确认。例如：
-
pip install python-dotenv→ 导入用import dotenv -
pip install PyYAML→ 导入用import yaml（全小写） -
pip install opencv-python→ 导入用import cv2
不确定时，用 pip show 包名 查 Name: 和 Location: 字段；再进到 Location 目录里看是否存在 __init__.py 或对应模块文件。
多 Python 版本 / 多环境导致 pip 和 python 不配套
这是生产环境中最隐蔽也最常踩的坑：你用 pip3.9 install flask 装了包，但运行的是 python3.10 script.py —— 两个解释器的 site-packages 完全隔离，自然找不到。
验证方法很简单：
which python which pip python -m pip --version
三者输出的路径和版本号必须一致。常见错配场景：
- macOS 上用 Homebrew 装了 Python，但系统自带的
/usr/bin/python3仍存在 - VS Code 终端自动激活了某个虚拟环境，而命令行里没激活，导致
pip和python指向不同位置 - 在 Dockerfile 里写了
RUN pip install，但后续CMD ["python", "app.py"]启动时用了另一个基础镜像的 Python
安全做法永远是：用 python -m pip install xxx，确保调用的是当前 python 对应的 pip。
临时修复 vs 长期解法：什么时候该改 sys.path？
在脚本开头加 sys.path.insert(0, '/path/to/my/module') 能快速绕过错误，但这是权宜之计。它会让模块加载行为依赖硬编码路径，破坏可移植性，且无法解决 IDE 导入高亮、类型检查等问题。
真正可持续的做法只有两类：
- 把模块打成合规包（含
setup.py或pyproject.toml），用pip install -e .开发安装 - 把模块所在目录设为
PYTHONPATH环境变量（仅限开发调试，CI/CD 中不推荐）
特别注意：__pycache__ 目录或 .pyc 文件不会影响模块发现逻辑；但如果你删了 __init__.py（哪怕是空文件），那个目录就不再是 Python 包，import 必然失败 —— 这个细节常被忽略。
