uv：一个二进制替掉 pip + venv + poetry + pyenv + pipx

uv 是 2025–2026 年 Python 生态里最炙手可热的工具，由 Ruff 背后的 Astral 公司用 Rust 写成。官方称常见操作比 pip 快 10–100 倍。一个二进制同时承担五件事：Python 版本管理、虚拟环境、依赖管理、一次性 CLI 工具（替代 pipx）、项目构建与发布。

前两篇是 lazygit（管 Git）和 mise（管运行时版本），这篇是它们的天然下游——代码历史管好了、运行环境也有了，剩下"怎么把 Python 依赖装得又快又稳"就交给 uv。

一、为什么是它

先看看你现在是不是也叠了好几层：

传统做法	解决什么	uv 怎么替
`pip` + 手维护 `requirements.txt`	装包	`uv add` / `uv pip`（快一个数量级）
`python -m venv`	虚拟环境	`uv venv`（秒级创建）
`poetry` / `pdm`	依赖与锁文件	`uv add` + `uv.lock`
`pyenv`	切 Python 版本	`uv python install` / `uv python pin`
`pipx`	装 CLI 工具（ruff/black 等）	`uvx` / `uv tool install`
`build` / `twine`	打包发布	`uv build` / `uv publish`

叠在一起的问题：工具链长、命令杂、不同项目约定不一样、requirements.txt 经常和实际装的不一致。uv 把它们收进同一套命令和同一份 pyproject.toml + uv.lock。

和 mise 怎么分工：mise 适合在系统层面管"一堆语言运行时"并随目录自动切换；uv 在自己项目里也内置了 uv python install，两者不冲突。常见搭配是 mise 管全局多版本、uv 管项目内依赖，或者干脆只让 uv 一个人把 Python 这摊事全包了。

二、安装

各平台安装命令

# macOS / Linux 官方独立安装器（装到 ~/.local/bin）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 包管理器
brew install uv                 # macOS / Linux
winget install --id=astral-sh.uv -e
scoop install main/uv
pipx install uv                 # 有 Python 环境即可
cargo install --locked uv       # 从源码构建，需要 Rust 工具链

开补全、会升级

# zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# 独立安装器装的 uv 可以自我更新
uv self update

# 清理缓存（排障时常有用）
uv cache clean

验证：

uv --version

三、uv 在管什么：一张图看懂

        uv python install 3.13   ← 装解释器（替代 pyenv）
                  │
        uv init / uv venv        ← 建项目与虚拟环境（替代 venv）
                  │
        uv add httpx             ← 加依赖并写进 pyproject.toml
        uv add --dev pytest      ← 加开发依赖（写入依赖组）
                  │
        uv lock / uv sync        ← 锁版本、还原环境（替代 poetry）
                  │
        uv run <cmd>             ← 在隔离环境里跑命令
        uvx ruff                 ← 临时跑一个 CLI 工具（替代 pipx）
                  │
        uv build / uv publish    ← 打包发布（替代 build + twine）

核心心智模型就一句话：pyproject.toml 写"我要什么"，uv.lock 锁"实际装了什么"，uv run 保证每次都跑在同一套环境里。

四、速查表

Python 与虚拟环境

命令	说明
`uv python install 3.13`	下载并安装指定 Python
`uv python pin 3.13`	写 `.python-version`，固定项目用的版本
`uv venv`	创建 `.venv` 虚拟环境
`uv python list`	列出已安装 / 可安装的 Python

项目依赖

命令	说明
`uv init`	初始化项目（生成 `pyproject.toml` + `.python-version` + `.gitignore`）
`uv add <pkg>`	加依赖并写入 `pyproject.toml`
`uv add --dev <pkg>`	加开发依赖（写入 `dev` 依赖组）
`uv add -r requirements.txt`	从旧文件批量导入
`uv remove <pkg>`	移除依赖
`uv lock`	解析并生成 `uv.lock`
`uv sync`	按 lock 还原环境
`uv tree`	查看依赖树

