在 Jupyter Notebook 中无法直接导入兄弟目录下的模块，根本原因是 Python 的模块搜索路径（sys.path）默认不包含项目根目录；需显式添加或借助 IPython 魔法命令实现优雅导入。
在 jupyter notebook 中无法直接导入兄弟目录下的模块，根本原因是 python 的模块搜索路径（`sys.path`）默认不包含项目根目录；需显式添加或借助 ipython 魔法命令实现优雅导入。
当你在 /usr/src/root/notebooks/myNotebook.ipynb 中执行 from folderA.folderB.folderC.classFileName import MyClass 时失败，是因为 Python 启动时仅将当前工作目录（即 /usr/src/root/notebooks）加入 sys.path，而 folderA 并不在该路径下——它位于上层目录 /usr/src/root/。因此，folderA 不被视为可导入的包，触发 ModuleNotFoundError。
相对导入（如 from ..folderA... import ...）同样无效，因为 Jupyter Notebook 的 .ipynb 文件并非以模块形式被 Python 解释器加载（即没有 __package__ 属性），故不支持 .. 这类基于包层级的相对引用，报错 ImportError: attempted relative import with no known parent package。
你当前使用的 sys.path.append('/usr/src/root/') 方案虽有效，但存在隐患：
- 修改全局
sys.path可能引发命名冲突或污染后续导入； - 在多 notebook 协作或容器重启后需重复操作，缺乏可维护性；
- 不符合 Python 包管理的最佳实践。
✅ 更优雅、可复用的替代方案是使用 IPython %run 魔法命令：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
# 切换到项目根目录（确保 __init__.py 存在，使文件夹成为合法包） %cd /usr/src/root/ # 以模块方式交互式运行目标文件（-i 表示交互模式，-m 表示按模块名执行） %run -i -m folderA.folderB.folderC.classFileName # 恢复原始工作目录（可选，提升 notebook 可移植性） %cd /usr/src/root/notebooks
该方法本质是将 classFileName.py 作为模块在当前 notebook 命名空间中执行（类似 import 效果），所有定义（包括 MyClass）将直接注入全局变量空间，之后即可直接使用：
instance = MyClass() # ✅ 正常工作
⚠️ 注意事项：
- 所有含
__init__.py的中间目录（folderA/,folderB/,folderC/）必须存在，否则 Python 不识别为包结构； -
%run -i -m会执行整个文件，若含副作用代码（如顶层print()或初始化逻辑），将在导入时触发； - 若只需导入特定类/函数且避免副作用，推荐结合
sys.path临时修改 +importlib动态导入，或在容器启动时通过环境变量PYTHONPATH=/usr/src/root预设路径（一劳永逸）：
# Dockerfile 中添加（推荐生产环境使用）
ENV PYTHONPATH="/usr/src/root:${PYTHONPATH}"总结：sys.path.append() 是快速验证方案，而 %run -i -m 更适合开发调试阶段的轻量级导入；长期项目应统一通过 PYTHONPATH 或安装为可编辑包（pip install -e .）来规范依赖管理，兼顾清晰性、可复现性与工程健壮性。
