uv 实战指南：用一个工具重塑 Python 开发工作流

uv 实战指南：用一个工具重塑 Python 开发工作流

适读对象 ：熟悉 Python 基础，了解 pip、venv 或 requirements.txt 的基本用法。
阅读目标 ：理解 uv 的核心概念，并能在新项目、老项目、脚本、CLI 工具和 CI/CD 中快速落地。
参考文档 ：本文基于 uv 官方文档整理，建议搭配 https://docs.astral.sh/uv/ 一起阅读。

---

1. uv 是什么：它解决了 Python 工具链的哪些问题

1.1 一句话理解 uv

uv 是 Astral 使用 Rust 编写的 Python 包管理器和项目管理器。

它的目标不是单纯做一个"更快的 pip"，而是把 Python 日常开发中分散在多个工具里的能力整合起来：

• 安装依赖：替代 pip install
• 创建虚拟环境：替代 python -m venv
• 锁定依赖：替代 pip-tools
• 运行和安装 CLI 工具：替代 pipx
• 管理 Python 版本：替代一部分 pyenv 场景
• 初始化项目、运行项目、构建和发布项目：覆盖 Poetry / PDM / Rye 的部分工作流

1.2 为什么 Python 开发者需要 uv

Python 工具链长期存在一个问题：不同任务需要不同工具，学习和维护成本都不低。

开发场景	传统方案	uv 方案
安装依赖	pip install	uv add / uv pip install
创建虚拟环境	python -m venv	uv venv，或由项目命令自动创建
锁定依赖	pip-compile	uv lock
同步环境	pip-sync	uv sync
运行 CLI 工具	pipx run / pipx install	uvx / uv tool install
管理 Python 版本	pyenv	uv python install
初始化项目	poetry new / cookiecutter	uv init
构建发布	python -m build / twine upload	uv build / uv publish

uv 的价值在于：用一个统一的命令体系，覆盖 Python 开发从创建项目到发布包的大部分流程。

1.3 uv 为什么快

uv 的速度优势主要来自三点：

1. Rust 实现：依赖解析、下载、安装等核心流程由原生代码完成。
2. 全局缓存：多个项目共享缓存，避免重复下载和重复构建。
3. 并行执行：依赖解析、下载、安装尽量并行化。

因此，uv 不是"稍微快一点的 pip"，而是把依赖管理的整体体验重新设计了一遍。

---

2. 安装与首次运行

2.1 安装 uv

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"

也可以通过常见包管理器安装：

pip install uv
brew install uv

2.2 验证安装

uv
uv --version

能看到帮助菜单或版本号，就说明安装成功。

2.3 uv 的默认行为

uv 的设计理念是：尽量让常见操作不需要额外配置。

例如：

• 没有虚拟环境时，项目命令可以自动创建 .venv。
• 缺少指定 Python 版本时，uv 可以自动下载。
• 运行项目命令时，uv 会自动检查依赖是否需要同步。
• 添加依赖时，uv 会同步更新 pyproject.toml、uv.lock 和虚拟环境。

这也是 uv 上手体验顺滑的原因：你不必先记住一堆环境管理细节，先用起来，再逐步理解背后的模型。

---

3. 核心心智模型：五类使用场景

学习 uv 时，不建议一开始死记命令。更好的方式是先把它理解成五类使用场景。

uv
├── Project：正式项目管理
├── Script：单文件脚本运行
├── Tool：CLI 工具运行与安装
├── Python：Python 版本管理
└── pip interface：兼容 pip 的底层接口

场景	核心命令	适合解决什么问题
Project	uv init、uv add、uv sync、uv lock、uv run	管理有 pyproject.toml 的正式项目
Script	uv run script.py、uv add --script	运行单文件脚本，并让脚本自己声明依赖
Tool	uvx、uv tool install	临时运行或长期安装 Python CLI 工具
Python	uv python install、uv python list、uv python pin	安装、查看、固定 Python 版本
pip interface	uv pip install、uv pip compile、uv pip sync	兼容传统 pip / requirements.txt 工作流

最常用、也最推荐优先掌握的是 Project 工作流。

---

4. 项目管理：最推荐的 uv 工作流

Project 是 uv 的核心能力，对标 Poetry、PDM、Rye 等现代 Python 项目管理工具。

4.1 创建项目

uv init my-project
cd my-project

