如何在 Jupyter Notebook 中正确导入同级子目录中的模块-Python教程-PHP中文网

如何在 Jupyter Notebook 中正确导入同级子目录中的模块

本文详解在 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 中使用 绝对导入（基于项目根目录）：

Jupyter Notebook 7.5.4

Jupyter Notebook 7.5.4 官方 PyPI wheel 包下载，适合用于本地交互式代码运行、数据分析、教学演示和配置文件实践。

下载

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 后能用，但它破坏了命名空间清晰性，且无法区分同名模块。