分享一个 Python 包管理器：uv
写在前面
如果你用 Python 有一段时间，下面的场景应该不陌生：
- •
pip install 一个大点的库，风扇转半天还卡在 "Collecting ..."； - • 换台机器部署，同一个
requirements.txt 装出来的环境却跑不起来； - • 项目 A 要 Python 3.10，项目 B 要 3.13，切来切去一团乱；
- • 装个
pip，装个 venv，再装个 pyenv，再来个 pipx……工具多到记不住。
这篇文章要介绍的 uv，就是冲着解决这些问题来的。
一、uv 是什么
一句话：uv 是一个用 Rust 写的 Python 包管理工具，一个命令替代 pip + venv + pyenv + pipx 等一堆工具。
它由 Astral（做 Ruff 那家公司）开发，目标是成为 Python 界的 "Cargo"——像 Rust 的 Cargo 那样，装版本、建环境、管依赖、打包发布，一把梭。
二、为什么要用 uv
对新手来说，记住三点就够了：
1. 快。 安装依赖比 pip 快 10–100 倍。原来要等一两分钟的事，现在几秒钟搞定。
2. 省心。 一个工具就够了，不用再去研究 pip、venv、pyenv 各自怎么用、怎么配合。
3. 环境可复现。 它会生成一个 uv.lock 文件，锁定所有依赖的精确版本，保证你和同事、本地和服务器装出来的环境完全一致——再也不会出现"我这能跑你那不能跑"的情况。
三、什么时候用得上
四、从零开发一个项目：完整实战
下面用一个具体的小项目——抓取 GitHub 仓库 star 数的命令行工具——把 uv 的典型工作流走一遍。每一步我都会解释"做了什么"和"为什么这么做"。
步骤 0：安装 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"
为什么这样装：官方推荐的独立安装脚本会把 uv 二进制放到 ~/.local/bin/，这样 uv 完全独立于任何一个 Python 环境存在。这是它"不依赖 Python 也能管理 Python"的根本前提——如果你用 pip install uv 装它，就又陷入"先要有 Python 才能管 Python"的循环了。
验证安装：
uv --version
步骤 1：初始化项目
uv init github-stars
cd github-stars
执行后目录结构如下：
github-stars/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml
每个文件的作用：
- •
pyproject.toml：项目的单一信息源，遵循 PEP 621，声明项目名、版本、依赖、构建后端等所有元数据； - •
.python-version：锁定项目使用的 Python 版本，uv 运行任何命令时都会读取它来选择解释器； - •
.gitignore：自动生成，已经把 .venv/、__pycache__/ 等都排除好了；
为什么不是手动创建：uv init 帮你一次性搭好符合现代 Python 打包规范的骨架。手动写 pyproject.toml 很容易漏掉关键字段（比如 build-system），导致后续打包出问题。
步骤 2：指定（或安装）Python 版本
uv python install 3.13
uv python pin 3.13
做了什么：第一条命令下载 CPython 3.13 到 uv 的管理目录（macOS 上在 ~/.local/share/uv/python/）；第二条命令把版本号写入 .python-version。
为什么这么做：
- • 不污染系统 Python：uv 管理的解释器和系统里的
python3 完全隔离； - • 团队一致性：
.python-version 提交到 Git 后，同事 uv sync 时如果本机没有 3.13，uv 会自动下载，不需要他再去研究 pyenv； - • 可审计：某一天某个库要求最低 Python 3.12，你在
.python-version 里改一行就完事，不用重建整个环境。
步骤 3：添加项目依赖
我们这个工具要用到 httpx 发请求、rich 美化输出、click 做 CLI：
uv add httpx rich click
你会看到输出里 uv 做了几件事：
- 1. 自动创建
.venv/ 虚拟环境（如果还没有）； - 4. 把声明写入
pyproject.toml 的 [project].dependencies； - 5. 把包硬链接（不是复制）到
.venv/ 里。
为什么是 uv add 而不是 pip install：
- •
pip install 只做安装，不更新 pyproject.toml，你还得手动同步依赖声明； - •
uv add 是声明式的：你告诉它"这个项目需要这些依赖"，它负责解析、记录、安装、锁定一条龙。这个思路和 Cargo 的 cargo add、npm 的 npm install --save 是一致的。
再加一个开发期才用的工具（比如测试框架）：
uv add --dev pytest
--dev 标志会把它放到 [dependency-groups].dev 下，发布时不会带上，但本地开发和 CI 能用到。
步骤 4：写代码
把 main.py 换成一个真正的小工具（简化版，便于说明流程）：
import click
import httpx
from rich.console import Console
from rich.table import Table
console = Console()
@click.command()
@click.argument("repos", nargs=-1, required=True)
def main(repos: tuple[str, ...]) -> None:
"""查询一个或多个 GitHub 仓库的 star 数，格式：owner/repo"""
table = Table(title="GitHub Stars")
table.add_column("Repository", style="cyan")
table.add_column("Stars", justify="right", style="green")
with httpx.Client(timeout=10.0) as client:
for repo in repos:
resp = client.get(f"https://api.github.com/repos/{repo}")
if resp.status_code == 200:
table.add_row(repo, f"{resp.json()['stargazers_count']:,}")
else:
table.add_row(repo, "[red]N/A[/red]")
console.print(table)
if __name__ == "__main__":
main()
步骤 5：运行代码
uv run main.py astral-sh/uv astral-sh/ruff
uv run 做了什么：
- 1. 检查
.venv/ 是否存在且和 uv.lock 一致，如果不一致会自动同步； - 2. 在虚拟环境内执行命令，但不需要你手动
source .venv/bin/activate；
为什么这是个大进步：传统流程是 source .venv/bin/activate && python main.py，切到别的项目前还要 deactivate。uv run 把激活/退出完全隐藏了，你只需要关心"我要跑什么"，不用关心"当前 shell 处于什么状态"。CI 脚本也因此变得更短、更不容易出错。
步骤 6：查看依赖树
uv tree
会打印出完整的依赖树，包括间接依赖。调试"为什么装了这个奇怪的包"时非常有用。
步骤 7：锁定与同步
把项目推到 Git 后，同事 clone 下来：
git clone <repo>
cd github-stars
uv sync
uv sync 做的事：
- 1. 读取
.python-version，必要时自动下载对应 Python 版本； - 2. 读取
uv.lock，按锁文件里精确到 hash 的版本还原环境；
为什么要提交 uv.lock：它是可复现构建的保证。pyproject.toml 里写的是"我要 httpx >= 0.27"这种范围约束，而 uv.lock 记录的是"我们实际用的是 httpx 0.28.1，它依赖 anyio 4.4.0..."这种精确快照。提交锁文件，CI 和同事的环境就和你严格一致。
在 CI 里建议用更严格的 --frozen：
uv sync --frozen
这会拒绝任何偏离锁文件的情况，如果 pyproject.toml 和 uv.lock 不一致会直接报错，防止"改了依赖但忘了提交锁文件"的事故。
步骤 8：升级依赖
uv lock --upgrade-package httpx
只升级指定的包；要全量升级则用 uv lock --upgrade。升级后记得 uv sync 让本地环境跟上。
为什么不用 pip install -U：pip install -U 会直接装到环境里，但不会告诉你"这次升级同时带起来了哪些间接依赖变更"。uv 的做法是先更新锁文件再同步，升级过程完全透明、可审查，你可以 git diff uv.lock 看到所有变化。
步骤 9：构建与发布
如果要把这个工具发到 PyPI：
uv build
uv publish
- •
uv build 生成 dist/ 下的 wheel 和 sdist； - •
uv publish 上传到 PyPI（需要配置 token）。
为什么这很爽：以前要 pip install build twine，然后 python -m build、twine upload dist/*。现在一个 uv 搞定，不需要额外装工具。
步骤 10（额外）：单文件脚本模式
如果你的需求小到"就是一个脚本"，连项目目录都懒得建，可以用 PEP 723 内联依赖：
新建 quick.py：
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx", "rich"]
# ///
import httpx
from rich import print
print(httpx.get("https://api.github.com/repos/astral-sh/uv").json()["stargazers_count"])
执行：
uv run quick.py
uv 会读取文件头里的元数据，临时创建一个隔离环境把依赖装进去再执行。脚本跑完环境进入缓存，下次再跑直接复用。
这解决了什么痛点：以前分享一个 Python 小脚本给别人，还要附一句"先 pip install 这几个包"。现在脚本自己就包含依赖声明，对方只要有 uv，uv run script.py 就够了。
五、常用命令速查
| |
|---|
| uv init <n> |
| uv python install 3.13 |
| uv python pin 3.13 |
| uv add <pkg> |
| uv add --dev <pkg> |
| uv remove <pkg> |
| uv run <cmd> |
| uv sync |
| uv sync --frozen |
| uv tree |
| uv lock --upgrade |
| uv tool install ruff |
| uvx ruff check |
| uv build |
| uv publish |
| uv pip install/freeze/... |
六、迁移建议与小结
对已有项目，我的迁移路径推荐是：
- 1. 第一阶段：先用
uv pip 替代 pip，零成本感受速度提升； - 2. 第二阶段：用
uv init 在新分支上重建项目，把 requirements.txt 里的依赖用 uv add 重新声明，生成 pyproject.toml 和 uv.lock； - 3. 第三阶段：CI 改成
uv sync --frozen，团队统一切换。
uv 不是"又一个包管理器"，它更像是 Python 生态打包这个问题被重新严肃思考之后的一个答案。速度只是表象，一个工具搞定所有事带来的心智负担减轻才是真正的价值，值得你花一个下午迁移过去试试。
参考链接
- • 官方文档：https://docs.astral.sh/uv/
- • GitHub 仓库：https://github.com/astral-sh/uv
- • Astral 博客（uv 发布文）：https://astral.sh/blog/uv
- • PEP 621（项目元数据）：https://peps.python.org/pep-0621/
- • PEP 723（脚本内联元数据）：https://peps.python.org/pep-0723/
