在 Jupyter 中使用 uv
Jupyter Notebook 是一种流行的交互式计算、数据分析和可视化工具。你可以通过多种方式将 Jupyter 与 uv 结合使用，既可以用于与项目交互，也可以将其作为独立工具使用。
在项目中使用 Jupyter
如果你在项目内工作，可以通过以下命令启动 Jupyter 服务器，以访问项目的虚拟环境：
默认情况下，jupyter lab 会在 https://:8888/lab 启动服务器。
在 Notebook 内部，你可以像在项目中的任何其他文件一样导入项目的模块。例如，如果你的项目依赖于 requests，import requests 将从项目的虚拟环境中导入 requests。
如果你只需要对项目虚拟环境进行只读访问，那么到此为止即可。但是，如果你需要在 Notebook 内部安装额外的包，还有一些额外的细节需要注意。
创建内核 (Kernel)
如果你需要在 Notebook 内部安装包，我们建议为你的项目创建一个专用的内核。内核使 Jupyter 服务器能够在一个环境中运行，而各个 Notebook 则在它们自己独立的环境中运行。
在 uv 的上下文中，我们可以为项目创建一个内核，同时将 Jupyter 本身安装在隔离的环境中，如 uv run --with jupyter jupyter lab。为项目创建内核可确保 Notebook 连接到正确的环境，并且从 Notebook 内部安装的任何包都会安装到项目的虚拟环境中。
要创建内核，你需要将 ipykernel 安装为开发依赖项：
然后，你可以使用以下命令为 project 创建内核：
接下来，使用以下命令启动服务器：
创建 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 包含在项目的虚拟环境中。例如：
随后的 Notebook 内 %pip install 调用将把包安装到项目的虚拟环境中。但是，这些修改将“不会”反映在项目的 pyproject.toml 或 uv.lock 文件中。
将 Jupyter 作为独立工具使用
如果你需要临时访问 Notebook（例如交互式运行一段 Python 代码），可以随时使用 uv tool run jupyter lab 启动 Jupyter 服务器。这将在隔离环境中运行 Jupyter 服务器。
在非项目环境中使用 Jupyter
如果你需要在未与项目关联的虚拟环境中运行 Jupyter（例如没有 pyproject.toml 或 uv.lock），你可以直接将 Jupyter 添加到环境中。例如：
从这里开始，import pydantic 将在 Notebook 中工作，你可以通过 !uv pip install 甚至 !pip install 安装额外的包。
在 VS Code 中使用 Jupyter
你也可以在 VS Code 等编辑器中使用 Jupyter Notebook。要将 uv 管理的项目连接到 VS Code 中的 Jupyter Notebook，我们建议按如下方式为项目创建内核：
# Create a project.
$ uv init project
# Move into the project directory.
$ cd project
# Add ipykernel as a dev dependency.
$ uv add --dev ipykernel
# Open the project in 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 添加为显式的开发依赖项：
之后，你可以使用 !uv add pydantic 将 pydantic 添加到项目的依赖项中，或者使用 !uv pip install pydantic 将 pydantic 安装到项目的虚拟环境中，而不更新项目的 pyproject.toml 或 uv.lock 文件。