（四）用 uv 管理项目

1. 建立 Python 3.12 项目

uv 可以管理 Python 版本、项目依赖和运行环境。安装方法见 uv 官方安装说明。在已经能够运行 Python 3.12 的终端中，也可以用下面的方式安装 uv：

# 用 Python 3.12 对应的 pip 安装 uv 命令行工具。
py -3.12 -m pip install uv
# 确认终端能够找到 uv。
uv --version

接下来建立另一个项目 reading-uv：

# 获取 3.12 解释器并建立应用项目。
uv python install 3.12
uv init --app --python 3.12 reading-uv
cd reading-uv
# 明确记录这个项目使用的 Python 系列。
uv python pin 3.12
# 添加运行依赖；同时更新项目声明、锁定文件和项目环境。
uv add "httpx==0.28.1"
# 用项目环境执行 Python 文件。
uv run main.py

把项目中的 main.py 改成上一节的 package_check.py 内容，再执行 uv run main.py，就会输出 HTTPX 版本。uv run 会使用项目环境，不必先手动激活它。

2. 声明、锁定、同步与运行

uv init --python 3.12 生成的项目通常写入 requires-python = ">=3.12"。这表示项目声明支持从 3.12 开始的版本；.python-version 则告诉 uv 当前项目默认选 3.12。想让一个复现实验只选择 3.12 系列，可以把前者写成 ">=3.12,<3.13"，随后重新锁定。

# pyproject.toml 中的项目声明，供本章安装练习使用。
[project]
name = "reading-uv"
version = "0.1.0"
requires-python = ">=3.12,<3.13"
dependencies = ["httpx==0.28.1"]

保存后，分步执行：

# 读取依赖声明，生成或更新锁定记录。
uv lock
# 按项目和锁定记录同步 .venv 中的依赖。
uv sync
# 在同步的项目环境中运行程序。
uv run main.py

uv add 会连着完成多个更新动作。图中把声明、锁定、同步与运行分开，是为了观察每一步读取和改变的内容。uv run 也会检查项目与环境的状态。uv 项目指南

3. 修改依赖、开发工具与环境重建

# 把 pytest 加入开发依赖组，供以后运行测试。
uv add --dev pytest
# 在项目环境中运行这个开发工具。
uv run pytest --version
# 查看直接和间接依赖的关系。
uv tree
# 删除一个开发依赖，同时更新声明、锁定结果和环境。
uv remove --dev pytest

这里的“运行依赖”是程序工作时要导入的包，“开发依赖”是编写、测试和检查程序时使用的工具。以后把自己的代码做成包，还会用到 pip install -e . 或 uv add --editable ../某个包：安装后继续编辑源文件，导入时就使用这份源代码。包目录与构建配置会在项目组织章节中实际建立。

更新单个依赖时，例如把严格版本声明改成 httpx>=0.28,<0.29，再执行：

# 在项目声明的版本范围内，重新选择 HTTPX 的版本。
uv lock --upgrade-package httpx
# 把锁定结果应用到项目环境。
uv sync

复制项目到另一台电脑时，带上源代码、pyproject.toml、.python-version 和 uv.lock。在项目目录执行 uv sync --locked，再运行 uv run main.py。--locked 会检查锁定文件与声明是否一致，声明改变而锁定记录没有更新时会报错，提醒我们先完成解析。

.venv 里保存的是本机环境，路径与系统相关；它放入 Git 忽略规则，依赖声明和锁定文件则随项目保存。用它们重新建立环境，比复制整个 .venv 更直接。

4. uv pip 与 uv 项目管理

也可以只用 uv 创建环境和安装包：

# 在新的文件夹中建立一个 3.12 环境。
uv venv --python 3.12 .venv
# 为找到的虚拟环境安装一个包。
uv pip install --python .venv "httpx==0.28.1"
# 查看这个环境中已经安装的包。
uv pip list --python .venv

这里用 --python .venv 明确选中刚创建的环境。uv pip install 改变的是环境中的安装结果。uv add 则把依赖写入项目声明，并更新锁定与环境。可以自己做一次对照：手动安装一个没有写进项目声明的包，再执行 uv sync，观察它怎样按项目记录重新同步环境。工具命令的相似外观，不代表它们保存了相同的信息。uv 环境指南