modulenotfounderror本质是python在sys.path中未找到模块，主因是pip与python环境不匹配：执行which python和python -m pip --version确认路径及版本一致，否则统一用python -m pip install；同时核对导入名与包名差异、虚拟环境是否激活、自定义模块是否有__init__.py及正确路径。
不是库没装上，而是 Python 解释器根本没“看见”它——ModuleNotFoundError 本质是路径错位，不是缺包。
怎么确认 pip 装的包和你运行脚本的 Python 是同一个环境？
很多人用 pip install requests，但脚本跑在 python3.10，而 pip 实际对应的是 python3.9。结果包装进 A 环境，脚本在 B 环境里找，当然找不到。
- 在终端执行
which python（macOS/Linux）或where python（Windows），记下路径 - 再执行
python -m pip --version，看输出里 Python 版本和路径是否跟你上面查的一致 - 如果不一致，就别用裸
pip install，统一改用python -m pip install xxx - VS Code 用户注意右下角 Python 解释器路径，必须跟
which python输出一致；Jupyter 用户直接在 cell 里运行!pip show xxx才准
为什么 sys.path 里没有 site-packages？
当你看到 import sys; print('\n'.join(sys.path)) 的输出里压根没有类似 /path/to/python3.10/site-packages 的路径，说明当前 Python 没加载用户或系统包目录——常见于未激活虚拟环境、用了 python -s 启动（禁用用户站点）、或某些 Docker 镜像默认关闭了用户站点支持。
- 检查是否忘了
source venv/bin/activate（Linux/macOS）或venv\Scripts\activate（Windows） - 运行
python -c "import site; print(site.getusersitepackages())"，看路径是否存在且可写 - 如果返回空或报错，说明用户站点被禁用，此时
--user安装无效，必须用python -m pip install --target /some/existing/path xxx或切回正常环境
为什么 import 名和 pip install 名不一致？
第三方包的安装名和导入名经常不同，硬按 pip install 名去写 import 必然失败。
-
pip install python-dotenv→ 正确导入是import dotenv，不是import python-dotenv（连字符非法） -
pip install opencv-python→ 导入用import cv2，不是import opencv -
pip install Pillow→ 导入用from PIL import Image，不是import Pillow - 最稳办法：装完后进 Python，执行
help('modules')搜关键词，或查官网文档 “Usage” 小节
自定义模块为啥总报 ModuleNotFoundError？
本地写的 myutils.py 放在项目里，却死活 import 不进来，问题大概率出在路径或包结构上。
- 文件名含连字符（如
data-loader.py）→ Python 不认，改成data_loader.py再 import - 子目录想当包用（如
src/utils/），但里面缺__init__.py→ 补一个空文件 - 用
python script.py运行时，只有脚本所在目录自动加进sys.path[0]；如果模块在上层或同级其他目录，得手动加路径：sys.path.insert(0, os.path.dirname(os.path.dirname(__file__))) - 别用相对路径如
sys.path.append('./lib')，工作目录一变就失效；优先用绝对路径或设PYTHONPATH
真正卡住人的从来不是“没装”，而是“装对地方没找对路”。每一步都要验证路径和解释器是否咬合，而不是凭感觉重装一遍。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
