UV 相比 pip 的主要优势

  1. 速度更快

    • 使用 Rust 编写，性能优化更好
    • 并行下载依赖
    • 更智能的依赖解析算法

  2. 更好的依赖解析

    • 更准确的依赖树计算
    • 更好地处理版本冲突
    • 支持 lockfile，确保环境的可重现性

  3. 现代化特性

    • 原生支持虚拟环境管理
    • 与 pip 完全兼容
    • 支持从多种源安装包（PyPI、Git、本地等）

安装方法

在 macOS 上安装 UV：

brew install uv

基础使用

虚拟环境管理

# 创建虚拟环境
uv venv <env_name>

# 激活虚拟环境
source <env_name>/bin/activate

包管理基础命令（pip适配）

# 安装单个包
uv pip install package_name

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

# 卸载包
uv pip uninstall package_name

# 列出当前环境中已安装的所有包
uv pip list

# 显示特定包的详细信息（版本、依赖等）
uv pip show package_name

# 导出当前环境的依赖到 requirements.txt
uv pip freeze > requirements.txt

# 以开发模式安装当前目录下的项目
# 适用于开发自己的包时，修改代码后无需重新安装
uv pip install -e .

依赖管理最佳实践

requirements.in vs requirements.txt

  1. requirements.in（源依赖文件）

    fastapi>=0.100.0
uvicorn[standard]
python-dotenv
requests
    • 手动维护的直接依赖声明
    • 使用灵活的版本限制（>=, ~=, ^）
    • 只包含项目直接需要的包

  2. requirements.txt（锁定文件）

    # This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in -o requirements.txt
annotated-types==0.7.0
    # via pydantic
anyio==4.9.0
    # via starlette, watchfiles
...
    • 由 uv pip compile 自动生成
    • 包含所有依赖的精确版本
    • 确保环境的可重现性

依赖管理工作流

# 创建 requirements.in 文件声明直接依赖
# 编译依赖生成 requirements.txt
uv pip compile requirements.in -o requirements.txt

# 安装依赖
uv pip sync requirements.txt

多环境依赖管理

# 开发环境依赖
uv pip compile requirements.in requirements-dev.in -o requirements-dev.txt

# 生产环境依赖
uv pip compile requirements.in -o requirements.txt

# 测试环境依赖
uv pip compile requirements.in requirements-test.in -o requirements-test.txt

依赖更新与安全

# 更新单个包
uv pip compile --upgrade-package fastapi

# 更新所有包
uv pip compile --upgrade

# 更新到最新的兼容版本
uv pip compile --upgrade-compatible

# 生成带哈希值的依赖文件以确保安全性
uv pip compile --generate-hashes requirements.in -o requirements-hashes.txt

依赖约束

# 使用约束文件限制版本
uv pip compile --constraint constraints.txt requirements.in

项目实践示例

1. 项目初始化

# 创建项目目录
mkdir uv-demo
cd uv-demo

# 创建并激活虚拟环境
uv venv .venv
source .venv/bin/activate

2. 依赖管理实践

创建 requirements.in 文件：

fastapi>=0.100.0
uvicorn[standard]
python-dotenv
requests

编译并安装依赖：

uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

3. 示例应用

创建 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello from UV managed environment!"}

运行应用：

uvicorn main:app --reload

UVX 工具

UVX 是 UV 的扩展工具，提供了一种简单的方式来运行 Python 包提供的命令。

UVX 基本用法

# 使用特定包提供的命令
uvx --from <package_name> <command>

# 使用临时安装的包运行命令
uvx --with <package_name> <command>

# 使用 requirements.txt 中的依赖运行命令
uvx --with-requirements requirements.txt <command>

常见用例

# 运行 pytest 测试
uvx --with pytest pytest

# 使用 black 格式化代码
uvx --with black black .

# 在 CI 环境中运行测试
uvx --with-requirements requirements-dev.txt pytest

快速尝试新包：itry 模式

Simon Willison 提出了一种使用 uvx 快速尝试新 Python 包的简单模式，无需预先安装或创建虚拟环境：

# 使用 uvx 启动带有指定包的 ipython 环境
uvx --with llm --with sqlite-utils ipython

这个命令会：

  1. 创建一个专用的临时虚拟环境
  2. 安装指定的包（这里是 llm 和 sqlite-utils）以及 ipython
  3. 启动 ipython REPL，让你可以立即开始使用这些包

你还可以通过 --python 选项指定 Python 版本：

uvx --python 3.13 --with llm --with sqlite-utils ipython

可以将这个模式封装成一个简单的 shell 脚本，方便日常使用：

#!/bin/sh
# itry - 用于通过 uvx 启动带有指定包的 ipython 的脚本

# 显示帮助信息
[ "$1" = "--help" ] && {
    echo "用法: itry [包名...]"
    echo "示例: itry llm sqlite-utils datasette"
    exit 0
}

# 初始化空字符串用于存储包
PACKAGES=""

# 处理所有参数，在每个参数前添加 --with
for arg in "$@"; do
    PACKAGES="$PACKAGES --with $arg"
done

# 如果存在，移除开头的空格
PACKAGES="${PACKAGES# }"

# 执行 uvx 命令
exec uvx $PACKAGES --python 3.13 ipython

推荐的项目结构

project/
├── pyproject.toml    # 项目配置
├── requirements.in   # 依赖声明
├── requirements.txt  # 锁定的依赖
└── src/             # 源代码目录

版本控制与 CI/CD 集成

  1. 版本控制策略

    • 将 requirements.txt 和 requirements-*.txt 加入版本控制
    • 将虚拟环境（.venv）添加到 .gitignore

  2. CI/CD 集成

    # CI/CD 环境中使用
uv pip sync requirements.txt

# 开发环境使用
uv pip sync requirements-dev.txt

  3. 开发工作流

    # 1. 创建虚拟环境
uv venv .venv
source .venv/bin/activate

# 2. 安装开发依赖
uv pip sync requirements-dev.txt

# 3. 开发模式安装项目
uv pip install -e .

总结

UV 是一个现代化的 Python 包管理器，它在保持与 pip 兼容的同时，提供了更好的性能和依赖管理能力。它特别适合：

  • 需要快速依赖安装的大型项目
  • 需要严格依赖版本控制的生产环境
  • 需要可重现构建环境的团队协作项目

参考文档