04在 VS Code 中配置 Python 与 Jupyter

Python Profile 的核心不是保存某个 python.exe 的绝对路径，而是让 VS Code 在每个项目中发现并选择正确环境。解释器位置随电脑和环境名称变化，扩展 ID 与项目内 .venv 约定更适合迁移。

安装核心扩展

code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension ms-python.vscode-python-envs

需要编辑 .ipynb 或使用 Interactive Window 时再安装：

code --install-extension ms-toolsai.jupyter

Python extension 负责运行、调试和测试入口，Pylance 提供语言分析，Python Environments 负责发现和管理环境。debugpy 以及部分 Jupyter renderer 会作为依赖安装，不需要逐个记录。Python in VS Code

每个项目选择自己的环境

常见项目结构：

project/
├── .venv/
├── pyproject.toml
├── src/
└── tests/

打开项目后运行 Python: Select Interpreter，选择 .venv 中的解释器。VS Code 会把该选择与工作区关联，运行、调试、补全和新终端都会使用它。

Python Environments 默认搜索工作区中的 .venv。需要扩展搜索范围时，在项目 .vscode/settings.json 中设置相对路径：

{
  "python-envs.workspaceSearchPaths": [
    "./**/.venv",
    "./envs/**"
  ]
}

这项设置只能放在 workspace/folder 范围。Conda、venv、uv、Poetry 和其他常见环境通常会自动发现，不必在可迁移的用户设置中写死 python.defaultInterpreterPath 或 python.condaPath。Python Environments

Formatter 单独安装和指定

Python extension 不再意味着自动拥有某个 formatter。选择 Black 时安装官方扩展：

code --install-extension ms-python.black-formatter

在工作区中指定：

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.tabSize": 4,
    "editor.insertSpaces": true
  }
}

formatter 属于项目约定时应提交 workspace 设置；只是个人试用时则放在 Profile 中。不要同时指定多个默认 formatter。

Notebook 还要选择 kernel

打开 .ipynb 后，从 Notebook 右上角选择 kernel。Notebook kernel 与普通 .py 文件的 interpreter 选择相关，但不是完全相同的发现流程，因此两处显示不同环境时需要分别选择。Manage Jupyter Kernels

使用普通 Python 文件模拟 notebook cell，可以写：

# %%
import pandas as pd

df = pd.DataFrame({"x": [1, 2, 3]})
df

Jupyter extension 会在 # %% 上方提供 Run Cell。只有使用 notebook 或 Interactive Window 时才需要 Jupyter；普通脚本、测试和调试不依赖它。

不把本机环境写进共享配置

下面这些值不应进入公开的用户配置模板：

{
  "python.defaultInterpreterPath": "D:/specific/environment/python.exe",
  "python.condaPath": "D:/specific/conda.exe"
}

绝对路径会在换电脑、重建环境或升级发行版后失效。优先使用项目 .venv、Status Bar 环境选择和 Python Environments 的发现机制。必须配置全局搜索目录时，也只保存在本机用户设置。

ms-python.python
ms-python.vscode-pylance
ms-python.vscode-python-envs
ms-python.black-formatter

ms-toolsai.jupyter

{
  "python-envs.workspaceSearchPaths": ["./**/.venv"],
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.tabSize": 4,
    "editor.insertSpaces": true
  }
}