运行

命令	说明
`uv run python -c "..."`	在项目环境里跑命令
`uv run example.py`	带 PEP 723 内联声明的脚本会隔离运行
`uv run --with httpx==0.26.0 python ...`	本次临时附加 / 覆盖某个依赖
`uv pip install <pkg>`	pip 兼容接口，直接装到当前环境

工具（替代 pipx）

命令	说明
`uvx <tool>`	临时跑一个 CLI 工具（= `uv tool run`）
`uvx ruff@0.6.0`	指定版本跑
`uv tool install <tool>`	常驻安装，可执行文件上 PATH
`uv tool list` / `uv tool upgrade`	列出 / 升级已装工具

其他

命令	说明
`uv build`	构建 sdist 与 wheel
`uv publish`	发布到 PyPI
`uv export --format requirements-txt`	导出 requirements.txt
`uv self update`	独立安装器自更新

五、五个真实场景

场景 1：从零起一个项目，一条 `uv init` 搞定

mkdir myapp && cd myapp
uv init

它一次性生成 pyproject.toml、.python-version、.gitignore，并自动创建一个 .venv。再也不用 python -m venv venv && source venv/bin/activate 手动三件套。

场景 2：加依赖不用再手改 requirements.txt

uv add "httpx>=0.27"
uv add --dev pytest ruff

uv add 会：把依赖写进 pyproject.toml、解析并写入 uv.lock、装进 .venv，一步到位。开发依赖进了 dev 依赖组，发布时不会被打进运行依赖。

需要 Git / URL 依赖也支持：

uv add git+https://github.com/encode/httpx --tag 0.27.0

场景 3：跑脚本，环境自动就位

最常用的是在项目里：

uv run python main.py
uv run pytest

uv run 每次都会先确认环境是最新的。临时想用一个不在依赖里的包：

uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"

还可以写单文件脚本，把依赖声明直接写在文件头（PEP 723），uv run demo.py 会为它单独建隔离环境：

# /// script
# dependencies = ["httpx"]
# ///
import httpx
print(httpx.get("https://peps.python.org/api/peps.json").status_code)

场景 4：用 `uvx` 跑一次性工具，告别 pipx

uvx ruff check .          # 跑一次 lint，不污染全局
uvx --with watchfiles -- ruff ...
uvx cookiecutter <模板>   # 临时起一个脚手架
uvx pycowsay "hi"

不想每次临时下载，就常驻安装：

uv tool install ruff
ruff --version            # 已经在 PATH 上，直接可用

uvx 第一次会缓存版本，之后默认复用；想强制最新就 uvx ruff@latest。

场景 5：CI / Docker 复现同一套环境

CI 里最干净的做法——只依赖 pyproject.toml + uv.lock：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv sync --frozen          # 严格按 uv.lock 还原，不重新解析
uv run pytest

--frozen 保证 CI 装的版本和本地锁文件完全一致，不会出现"本地能跑 CI 挂"。Docker 里同理，官方还提供了 ghcr.io/astral-sh/uv 镜像。

六、从 poetry / pipx / conda 迁过来

poetry 用户：pyproject.toml 基本能直接复用；poetry add 对应 uv add，poetry lock 对应 uv lock，速度有数量级提升。
pipx 用户：所有"装命令行工具"的需求改成 uvx（临时）或 uv tool install（常驻）。
conda 用户：如果只是做 Python 依赖与轻量环境，uv 明显更轻更快；需要复杂科学计算栈（CUDA、MKL 等）时 conda 仍有其位置。
pyenv 用户：uv python install / uv python pin 已经覆盖版本切换；想系统级多语言统一切换再叠加 mise。

迁移建议：别急着删旧工具。先用 uv 跑通一个项目，确认工作流顺手，再逐步替换。

七、几个值得马上用上的技巧

（1）用依赖组区分环境

[dependency-groups]
dev = ["pytest"]
lint = ["ruff"]