uv init 默认创建的是 application 项目，适合 Web 服务、脚本和普通应用；如果你要创建可发布到 PyPI 的库或带 package 入口的项目，可以使用 uv init --lib 或 uv init --package。默认 application 项目不会自动带 [build-system]，因此它本身通常不会作为 package 安装进环境。

典型默认 application 项目结构如下：

my-project/
├── .python-version      # 项目使用的 Python 版本
├── README.md
├── main.py              # 示例入口文件
└── pyproject.toml       # 项目元数据与依赖声明

首次执行 uv run、uv sync 或 uv lock 后，通常还会出现：

my-project/
├── .venv/               # 项目虚拟环境，不提交 Git
└── uv.lock              # 锁文件，建议提交 Git

pyproject.toml 的最小结构大致如下：

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

4.2 添加和移除依赖

添加普通依赖：

uv add httpx
uv add "fastapi>=0.100"

添加开发依赖：

uv add --dev pytest
uv add --dev ruff

从 requirements.txt 导入依赖：

uv add -r requirements.txt

从 Git 仓库添加依赖：

uv add "httpx @ git+https://github.com/encode/httpx"

从特定 index 添加依赖，例如 PyTorch CPU 版：

uv add torch --index pytorch=https://download.pytorch.org/whl/cpu

移除依赖：

uv remove httpx

uv add 的价值在于：它不只是"安装包"，而是会同时更新：

1. pyproject.toml
2. uv.lock
3. 当前项目的 .venv

这比手动修改 requirements.txt 再安装更加一致。

4.3 运行项目命令

uv run python main.py
uv run pytest
uv run ruff check .

uv run 会在项目环境中执行命令，并在运行前自动检查：

1. .venv 是否存在；不存在则创建。
2. uv.lock 是否需要更新。
3. 当前环境是否与 lockfile 同步。

因此，很多时候你不需要先手动激活虚拟环境：

# 传统方式
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

# uv 方式
uv run python main.py

在 Windows PowerShell 中，如果你确实想手动激活虚拟环境，可以这样做：

uv sync
.venv\Scripts\activate
python main.py

4.4 lock 与 sync：两个必须理解的概念

uv 项目管理的核心是三件事：

pyproject.toml  →  uv.lock  →  .venv
依赖声明          精确锁定       实际安装环境

文件 / 命令	作用
pyproject.toml	声明项目元数据和依赖范围
uv.lock	记录依赖解析后的精确版本，建议提交 Git
.venv	项目的实际虚拟环境，不提交 Git
uv lock	更新锁文件，但不一定安装依赖
uv sync	按照锁文件同步虚拟环境
uv run	在项目环境中运行命令，并自动处理必要的 lock / sync

显式更新 lockfile：

uv lock

同步环境：

uv sync

排除开发依赖：

uv sync --no-dev

只安装开发依赖：

uv sync --only-dev

4.5 extras 与 dependency groups

uv 支持两类常见的依赖分组方式。

第一类是 optional dependencies / extras，通常用于可选功能：

uv add --optional gpu torch
uv sync --extra gpu

uv sync --extra gpu 的意思是：同步项目环境时，额外安装名为 gpu 的 optional dependencies。

第二类是 dependency groups，常用于本地开发、测试、文档等场景：

uv add --dev pytest
uv add --group docs mkdocs
uv sync --group docs
uv sync --all-groups

可以这样区分：

类型	常见用途	是否面向包使用者
extras	gpu、postgres、redis 等可选功能	是
dependency groups	dev、test、docs、lint 等开发工作流	更多面向项目维护者

4.6 查看依赖树

uv tree

它可以帮助你理解某个包为什么被安装、是谁间接依赖了它。

4.7 构建与发布

构建源码包和 wheel：

uv build

发布到 PyPI：

uv publish

对于只开发应用、不发布 Python 包的项目，这部分可以暂时跳过；对于库作者，则建议深入理解构建后端、包元数据和发布流程。

---

5. 脚本运行：单文件也能声明依赖

uv 的脚本模式非常适合一次性工具、数据清洗脚本、教学示例和可复制的小脚本。

5.1 临时运行带依赖的脚本

如果脚本依赖 pandas 和 openpyxl，可以不创建项目，直接运行：

uv run --with pandas --with openpyxl clean_excel.py

这种方式适合临时使用，但依赖不会写入脚本本身。

