在VS Code和Jupyter Notebook服务器中为Python开发设置PYTHONPATH的最简方案

最近我在帮公司的团队梳理Python代码结构，遇到了一个路径配置的难题——项目拆成了多个子目录，得靠PYTHONPATH把这些目录加入搜索路径才能让代码正常引用。比如我们的项目结构是这样的：

project/
   .venv/
   foo/
      bar.py
   jim/
      jam.py

我们希望Jupyter笔记本里能直接运行import jim、import jam这类代码，而且得同时支持两个场景：在VS Code本地运行，以及启动Jupyter服务器后从Google Colab连接过来使用。

我们的核心诉求很明确：

• 尽量少的用户配置工作，最好克隆项目后跑个脚本就能搞定
• 绝对不能硬编码绝对路径（同一台机器可能有多个项目副本）
• 路径配置要集中，别在Python、Jupyter、VS Code、pytest这些工具里重复维护
• 不用在每个笔记本开头加sys.path修改代码
• 支持实时开发：改完核心库代码，笔记本里能即时生效

已经搞定的VS Code和pytest配置 #

我已经把VS Code里的配置搞定了，步骤很简单：

1. 项目根目录建个.env文件，内容就是PYTHONPATH=foo:jim——VS Code的Python扩展默认会读取${workspaceFolder}/.env，所以不用额外改设置
2. 把VS Code的jupyter.notebookFileRoot从默认的${fileDirname}改成${workspaceFolder}，确保所有笔记本都从项目根目录启动

另外为了让pytest也能正常跑，我在pyproject.toml里加了这段配置：

[tool.pytest.ini_options]
pythonpath = [
    "foo",
    "jim",
]

不过现在卡壳的地方是：怎么让团队成员在虚拟环境里启动Jupyter服务器时，也能自动拿到正确的PYTHONPATH？我不想写个启动脚本还得再重复一遍路径列表，毕竟实际项目里的目录名更长更多，重复维护太容易出错了。

最简解决方案：复用.env配置启动Jupyter服务器 #

其实我们可以直接复用已经在.env里集中维护的路径配置，写一个不用重复维护路径的启动脚本，完美解决问题。

1. 编写跨平台启动脚本 #

Linux/macOS用户：创建launch_jupyter.sh

在项目根目录建这个脚本，内容如下：

#!/bin/bash
# 从.env读取PYTHONPATH（跳过注释行）
export $(grep -v '^#' .env | xargs)
# 激活项目虚拟环境
source .venv/bin/activate
# 启动Jupyter服务器
jupyter notebook

然后给脚本加执行权限：

chmod +x launch_jupyter.sh

Windows用户：创建launch_jupyter.bat

如果是Windows环境，就建个批处理脚本：

@echo off
:: 从.env读取PYTHONPATH（跳过注释行）
for /f "tokens=*" %%i in ('findstr /v "^#" .env') do set %%i
:: 激活虚拟环境
call .venv\Scripts\activate.bat
:: 启动Jupyter服务器
jupyter notebook

2. 使用方法 #

用户只需要：

1. 克隆项目
2. 进入项目根目录
3. 运行对应的启动脚本（./launch_jupyter.sh或者launch_jupyter.bat）

脚本会自动帮你读取.env里的PYTHONPATH配置，激活虚拟环境，然后启动Jupyter服务器——完全不用手动配置任何路径。

3. 验证Colab连接场景 #

当你从Google Colab连接到这个本地Jupyter服务器时，Colab会自动继承服务器的PYTHONPATH配置，直接在Colab笔记本里写import jim这类代码就能正常运行，不需要额外做任何配置。

为什么这个方案靠谱？ #

• 单一数据源：所有路径配置都集中在.env里，VS Code、pytest、Jupyter服务器都复用这一份配置，不用重复维护
• 零硬编码绝对路径：所有路径都是相对项目根目录的，不管项目放在哪里都能正常工作
• 低用户成本：克隆项目后跑个脚本就搞定，不用每个用户手动改一堆配置
• 兼容所有场景：不管是VS Code本地运行，还是Colab连接服务器，都能正常使用

备注：内容来源于stack exchange，提问作者Phrogz