Jupyter 添加虚拟环境 Kernel 笔记

一、如何将虚拟环境添加到 Jupyter

在实际开发中，经常会遇到这样的情况：

Jupyter Notebook 安装在 base 环境中
项目依赖安装在独立虚拟环境中

例如：

复制代码

base环境
│
└── jupyter notebook


langchain环境
│
├── python
├── langchain
└── 其他依赖

希望实现：

使用 base 环境中的 Jupyter，但是运行 langchain 环境中的代码。

1. 进入目标虚拟环境

首先进入需要添加到 Jupyter 的环境：

复制代码

conda activate langchain

此时后续操作都会针对 langchain 环境。

2. 安装 ipykernel

执行：

复制代码

pip install ipykernel

作用：

让这个 Python 环境具备作为 Jupyter Kernel 的能力。

3. 注册 Kernel

执行：

复制代码

python -m ipykernel install --user --name langchain --display-name "Python(langchain)"

其中：

--name langchain

表示 Kernel 的内部名称。

--display-name "Python(langchain)"

表示 Jupyter 界面中显示的名称。

--user

表示将 Kernel 配置写入当前用户的 Jupyter 配置目录。

4. 查看是否注册成功

执行：

复制代码

jupyter kernelspec list

如果出现：

复制代码

Available kernels:

python3
langchain

说明注册成功。

之后打开 Notebook：

复制代码

Kernel
  ↓
Python(langchain)

即可使用该环境。

二、为什么 Jupyter 在 base 环境，却能使用其他环境？

这里需要理解 Jupyter 的运行机制。

很多人的误解：

复制代码

Jupyter安装在哪里
        ↓
只能使用哪里的Python

实际上不是。

Jupyter 本身不负责执行 Python 代码。

它主要负责：

提供 Notebook 页面
管理代码单元
管理 Kernel

真正执行代码的是 Kernel。

整体结构：

复制代码

浏览器
   |
   |
Jupyter Server
   |
   |
Kernel
   |
   |
Python解释器

所以：

base 中的 Jupyter 只是管理端。

真正运行代码的是被选择的 Kernel。

三、ipykernel 注册到底做了什么？

执行：

复制代码

python -m ipykernel install --user ...

并不会复制整个虚拟环境。

它主要生成一个 Kernel 配置文件。

例如 Windows：

复制代码

C:\Users\用户名\AppData\Roaming\jupyter\kernels\langchain

里面有：

复制代码

kernel.json

内容类似：

复制代码

{
    "argv": [
        "D:\\anaconda3\\envs\\langchain\\python.exe",
        "-m",
        "ipykernel_launcher"
    ],
    "display_name": "Python(langchain)"
}

其中最重要的是：

复制代码

D:\anaconda3\envs\langchain\python.exe

它告诉 Jupyter：

当用户选择 Python(langchain) 时，启动这个 Python。

四、为什么 base 的 Jupyter 能找到这个环境？

因为注册时使用了：

复制代码

--user

它写入的是：

当前操作系统用户的 Jupyter 配置目录。

例如：

复制代码

C:\Users\用户名\AppData\Roaming\jupyter\kernels

这个目录中保存：

有哪些 Kernel
Kernel 名称
启动命令
对应 Python 路径

当你启动：

复制代码

(base)
jupyter notebook

Jupyter 会扫描这些目录。

发现：

复制代码

kernels
└── langchain
    └── kernel.json

于是显示：

复制代码

Python(langchain)

五、Kernel 和虚拟环境的区别

需要注意：

Kernel 不等于虚拟环境。

二者关系：

复制代码

虚拟环境：

langchain

├── python.exe
├── numpy
├── torch
└── langchain


Kernel：

kernel.json

记录：
使用哪个python
如何启动
显示什么名字

可以理解为：

虚拟环境：提供运行代码的实际环境
Kernel：告诉 Jupyter 如何连接这个环境

关系：

复制代码

Jupyter
   |
   |
Kernel(ipykernel)
   |
   |
Python虚拟环境
   |
   |
第三方库

六、进一步理解

1. 一个虚拟环境可以有多个 Kernel

例如：

同一个环境：

复制代码

langchain环境

python.exe

复制代码

Kernel A

Kernel B

那么 Jupyter 中可能出现：

复制代码

Python(实验A)

Python(实验B)

但是两个 Kernel 都可能指向：

复制代码

langchain/python.exe

所以：

一个环境可以对应多个 Kernel。

2. 一个 Kernel 也不一定对应虚拟环境

Kernel 可以指向：

系统 Python：

复制代码

C:\Python311\python.exe

也可以指向：

conda 环境：

复制代码

D:\anaconda3\envs\langchain\python.exe

所以：

Kernel 本质是一个启动配置，而不是一个完整运行环境。

七、最终总结

添加 Jupyter 环境的核心流程：

复制代码

创建虚拟环境

↓

安装 ipykernel

↓

注册 Kernel

↓

生成 kernel.json 配置文件

↓

Jupyter扫描配置

↓

选择对应 Kernel 执行代码

核心思想：

虚拟环境负责提供 Python 解释器和依赖，Kernel 负责连接 Jupyter 和这个 Python 环境。Jupyter 通过扫描 Kernel 配置文件，找到并启动对应的 Python。

因此：

复制代码

Jupyter(base)
        |
        |
Kernel(langchain)
        |
        |
langchain虚拟环境

这就是为什么一个安装在 base 环境的 Jupyter，可以同时管理多个不同的 Python 环境。