python -m报ModuleNotFoundError的根本原因是未从包的父目录启动且包结构不完整：必须确保各级目录含__init__.py，并在顶层包的上一级目录执行命令，否则Python无法识别为有效包。
为什么python -m运行时仍报ModuleNotFoundError
根本不是模块写错了，而是 python -m 要求你从**包的父目录**启动，且路径必须和 import 语句中的包名完全一致。比如你想执行 python -m src.utils.helper，那必须确保：src/ 目录下有 __init__.py，且你当前在 src 的上一级目录（如项目根目录）运行命令。
常见错误包括：
– 在 src/ 目录里直接执行 python -m utils.helper（缺了顶层包名 src）
– src/ 下没有 __init__.py，导致 Python 不认为它是包
– helper.py 里用了 from . import config，但 config.py 所在目录没 __init__.py
- 检查每一级子目录是否都有
__init__.py（哪怕空文件） - 用
ls -R | grep __init__.py快速扫一遍包结构 - 运行前先
cd到项目根目录，再python -m src.utils.helper
sys.path.append() 加路径为什么有时失效
因为 sys.path.append() 是往列表末尾加路径，而 Python 优先查前面的路径——如果前面已有同名模块（比如某个已安装的第三方包也叫 utils），就会加载错的版本，甚至静默失败。
更危险的是：相对路径如 sys.path.append('./lib') 依赖当前工作目录，而自动化脚本常被 cron 或 CI 系统调用，工作目录不可控。
立即学习“Python免费学习笔记（深入）”；
- 改用
sys.path.insert(0, str(Path(__file__).parent.parent))，把项目根目录插到最前面 - 绝对路径构造必须基于
__file__，不能靠os.getcwd() - 避免在正式脚本中硬编码路径；调试时可用，上线前应替换为
pip install -e .
pip install -e . 后还是找不到模块？
说明 setup.py 或 pyproject.toml 里定义的 packages 没覆盖实际目录，或者你没在项目根目录执行安装命令。
典型陷阱：find_packages() 默认只发现含 __init__.py 的子目录，但如果你用了命名空间包（比如 myorg.utils），就得显式声明 packages=['myorg', 'myorg.utils']。
- 运行
pip install -e .前，确认终端pwd输出是项目根目录（即setup.py所在位置） - 安装后执行
python -c "import mypackage; print(mypackage.__file__)"，看路径是否指向你的源码目录 - 若用
pyproject.toml，检查[project]下的requires-python是否匹配当前 Python 版本
IDE 里能跑，命令行跑就 ModuleNotFoundError
VS Code / PyCharm 默认把当前打开文件所在目录设为工作目录，并悄悄注入 sys.path；但命令行不会。这不是 bug，是设计如此。
验证方式：在脚本开头加 print(os.getcwd(), '\n'.join(sys.path))，对比 IDE 和终端输出。
- 不要依赖 IDE 的自动路径补全来判断 import 是否合法
- 统一用
python -m mypackage.main替代python mypackage/main.py - CI/CD 中务必用
cd $PROJECT_ROOT && python -m mypackage.cli这类明确路径的写法
-m、部分用 sys.path.append、部分靠 IDE 注入），后续维护成本会指数上升。 