默认 uv run / uv sync 会带 dev 组；不想带就 --no-default-groups，或用 [tool.uv] default-groups 调整。

（2）导出给老系统 / 容器用

uv export --format requirements-txt > requirements.txt

（3） Python 解释器统一管理

uv python install 3.13 3.12   # 一次装多个
uv python pin 3.12            # 当前项目锁 3.12

（4）缓存与排障

uv cache clean                # 依赖解析异常时先清缓存
uv tool update-shell         # 把工具可执行目录写进 PATH（装完 uvx 工具却找不到时）

八、常见坑

现象	原因 / 解法
Windows 上装 uv 报执行策略错误	用文档给的 `powershell -ExecutionPolicy ByPass -c "..."` 整条命令
`uvx ruff` 装完却敲 `ruff` 找不到	工具可执行目录没在 PATH；跑 `uv tool update-shell`
想升级 uv 但用 pip/brew 装的、没反应	非独立安装器关闭了自更新，改用对应包管理器的升级命令
`uv run` 老去联网解析、很慢	提交 `uv.lock` 后用 `uv sync --frozen` / `uv run --frozen` 走离线
和 mise 都装了 Python，版本对不上	两者独立管理解释器不冲突；用 `uv python pin` 固定项目解释器即可
`--with` 指定的版本和工具要求冲突	解析失败报错，降低/对齐版本约束再试

九、上手路径

第一天：装好 uv，uv init 起个练手项目，体验「一条命令全建好」；
第二天：用 uv add / uv remove 替代手动改 requirements.txt；
第一周：所有"跑一下 pytest / flask"都走 uv run，告别手动 activate；
第二周：把 ruff / black / cookiecutter 这类工具从 pipx 迁到 uvx 或 uv tool install；
再往后：CI 里用 uv sync --frozen，让本地和流水线环境完全对齐。

一句话总结：如果你还在手敲 python -m venv、手维护 requirements.txt，uv 是 2026 年最值得换上的那一个。

参考

官方文档：https://docs.astral.sh/uv/
安装：https://docs.astral.sh/uv/getting-started/installation/
项目依赖：https://docs.astral.sh/uv/concepts/projects/dependencies/
运行命令：https://docs.astral.sh/uv/concepts/projects/run/
工具（uvx）：https://docs.astral.sh/uv/concepts/tools/

本文基于 2026 年 uv 官方文档（0.12.x 系列）编写。uv 迭代极快，命令细节以 uv --help 和官方文档为准。

uv-学习文章

uv：一个二进制替掉 pip + venv + poetry + pyenv + pipx

一、为什么是它

二、安装

各平台安装命令

开补全、会升级

三、uv 在管什么：一张图看懂

四、速查表

五、五个真实场景

场景 1：从零起一个项目，一条 `uv init` 搞定

场景 2：加依赖不用再手改 requirements.txt

场景 3：跑脚本，环境自动就位

场景 4：用 `uvx` 跑一次性工具，告别 pipx

场景 5：CI / Docker 复现同一套环境

六、从 poetry / pipx / conda 迁过来

七、几个值得马上用上的技巧

八、常见坑

九、上手路径

参考

Administrator

uv：一个二进制替掉 pip + venv + poetry + pyenv + pipx

一、为什么是它

二、安装

各平台安装命令

开补全、会升级

三、uv 在管什么：一张图看懂

四、速查表

五、五个真实场景

场景 1：从零起一个项目，一条 uv init 搞定

场景 2：加依赖不用再手改 requirements.txt

场景 3：跑脚本，环境自动就位

场景 4：用 uvx 跑一次性工具，告别 pipx

场景 5：CI / Docker 复现同一套环境

六、从 poetry / pipx / conda 迁过来

七、几个值得马上用上的技巧

八、常见坑

九、上手路径

参考

mise-学习文章

Administrator

场景 1：从零起一个项目，一条 `uv init` 搞定

场景 4：用 `uvx` 跑一次性工具，告别 pipx