ModuleNotFoundError本质是Python解释器在sys.path中未找到目标模块。需检查sys.path是否包含模块实际路径、pip与Python解释器是否匹配、虚拟环境是否激活，并优先用python -m pip安装确保环境一致。
ModuleNotFoundError 本质是 Python 找不到模块的路径问题
这个错误不是代码写错了，而是 Python 解释器在 sys.path 列表里翻了一遍，没找到你要 import 的那个包或模块。它不关心你“以为”装了什么，只认 sys.path 里真实存在的路径。
怎么快速确认是不是路径错位导致的
在报错的同一环境（比如你运行脚本的终端、或 Jupyter notebook 的 kernel）中，直接执行：
import sys
print('\n'.join(sys.path))
重点看三处：
- 第一项通常是当前脚本所在目录（但仅当用
python script.py运行时才生效；用 IDE 或python -m可能不同） - 有没有你 pip 安装包的真实位置？比如
/usr/local/lib/python3.9/site-packages或$HOME/.local/lib/python3.9/site-packages - 有没有明显不该出现的路径（比如旧虚拟环境残留、拼错的路径）
如果 site-packages 路径压根不在 sys.path 里，那基本就是环境错乱——你可能在系统 Python 里运行，却把包装进了虚拟环境，或者反过来。
pip install 后还是找不到？检查安装目标和 Python 解释器是否匹配
常见陷阱：
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
- 用
pip install requests，但实际运行脚本的是python3.10，而pip对应的是python3.9—— 查证方式：which pip和which python看路径，再用pip --version和python -m pip --version对比 - 在虚拟环境中忘了激活，却用全局
pip安装 —— 结果包装到了系统 site-packages，而你的脚本跑在 venv 里 - 用了
--user安装，但当前 Python 没启用用户站点（python -s会禁用，某些 Docker 镜像或受限环境默认如此）
最稳做法：统一用 python -m pip install xxx，确保 pip 和解释器完全绑定。
临时加路径不是长久之计，但调试时很管用
如果确认模块就在某目录下（比如你有个本地 myutils/ 包），只是没进 sys.path，可以临时加：
import sys sys.path.insert(0, '/path/to/myutils') # 插在最前，优先级最高 import myutils
但注意：
- 这行代码必须在任何
import myutils之前执行 -
sys.path修改只对当前进程有效，重启就失效 - 上线或团队协作时，应该用
pip install -e .（可编辑安装）或正确配置PYTHONPATH，而不是硬编码路径
真正容易被忽略的是：IDE（如 VS Code、PyCharm）可能缓存了旧的 Python 解释器路径或 sys.path，改完环境后不重启终端或不重载 Python 解释器，看到的仍是旧状态。
