uv —— Rust 写的极速 Python 包与项目管理器
maiaimei
# uv —— Rust 写的极速 Python 包与项目管理器
# 1. uv 是什么
uv（读音 /juː viː/，Astral 出品，Ruff 同团队）
官方定位：An extremely fast Python package and project manager, written in Rust
uv 是 Rust 编译出的原生二进制，整合 pip + pip-tools + virtualenv + pyenv + pipx + poetry 的大部分职责。
uv 本身是一个不依赖 Python 运行的独立工具，但它负责“下载、管理、调用、隔离”多个 Python 解释器，是 Python 生态的“调度中心。
官方文档：https://docs.astral.sh/uv
# 2. uv 怎么装
安装文档： https://docs.astral.sh/uv/getting-started/installation/ (opens new window)
uv提供了一个独立的安装程序，用于下载和安装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"
1
2
3
4
5
2
3
4
5
在 Windows 上安装 uv 独立程序后，需将其可执行文件所在目录添加到系统或用户 PATH 环境变量中。
或用 pip 安装：
python -m pip install uv
1
验证有没有安装 uv：
where.exe uv
uv --version
1
2
2
其他命令：
uv self update # 升级 uv 自己
uv cache clean # 清缓存
uv -h # 帮助命令
uv help sync # 看某子命令帮助
1
2
3
4
2
3
4
命令文档：https://docs.astral.sh/uv/getting-started/features/ (opens new window)
# 3. 核心概念
| 文件 / 命令 | 作用 |
|---|---|
pyproject.toml | 项目元数据 + 抽象依赖 |
uv.lock | 精确锁版本（含传递依赖），提交进 git |
.venv/ | 虚拟环境，uv 自动建，不提交 |
.python-version | 固定项目 Python 版本 |
uv run xxx | 自动同步环境后执行，不需手动 activate |
# 4. Python 版本管理（替代 pyenv）
uv python list # 已装/可装哪些版本
uv python install 3.12 # 装 CPython 3.12
uv python install 3.11 3.13 # 一次装多个
uv python pin 3.12 # 当前项目固定某个 Python 版本，例如： 3.12（写 .python-version）
uv python find # 当前会用到哪个 python
uv python uninstall 3.11 # 卸掉 uv 管理的版本
uv venv --python 3.12
1
2
3
4
5
6
7
2
3
4
5
6
7
首次会下载预编译 CPython，几秒完事，不编译源码。
项目里没装对应 Python 时，uv venv / uv run 会自动下载，不用手动预装。
# 5. 新项目（标准工作流）
# 1. 初始化项目（生成 pyproject.toml / .python-version / README）
uv init myproject
cd myproject
# 2. 固定 Python 版本（可选，会自动下载预编译解释器）
uv python pin 3.12
# 3. 加运行依赖
uv add requests pandas
# 4. 加开发依赖
uv add --dev ruff pytest pytest-cov mypy pre-commit
# 5. 跑代码 / 测试（自动用 .venv）
uv run python main.py
uv run pytest
# 6. 别人拉下来复现环境
uv sync # 按 uv.lock 装
# 或 CI 中用严格模式
uv sync --frozen
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
uv add 会自动：改 pyproject.toml → 解析 → 装包 → 更新 uv.lock
# 6. 兼容旧项目（不写 pyproject.toml 也能用）
# 建环境
uv venv
# 用 pip 风格装
uv pip install -r requirements.txt
# 编译锁文件
uv pip compile pyproject.toml -o requirements.txt
# 严格按锁定文件同步
uv pip sync requirements.txt
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
👉 老项目零改造享受 uv 速度。
# 7. 跑脚本与 CLI 工具（替代 pipx）
# 单文件脚本内联依赖（PEP 723）
uv run analyze.py
# 临时跑工具，不污染环境（= npx / pipx run）
uvx ruff check .
uvx pycowsay hi
# 永久装工具到 uv 工具区
uv tool install ruff
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 8. 构建与发布
uv build # 出 sdist + wheel 到 dist/
uv publish # 传 PyPI（类似 twine）
1
2
2