VS Code中Jupyter Notebook无法导入兄弟目录Python模块的问题咨询

我正在Visual Studio Code中使用官方Jupyter扩展运行Jupyter Notebook，项目结构如下：

my_project/
├── notebooks/
│   └── analysis.ipynb
├── libs/
│   ├── __init__.py
│   └── my_module.py

我希望在analysis.ipynb中用以下两种方式之一导入my_module：

from libs import my_module

或者：

import my_module

但一直遇到错误：

ModuleNotFoundError: No module named 'libs'

我查阅了VS Code官方Jupyter文档，但其中未涉及导入路径或sys.path的处理方式。我尝试了两种方法均无效：

1. 更改工作目录：

import os
os.chdir("..")

导入仍然失败。
2. 手动将路径添加到sys.path：

import sys
import os
sys.path.append(os.path.abspath("../libs"))
import my_module

仍报相同的ModuleNotFoundError错误。

这些方法在普通Python脚本中有效，但在VS Code的Jupyter Notebook环境中无法正常工作。我想知道：

1. 为何这些方法在此环境中无效？
2. 如何在此环境中正确从兄弟或父目录导入模块？
3. 在VS Code中使用Jupyter Notebook时，推荐的项目结构是什么？

问题解答 #

1. 常规方法无效的原因 #

VS Code的Jupyter扩展启动内核时，模块搜索路径sys.path是启动阶段就确定的，后续操作无法直接改变这一初始设置：

• os.chdir("..")仅改变当前进程的工作目录，但不会更新内核已加载的sys.path，因此Python依然找不到目标包。
• 你添加../libs到sys.path的逻辑有误：from libs import my_module需要Python找到名为libs的包，而你添加的是libs目录本身，正确的做法应该添加项目根目录（my_project/）到sys.path；另外如果先执行导入语句再修改路径，也会导致设置无效。

2. 正确的导入方式 #

以下是几种可靠的解决方法：

方法一：动态添加项目根目录到sys.path

在Notebook的最顶部执行这段代码，确保先设置路径再导入模块：

import sys
from pathlib import Path

# 获取当前Notebook所在目录
notebook_dir = Path().resolve()
# 获取项目根目录（notebooks的父目录）
project_root = notebook_dir.parent
# 将根目录加入sys.path
if str(project_root) not in sys.path:
    sys.path.append(str(project_root))

# 现在可以正常导入
from libs import my_module

方法二：通过VS Code设置内核工作目录

• 打开analysis.ipynb，点击右上角的内核选择器，选择项目对应的Python解释器（如虚拟环境）。
• 打开命令面板（Ctrl+Shift+P），运行Jupyter: Set Workspace Folder，选择my_project/作为工作目录。内核启动时会自动将项目根目录加入sys.path，直接使用from libs import my_module即可。

方法三：通过环境变量永久配置

在项目根目录创建.env文件，写入以下内容（替换为你的项目绝对路径）：

PYTHONPATH=/实际路径/my_project

VS Code的Python扩展会自动读取该文件，将路径加入sys.path，Notebook和普通脚本均可直接使用。

3. 推荐的项目结构 #

采用分层结构，核心代码与Notebook分离，便于维护和复用：

my_project/
├── notebooks/          # 存放Jupyter Notebook
│   ├── exploratory/    # 探索性分析笔记
│   └── reports/        # 报告类笔记
├── src/                # 核心业务代码（替代原libs目录）
│   ├── __init__.py
│   ├── data_processing.py
│   └── visualization.py
├── data/               # 数据存储目录
│   ├── raw/            # 原始数据
│   └── processed/      # 处理后数据
├── tests/              # 测试代码
└── requirements.txt    # 依赖清单

• 核心逻辑放在src/目录作为可导入包，Notebook仅负责调用函数，避免重复编写逻辑。
• 使用pathlib处理路径，避免硬编码路径导致的兼容性问题。

内容的提问来源于stack exchange，提问作者Allan Xu