如何修复Python项目中导入自定义模块时报出的ModuleNotFoundError？-Python教程-PHP中文网

根本原因是python解释器未在sys.path中找到模块路径，需检查工作目录与脚本路径差异、确保__init__.py存在、避免误用相对导入，并优先通过sys.path.insert(0, ...)或python -m方式解决。

如何修复python项目中导入自定义模块时报出的modulenotfounderror？

为什么 `import` 自定义模块会报 `ModuleNotFoundError`

根本原因不是代码写错了，而是 Python 解释器根本没在它搜索路径里找到那个模块。它只查 sys.path 列表里的目录，而你的模块文件很可能不在其中——比如你从项目根目录外运行脚本，或把模块放在了没被自动包含的子目录里。

常见现象：python src/main.py 运行时，src/ 下的 utils.py 被 main.py 导入失败，即使两个文件在同一目录
本质区别：Python 的“当前工作目录”（os.getcwd()）和“脚本所在目录”（__file__ 所在路径）经常不一致
别信 ./ 或相对导入能自动生效——除非你用 python -m 启动且目录结构符合包规范

让 Python 找到模块的三种可靠方式

优先级从高到低：修改 sys.path → 设置 PYTHONPATH → 用 -m 运行。不要改系统级 site-packages，那属于污染环境。

在入口脚本开头插入（最直接）：
```
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))
```
—— 注意是 insert(0)，不是 append，否则可能被其他路径覆盖
设置环境变量（适合调试或 CI）：PYTHONPATH=/path/to/your/project/src，然后运行 python main.py
用 -m 运行（推荐用于包结构）：确保项目有 __init__.py，然后从项目根目录执行 python -m src.main，此时 src 自动成为顶层包

相对导入失效时该检查什么

相对导入（如 from . import utils）只在模块作为包的一部分被导入时才有效，单独运行文件会直接炸。

Python 3.14.2

Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。

下载

错误做法：python src/main.py 中写 from .utils import helper → 报 SystemError: Parent module '' not loaded
正确前提：必须通过 -m 启动，且 src/__init__.py 存在（哪怕为空），且 main.py 不能是顶层脚本（应改为 src/__main__.py）
替代方案：放弃相对导入，改用绝对导入 + 调整 sys.path，更可控