ModuleNotFoundError本质是Python在sys.path中未找到目标模块，修复核心为修改sys.path或设置PYTHONPATH环境变量；需注意绝对路径、插入顺序、相对导入限制及IDE缓存问题。
ModuleNotFoundError 本质是 Python 找不到模块的路径
这个错误不是代码写错了，而是 Python 解释器在 sys.path 列表里挨个查了一圈，没找到你要 import 的那个模块。它不看当前文件在哪，也不自动往上翻父目录——除非你显式告诉它“去这儿找”。所以修复核心就两条：改 sys.path，或者让环境变量 PYTHONPATH 帮你提前声明搜索位置。
临时加路径：用 sys.path.insert(0, ...) 最快但有风险
适合调试、脚本快速验证，不适合长期部署。关键是把新路径插到最前面（索引 0），否则可能被已有的 site-packages 盖掉。
-
sys.path.insert(0, "/absolute/path/to/your/module")—— 必须是绝对路径，相对路径容易因运行位置不同失效 - 别用
sys.path.append()，它加在末尾，如果同名模块已存在于标准库或第三方包里，Python 会优先加载那个，导致静默错用 - 插入后建议立刻检查：
print([p for p in sys.path if 'your' in p])，确认路径确实进去了且拼写无误
永久生效：靠 PYTHONPATH 环境变量更干净
比改代码更可控，所有 Python 进程启动时都会读取它，且不会污染源码逻辑。但要注意 shell 层级和生效范围。
- Linux/macOS：在
~/.bashrc或~/.zshrc中加一行export PYTHONPATH="/path/to/modules:$PYTHONPATH"，然后source ~/.zshrc - Windows（cmd）：用
set PYTHONPATH=C:\path\to\modules;%PYTHONPATH%；PowerShell 用$env:PYTHONPATH="C:\path\to\modules;$env:PYTHONPATH" - IDE（如 PyCharm）需在运行配置里单独设置环境变量，它不继承系统终端的
PYTHONPATH - 虚拟环境中也生效，但注意：如果路径指向的是全局 site-packages 外的代码，要确保该代码与当前 Python 版本兼容
常见陷阱：相对导入、__init__.py 和 IDE 缓存
很多 ModuleNotFoundError 其实和路径无关，而是项目结构或工具行为导致的假象。
立即学习“Python免费学习笔记（深入）”；
- 用
from . import xxx是相对导入，只在 package 内部有效，不能直接运行python mypackage/submodule.py—— 会报错，得用python -m mypackage.submodule - 缺少
__init__.py（哪怕空文件）会让 Python 不认为那是 package，from mypackage import mod就会失败 - PyCharm/VSCodium 可能缓存旧的
sys.path，改完环境变量或代码后要重启解释器或清缓存（File → Invalidate Caches） - pip 安装的 editable 模式（
pip install -e .）其实也是往sys.path加了一个 .pth 文件，比手动改更可靠，适合开发态
