ModuleNotFoundError本质是Python解释器在sys.path中未找到目标模块，主因有三：模块未安装、已安装但路径不在sys.path中、或导入语句路径/名称错误。
Python报错 ModuleNotFoundError，本质是解释器在指定路径中没找到你要导入的模块。核心原因就三类：模块压根没装、装了但不在 Python 的 sys.path 里、或者导入语句写错了路径或名字。
确认模块是否已安装
运行 pip list 或 pip show 模块名 查看是否已安装。注意区分大小写和拼写（比如 requests 不是 request）。虚拟环境中要确保激活了对应环境再查，否则可能看到的是全局或另一个环境的包列表。
- 没安装就用
pip install 模块名安装 - 装了但版本太老，可加
--upgrade更新 - 某些模块名和导入名不同（如
python-dotenv要import dotenv），查官方文档确认导入名
检查 Python 解释器和当前工作目录
同一台机器可能有多个 Python 版本或虚拟环境。运行 which python（macOS/Linux）或 where python（Windows）确认你执行脚本时用的是哪个解释器；再在 Python 中打印 import sys; print(sys.executable) 和 print(sys.path)，核对路径是否包含模块所在位置。
- 当前工作目录（
os.getcwd()）会影响相对导入，尤其用from . import xxx时必须在包内运行 - 不要直接双击运行 .py 文件——可能调用错误解释器或工作目录异常，统一用终端
python script.py
验证模块路径是否在 sys.path 中
sys.path 是 Python 查找模块的路径列表。如果模块装在非标准位置（比如自己写的工具库放在 /home/user/mylib），需要手动添加：
立即学习“Python免费学习笔记（深入）”；
- 临时加：脚本开头加
import sys; sys.path.append('/path/to/your/module') - 永久加：设置环境变量
PYTHONPATH，值为模块所在目录（多个用冒号或分号分隔） - 开发时推荐用
pip install -e .安装本地包（需有setup.py或pyproject.toml），这样会以“开发模式”链接到 site-packages
检查导入语法和包结构
相对导入只能用于包内，且必须通过 python -m package.module 方式运行，不能直接 python module.py。同时确保包目录下有 __init__.py（哪怕为空）。
-
import mypackage要求mypackage是顶层目录名，且该目录在sys.path中 -
from mypackage.sub import func要求mypackage/__init__.py和mypackage/sub/__init__.py都存在 - 避免用
from . import xxx在非包上下文运行，会直接报错
不复杂但容易忽略。定位时优先打印 sys.executable 和 sys.path，再对照模块实际位置，基本就能锁定问题在哪一环。
