uv 与 Jupyter 集成实战：项目内核创建、环境隔离与笔记本内依赖管理

在 Jupyter 集成指南 所覆盖的场景中，uv 与 Jupyter 的组合可以按三种层次使用：在 uv 项目内启动带项目环境访问权限的 Jupyter 服务器、为项目创建专用内核（kernel）以便在笔记本中安装并持久化依赖、以及将 Jupyter 作为独立工具或临时环境使用。读完本篇，你将掌握 uv run --with、ipykernel 内核注册、uv venv --seed 等关键命令的正确用法，理解笔记本内 !uv add 与 !uv pip install 在“有内核/无内核”两种模式下分别作用于哪个环境的底层原因，并能在 VS Code 中把 uv 管理的项目与 Jupyter 笔记本正确连接起来。

在项目内启动 Jupyter：uv run --with jupyter

当你在一个 uv 项目 中工作时，可以直接用下面这条命令启动一个能够访问项目虚拟环境的 Jupyter 服务器：

$ uv run --with jupyter jupyter lab

jupyter lab 默认会在 http://localhost:8888/lab 启动服务器。在笔记本单元格中，你可以像在项目的任何其他文件里一样导入项目的模块：如果项目依赖了 requests，那么 import requests 导入的就是项目虚拟环境中的 requests。

这条命令的关键在于 --with 标志的语义。从 uv 命令行定义 可以看到，--with（短选项 -w）接收逗号分隔的依赖项，其官方说明是：

Run with the given packages installed. When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

也就是说，--with jupyter 并不会把 jupyter 写进项目的 pyproject.toml 或 uv.lock，而是把 Jupyter 及其依赖“叠加”在项目管理的环境之上的一个临时（ephemeral）环境中，且这些叠加的依赖允许与项目自身依赖冲突。这正是 uv 推荐的 Jupyter 集成方式：服务器本身运行在隔离环境里，而笔记本代码通过内核连接回项目的虚拟环境。如果你只需要只读访问项目环境，到这里就足够了。

为项目创建专用内核

如果需要在笔记本内部安装额外的包，官方文档推荐为项目创建一个专用内核。内核（kernel）的机制是让 Jupyter 服务器运行在一个环境中，而各个笔记本在各自独立的环境中运行。对 uv 而言，创建内核可以做到：Jupyter 本身仍安装在隔离环境（如 uv run --with jupyter jupyter lab 中的临时环境），但笔记本进程连接的是项目的虚拟环境，因此在笔记本中安装的包会落到项目的虚拟环境里。

操作步骤：

1. 将 ipykernel 作为开发依赖安装到项目中：

   $ uv add --dev ipykernel
   

2. 为项目创建并注册一个名为 project 的内核：

   $ uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project
   

   这里 --env VIRTUAL_ENV $(pwd)/.venv 明确告诉内核“你的解释器所在环境是项目根目录下的 .venv”，--name=project 则决定它在 Jupyter 界面下拉菜单中的显示名称。

3. 启动服务器：

   $ uv run --with jupyter jupyter lab
   

4. 创建新笔记本时，从内核下拉菜单中选择 project。此后在单元格中：

   • 执行 !uv add pydantic：把 pydantic 加入项目的依赖声明（同时更新 pyproject.toml 与 uv.lock 并同步进虚拟环境）；
   • 执行 !uv pip install pydantic：只把 pydantic 安装进项目的虚拟环境，不会持久化修改 pyproject.toml 或 uv.lock。

   两种方式的最终效果都是让 import pydantic 在笔记本中立即生效，区别只在于依赖是否进入项目的声明式依赖图。

不创建内核时安装包的差异与注意事项

即使不创建内核，也可以在笔记本中安装包，但两条命令的作用环境完全不同，需要特别注意：

• !uv add（以及相关的 !uv sync 等项目管理命令）始终作用于项目。 尽管 uv run --with jupyter 本身运行在隔离环境中，但从笔记本内执行 !uv add pydantic 时，uv 会根据当前工作目录向上发现项目，把 pydantic 加入项目依赖并安装进项目的虚拟环境——import pydantic 可以立即生效，无需任何额外配置或重启服务器。

• !uv pip install 作用于“当前激活环境”，即 Jupyter 服务器所在的隔离环境。 因为 Jupyter 服务器才是“active”环境，所以 !uv pip install pydantic 会装进 Jupyter 的临时环境而非项目环境。这类依赖只在当前 Jupyter 服务器进程的生命周期内存在，下次重新调用 jupyter 时可能就消失了（因为 --with 环境是临时且按内容缓存的）。

一句话总结：需要持久化、可复现的依赖变更用 !uv add；一次性、不进锁文件的安装用 !uv pip install 并清楚它装在临时环境；要安装进项目环境且不进锁文件，则先创建内核。

让 %pip magic 可用：uv venv --seed

如果你的笔记本依赖 pip（例如使用 %pip install magic），默认由 uv 创建的虚拟环境里没有 pip，需要先用 --seed 选项创建环境：

$ uv venv --seed
$ uv run --with jupyter jupyter lab

