如何为.ipynb文件配置uv创建的Python环境作为内核？

DevOps 小满

2026-6-13

解决uv创建的.venv环境无法作为Jupyter内核的问题

方法1：手动安装ipykernel并注册内核

激活uv创建的.venv环境：

source .venv/bin/activate  # Linux/macOS系统
.venv\Scripts\activate     # Windows系统

在激活的环境中安装ipykernel：
```
uv pip install ipykernel
```
将该环境注册为Jupyter内核：
```
python -m ipykernel install --user --name=uv-venv --display-name="UV虚拟环境"
```
其中--name是内核的内部标识名，--display-name是Jupyter界面中显示的名称，可根据需求自定义。
重启Jupyter Notebook/Lab，就能在内核选择列表中看到注册好的UV虚拟环境。

方法2：用绝对路径重新注册（针对手动路径无效的情况）

确认.venv环境中Python的绝对路径，比如Linux/macOS下为/你的项目路径/.venv/bin/python，Windows下为你的项目路径\.venv\Scripts\python.exe。

使用绝对路径执行内核注册命令：

/你的项目路径/.venv/bin/python -m ipykernel install --user --name=uv-venv

方法3：检查并修正内核配置文件

打开Jupyter的内核配置目录，一般路径为~/.local/share/jupyter/kernels/（Linux/macOS）或C:\Users\你的用户名\AppData\Roaming\jupyter\kernels\（Windows）。

找到刚才注册的uv-venv文件夹，打开里面的kernel.json文件，确认argv中的Python路径是否正确指向.venv环境的Python可执行文件。正确格式示例：

{
 "argv": [
  "/你的项目路径/.venv/bin/python",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "UV虚拟环境",
 "language": "python"
}