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 不是"又一个包管理器"，而是一个工具替掉一整条工具链：
#mermaid-svg-q77AD87HzKIp162c{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-q77AD87HzKIp162c .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-q77AD87HzKIp162c .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-q77AD87HzKIp162c .error-icon{fill:#552222;}#mermaid-svg-q77AD87HzKIp162c .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-q77AD87HzKIp162c .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-q77AD87HzKIp162c .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-q77AD87HzKIp162c .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-q77AD87HzKIp162c .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-q77AD87HzKIp162c .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-q77AD87HzKIp162c .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-q77AD87HzKIp162c .marker{fill:#333333;stroke:#333333;}#mermaid-svg-q77AD87HzKIp162c .marker.cross{stroke:#333333;}#mermaid-svg-q77AD87HzKIp162c svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-q77AD87HzKIp162c p{margin:0;}#mermaid-svg-q77AD87HzKIp162c .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-q77AD87HzKIp162c .cluster-label text{fill:#333;}#mermaid-svg-q77AD87HzKIp162c .cluster-label span{color:#333;}#mermaid-svg-q77AD87HzKIp162c .cluster-label span p{background-color:transparent;}#mermaid-svg-q77AD87HzKIp162c .label text,#mermaid-svg-q77AD87HzKIp162c span{fill:#333;color:#333;}#mermaid-svg-q77AD87HzKIp162c .node rect,#mermaid-svg-q77AD87HzKIp162c .node circle,#mermaid-svg-q77AD87HzKIp162c .node ellipse,#mermaid-svg-q77AD87HzKIp162c .node polygon,#mermaid-svg-q77AD87HzKIp162c .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-q77AD87HzKIp162c .rough-node .label text,#mermaid-svg-q77AD87HzKIp162c .node .label text,#mermaid-svg-q77AD87HzKIp162c .image-shape .label,#mermaid-svg-q77AD87HzKIp162c .icon-shape .label{text-anchor:middle;}#mermaid-svg-q77AD87HzKIp162c .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-q77AD87HzKIp162c .rough-node .label,#mermaid-svg-q77AD87HzKIp162c .node .label,#mermaid-svg-q77AD87HzKIp162c .image-shape .label,#mermaid-svg-q77AD87HzKIp162c .icon-shape .label{text-align:center;}#mermaid-svg-q77AD87HzKIp162c .node.clickable{cursor:pointer;}#mermaid-svg-q77AD87HzKIp162c .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-q77AD87HzKIp162c .arrowheadPath{fill:#333333;}#mermaid-svg-q77AD87HzKIp162c .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-q77AD87HzKIp162c .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-q77AD87HzKIp162c .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-q77AD87HzKIp162c .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-q77AD87HzKIp162c .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-q77AD87HzKIp162c .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-q77AD87HzKIp162c .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-q77AD87HzKIp162c .cluster text{fill:#333;}#mermaid-svg-q77AD87HzKIp162c .cluster span{color:#333;}#mermaid-svg-q77AD87HzKIp162c div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-q77AD87HzKIp162c .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-q77AD87HzKIp162c rect.text{fill:none;stroke-width:0;}#mermaid-svg-q77AD87HzKIp162c .icon-shape,#mermaid-svg-q77AD87HzKIp162c .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-q77AD87HzKIp162c .icon-shape p,#mermaid-svg-q77AD87HzKIp162c .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-q77AD87HzKIp162c .icon-shape .label rect,#mermaid-svg-q77AD87HzKIp162c .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-q77AD87HzKIp162c .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-q77AD87HzKIp162c .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-q77AD87HzKIp162c :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} pip

装包
uv

一个 Rust 二进制

快 10~100 倍
venv / virtualenv

虚拟环境
pyenv

Python 版本
pipx

全局 CLI 工具
poetry / pip-tools

项目 + 锁依赖

