uv 全面指南：比 pip 快 100 倍的 Python 包管理器，从安装到团队落地

前言：你的时间正在被 pip 悄悄浪费

先做个小测试。新建一个虚拟环境，装一个 fastapi：

python -m venv .venv && .venv/Scripts/activate
pip install fastapi

在 2026 年的今天，这仍然可能要等 30 秒以上。pip 会先做一次全量依赖解析，再一个一个地下载 wheel，最后逐个安装。如果 requirements.txt 里有几十个包，或者你每天要在多个项目间切换、反复重建环境，浪费的时间就非常可观了。

uv 就是冲着这个问题来的。它是 Astral 公司（对，就是做 Ruff 的那家）用 Rust 写的 Python 包管理器和解析器，号称比 pip 快 10~100 倍。本文不吹概念，直接给你一套从「看懂它」到「在团队里落地」的完整路径，所有命令都经过验证。

一、uv 为什么能快这么多

快不是玄学，主要来自四个设计：

1. Rust 实现：下载、解压、安装全链路没有 Python 解释器参与，省掉了大量 Python 层开销；
2. 全局内容寻址缓存 ：所有下载过的 wheel 存在一个全局缓存里（Linux/macOS 在 ~/.cache/uv，Windows 在 %LOCALAPPDATA%\uv\cache），新项目安装时通过硬链接直接复用，而不是重新复制；
3. 并发下载：同时拉取所有依赖，而不是像 pip 那样逐个排队；
4. 更聪明的解析器：基于 PubGrub 算法（Cargo 同款），一次解析出完整依赖图，锁定精确版本。

同样的依赖，pip 需要 30 秒，uv 通常 1~2 秒内完成------第一次要下包，之后几乎是瞬间。

二、安装 uv（三条路任选）

# 方式一：pip 安装（最省事）
pip install 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"

包管理器用户：winget install astral-sh.uv、scoop install uv、brew install uv 也都支持。

装完验证：

uv --version

三、先忘掉复杂概念：最常用的三个命令

uv 的定位是「全家桶」，但日常 90% 的场景只需要三个命令：

1. uv venv ------ 创建虚拟环境

cd myproject
uv venv
# 输出：Using Python 3.12.7
#       Creating virtual environment at: .venv

如果本机没有合适的 Python 版本，uv 会自动下载一个（见第五节），完全不需要手动装。

2. uv pip install ------ 兼容 pip 的安装命令

uv pip install -r requirements.txt
uv pip install fastapi "pydantic>=2.0" pytest --dev

它兼容 pip 的参数习惯，旧项目可以直接切换。

3. uv run ------ 一键执行

uv run python main.py
# 或直接执行脚本
uv run main.py

uv run 会自动激活当前目录的 .venv 并运行命令，不需要手动 source activate。

四、从 requirements.txt 迁移到 uv.lock

临时项目用 uv pip install 就够了；长期维护的项目建议直接上 pyproject.toml + uv.lock，这才是 uv 的真正威力。

4.1 初始化项目

uv init myapp
cd myapp

这会生成：

myapp/
├── .python-version    # 记录 Python 版本
├── pyproject.toml     # 项目元数据 + 依赖声明
├── main.py
└── README.md

4.2 添加依赖

uv add fastapi "uvicorn[standard]" httpx

uv add 会做两件事：把依赖写进 pyproject.toml 的 [project.dependencies]，同时生成/更新 uv.lock 锁定精确版本。

4.3 同步安装（对应 pip 的 install）

uv sync

uv sync 严格按照 uv.lock 安装，保证团队每个人、每台 CI 机器拿到的依赖字节级一致。新增成员克隆仓库后只需要两步：

uv sync
uv run python main.py

4.4 升级依赖

uv lock --upgrade        # 重新解析并升级 lock 文件
uv lock --upgrade-package fastapi   # 只升级某个包

4.5 已有 requirements.txt 怎么办？

# 自动把 requirements.txt 的内容迁移到 pyproject.toml
uv add -r requirements.txt

之后删掉 requirements.txt，统一走 pyproject.toml。

五、Python 版本管理（替代 pyenv）