5.2 PEP 723 内联元数据

更推荐的方式是把依赖写进脚本文件顶部：

# /// script
# dependencies = [
#     "requests<3",
#     "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
pprint(resp.json())

运行：

uv run example.py

uv 会为这个脚本创建隔离环境，安装脚本声明的依赖，然后执行脚本。

5.3 给脚本添加依赖

uv add --script example.py "requests<3" rich

这会自动把依赖写入脚本顶部的 metadata 区块。

5.4 声明 Python 版本

# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///

如果本机没有合适的 Python 版本，uv 可以按需下载。

5.5 Shebang 支持

#!/usr/bin/env -S uv run --script

# /// script
# dependencies = ["httpx"]
# ///

import httpx
print(httpx.get("https://example.com"))

给脚本增加可执行权限后，可以直接运行：

chmod +x my_script
./my_script

5.6 锁定脚本依赖

uv lock --script example.py

这会生成：

example.py.lock

如果你希望脚本在团队、CI 或未来时间点保持更强复现性，可以把 .lock 文件一起提交。

---

6. 工具运行与安装：替代 pipx 的体验

很多 Python 包本质上是 CLI 工具，例如 ruff、black、httpie、pycowsay。uv 为这类场景提供了两种方式。

6.1 临时运行工具：uvx

uvx 是 uv tool run 的别名。

uvx pycowsay "hello uv"
uvx ruff check .
uvx black --check .

指定版本：

uvx ruff@0.6.0 check .
uvx ruff@latest check .

如果包名和命令名不同，可以用 --from：

uvx --from httpie http GET https://example.com

6.2 长期安装工具

uv tool install ruff
uv tool install black

安装后可以直接使用：

ruff --version

查看已安装工具：

uv tool list

升级工具：

uv tool upgrade ruff
uv tool upgrade --all

卸载工具：

uv tool uninstall ruff

6.3 uvx、uv tool install 与 uv run 怎么选

命令	适合场景	生命周期	是否依赖当前项目环境
uvx <tool>	偶尔运行一次 CLI 工具	临时	否
uv tool install <tool>	长期使用某个 CLI 工具	持久	否
uv run <cmd>	在当前项目中运行测试、格式化、应用入口	跟随项目	是

一个实用原则：

• 项目里的 pytest、ruff、mypy，优先用 uv run。
• 临时试用一个外部工具，用 uvx。
• 每天都要用的全局工具，用 uv tool install。

---

7. Python 版本管理：让 uv 帮你安装解释器

uv 也可以安装和管理 Python 解释器。

7.1 安装 Python

uv python install 3.12
uv python install 3.11 3.12
uv python install 3.12.3
uv python install pypy

7.2 查看 Python 版本

uv python list
uv python list --only-installed
uv python list 3.12

7.3 固定项目 Python 版本

uv python pin 3.12

这会创建或更新 .python-version。

全局固定：

uv python pin --global 3.12

7.4 自动下载 Python

当你运行下面命令时：

uv venv --python 3.11
uv run --python 3.10 python --version

如果对应版本不存在，uv 可以自动下载并使用。

7.5 Managed Python 与 System Python

类型	含义
Managed Python	由 uv 下载和管理的 Python
System Python	系统已有的 Python，包括系统自带、手动安装、pyenv 安装等

多数时候你不需要关心 uv 最后选择了哪一种；只有在企业环境、固定系统解释器或特殊部署场景中，才需要显式控制。

---

8. pip 兼容接口：老项目的渐进式迁移方案

如果你手上的项目仍然使用 requirements.txt，不必立刻迁移到 pyproject.toml + uv.lock。uv 提供了 uv pip 接口，方便你渐进式替换传统工具链。

8.1 创建虚拟环境

uv venv
uv venv --python 3.12

8.2 安装依赖

uv pip install requests
uv pip install "fastapi[all]"
uv pip install -r requirements.txt

8.3 编译依赖：替代 pip-compile

uv pip compile requirements.in -o requirements.txt

生成跨平台 requirements：

uv pip compile requirements.in --universal -o requirements.txt

8.4 同步环境：替代 pip-sync

uv pip sync requirements.txt

它会让当前虚拟环境与 requirements.txt 保持一致。

8.5 常用 pip 兼容命令

