本文详解在 Jupyter Notebook 中因工作目录变化导致跨子目录（如 /Library）导入失败的问题，提供可靠路径配置方案、环境差异对比及最佳实践，助你稳定实现 from Library.some import function 类型的相对导入。
本文详解在 jupyter notebook 中因工作目录变化导致跨子目录（如 `/library`）导入失败的问题，提供可靠路径配置方案、环境差异对比及最佳实践，助你稳定实现 from library.some import function 类型的相对导入。
在项目结构从扁平化（/Main Folder/Library/ + 同级 .ipynb）转向规范化分层（/Main Folder/Library/ + /Main Folder/Notebook/some.ipynb）后，Jupyter Notebook 中常见的 ModuleNotFoundError: No module named 'Library' 本质是 Python 导入机制与当前工作目录（os.getcwd()）不匹配所致。
关键在于：Python 的 import 语句默认只搜索 sys.path 中的路径，而 Jupyter Notebook 的工作目录默认为 .ipynb 文件所在目录（即 /Main Folder/Notebook），而非项目根目录 /Main Folder。因此，即使 Library 是同级子目录，它也不在 sys.path 中，自然无法被识别。
✅ 正确解决方案（推荐）：
在 Notebook 开头统一添加以下代码，将项目根目录动态加入 sys.path：
import sys
import os
# 获取当前 notebook 所在目录的父目录（即 /Main Folder）
project_root = os.path.dirname(os.path.dirname(os.getcwd()))
# 将项目根目录加入 Python 模块搜索路径
if project_root not in sys.path:
sys.path.insert(0, project_root)
# 此时即可正常使用标准导入语法
from Library.some import your_function # ✅ 成功！
⚠️ 注意事项：
- 避免硬编码路径（如 from Main_Folder.Library.some import ...）：虽在特定环境下可行，但破坏可移植性，且大小写、空格、特殊字符易引发错误；
- sys.path.append() vs sys.path.insert(0,)：建议使用 insert(0, ...)，确保新路径优先于其他路径（如系统 site-packages），避免同名模块冲突；
- PyCharm 无需手动配置的原因：PyCharm 默认将项目根目录设为“Sources Root”（标记为蓝色文件夹），自动将其加入 sys.path；VS Code + Jupyter 插件则无此自动行为；
- .py 文件与 .ipynb 的差异：普通 .py 脚本运行时，若在项目根目录执行（如 python Notebook/main.py），os.getcwd() 即为根目录，故 sys.path.append(".") 有效；但 Notebook 的工作目录始终是其自身位置，必须显式上溯。
? 进阶建议：
为长期维护性考虑，推荐在项目根目录下创建 __init__.py（可为空）使 Library 成为正规包，并配合 pip install -e . 安装为可编辑包（需配置 setup.py 或 pyproject.toml）。这样无论在哪运行 Notebook，均可直接导入，彻底摆脱路径管理负担。
总结：路径问题不是 Bug，而是 Python 导入机制的设计特性。掌握 os.path.dirname(os.getcwd()) 动态定位项目根目录 + sys.path.insert(0, ...) 主动注册，即可一劳永逸解决跨子目录导入难题。
