VS Code Jupyter 自动选择 Conda Kernel 全攻略

python

2025-03-12 16:28:17

VS Code 工作区 Jupyter Notebook 自动选择 Conda Kernel

你是不是也遇到过这个问题：在 VS Code 里打开一个 Jupyter Notebook，每次都要手动选择 Conda 环境？烦死了！这篇文章，就是为了帮你彻底解决这个烦恼。

为什么每次都要选？

VS Code 本身并不知道你每个项目具体要用哪个 Conda 环境。默认情况下，它会列出所有可用的 Jupyter Kernel，让你自己选。这在你有多个 Conda 环境，或者需要在不同项目切换的时候，就很不方便。

解决方法全在这！

咱们有好几种办法能让 VS Code 乖乖记住你要用的 Conda Kernel。

1. 使用 VS Code 的工作区设置 (推荐!)

这是最直接也最推荐的方法。通过修改工作区设置，可以告诉 VS Code，这个项目默认用哪个 Conda 环境。

找到工作区设置文件:

通常在你的项目根目录下，有一个 .vscode 文件夹。如果没有, 就自己创建一个。在 .vscode 文件夹里，创建一个名叫 settings.json 的文件。

修改 settings.json:

把下面的代码复制到 settings.json 文件里：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python", // 解释器路径, 先留个示例
  "jupyter.defaultKernel": "your_kernel_name" // 替换成你的kernel名!
}

解释一下:
* python.defaultInterpreterPath：这个配置项告诉VS Code 你的Python解释器在哪。虽然名字叫"default", 但在工作区设置里, 它的优先级更高。 ${workspaceFolder} 代表你当前项目的根目录。如果你用了虚拟环境 (比如.venv)，这里应该设置成虚拟环境里的 Python 解释器的路径。如果直接用 Conda, 可以像原问题一样，使用 ${env:CONDA_PREFIX}/bin/python 。
* jupyter.defaultKernel：这就是关键！把 your_kernel_name 替换成你的 Conda 环境对应的 Jupyter Kernel 名称。你可以用 jupyter kernelspec list 命令在终端里查看所有可用的 Kernel 和它们的名字。

正确获取Kernel 名称
很多情况下, 出错的原因是kernel 名称不正确. 通过jupyter kernelspec list 获取的名称往往是准确的.
例如：

 Available kernels:
   geotgr        /home/darkknight/anaconda3/envs/geotgr/share/jupyter/kernels/geotgr
   python3       /home/darkknight/.local/share/jupyter/kernels/python3

geotgr 就是正确的kernel名称

重新加载 VS Code:
修改完settings.json之后，建议重新加载一下VS Code 窗口 (按Ctrl+Shift+P (或者 Cmd+Shift+P on macOS), 然后输入 "Reload Window", 回车). 这样才能确保设置生效.

安全建议:

尽量不要直接修改全局的 VS Code 设置，而是针对每个项目使用工作区设置。这样可以避免不同项目之间的配置冲突。

2. 使用 Jupyter Notebook 自身的元数据 (不太推荐)

每个 Jupyter Notebook 文件 (.ipynb) 内部其实都有一段 JSON 格式的元数据。这里面包含了创建这个 Notebook 时使用的 Kernel 信息。VS Code 可以读取这些信息。

手动修改 Notebook 文件的元数据:

你可以用文本编辑器 (比如 VS Code 自己) 打开 .ipynb 文件。找到 metadata -> kernelspec -> name 这一项。把 name 的值改成你的 Conda 环境对应的 Kernel 名称。

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Hello\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3" // <- 改这里!改成你的kernel 名称,比如 geotgr
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7" // 版本号可能不一样
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

缺点：

麻烦！ 每个 Notebook 文件都要手动改一遍。
容易出错。 万一改错了， Notebook 可能就打不开了。
不适合团队协作。 其他人在打开你的 Notebook 时，可能还是会遇到 Kernel 选择的问题。

3. 使用 nb_conda_kernels 扩展 (如果你经常切换环境)

nb_conda_kernels 是一个 Jupyter 扩展，可以自动检测你所有的 Conda 环境，并为它们创建对应的 Jupyter Kernel。

安装 nb_conda_kernels:

在你的 base Conda 环境里 (不是你要用的那个环境!) 执行：
```
conda install -c conda-forge nb_conda_kernels
```
启用 nb_conda_kernels:

重启 Jupyter Notebook 或 VS Code。

之后, 在VS Code 选取Kernel 的下拉列表里面, 你应该可以见到一个分组, 列出你的各个Conda 环境了.

原理：

nb_conda_kernels 会扫描你的 Conda 环境，并为每个环境生成一个 Kernel 配置文件。这些 Kernel 配置文件会被 Jupyter Notebook (以及 VS Code) 识别。

安全建议：

如果你只是偶尔用一下不同的 Conda 环境, 或只需要在一个项目中选择kernel，可能没必要安装这个扩展. 使用方法1 就足够了.

解决原问题中遇到的问题

原问题中提供的 settings.json 文件配置基本正确，但可能有以下几个小问题：

Kernel 名称是否准确？
务必使用 jupyter kernelspec list 确认 kernel 名称 完全一致. 大小写, 空格都要注意.
路径问题 :
"python.defaultInterpreterPath": "${env:CONDA_PREFIX}/bin/python" 这是一个推荐的写法, 它使用环境变量, 通常是可靠的.
如果你依然遇到问题, 可以尝试使用绝对路径. 但请确保路径最后是 python 可执行文件, 而不是 bin 目录本身:
```
{
    "python.defaultInterpreterPath": "/home/darkknight/anaconda3/envs/geotgr/bin/python"
}
```
"jupyter.jupyterServerType": "local" 这个设置一般不需要手动修改, 除非你用了远程服务器.
"jupyter.kernels.exclude" 和 "jupyter.kernels.default" 在这个场景中意义不大, 可以移除.

建议的 settings.json (修改版):

{
  "python.defaultInterpreterPath": "${env:CONDA_PREFIX}/bin/python",
  "python.analysis.extraPaths": ["${env:CONDA_PREFIX}/lib/python3.12/site-packages"],
  "jupyter.defaultKernel": "geotgr"
}

排错步骤

如果按照上面的修改还是不行, 尝试以下步骤:

重启 VS Code : 确保设置生效。
清理缓存 ：VS Code 会缓存一些信息。按 Ctrl+Shift+P (或 Cmd+Shift+P), 输入 "Jupyter: Clear Cache", 回车.
检查日志: VS Code 的输出面板可能会提供一些有用的信息。按 Ctrl+Shift+P (或 Cmd+Shift+P), 输入 "View: Toggle Output", 回车。在输出面板的下拉菜单里选择 "Jupyter"。看看有没有什么错误提示。
更新 Jupyter 和相关扩展: 有时候，旧版本的软件可能会有 bug。

进阶：结合使用 .condarc

如果你希望对 Conda 环境有更细粒度的控制, 可以考虑结合 .condarc 文件进行配置。比如，你可以设置 Conda 环境自动激活，或者指定包的安装渠道等。
但这个稍微复杂一点，不属于本篇文章讨论的范畴，就不详细展开了。

按照以上的方法操作，大概率能解决问题。