uv pip list
uv pip freeze
uv pip show requests
uv pip check
uv pip tree
uv pip uninstall requests

8.6 什么时候用 uv pip，什么时候用 uv project

场景	推荐方式
老项目暂时不想改结构	uv pip
新项目	uv init + uv add + uv run
团队项目需要 lockfile	uv.lock
仍要输出 requirements.txt 给部署平台	uv export

---

9. 依赖解析：理解 universal lockfile

uv.lock 是 uv 项目管理中最重要的文件之一。

9.1 什么是 universal lockfile

传统 requirements.txt 往往和当前平台绑定：你在 macOS 上生成的文件，在 Linux、Windows 或不同 Python 版本中可能出现差异。

uv 的 uv.lock 是跨平台的，它可以记录不同平台、不同 Python 版本下需要的依赖版本，并通过 environment markers 区分安装条件。

换句话说：

requirements.txt：更像某个环境的一次冻结结果
uv.lock：更像整个项目在多个环境下的完整依赖解析结果

9.2 解析策略

默认更新 lockfile：

uv lock

使用最低版本解析，用来测试依赖下界：

uv lock --resolution lowest

直接依赖用最低版本，间接依赖用最新版本：

uv lock --resolution lowest-direct

9.3 限制解析环境

如果你的项目只支持 macOS 和 Linux，可以在 pyproject.toml 中限制环境：

[tool.uv]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
]

这样可以减少无关平台带来的解析复杂度。

9.4 requires-python 的影响

[project]
requires-python = ">=3.8"

这意味着 uv 需要保证依赖集合兼容 Python 3.8 及以上版本。

如果某个依赖的新版本只支持 Python 3.9+，uv 可能会在同一个 lockfile 中为不同 Python 版本记录不同的包版本。

9.5 依赖冲突与 overrides

当上游依赖声明不合理，导致解析失败时，可以使用 overrides 做强制覆盖：

[tool.uv]
override-dependencies = ["cryptography==42.0.0"]

这属于高级能力。正常项目中应优先修正依赖声明，而不是一上来使用 override。

---

10. 缓存机制：uv 为什么这么快

10.1 全局缓存

uv 使用全局缓存。多个项目安装同一个包时，不需要反复下载和构建。

典型流程是：

第一次安装 requests：下载 → 构建/解压 → 写入缓存
第二次安装 requests：复用缓存 → 快速链接到环境

这也是 uv 在多项目、多虚拟环境场景下非常快的原因。

10.2 不同依赖类型的缓存依据

依赖类型	常见缓存依据
PyPI 包	HTTP 缓存信息、包版本与文件内容
Git 依赖	commit hash
URL 依赖	URL 与 HTTP 缓存信息
本地目录	项目元数据文件、文件修改时间等

10.3 缓存管理命令

uv cache dir
uv cache clean
uv cache clean ruff
uv cache prune
uv cache prune --ci

常用解释：

命令	作用
uv cache dir	查看缓存目录
uv cache clean	清空全部缓存
uv cache clean <pkg>	清理某个包的缓存
uv cache prune	清理不再需要的缓存条目
uv cache prune --ci	面向 CI 的缓存清理策略

10.4 强制刷新与重装

重新验证缓存：

uv sync --refresh

只刷新某个包：

uv sync --refresh-package ruff

强制重装：

uv sync --reinstall

---

11. Workspace：大型项目与 Monorepo 方案

Workspace 适合一个仓库里维护多个相关 Python 包的场景，类似 Rust Cargo workspace 的设计。

11.1 典型结构

my-monorepo/
├── pyproject.toml           # workspace root
├── uv.lock                  # 整个 workspace 共享一个 lockfile
└── packages/
    ├── core-lib/
    │   ├── pyproject.toml
    │   └── src/core_lib/__init__.py
    └── web-app/
        ├── pyproject.toml
        └── src/web_app/__init__.py

11.2 根项目配置

[project]
name = "my-monorepo"
version = "0.1.0"
dependencies = ["core-lib", "web-app"]

[tool.uv.sources]
core-lib = { workspace = true }
web-app = { workspace = true }

[tool.uv.workspace]
members = ["packages/*"]

11.3 运行 workspace 中某个包的命令

uv run --package core-lib pytest
uv run --package web-app python -m web_app

11.4 成员间依赖

# packages/web-app/pyproject.toml
[project]
dependencies = ["core-lib"]

