uv包管理器

简介

uv 是由 Astral（Ruff 的作者）团队使用 Rust 编写的 Python 包和项目管理器。它旨在用单一工具统一替代传统 Python 开发中的多件套：

pip → 包安装
virtualenv / venv → 虚拟环境
pip-tools → 依赖锁定
pyenv → Python 版本管理
pipx → 工具安装
poetry → 项目管理

截至 2026 年，uv 在 PyPI 月下载量已超过 1.26 亿，成为 Python 生态中增长最快的工具。

核心优势

特性	说明
极快速度	Rust 实现 + 并行下载 + 智能缓存，比 pip 快 10-100 倍
统一入口	一个工具覆盖包管理、虚拟环境、版本管理、工具安装
空间高效	全局缓存与包去重，减少重复下载和磁盘占用
兼容生态	完全兼容 `pip` 的命令行接口和 `requirements.txt` 格式
可移植	`uv.lock` 提供跨平台一致的依赖锁定结果
轻量无依赖	单二进制文件（约 10-15MB），无需 Python 解释器即可运行

安装

官方推荐（跨平台）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

其他方式

# Homebrew (macOS)
brew install uv

# Scoop (Windows)
scoop install uv

# pip / pipx
pip install uv
# 或
pipx install uv

# Docker
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

验证安装

1	uv --version

核心功能

1. 项目管理（推荐用法）

# 初始化项目
uv init my-project
cd my-project

# 添加依赖（自动创建 .venv）
uv add requests fastapi

# 添加开发依赖
uv add --dev pytest ruff

# 移除依赖
uv remove requests

# 锁定依赖（生成 uv.lock）
uv lock

# 同步依赖（根据 uv.lock 精确安装）
uv sync

项目结构：

my-project/
├── .python-version   # Python 版本锁定
├── pyproject.toml    # 项目配置 + 依赖声明
├── uv.lock           # 精确依赖锁定（应提交 Git）
├── README.md
└── src/
    └── my_project/
        └── __init__.py

2. 运行代码

# 自动在项目的虚拟环境中运行（无需手动激活）
uv run python main.py

# 运行测试
uv run pytest

# 运行脚本（自动解析内联依赖）
uv run script.py

3. 虚拟环境管理

# 创建虚拟环境（极快，~10ms）
uv venv

# 指定 Python 版本创建
uv venv --python 3.11

# 指定路径
uv venv myenv

4. Python 版本管理

# 安装指定 Python 版本
uv python install 3.12 3.13

# 为项目固定 Python 版本
uv python pin 3.12

# 查看已安装的版本
uv python list --only-installed

5. 兼容 pip 模式

# 安装包
uv pip install requests

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 导出依赖
uv pip freeze > requirements.txt

# 查看已安装的包
uv pip list

6. 全局工具管理（替代 pipx）

# 安装全局工具
uv tool install ruff

# 临时运行（一次性使用）
uvx pycowsay 'hello'

# 列出已安装的工具
uv tool list

7. 单文件脚本（内联依赖）

在脚本头部直接声明依赖，无需创建完整项目：

# /// script
# dependencies = ["requests", "rich"]
# ///

import requests
from rich import print

resp = requests.get("https://api.github.com")
print(resp.json())

运行方式：

1 2	uv run script.py # uv 会自动创建临时环境并安装依赖

从现有项目迁移

从 pip + requirements.txt

# 进入现有项目
cd existing-project

# 初始化 uv（保留现有文件）
uv init

# 导入现有依赖
uv pip install -r requirements.txt

# 生成 pyproject.toml + uv.lock
# 之后可以删除 requirements.txt

从 Poetry

# 将 [tool.poetry.dependencies] 迁移到 [project.dependencies]（PEP 621 格式）
# 然后重新初始化
uv init
uv lock

CI/CD 集成

GitHub Actions

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --frozen
      - run: uv run pytest

与传统工具对比

操作	传统方式	uv 方式
创建虚拟环境	`python -m venv .venv` (~800ms)	`uv venv` (~10ms)
安装包	`pip install requests`	`uv pip install requests` 或 `uv add requests`
锁定依赖	`pip-tools` + `pip-compile`	`uv lock`
同步依赖	`pip-sync`	`uv sync`
管理 Python 版本	`pyenv install 3.12`	`uv python install 3.12`
运行 CLI 工具	`pipx run ruff`	`uvx ruff`
导出依赖	`pip freeze > requirements.txt`	`uv pip freeze`

常见问题

缓存管理

# 查看缓存大小
uv cache info

# 清理缓存
uv cache clean

更新 uv

1	uv self update

总结

uv 是 Python 包管理工具的未来方向。它以极致的速度、统一的功能集和对现有生态的兼容性，正在成为 Python 开发者的首选工具。无论是个人项目、团队协作还是 CI/CD 流水线，uv 都能显著提升开发效率。