2.7.2 与 Jupyter 配合使用

原文链接: https://docs.astral.sh/uv/guides/integration/jupyter/

2.7.2 与 Jupyter 配合使用

Jupyter notebook 是交互式计算、数据分析和可视化的常用工具。你可以用几种不同方式把 Jupyter 与 uv 配合使用，既可以与项目交互，也可以把它当作独立工具。

在项目中使用 Jupyter

如果你在项目中工作，可以通过下面的命令启动一个能够访问项目虚拟环境的 Jupyter 服务器：

1

$ uv run --with jupyter jupyter lab

默认情况下，jupyter lab 会在 http://localhost:8888/lab 启动服务器。

在 notebook 中，你可以像在项目里其他文件那样导入项目的模块。例如，如果你的项目依赖 requests，那么 import requests 会从项目的虚拟环境中导入 requests。

如果你只是要对项目的虚拟环境进行只读访问，那就不需要再做别的事情。但如果你需要在 notebook 内安装额外的包，就有一些额外细节需要考虑。

创建内核

如果你需要在 notebook 内安装包，我们建议为项目创建专用内核。内核让 Jupyter 服务器运行在一个环境中，而各个 notebook 运行在各自独立的环境中。

在 uv 的语境下，我们可以在为项目创建内核的同时，把 Jupyter 自身安装在隔离环境中，就像 uv run --with jupyter jupyter lab 那样。为项目创建内核可以确保 notebook 连接到正确的环境，并确保在 notebook 内安装的任何包都被安装到项目的虚拟环境中。

要创建内核，你需要把 ipykernel 安装为开发依赖：

1

$ uv add --dev ipykernel

然后，这样为 project 创建内核：

1

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

接着启动服务器：

1

$ uv run --with jupyter jupyter lab

创建 notebook 时，请在下拉列表中选择 project 内核。之后可以用 !uv add pydantic 把 pydantic 添加到项目依赖，或用 !uv pip install pydantic 把 pydantic 安装到项目虚拟环境中而不把变更写入项目的 pyproject.toml 或 uv.lock 文件。两种命令都能让 import pydantic 在 notebook 中生效。

不使用内核安装包

如果你不想创建内核，仍然可以在 notebook 内安装包。不过有几点需要注意。

尽管 uv run --with jupyter 运行在隔离环境中，但在 notebook 内部，!uv add 及相关命令即使没有内核也会修改项目环境。

例如，在 notebook 中运行 !uv add pydantic 会把 pydantic 加入项目依赖和虚拟环境，因此 import pydantic 会立即生效，无需额外配置或重启服务器。

不过，由于 Jupyter 服务器才是“激活的”环境，!uv pip install 会把包安装到 Jupyter 的环境，而不是项目环境。这类依赖会在 Jupyter 服务器的生命周期内保留，但后续再次调用 jupyter 时可能消失。

如果你使用的 notebook 依赖 pip（例如通过 %pip 魔术命令），可以在启动 Jupyter 服务器之前运行 uv venv --seed，把 pip 包含进项目虚拟环境。例如：

1
2

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

此后在 notebook 中执行 %pip install 会把包装入项目虚拟环境。不过这类修改不会反映到项目的 pyproject.toml 或 uv.lock 文件中。

把 Jupyter 当作独立工具使用

如果你只是临时需要一个 notebook（例如交互式运行一段 Python 代码），可以随时用 uv tool run jupyter lab 启动 Jupyter 服务器。它会在隔离环境中运行 Jupyter 服务器。

在非项目环境中使用 Jupyter

如果你需要在不与项目关联的虚拟环境（例如没有 pyproject.toml 或 uv.lock）中运行 Jupyter，可以直接把 Jupyter 加入该环境。例如：

• macOS 和 Linux
• Windows

1
2
3
4

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

1
2
3
4

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

这样 import pydantic 就能在 notebook 中生效，你也可以通过 !uv pip install 甚至 !pip install 安装额外的包。

在 VS Code 中使用 Jupyter

你也可以在 VS Code 这类编辑器中操作 Jupyter notebook。要把 uv 管理的项目连接到 VS Code 中的 Jupyter notebook，我们建议先为项目创建内核，如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 创建项目。
$ uv init project

# 进入项目目录。
$ cd project

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

# 在 VS Code 中打开项目。
$ code .

在 VS Code 中打开项目目录后，你可以从命令面板选择 “Create: New Jupyter Notebook” 来新建 Jupyter notebook。当提示选择内核时，选择 “Python Environments”，然后选择你此前创建的虚拟环境（例如 macOS 和 Linux 上的 .venv/bin/python，或 Windows 上的 .venv\Scripts\python）。

注意

VS Code 要求项目环境中存在 ipykernel。如果你不想把 ipykernel 添加为开发依赖，可以用 uv pip install ipykernel 把它直接安装到项目环境中。

如果你需要在 notebook 内操作项目环境，可能需要把 uv 添加为显式开发依赖：

1

$ uv add --dev uv

之后，你可以用 !uv add pydantic 把 pydantic 添加到项目依赖，或用 !uv pip install pydantic 把 pydantic 安装到项目虚拟环境中而不更新项目的 pyproject.toml 或 uv.lock 文件。