将 uv 与 Jupyter 结合使用

Jupyter 笔记本是一款广受欢迎的交互式计算、数据分析和可视化工具。你可以通过几种不同的方式将 Jupyter 与 uv 结合使用，既可以与项目进行交互，也可以将其作为独立工具使用。

在项目中使用 Jupyter

如果你正在处理一个项目，可以通过以下方式启动一个可访问项目虚拟环境的 Jupyter 服务器：

$ uv run --with jupyter jupyter lab

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

在笔记本中，你可以像在项目的其他任何文件中一样导入项目的模块。例如，如果你的项目依赖 requests，import requests 将从项目的虚拟环境中导入 requests。

如果你只是希望对项目的虚拟环境进行只读访问，那么这样就足够了。但是，如果你需要在笔记本中安装其他软件包，则需要考虑一些额外的细节。

创建内核

如果需要在笔记本中安装软件包，我们建议为项目创建一个专用内核。内核使 Jupyter 服务器能够在一个环境中运行，而各个笔记本则在其各自独立的环境中运行。

在 uv 的环境中，我们可以为项目创建一个内核，同时将 Jupyter 本身安装在一个隔离的环境中，例如 uv run --with jupyter jupyter lab。为项目创建内核可确保笔记本连接到正确的环境，并且从笔记本中安装的任何软件包都会安装到项目的虚拟环境中。

要创建内核，需要将 ipykernel 作为开发依赖项进行安装：

$ uv add --dev ipykernel

然后，可以使用以下命令为 project 创建内核：

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

之后，使用以下命令启动服务器：

$ uv run --with jupyter jupyter lab

创建笔记本时，从下拉菜单中选择 project 内核。然后使用 !uv add pydantic 将 pydantic 添加到项目的依赖项中，或者使用 !uv pip install pydantic 将 pydantic 安装到项目的虚拟环境中，但不会将更改持久化到项目的 pyproject.toml 或 uv.lock 文件中。这两个命令中的任何一个都能使 import pydantic 在笔记本中生效。

不使用内核安装包

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

虽然 uv run --with jupyter 在隔离环境中运行，但在笔记本本身中，即使没有内核，!uv add 及相关命令也会修改项目的环境。

例如，在笔记本中运行 !uv add pydantic 会将 pydantic 添加到项目的依赖项和虚拟环境中，这样 import pydantic 无需进一步配置或重启服务器即可立即生效。

然而，由于 Jupyter 服务器是 “活动” 环境，!uv pip install 会将包安装到 Jupyter 的环境中，而不是项目环境。这些依赖项在 Jupyter 服务器运行期间会一直存在，但在后续调用 jupyter 时可能会消失。

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

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

之后在笔记本中调用 %pip install 会将包安装到项目的虚拟环境中。不过，这些修改不会反映在项目的 pyproject.toml 或 uv.lock 文件中。

将 Jupyter 用作独立工具

如果需要临时访问笔记本（即交互式运行 Python 代码片段），可以随时使用 uv tool run jupyter lab 启动 Jupyter 服务器。这将在隔离环境中运行 Jupyter 服务器。

在非项目环境中使用 Jupyter

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

macOS 和 LinuxWindows

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

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

这样，在笔记本中就可以 import pydantic，还可以通过 !uv pip install 甚至 !pip install 安装其他软件包。

从 VS Code 中使用 Jupyter

也可以在像 VS Code 这样的编辑器中使用 Jupyter 笔记本。要将 uv 管理的项目连接到 VS Code 中的 Jupyter 笔记本，建议为项目创建一个内核，如下所示：

# 创建一个项目。
$ uv init project


# 进入项目目录。
$ cd project


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

在 VS Code 中打开项目。

$ code .

在 VS Code 中打开项目目录后，你可以通过在命令面板中选择“创建：新建 Jupyter 笔记本”来创建一个新的 Jupyter 笔记本。当提示选择内核时，选择“Python 环境”，然后选择你之前创建的虚拟环境（例如，在 macOS 和 Linux 上是 `.venv/bin/python`，在 Windows 上是 `.venv\Scripts\python`）。

!!! 注意

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

如果你需要在笔记本中操作项目的环境，可能需要将 `uv` 作为显式的开发依赖添加：

```console
$ uv add --dev uv

从这开始，你可以使用 !uv add pydantic 将 pydantic 添加到项目的依赖中，或者使用 !uv pip install pydantic 将 pydantic 安装到项目的虚拟环境中，而无需更新项目的 pyproject.toml 或 uv.lock 文件。