你原来用	现在用 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 的五大命令板块展开，先给张导览图，看完这篇你会用下面每一块：
#mermaid-svg-SuneSZZGx32kkhZ0{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-SuneSZZGx32kkhZ0 .error-icon{fill:#552222;}#mermaid-svg-SuneSZZGx32kkhZ0 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-SuneSZZGx32kkhZ0 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-SuneSZZGx32kkhZ0 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-SuneSZZGx32kkhZ0 .marker.cross{stroke:#333333;}#mermaid-svg-SuneSZZGx32kkhZ0 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-SuneSZZGx32kkhZ0 p{margin:0;}#mermaid-svg-SuneSZZGx32kkhZ0 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 .cluster-label text{fill:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 .cluster-label span{color:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 .cluster-label span p{background-color:transparent;}#mermaid-svg-SuneSZZGx32kkhZ0 .label text,#mermaid-svg-SuneSZZGx32kkhZ0 span{fill:#333;color:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 .node rect,#mermaid-svg-SuneSZZGx32kkhZ0 .node circle,#mermaid-svg-SuneSZZGx32kkhZ0 .node ellipse,#mermaid-svg-SuneSZZGx32kkhZ0 .node polygon,#mermaid-svg-SuneSZZGx32kkhZ0 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-SuneSZZGx32kkhZ0 .rough-node .label text,#mermaid-svg-SuneSZZGx32kkhZ0 .node .label text,#mermaid-svg-SuneSZZGx32kkhZ0 .image-shape .label,#mermaid-svg-SuneSZZGx32kkhZ0 .icon-shape .label{text-anchor:middle;}#mermaid-svg-SuneSZZGx32kkhZ0 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-SuneSZZGx32kkhZ0 .rough-node .label,#mermaid-svg-SuneSZZGx32kkhZ0 .node .label,#mermaid-svg-SuneSZZGx32kkhZ0 .image-shape .label,#mermaid-svg-SuneSZZGx32kkhZ0 .icon-shape .label{text-align:center;}#mermaid-svg-SuneSZZGx32kkhZ0 .node.clickable{cursor:pointer;}#mermaid-svg-SuneSZZGx32kkhZ0 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-SuneSZZGx32kkhZ0 .arrowheadPath{fill:#333333;}#mermaid-svg-SuneSZZGx32kkhZ0 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-SuneSZZGx32kkhZ0 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-SuneSZZGx32kkhZ0 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-SuneSZZGx32kkhZ0 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-SuneSZZGx32kkhZ0 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-SuneSZZGx32kkhZ0 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-SuneSZZGx32kkhZ0 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-SuneSZZGx32kkhZ0 .cluster text{fill:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 .cluster span{color:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-SuneSZZGx32kkhZ0 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-SuneSZZGx32kkhZ0 rect.text{fill:none;stroke-width:0;}#mermaid-svg-SuneSZZGx32kkhZ0 .icon-shape,#mermaid-svg-SuneSZZGx32kkhZ0 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-SuneSZZGx32kkhZ0 .icon-shape p,#mermaid-svg-SuneSZZGx32kkhZ0 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-SuneSZZGx32kkhZ0 .icon-shape .label rect,#mermaid-svg-SuneSZZGx32kkhZ0 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-SuneSZZGx32kkhZ0 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-SuneSZZGx32kkhZ0 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-SuneSZZGx32kkhZ0 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} uv
项目管理

对标 poetry
pip 兼容接口

对标 pip
Python 版本管理

对标 pyenv
工具管理 uvx

对标 pipx
PEP 723 脚本

单文件内联依赖
uv init / add / run

sync / lock
uv pip install / freeze
uv python install / pin
uv tool install / uvx
uv run script.py

二、安装与自更新

bash 复制代码

# 官方安装脚本（推荐，独立二进制，不依赖任何 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 管理整个项目。

bash 复制代码

# 初始化一个新项目（生成 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 的直接替代，命令一样、速度飞起：

bash 复制代码

# 建虚拟环境（默认建在 .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 可以退休了：

bash 复制代码

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，隔离且干净：

bash 复制代码

# 长期安装一个 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 标准），直接跑：

bash 复制代码

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

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

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

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

python 复制代码

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

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

八、其他常用

bash 复制代码

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

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

日常最高频的一把：

text 复制代码

项目：  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 常用命令速查：一个工具干掉 pip + venv + pyenv + pipx + poetry，Python 工具链从此清爽

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

二、安装与自更新

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

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

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

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

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

八、其他常用

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

延伸阅读