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

uv 常用命令速查：一个工具干掉 pip + venv + pyenv + pipx + poetry，Python 工具链从此清爽的重点在于把前置条件、操作顺序和容易误判的地方分清楚。

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

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

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

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

二、安装与自更新

 复制代码# 官方安装脚本（推荐，独立二进制，不依赖任何 Python）curl -LsSf  | sh# 或者用包管理器brew install uv            # macOSpipx install uv            # 已有 pipx 的话# 自我更新 / 查版本uv self updateuv --version

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

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

 复制代码# 初始化一个新项目（生成 pyproject.toml、.python-version、main.py、README 等；.venv 首次 uv run/add 时才建）uv init myprojectcd myproject# 加依赖（自动更新 pyproject.toml + uv.lock + 装进 .venv，一步到位）uv add requestsuv add 'flask>=3.0'          # 带版本约束uv add --dev pytest ruff     # 开发依赖（dev 分组）uv add --group docs mkdocs   # 自定义依赖分组# 删依赖uv remove requests# 在项目环境里跑命令（不用手动 activate 虚拟环境！）uv run python main.pyuv run pytestuv run ruff check .# 锁定 / 同步uv lock                      # 生成 / 更新 uv.lockuv lock --upgrade            # 升级所有依赖到允许的最新uv sync                      # 让 .venv 严格匹配 uv.lock（CI / 新机器拉起环境）# 看依赖树uv tree

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

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

 复制代码# 建虚拟环境（默认建在 .venv）uv venvuv venv --python 3.12        # 指定 Python 版本建环境# 装包（用法和 pip 一模一样，但快得多）uv pip install requestsuv pip install -r requirements.txtuv pip uninstall requestsuv pip listuv pip freeze# pip-tools 那套「编译锁定」也内置了uv pip compile requirements.in -o requirements.txt   # 解析并锁定uv pip sync requirements.txt                          # 让环境精确匹配

五、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

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

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

 复制代码# 长期安装一个 CLI 工具（全局可用，独立环境隔离）uv tool install ruffuv tool list                    # 看装了哪些uv tool upgrade --all           # 全部升级uv tool uninstall ruff# 临时跑一次、用完即走（不安装，等价 pipx run）—— 高频！uvx ruff check .                # uvx 是 uv tool run 的简写uvx black --versionuvx --from httpie http GET example.com    # 包名和命令名不一致时用 --from

七、内联依赖脚本：单文件也能带依赖（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 export --format requirements-txt > requirements.txt   # 导出为传统 requirements.txt（给不用 uv 的环境）uv build                        # 打包成 sdist / wheeluv publish                      # 发布到 PyPIuv cache clean                  # 清理下载缓存uv cache dir                    # 看缓存目录位置

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

日常最高频的一把：

 复制代码项目：  uv init  →  uv add 包  →  uv run 命令  →  uv sync（拉起环境）锁定：  uv lock  /  uv lock --upgradepip：   uv pip install / uv pip compile / uv pip syncPython：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 的价值：

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

延伸阅读

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

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