[tool.uv.sources]
core-lib = { workspace = true }

workspace 成员之间通常以可编辑方式安装。修改 core-lib 后，web-app 可以直接使用最新代码，而不需要反复发布内部包。

---

12. 配置体系：配置文件、环境变量与命令行参数

uv 支持多层配置。理解配置优先级，有助于排查"为什么这个命令在不同机器上表现不一样"。

12.1 配置优先级

从低到高大致可以理解为：

系统级配置 → 用户级配置 → 项目级配置 → 环境变量 → 命令行参数

也就是说，命令行参数通常优先级最高。

12.2 项目级配置

在 pyproject.toml 中配置默认 package index，推荐使用 [[tool.uv.index]]：

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

也可以使用独立的 uv.toml。uv.toml 的结构与 pyproject.toml 中的 uv 配置基本一致，但要去掉 [tool.uv] 前缀：

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

如果同一目录同时存在 uv.toml 和 pyproject.toml，uv 会优先读取 uv.toml，并忽略该目录下 pyproject.toml 中的 [tool.uv] 配置。

12.3 环境变量

uv 的许多配置都有对应环境变量，常见格式是 UV_<SETTING>：

export UV_CACHE_DIR="/tmp/uv-cache"
export UV_PYTHON="3.12"
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

12.4 .env 文件

uv run --env-file .env python main.py
uv run --env-file .env --env-file .env.local python main.py

这对 Web 应用、本地开发和多环境配置很有用。

12.5 临时忽略配置

uv run --no-config python main.py
uv run --config-file my-uv.toml python main.py

---

13. 构建与发布：从源码到 PyPI

uv 不仅能管理依赖，也能参与构建和发布流程。

13.1 构建项目

uv build

通常会生成：

dist/
├── my_project-0.1.0.tar.gz
└── my_project-0.1.0-py3-none-any.whl

13.2 发布项目

uv publish

如果你只是开发内部应用，不需要发布包，可以暂时不深入这部分。

13.3 uv_build 构建后端

uv 提供自己的构建后端 uv_build。

[build-system]
requires = ["uv_build>=0.11.8,<0.12"]
build-backend = "uv_build"

适合：

• 纯 Python 包
• 结构相对标准的项目
• 希望使用 uv 默认构建体验的项目

不太适合：

• 需要编译 C / Rust 扩展的包
• 构建流程非常复杂的项目
• 已经深度依赖 setuptools、maturin、scikit-build 或 hatchling 的项目

---

14. CI/CD 集成实践

14.1 GitHub Actions 示例

- name: Install uv
  uses: astral-sh/setup-uv@v4

- name: Install dependencies
  run: uv sync --locked

- name: Run tests
  run: uv run --locked pytest

--locked 的作用是：如果 pyproject.toml 和 uv.lock 不一致，则直接失败，而不是在 CI 中悄悄更新 lockfile。

14.2 缓存优化

- name: Cache uv
  uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
    restore-keys: |
      uv-${{ runner.os }}-

- name: Prune cache
  run: uv cache prune --ci

14.3 Docker 示例

FROM python:3.12-slim

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# 先复制依赖文件，利用 Docker 层缓存
COPY pyproject.toml uv.lock ./

# 先只安装第三方依赖，不安装当前项目本身
RUN uv sync --frozen --no-dev --no-install-project

# 再复制源码
COPY . .

# 如果这是 packaged application，需要再安装当前项目本身；
# 如果只是默认 application 且没有 build-system，这一步通常不会安装项目包。
RUN uv sync --frozen --no-dev

CMD ["uv", "run", "--frozen", "--no-sync", "python", "main.py"]

说明：

• --frozen：使用现有 lockfile，不尝试更新。
• --no-dev：排除开发依赖。
• --no-install-project：在源码尚未复制完整时，先只安装第三方依赖，方便 Docker 缓存复用。
• --no-sync：运行阶段不再检查和同步环境，避免容器启动时发生额外安装。

---

15. 从其他工具迁移到 uv

15.1 从 pip + requirements.txt 迁移

渐进式方式：

uv venv
uv pip sync requirements.txt

现代项目方式：

uv init
uv add -r requirements.txt
uv run python main.py

如果部署平台仍要求 requirements.txt，可以导出：

uv export --format requirements.txt -o requirements.txt

15.2 从 pipx 迁移

