ModuleNotFoundError 是 Python 解释器运行时报错，非 pip 报错；主因是 pip 与 python 指向不同环境，需用 python -m pip 安装并交叉验证 sys.path、pip show 和实际 site-packages 路径。
直接说结论：ModuleNotFoundError 不是 pip 报的错，而是 Python 解释器在运行时抛出的；pip 本身成功执行了，但你用的 python 和 pip 根本不是同一个环境——这是 90% 场景的真实原因。
确认 pip 和 python 是否指向同一环境
很多人在终端敲 pip install requests 显示 “Successfully installed”，但一跑 python main.py 就报 ModuleNotFoundError: No module named 'requests'。核心问题就在这里：
-
which pip（macOS/Linux）或where pip（Windows）查 pip 路径 -
which python或where python查 python 路径 - 两个路径不一致？说明 pip 装到了 A 环境，而 python 启动的是 B 环境
- 更可靠的做法：统一用
python -m pip install requests，它强制调用当前python对应的 pip
检查模块是否真在当前解释器的 site-packages 里
装完包后别只信“Successfully installed”，要验证它是否落在 sys.path 的第三方目录中：
- 运行
python -c "import sys; [print(p) for p in sys.path if 'site-packages' in p]"，拿到site-packages路径 - 再运行
pip show requests，看输出里的Location:是否和上一步路径一致 - 如果不一致，或者
pip show报 “Package not found”，说明包根本没装到当前环境 - 特别注意：Jupyter Notebook 用户必须在 notebook cell 里执行
!pip show xxx，因为 kernel 和启动 shell 可能不同
警惕包名 ≠ 导入名这个隐形坑
很多报错其实和环境无关，纯粹是 import 写错了：
-
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 - 最稳的办法：装完后进 Python，执行
help('modules')或查官方文档的 “Usage” 小节
当前目录干扰导致的假性 ModuleNotFoundError
Python 默认把当前目录（''）排在 sys.path 第一位，这会引发两种静默故障：
- 当前目录下有个
requests.py文件，会覆盖真正的requests包，可能不报错但行为异常 - 项目结构是
project/src/main.py，你在src/下直接运行python main.py，但依赖模块在project/根目录，此时相对导入失败 - 临时加路径如
sys.path.append('..')是权宜之计，长期建议用python -m src.main方式运行，或设PYTHONPATH=..
真正麻烦的从来不是“没装包”，而是你以为装了、路径对了、名字也对了，结果还是找不到——这时候得盯住 python -m pip、pip show 和 sys.path 三者的交叉验证，少一个环节都可能绕半天。
