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

uv 与 Jupyter 集成实战项目内核创建、环境隔离与笔记本内依赖管理【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv在 Jupyter 集成指南 所覆盖的场景中uv 与 Jupyter 的组合可以按三种层次使用在 uv 项目内启动带项目环境访问权限的 Jupyter 服务器、为项目创建专用内核kernel以便在笔记本中安装并持久化依赖、以及将 Jupyter 作为独立工具或临时环境使用。读完本篇你将掌握uv run --with、ipykernel内核注册、uv venv --seed等关键命令的正确用法理解笔记本内!uv add与!uv pip install在“有内核/无内核”两种模式下分别作用于哪个环境的底层原因并能在 VS Code 中把 uv 管理的项目与 Jupyter 笔记本正确连接起来。在项目内启动 Jupyteruv run --with jupyter当你在一个 uv 项目 中工作时可以直接用下面这条命令启动一个能够访问项目虚拟环境的 Jupyter 服务器$ uv run --with jupyter jupyter labjupyter 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 environmentin 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中的临时环境但笔记本进程连接的是项目的虚拟环境因此在笔记本中安装的包会落到项目的虚拟环境里。操作步骤将ipykernel作为开发依赖安装到项目中$ uv add --dev ipykernel为项目创建并注册一个名为project的内核$ uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --nameproject这里--env VIRTUAL_ENV $(pwd)/.venv明确告诉内核“你的解释器所在环境是项目根目录下的.venv”--nameproject则决定它在 Jupyter 界面下拉菜单中的显示名称。启动服务器$ uv run --with jupyter jupyter lab创建新笔记本时从内核下拉菜单中选择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并清楚它装在临时环境要安装进项目环境且不进锁文件则先创建内核。让%pipmagic 可用uv venv --seed如果你的笔记本依赖 pip例如使用%pip installmagic默认由 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 ofpip,setuptools, andwheel) into the virtual environment. Note thatsetuptoolsandwheelare 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 labuv 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 labWindowsPowerShellPS 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 中使用 Jupyteruv 管理的 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/pythonWindows 下为.venv\Scripts\python。有两个前提条件需要注意环境内必须存在ipykernel。VS Code 依赖ipykernel才能以该环境为内核运行笔记本。如果不希望把它列为开发依赖也可以直接用uv pip install ipykernel装进项目环境效果相同。若要在笔记本内操作项目环境可能需要把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做依赖管理而不用担心解析质量。小结场景推荐做法包安装去向项目内只读使用 Jupyteruv run --with jupyter jupyter lab服务器在临时环境导入来自项目.venv笔记本内持久化装包创建内核ipykernelipython kernel install后!uv add项目pyproject.tomluv.lock.venv一次性装包不进锁文件内核下!uv pip install仅项目.venv无内核时误用!uv pip install注意其装入 Jupyter 临时环境Jupyter 隔离环境临时兼容%pipmagicuv venv --seed后再启动项目.venv不进锁文件临时/无项目uv tool run jupyter lab工具隔离环境非项目.venvuv venv --seeduv pip install jupyterlab该.venvVS Code 集成项目内核 环境内含ipykernel同“笔记本内持久化装包”以上行为以本仓库docs/guides/integration/jupyter.md的官方描述为准参数语义均可在 crates/uv-cli/src/lib.rs 中对应的子命令结构体里核对。【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考