# pipx run 替代
uvx ruff check .

# pipx install 替代
uv tool install ruff

15.3 从 pyenv 迁移

uv python install 3.12
uv python pin 3.12

需要注意的是，uv 不一定要完全替代 pyenv。对于已经依赖 pyenv 的团队，也可以让 uv 使用现有的 system Python。

15.4 从 Poetry 迁移

迁移时重点关注三件事：

1. 依赖声明是否从 Poetry 私有格式迁移到 PEP 621 的 [project]。
2. 是否用 uv.lock 替代 poetry.lock。
3. 原有的 scripts、extras、dev dependencies 是否正确迁移。

不建议盲目删除 Poetry 配置后直接运行。更稳妥的方式是先建立一个分支，完成依赖和测试迁移，再合并。

---

16. 常用命令速查表

16.1 项目管理

uv init                       # 创建新项目
uv add <pkg>                  # 添加依赖
uv add --dev <pkg>            # 添加开发依赖
uv remove <pkg>               # 移除依赖
uv lock                       # 更新锁文件
uv sync                       # 同步环境
uv run <cmd>                  # 在项目环境中运行命令
uv tree                       # 查看依赖树
uv build                      # 构建分发包
uv publish                    # 发布到 PyPI

16.2 脚本

uv run script.py              # 运行脚本
uv run --with pandas script.py # 临时带依赖运行脚本
uv add --script script.py <pkg> # 给脚本添加内联依赖
uv lock --script script.py    # 锁定脚本依赖
uv init --script script.py    # 初始化脚本 metadata

16.3 工具

uvx <tool>                    # 临时运行工具
uvx <tool>@<version>          # 指定版本运行工具
uv tool install <tool>        # 长期安装工具
uv tool uninstall <tool>      # 卸载工具
uv tool list                  # 列出已安装工具
uv tool upgrade <tool>        # 升级工具

16.4 Python 版本

uv python install 3.12        # 安装 Python
uv python list                # 查看可用版本
uv python pin 3.12            # 固定项目 Python 版本
uv python find                # 查找 Python 可执行文件

16.5 pip 兼容接口

uv venv                       # 创建虚拟环境
uv pip install <pkg>          # 安装包
uv pip install -r requirements.txt
uv pip compile in -o out      # 编译依赖
uv pip sync requirements.txt  # 同步环境
uv pip list                   # 列出包
uv pip tree                   # 查看依赖树

16.6 缓存

uv cache dir                  # 查看缓存目录
uv cache clean                # 清空缓存
uv cache clean <pkg>          # 清理指定包缓存
uv cache prune                # 清理无用缓存
uv cache prune --ci           # CI 场景缓存优化

---

附录：关键概念速记

概念	说明
pyproject.toml	项目元数据和依赖声明文件
uv.lock	跨平台 lockfile，建议提交 Git
.venv	项目虚拟环境，不提交 Git
.python-version	项目 Python 版本提示文件
tool.uv.sources	指定依赖来源，如 Git、path、workspace、index
requires-python	项目支持的 Python 版本范围
dependency-groups	开发、测试、文档等依赖分组
optional-dependencies	extras，可选功能依赖
uvx	uv tool run 的别名
uv_build	uv 提供的构建后端
Universal Resolution	面向多平台、多 Python 版本的统一依赖解析

---

结语

uv 的意义不只是"更快地安装包"。它真正改变的是 Python 开发者组织项目、管理依赖和复现环境的方式。

对个人开发者来说，uv 可以减少在 pip、venv、pipx、pyenv 之间切换的心智负担。对团队项目来说，pyproject.toml + uv.lock + uv sync 提供了更清晰、更可复现的协作基础。

如果你刚开始使用 uv，建议按下面顺序掌握：

第一步：uv init / uv add / uv run
第二步：理解 pyproject.toml / uv.lock / .venv
第三步：掌握 uv sync / uv lock / --locked / --frozen
第四步：学习 uvx / uv tool / uv python / uv pip
第五步：把 uv 接入 CI/CD 和 Docker

掌握这条主线后，你就能把 uv 从"一个新工具"变成日常 Python 开发中的核心工作流。

---

本文基于 uv 官方文档整理。更多细节请参考官方文档：https://docs.astral.sh/uv/。
uv 由 Astral 开发，Astral 同时也是 Ruff 的开发团队。