之后再在笔记本中执行 %pip install，包就会安装进项目的虚拟环境。注意：这类修改不会反映到项目的 pyproject.toml 或 uv.lock 中，属于“只进环境、不进声明”的操作。

--seed 标志的具体行为可以从 uv 的 venv 子命令定义 得到印证：

Install seed packages (one or more of pip, setuptools, and wheel) into the virtual environment. Note that setuptools and wheel are not included in Python 3.12+ environments.

即 --seed 会向虚拟环境安装 pip（以及 Python 3.12 以下版本的 setuptools 和 wheel），它同时受环境变量 UV_VENV_SEED 控制。

将 Jupyter 作为独立工具使用

如果你只是需要临时运行一段交互 Python 代码（ad hoc），不必有项目上下文，可以随时用 uv tool run 启动一个完全隔离的 Jupyter 服务器：

$ uv tool run jupyter lab

uv tool run 同样支持 --with 标志来向隔离环境叠加依赖，其参数定义见 tool 子命令的参数结构。这条路径下没有 pyproject.toml/uv.lock 参与，一切安装都发生在工具专用的临时环境内，适合快速试验。

在非项目虚拟环境中运行 Jupyter

如果需要在一个不与任何 uv 项目关联的虚拟环境（没有 pyproject.toml 和 uv.lock）中运行 Jupyter，可以把 Jupyter 直接装进该环境。

macOS 和 Linux：

$ uv venv --seed
$ uv pip install pydantic
$ uv pip install jupyterlab
$ .venv/bin/jupyter lab

Windows（PowerShell）：

PS> uv venv --seed
PS> uv pip install pydantic
PS> uv pip install jupyterlab
PS> .venv\Scripts\jupyter lab

此时笔记本中的 import pydantic 可以正常工作，也可以通过 !uv pip install 甚至 !pip install（因为 --seed 已提供 pip）继续安装更多包——安装目标就是当前激活的这个 .venv。

从 VS Code 中使用 Jupyter

uv 管理的 uv 项目也可以直接在 VS Code 中与 Jupyter 笔记本协同。官方推荐的方式仍然是为项目创建内核：

# 创建项目
$ uv init project

# 进入项目目录
$ cd project

# 将 ipykernel 添加为开发依赖
$ uv add --dev ipykernel

# 用 VS Code 打开项目
$ code .

在 VS Code 中打开项目目录后，从命令面板（Command Palette）选择 “Create: New Jupyter Notebook” 创建新笔记本。当提示选择内核时，选择 “Python Environments”，并挑选之前创建的虚拟环境（macOS/Linux 下为 .venv/bin/python，Windows 下为 .venv\Scripts\python）。

有两个前提条件需要注意：

1. 环境内必须存在 ipykernel。 VS Code 依赖 ipykernel 才能以该环境为内核运行笔记本。如果不希望把它列为开发依赖，也可以直接用 uv pip install ipykernel 装进项目环境，效果相同。

2. 若要在笔记本内操作项目环境，可能需要把 uv 本身加为开发依赖：

   $ uv add --dev uv
   

   这样笔记本中的 !uv add pydantic（更新 pyproject.toml/uv.lock）和 !uv pip install pydantic（仅装进 .venv）都能像前面章节描述的那样工作。

参考：uv 对 Jupyter 生态锁定的回归验证

除了文档层面，uv 仓库还将 Jupyter 栈纳入了生态级（ecosystem）锁定测试：集成测试 jupyterlab 用例 会基于 test/ecosystem/jupyterlab 目录下的 pyproject.toml 副本，在 Python 3.12 下以 --no-build 方式对整个 JupyterLab 依赖树执行锁定，并与 锁文件快照 对比。该快照覆盖了 jupyterlab、jupyter-server、jupyter-client、jupyter-core、jupyterlab-server 等数十个包及完整的 wheel 哈希，说明 uv 对 Jupyter 这类依赖复杂的科学计算工具链的解析结果是有持续回归保障的——这也解释了为什么在笔记本场景中可以直接依赖 uv 做依赖管理而不用担心解析质量。

小结

场景	推荐做法	包安装去向
项目内只读使用 Jupyter	uv run --with jupyter jupyter lab	服务器在临时环境，导入来自项目 .venv
笔记本内持久化装包	创建内核（ipykernel + ipython kernel install）后 !uv add	项目 pyproject.toml + uv.lock + .venv
一次性装包（不进锁文件）	内核下 !uv pip install	仅项目 .venv
无内核时误用 !uv pip install	注意其装入 Jupyter 临时环境	Jupyter 隔离环境（临时）
兼容 %pip magic	uv venv --seed 后再启动	项目 .venv（不进锁文件）
临时/无项目	uv tool run jupyter lab	工具隔离环境
非项目 .venv	uv venv --seed + uv pip install jupyterlab	该 .venv
VS Code 集成	项目内核 + 环境内含 ipykernel	同“笔记本内持久化装包”

以上行为以本仓库 docs/guides/integration/jupyter.md 的官方描述为准，参数语义均可在 crates/uv-cli/src/lib.rs 中对应的子命令结构体里核对。