本文详解在 Jupyter Notebook 中跨子目录导入模块时常见的 ModuleNotFoundError 问题，涵盖路径原理、可靠解决方案（如修改 sys.path 和创建包）、IDE 差异原因及最佳实践。
本文详解在 jupyter notebook 中跨子目录导入模块时常见的 `modulenotfounderror` 问题，涵盖路径原理、可靠解决方案（如修改 `sys.path` 和创建包）、ide 差异原因及最佳实践。
当你将 Jupyter Notebook 移入独立子文件夹（如 /Notebook/some.ipynb），而模块位于同级的 /Library/ 目录下时，Python 默认无法识别该路径——因为 import 语句只搜索 sys.path 中的路径，而 Jupyter 内核启动时的当前工作目录（os.getcwd()）通常是 .ipynb 所在目录（即 /Notebook），而非项目根目录 /Main Folder。这就导致 from Library.some import function 失败：Python 在 /Notebook 下找不到 Library 包。
✅ 推荐方案：将项目结构升级为合法 Python 包
最健壮、可移植且符合 Python 规范的方式是在 /Main Folder 下添加 __init__.py 文件，并通过相对或绝对包路径导入：
/Main Folder/
__init__.py # ← 关键！使 Main Folder 成为顶层包
/Library/
__init__.py # ← 可选，但建议添加以明确为包
some.py
/Notebook/
some.ipynb然后在 notebook 中使用 绝对导入（基于项目根目录）：
import sys
import os
# 将项目根目录（/Main Folder）加入 sys.path —— 推荐一次执行即可
root_dir = os.path.dirname(os.path.dirname(os.getcwd())) # 从 /Notebook → /Main Folder
if root_dir not in sys.path:
sys.path.append(root_dir)
# 现在可正常导入（注意：包名区分大小写，且不带 .py 后缀）
from Library.some import your_function? 提示：os.path.dirname(os.getcwd()) 返回 /Notebook，再套一层 os.path.dirname(...) 即得 /Main Folder。这是比硬编码路径更安全的动态计算方式。
⚠️ 注意事项与常见误区
- 不要依赖 os.getcwd() 的“直观位置”：Jupyter 的工作目录由 notebook 文件位置决定，而非内核启动位置；PyCharm 自动将项目根加入 sys.path，VS Code 默认不这样做——这正是 IDE 行为差异的根本原因。
- 避免仅靠 sys.path.append(".")：在 /Notebook 中执行 sys.path.append(".") 只会添加 /Notebook，对 /Library 无效。
- 绝对路径导入（如 from Main_Folder.Library.some import ...）不可靠：需确保 Main_Folder 是顶层包且已加入 sys.path，否则仍报错；且模块名含下划线或特殊字符时易出错。
- 临时方案 ≠ 长期方案：虽然 from some import function 在 sys.path 加入 /Library 后能用，但它破坏了命名空间清晰性，且无法区分同名模块。
✅ 最佳实践总结
- 结构标准化：在项目根目录和所有子包中添加 __init__.py（空文件即可）；
- 统一入口管理：在 notebook 开头显式将项目根目录加入 sys.path；
- 使用绝对导入语法：from Package.Subpackage.module import func，语义清晰、易于维护；
- 配合 .pth 文件或 PYTHONPATH（进阶）：在开发环境中设置环境变量，避免每次 notebook 都手动追加路径。
遵循以上方法，你将彻底摆脱 “Module not found” 困扰，同时让代码具备跨平台、跨 IDE 和团队协作的可移植性。
