本文详解 Python 项目中跨并行子目录进行模块导入的规范方法，重点解决 ImportError: attempted relative import with no known parent package 错误，涵盖运行方式、目录结构、__init__.py 作用及绝对导入最佳实践。
本文详解 python 项目中跨并行子目录进行模块导入的规范方法，重点解决 `importerror: attempted relative import with no known parent package` 错误，涵盖运行方式、目录结构、`__init__.py` 作用及绝对导入最佳实践。
在 Python 项目开发中，当模块位于与当前脚本并行的子目录（而非同级或子级）时，直接使用 from ..subfolder2 import credentials 会触发 ImportError: attempted relative import with no known parent package。该错误的根本原因在于：Python 的相对导入依赖于模块的“包上下文”，而非文件物理位置；而直接执行 .py 文件（如 python my_prog.py）会使该文件被视为顶层脚本（__name__ == '__main__'），不构成任何包的一部分，因此 .. 等上级引用失效。
✅ 正确做法：以模块方式运行 + 绝对导入
假设项目结构如下：
project_folder/
├── __init__.py # 必须存在，声明 project_folder 为包
├── subfolder1/
│ ├── __init__.py # 推荐添加，显式支持子包
│ └── my_prog.py
└── subfolder2/
├── __init__.py # 推荐添加
└── credentials.py其中 credentials.py 内容为：
api_key = "supersecretapikey"
步骤 1：修改 my_prog.py 使用绝对导入
# subfolder1/my_prog.py from subfolder2 import credentials # ✅ 正确：从 project_folder 根包出发的绝对路径 print(credentials.api_key) # 输出: supersecretapikey
⚠️ 注意：此处 subfolder2 是相对于 project_folder（即包根目录）的名称，不是相对于 my_prog.py 的路径。
立即学习“Python免费学习笔记（深入）”；
步骤 2：在 project_folder 目录下，以 -m 模块方式运行
cd project_folder python -m subfolder1.my_prog
✅ 输出正常，无 ImportError。
❌ 常见错误及解释
| 错误操作 | 问题原因 |
|---|---|
| cd subfolder1 && python my_prog.py | 脚本作为 __main__ 运行，无包上下文，from subfolder2 import ... 被视为绝对导入但 subfolder2 不在 sys.path 中 → ModuleNotFoundError |
| from ..subfolder2 import credentials | 相对导入 .. 要求当前模块属于某个包（即 __package__ 非空），但直接运行脚本时 __package__ == None → 报错 attempted relative import with no known parent package |
| 仅加 __init__.py 却仍用 python my_prog.py 执行 | __init__.py 仅使目录可被识别为包，但不改变执行模式——关键在如何运行，而非是否含 __init__.py |
? 补充建议：增强可移植性与健壮性
- 推荐始终使用绝对导入：语义清晰、易于静态分析、避免路径歧义；
- 若需在任意路径下运行脚本，可动态修正 sys.path（不推荐用于生产）：
# subfolder1/my_prog.py（临时方案，仅作调试参考） import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "subfolder2")) import credentials # now works, but breaks PEP 8 & tooling
- 部署到远程服务器时：确保以 python -m 方式启动，并将 project_folder 加入部署路径（无需修改环境变量 PYTHONPATH）。
✅ 总结
要成功导入并行目录模块，请严格遵循三要素：
① 项目根目录（project_folder）下放置 __init__.py，使其成为有效包；
② 在根目录下使用 python -m subfolder1.my_prog 启动；
③ 在代码中采用 from subfolder2 import ... 等绝对导入语法。
这不仅是解决当前问题的标准方案，更是符合 Python 包管理规范、利于协作与维护的工程化实践。
