uv 常用命令速查：一个工具干掉 pip + venv + pyenv + pipx + poetry，Python 工具链从此清爽

每个 Python 开发者的电脑里，大概都住着这么一支杂牌军： 装包用 pip，隔离环境用 venv / virtualenv，管 Python 版本用 pyenv，装命令行工具用 pipx，锁依赖又得请出 poetry / pip-tools…… 五个工具、五套命令、五份配置，还时不时互相打架。 然后 Astral（就是写出 ruff 的那家）掏出了 uv——一个 Rust 写的二进制，把上面这五件事全干了，顺便快出 10~100 倍。这篇就是 uv 的常用命令速查。

一、uv 是什么：一个顶五个

先建立全局认知——uv 不是"又一个包管理器"，而是一个工具替掉一整条工具链：

flowchart LR
    P[&#34;pip<br/>装包&#34;] --> UV
    V[&#34;venv / virtualenv<br/>虚拟环境&#34;] --> UV
    PE[&#34;pyenv<br/>Python 版本&#34;] --> UV
    PX[&#34;pipx<br/>全局 CLI 工具&#34;] --> UV
    PO[&#34;poetry / pip-tools<br/>项目 + 锁依赖&#34;] --> UV
    UV(((&#34;uv<br/>一个 Rust 二进制<br/>快 10~100 倍&#34;)))
    style UV fill:#d5f0e0,stroke:#1e8449,stroke-width:2px

你原来用	现在用 uv
pip install	uv pip install / uv add
venv / virtualenv	uv venv（还会自动管理）
pyenv（装/切 Python 版本）	uv python install / uv python pin
pipx（装全局 CLI 工具）	uv tool install / uvx
poetry / pip-tools（项目 + 锁依赖）	uv init / uv add / uv lock / uv sync

而且它快得离谱——依赖解析和安装是 Rust 实现的，冷启动装一个中型项目，常常是 pip 的几十分之一时间。

全文就按 uv 的五大命令板块展开，先给张导览图，看完这篇你会用下面每一块：

flowchart TD
    UV([&#34;uv&#34;]) --> A[&#34;项目管理<br/>对标 poetry&#34;]
    UV --> B[&#34;pip 兼容接口<br/>对标 pip&#34;]
    UV --> C[&#34;Python 版本管理<br/>对标 pyenv&#34;]
    UV --> D[&#34;工具管理 uvx<br/>对标 pipx&#34;]
    UV --> E[&#34;PEP 723 脚本<br/>单文件内联依赖&#34;]
    A --> A1[&#34;uv init / add / run<br/>sync / lock&#34;]
    B --> B1[&#34;uv pip install / freeze&#34;]
    C --> C1[&#34;uv python install / pin&#34;]
    D --> D1[&#34;uv tool install / uvx&#34;]
    E --> E1[&#34;uv run script.py&#34;]
    style UV fill:#d5f0e0,stroke:#1e8449,stroke-width:2px

二、安装与自更新

# 官方安装脚本（推荐，独立二进制，不依赖任何 Python）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者用包管理器
brew install uv            # macOS
pipx install uv            # 已有 pipx 的话

# 自我更新 / 查版本
uv self update
uv --version

uv 本身是个独立二进制，不需要先有 Python——它甚至能帮你把 Python 装出来（见第五节）。这也是它能替代 pyenv 的底气。

三、项目管理：uv 的主场（对标 poetry）

这是 uv 最推荐的用法——围绕 pyproject.toml + uv.lock 管理整个项目。

# 初始化一个新项目（生成 pyproject.toml、.python-version、main.py、README 等；.venv 首次 uv run/add 时才建）
uv init myproject
cd myproject

# 加依赖（自动更新 pyproject.toml + uv.lock + 装进 .venv，一步到位）
uv add requests
uv add 'flask>=3.0'          # 带版本约束
uv add --dev pytest ruff     # 开发依赖（dev 分组）
uv add --group docs mkdocs   # 自定义依赖分组

# 删依赖
uv remove requests

# 在项目环境里跑命令（不用手动 activate 虚拟环境！）
uv run python main.py
uv run pytest
uv run ruff check .

# 锁定 / 同步
uv lock                      # 生成 / 更新 uv.lock
uv lock --upgrade            # 升级所有依赖到允许的最新
uv sync                      # 让 .venv 严格匹配 uv.lock（CI / 新机器拉起环境）

# 看依赖树
uv tree

🔑 最爽的一点是 uv run：它会自动确保环境和 uv.lock 一致再执行，你再也不用记得 source .venv/bin/activate 了。团队协作时，别人 git clone 下来一句 uv sync 就得到和你一模一样的环境。

📦 uv.lock 到底是什么、为什么要提交它：它是 uv 自动维护的锁文件，作用一句话——保证依赖可复现。

• pyproject.toml 写的是你「想要什么」（范围，如 flask>=3.0）；uv.lock 记的是这次解析实际锁成了哪个版本（如 flask==3.0.3），连所有间接依赖和文件哈希都钉死。
• 它是跨平台的：一份 uv.lock 同时覆盖 Linux / macOS / Windows，不是每台机各生成一份。
• 可复现：任何人 uv sync 都能装出和你逐字节一致的依赖树，专治「我这能跑、你那报错」。
• 自动维护、但要提交 git：由 uv add / uv lock / uv run 自动生成更新，你不用手改；但必须和 pyproject.toml 一起 commit 进 git，CI 和同事才能复现。

一句话记忆：pyproject.toml 管「意图」，uv.lock 管「事实」。（对标 poetry.lock / package-lock.json）

四、pip 兼容接口：平滑迁移（对标 pip / pip-tools）

还不想全面转项目模式？uv 提供了一套 uv pip 子命令，几乎是 pip 的直接替代，命令一样、速度飞起：

# 建虚拟环境（默认建在 .venv）
uv venv
uv venv --python 3.12        # 指定 Python 版本建环境

# 装包（用法和 pip 一模一样，但快得多）
uv pip install requests
uv pip install -r requirements.txt
uv pip uninstall requests
uv pip list
uv pip freeze

# pip-tools 那套「编译锁定」也内置了
uv pip compile requirements.in -o requirements.txt   # 解析并锁定
uv pip sync requirements.txt                          # 让环境精确匹配

迁移策略：老项目先把 pip install 换成 uv pip install，零改动尝鲜提速；等熟悉了再考虑迁到 uv add 的项目模式。

五、Python 版本管理（对标 pyenv）

uv 能直接装、切、钉 Python 版本，pyenv 可以退休了：

uv python install 3.12          # 装一个 Python 版本
uv python install 3.11 3.13     # 一次装多个
uv python list                  # 看已装 / 可装的版本
uv python pin 3.12              # 给当前项目钉版本（写入 .python-version）
uv python find                  # 看当前会用哪个 Python

uv add / uv run 时如果发现项目需要的 Python 版本没装，uv 会自动帮你装——真正做到「开箱即用」。

六、工具管理：装/跑命令行工具（对标 pipx）

装 ruff、black、httpie 这类全局 CLI 工具，用 uv tool，隔离且干净：

# 长期安装一个 CLI 工具（全局可用，独立环境隔离）
uv tool install ruff
uv tool list                    # 看装了哪些
uv tool upgrade --all           # 全部升级
uv tool uninstall ruff

# 临时跑一次、用完即走（不安装，等价 pipx run）—— 高频！
uvx ruff check .                # uvx 是 uv tool run 的简写
uvx black --version
uvx --from httpie http GET example.com    # 包名和命令名不一致时用 --from

uvx 是日常最顺手的命令之一：想临时用个工具、又不想污染环境，uvx 工具名 一把梭，跑完自动清理。等价于 pipx run，但快到几乎无感。

七、内联依赖脚本：单文件也能带依赖（PEP 723）

一个只有几十行、却依赖 requests 的小脚本，以前得专门建环境，现在 uv 支持把依赖写进脚本头部（PEP 723 标准），直接跑：

# 给脚本声明内联依赖（自动写入脚本顶部的元数据块）
uv add --script demo.py requests rich

# 直接运行，uv 自动准备临时环境（无需手动建 venv）
uv run demo.py

# 或临时加依赖跑
uv run --with rich demo.py

脚本顶部会长这样（uv 自动生成 / 识别）：

# /// script
# dependencies = ["requests", "rich"]
# requires-python = ">=3.11"
# ///
import requests, rich
...

一次性小工具、爬虫脚本、临时数据处理——单文件自带依赖声明，发给同事直接 uv run 就能跑，不用再附一句"记得先 pip install xxx"。

八、其他常用

uv export --format requirements-txt > requirements.txt   # 导出为传统 requirements.txt（给不用 uv 的环境）
uv build                        # 打包成 sdist / wheel
uv publish                      # 发布到 PyPI
uv cache clean                  # 清理下载缓存
uv cache dir                    # 看缓存目录位置

九、总结：一张速查卡 + 迁移对照

日常最高频的一把：

项目：  uv init  →  uv add 包  →  uv run 命令  →  uv sync（拉起环境）
锁定：  uv lock  /  uv lock --upgrade
pip：   uv pip install / uv pip compile / uv pip sync
Python：uv python install 3.12  /  uv python pin 3.12
工具：  uv tool install ruff   /   uvx 工具名（临时跑）
脚本：  uv add --script x.py 包   /   uv run x.py

从老工具迁过来，记住这张对照就够了：

旧命令	uv 对应
python -m venv .venv && source .venv/bin/activate	uv venv（配 uv run 连 activate 都省了）
pip install requests	uv add requests（项目）/ uv pip install requests（兼容）
pip freeze > requirements.txt	uv export / uv pip freeze
pyenv install 3.12 && pyenv local 3.12	uv python install 3.12 && uv python pin 3.12
pipx install ruff / pipx run ruff	uv tool install ruff / uvx ruff
poetry add / poetry install / poetry lock	uv add / uv sync / uv lock

一句话记住 uv 的价值：

它不是让你多学一个工具，而是让你少记四个工具。 一个 Rust 二进制，把 Python 的「装包、隔离、版本、工具、锁依赖」五件事收进一套心智模型里，还顺手快了几十倍。

你还在用 pip + venv + pyenv 的老组合吗？试试 uv add，大概率回不去了。欢迎评论区聊聊迁移体验。

---

延伸阅读

• uv 官方文档 —— 完整命令与配置
• uv 官方：项目管理（pyproject.toml / uv.lock） —— uv add / uv sync 工作流
• uv 官方：工具管理 uv tool / uvx —— pipx 替代
• uv 官方：Python 版本管理 —— pyenv 替代
• PEP 723 – Inline script metadata —— 单文件内联依赖标准

---

🏷️ 标签：uv Python 包管理 虚拟环境 pip 命令速查