uv 内置了 Python 版本管理，再也不用装 pyenv：

# 安装指定版本
uv python install 3.12
uv python install 3.11.9

# 查看可用版本
uv python list

# 为当前项目固定版本（写入 .python-version）
uv python pin 3.12

项目目录下有了 .python-version 后，uv venv、uv run 都会自动使用对应版本。在 2026 年，新机器配 Python 环境只需要一个 uv。

六、uvx：跑一次性工具

uvx（uv 的孪生命令）用于执行临时工具，装完即用、用完即走，不污染环境：

# 直接运行 ruff 检查代码
uvx ruff check .

# 起一个本地 HTTP 服务
uvx serve .

# 运行其他语言工具
uvx yamllint config.yml

原理：工具被缓存到全局，重复运行秒开。CI 里特别适合------不用预先 pip install 工具链。

七、在 CI / Docker 里落地

GitHub Actions

steps:
  - uses: actions/checkout@v4
  - uses: astral-sh/setup-uv@v5
    with:
      enable-cache: true        # 缓存 uv 依赖，CI 提速明显
  - run: uv sync --frozen       # --frozen: 严格按 lock 安装，lock 过期直接报错
  - run: uv run pytest

Dockerfile

FROM python:3.12-slim

# 安装 uv（官方镜像推荐方式）
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project

COPY . .
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

关键点：先拷贝 pyproject.toml 和 uv.lock 再 uv sync，可以充分利用 Docker 层缓存------依赖没变时这一层不会重建。

八、国内网络与私有源配置

uv 支持环境变量和配置文件（pyproject.toml 或 uv.toml）：

# 临时指定镜像源
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或写入环境变量，长期生效
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

私有仓库（如公司 Nexus / Artifactory）：

# uv.toml
[[index]]
url = "https://pypi.org/simple"

[[index]]
url = "https://nexus.example.com/repository/pypi/simple"
priority = "primary"

九、三个容易踩的坑

坑 1：把 uv pip install 和 uv add 混着用

一个项目里如果两种方式都用了，pyproject.toml 和实际环境可能不一致。新项目只用 uv add / uv sync；临时环境才用 uv pip install。

坑 2：在 CI 里忘加 --frozen

不加 --frozen 时，uv sync 在 lock 文件过期时会自动重新解析 ，导致 CI 装的版本和本地不一致。生产流程一律加 --frozen，让「锁文件过期」直接变成构建错误，倒逼开发者及时更新。

坑 3：以为 uv 会自己找 Python

uv venv 在系统没有合适 Python 时会自动下载，但如果系统里恰好有一个旧版本 （比如 3.9），它会「尊重」旧版本而不是自动升级。项目里用 uv python pin 3.12 显式固定，避免同事的机器环境不一致。

十、命令对照速查表

场景	pip 时代	uv 时代
创建环境	python -m venv .venv	uv venv
安装依赖	pip install -r requirements.txt	uv sync（有 lock）/ uv pip install -r requirements.txt
添加依赖	pip install fastapi && pip freeze > requirements.txt	uv add fastapi
移除依赖	手动改 requirements.txt	uv remove fastapi
运行脚本	source .venv/bin/activate && python main.py	uv run python main.py
管理 Python 版本	装 pyenv	uv python install / pin
一次性工具	pip install ruff && ruff check .	uvx ruff check .

结语

uv 最聪明的地方在于学习成本趋近于零 ：uv pip install 完全兼容 pip 的肌肉记忆，而 uv add / uv sync / uv.lock 又提供了现代包管理器该有的可复现性。它没有发明新概念，只是把「依赖解析 + 下载 + 安装 + 版本管理」这些苦活全部重做了一遍。

建议迁移节奏：第一周 ，把个人项目的 pip install 换成 uv pip install（零成本）；第一个月 ，新项目直接用 uv init，走 uv add / uv sync 流程；一个季度内，把团队 CI 和 Dockerfile 切到 uv，你会看到构建时间肉眼可见地缩短。

如果你的团队还在争论「用 pip 还是 poetry」------别争了，试试 uv，答案会自己浮现。