uv 实践：在 VS Code 中运行 Jupyter Notebook
A Practical Guide to Python Project Management with uv
为了简化 Python 环境与依赖管理，减少日常使用 Conda 的负担，我准备尝试用 uv 管理 Python 项目。这篇笔记以在 VS Code 中运行 Jupyter Notebook 为例，记录从安装 uv、创建项目到日常维护环境的完整流程。
本文以 macOS / Linux 终端为主，补充 Windows 的差异。示例统一使用 Python 3.12，便于跟随操作；实际项目可以根据依赖的兼容性选择版本。除安装 uv 外，项目相关命令都在
myproject目录下执行。
1. 安装 uv
以下三种安装方式选择一种即可。
1.1 使用官方安装脚本
macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows PowerShell：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
这种方式不需要预先安装 Python。安装完成后，重新打开终端，或按安装程序的提示使环境变量生效。
1.2 使用 Homebrew
如果 macOS 上已经安装了 Homebrew，可以直接执行：
brew install uv
1.3 使用 pip
如果已有可以使用 pip 的 Python 环境，也可以执行：
python -m pip install uv
这里的 python 应指向已有的 Python 解释器，部分系统需要使用 python3。通过 pip 安装的 uv 属于该 Python 环境；对新手而言，官方脚本或 Homebrew 更方便独立管理。如果系统提示 Python 环境由系统包管理器管理，可改用前两种安装方式。
1.4 检查安装与更新
uv --version
能够输出版本号，说明当前终端可以找到 uv。后续更新时，使用与安装方式对应的命令：
| 安装方式 | 更新命令 |
|---|---|
| 官方安装脚本 | uv self update |
| Homebrew | brew upgrade uv |
| pip | python -m pip install --upgrade uv |
安装与更新方式参见 uv 官方安装文档。
2. 创建项目并管理 Python 环境
2.1 创建目录
mkdir myproject
cd myproject
建议一个项目使用一个独立环境，避免不同项目的依赖版本互相影响。
2.2 安装 Python 并初始化项目
# 安装示例所用的 Python 版本
uv python install 3.12
# 在当前目录初始化项目，并指定 Python 版本
uv init --python 3.12
uv python install 管理 Python 解释器，uv init 创建项目配置。初始化时指定版本，可以让项目从一开始就使用合适的 Python。
初始化后，通常会看到 pyproject.toml、.python-version、main.py 和 README.md 等文件。此时不一定已经有 .venv 和 uv.lock，它们会在后续添加依赖或同步环境时生成。
如果之后需要重新指定项目使用的版本，可以执行：
uv python pin 3.12
该命令把版本要求写入 .python-version，供后续 uv 命令选择解释器。它不会同时修改 pyproject.toml 中的 requires-python：前者选择本地使用的版本，后者声明项目兼容的 Python 范围。切换版本时，两者需要保持兼容。
相关说明见 Python 版本管理 与 项目创建。
2.3 安装 Notebook 所需依赖
在 VS Code 中运行 Python Notebook，项目环境需要安装 ipykernel：
uv add --dev ipykernel
ipykernel 负责执行 Notebook 中的 Python 代码。这里使用 --dev，将它记录为开发依赖；默认情况下，uv 会安装 dev 组中的依赖。
如果笔记本需要数据处理和绘图，再添加对应的库：
uv add numpy pandas matplotlib
这些库不是运行 Notebook 的必需项，而是本例用于验证环境的分析工具。uv add 默认会完成依赖解析、更新项目配置与锁文件，并把依赖安装到项目环境中；如果 .venv 不存在，也会自动创建。
uv init、uv add、uv run构成本文采用的项目管理流程，通常不需要额外执行uv venv。
依赖的添加与分组参见 uv 依赖管理文档。
2.4 理解项目中的几个关键文件
完成依赖安装后，项目结构大致如下，部分辅助文件已省略：
myproject/
├── .venv/ # 当前机器上的项目虚拟环境
├── .python-version # uv 选择 Python 时使用的版本要求
├── pyproject.toml # 项目信息、Python 兼容范围和直接依赖
├── uv.lock # 解析后的依赖版本及其安装信息
├── main.py # 初始化生成的示例程序
└── README.md # 项目说明
可以把它们理解为：pyproject.toml 描述“项目需要什么”，uv.lock 记录“具体解析到了哪些版本”，.venv 保存“本机实际安装的环境”。
使用 Git 管理项目时，应提交 pyproject.toml、uv.lock 和 .python-version，并将 .venv/ 加入忽略规则。换电脑时，依靠配置和锁文件重新创建环境即可，无需复制 .venv。参见 uv 项目结构说明。
3. 在 VS Code 中运行 Notebook
3.1 打开项目并选择内核
- 在 VS Code 中安装 Microsoft 发布的 Python 和 Jupyter 扩展。
- 通过“打开文件夹”打开
myproject，也可以在该目录执行code .（需要先配置 VS Code 命令行入口）。 - 新建
demo.ipynb文件。 - 点击 Notebook 右上角的 Select Kernel（选择内核），必要时进入 Select Another Kernel（选择其他内核）→ Python Environments（Python 环境）。
- 选择当前项目
.venv中的 Python。
不同系统对应的解释器路径如下：
| 系统 | 项目解释器路径 |
|---|---|
| macOS / Linux | .venv/bin/python |
| Windows | .venv\Scripts\python.exe |
Notebook 的内核决定单元格实际使用哪个 Python。即使终端中的命令可以正常运行，也需要确认 Notebook 选中了同一个项目环境。VS Code 可以直接选择 .venv，本例不需要额外手动注册内核。参见 uv 与 VS Code 的集成说明。
3.2 验证环境并运行代码
在第一个单元格中检查 Python 路径：
import sys
print(sys.executable)
print(sys.version)
输出路径应位于 myproject/.venv 中。然后在另一个单元格中运行：
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
x = np.linspace(0, 2 * np.pi, 100)
data = pd.DataFrame({"x": x, "sin_x": np.sin(x)})
print(data.head())
plt.plot(data["x"], data["sin_x"])
plt.xlabel("x")
plt.ylabel("sin(x)")
plt.title("uv + Jupyter")
plt.show()
如果能够显示数据和曲线，就完成了从项目环境到 Notebook 内核的验证。VS Code 中的 Notebook 基本操作可参考 官方使用指南。
3.3 可选：使用浏览器中的 JupyterLab
如果还希望在浏览器中使用 JupyterLab，可以将它加入开发依赖并启动：
uv add --dev jupyterlab
uv run jupyter lab
按终端输出的地址打开页面即可。uv run 会在项目环境中执行命令，因此不需要先手动激活 .venv。只在 VS Code 中运行 .ipynb 时，前面安装的 ipykernel 已经足够，无需再安装 JupyterLab。参见 uv 的 Jupyter 集成文档。
4. 后续常用的 uv 命令
4.1 添加、删除和查看依赖
以下命令按需使用，不必依次执行：
# 添加项目依赖
uv add requests
# 添加带版本范围的依赖；引号用于避免 shell 解释特殊字符
uv add "requests>=2.31,<3"
# 添加开发依赖
uv add --dev pytest
# 删除对应类别的直接依赖
uv remove requests
uv remove --dev pytest
# 查看依赖树
uv tree
4.2 运行 Python 程序
# 运行初始化生成的示例程序
uv run python main.py
# 进入项目环境的 Python 交互终端
uv run python
# 查看项目实际使用的 Python 版本
uv run python --version
日常执行项目命令时，优先使用 uv run，可以减少误用系统 Python 或其他虚拟环境的情况。
4.3 同步环境与复现项目
手动修改 pyproject.toml 后，使用：
uv sync
从仓库获取项目后，如果项目已经提交了有效的 uv.lock，可以使用：
uv sync --locked
uv sync 根据项目配置和锁文件同步 .venv，必要时更新锁文件；--locked 要求锁文件已经存在且与项目配置一致，否则报错，避免复现环境时无意改写锁定结果。
uv sync默认会移除环境中不属于当前同步依赖集合的包。因此，需要长期保留的依赖应通过uv add记录到项目的pyproject.toml文件中。
4.4 升级依赖
普通的 uv sync 不会仅因为有新版本发布就升级所有依赖。需要主动升级时，可以按需执行：
# 在项目版本约束允许的范围内升级某个包，并同步环境
uv sync --upgrade-package numpy
# 在项目版本约束允许的范围内升级全部依赖，并同步环境
uv sync --upgrade
升级后应重新运行项目代码或 Notebook，确认兼容性。同步、锁定与升级的具体行为参见 uv 锁定与同步文档。
5. 常见问题
5.1 终端提示找不到 uv
先重新打开终端；如果仍提示 command not found，检查安装程序提示的安装目录是否已经加入 PATH。如果是通过 pip 安装，还要确认当前终端能够访问对应 Python 环境的可执行文件目录。
5.2 Notebook 提示找不到已安装的包
先运行 print(sys.executable) 检查 Notebook 是否使用当前项目的 .venv，再检查依赖是否已经通过 uv add 添加。新增依赖或升级包后，必要时重启 Notebook 内核。
如果 .venv 没有出现在内核列表中，可先在项目目录执行 uv sync，确认安装了 ipykernel，再重新加载 VS Code 窗口并选择内核。
5.3 uv add 和 uv pip install 有什么区别？
| 命令 | 主要用途 | 是否更新项目依赖声明和锁文件 |
|---|---|---|
uv add 包名 | 为 uv 项目添加并安装依赖 | 默认会更新 pyproject.toml 和 uv.lock |
uv pip install 包名 | 向目标 Python 环境安装包 | 不会更新这两个项目文件 |
本文采用项目管理方式，所以日常安装依赖使用 uv add。在 Notebook 中需要新包时，也建议回到项目终端执行该命令，让依赖记录与实际环境保持一致。两种方式的区别见 uv 的 Jupyter 环境管理说明。