uv使用指南 - 技术栈

🚀 Python 打包工具 UV 使用指南

UV 是一个用 Rust 编写的极速 Python 包管理器和解析器，旨在成为 pip、pip-tools、virtualenv 等工具的单一替代方案。

📋 目录

核心概念与设计哲学
安装与配置
基础使用方法
项目管理与工作流
高级功能与技巧
与其他工具集成
性能优化与最佳实践
故障排除与调试
学习资源与进阶

🧠 核心概念与设计哲学

设计目标

极速性能: 比传统工具快 10-100 倍
一体化解决方案: 替代 pip、pip-tools、virtualenv、pipenv 等
现代标准支持: 优先支持 pyproject.toml 和 PEP 标准
可靠性: 基于 Rust 的内存安全性和强大的依赖解析器

核心组件

包安装器: 替代 pip 的功能
虚拟环境管理器: 替代 virtualenv 的功能
依赖解析器: 基于 PubGrub 算法的高效解析
项目初始化器: 创建新项目结构

🔧 安装与配置

多种安装方式

bash 复制代码

# Windows PowerShell (推荐)
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

# 使用 pip (已安装Python的情况下)
pip install uv

# 使用 pipx
pipx install uv

# 使用 Homebrew (macOS)
brew install uv

# 手动安装 (从发布页面下载)
# 访问: https://github.com/astral-sh/uv/releases

配置设置

bash 复制代码

# 查看所有配置选项
uv config list

# 设置全局Python版本
uv config set default-python-version 3.11

# 配置镜像源 (国内用户推荐)
uv config set index-url https://pypi.tuna.tsinghua.edu.cn/simple/

# 或者通过环境变量
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/

配置文件位置

全局配置: ~/.config/uv/uv.toml (Linux/macOS) 或 %APPDATA%\uv\uv.toml (Windows)
项目级配置: 项目目录中的 uv.toml

📖 基础使用方法

虚拟环境管理

bash 复制代码

# 创建虚拟环境
uv venv .venv

# 创建指定Python版本的虚拟环境
uv venv --python 3.11 .venv

# 激活虚拟环境 (Windows)
.\.venv\Scripts\activate

# 激活虚拟环境 (Unix/macOS)
source .venv/bin/activate

# 列出可用Python版本
uv python list

# 安装特定Python版本
uv python install 3.11

包管理操作

bash 复制代码

# 安装单个包
uv pip install requests

# 安装多个包
uv pip install requests pandas numpy

# 安装指定版本的包
uv pip install "django==4.2.0"

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

# 列出已安装的包
uv pip list

# 卸载包
uv pip uninstall package-name

# 更新包
uv pip install --upgrade package-name

# 查看包信息
uv pip show package-name

依赖管理

bash 复制代码

# 生成requirements.txt
uv pip freeze > requirements.txt

# 安装开发依赖
uv pip install --dev black isort flake8

# 根据pyproject.toml安装依赖
uv pip install -e .

🏗️ 项目管理与工作流

项目初始化与设置

bash 复制代码

# 创建新项目
uv init my-project
cd my-project

# 添加生产依赖
uv add requests

# 添加开发依赖
uv add --dev black

# 安装所有依赖 (根据pyproject.toml)
uv sync

# 安装生产依赖 only
uv sync --production

# 更新依赖锁文件
uv sync --upgrade

依赖解析与锁文件

bash 复制代码

# 检查依赖更新
uv pip list --outdated

# 更新所有依赖
uv pip install --upgrade --all

# 生成精确的锁文件
uv sync --locked

# 验证当前依赖与锁文件一致性
uv sync --check

项目结构示例

复制代码

my-project/
├── pyproject.toml    # 项目配置和依赖声明
├── uv.lock           # 依赖锁文件 (自动生成)
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── module.py
├── tests/
│   └── test_module.py
└── .venv/            # 虚拟环境 (可选)

🚀 高级功能与技巧

缓存与性能优化

bash 复制代码

# 清理缓存
uv cache clean

# 查看缓存信息
uv cache info

# 预下载包到缓存 (用于CI环境)
uv pip download --only-binary=:all: --dest ./cache-dir -r requirements.txt

平台特定依赖

bash 复制代码

# 在pyproject.toml中指定平台特定依赖
[project]
dependencies = [
    "requests",
    "cffi; platform_machine == 'x86_64'",
]

# 或者使用环境标记
[project.optional-dependencies]
windows = ["pywin32"]
linux = ["dbus-python"]

自定义索引源

bash 复制代码

# 添加额外包索引源
uv config set extra-index-urls '["https://pypi.company.com/simple"]'

# 或使用TOML配置
[[index]]
url = "https://pypi.company.com/simple/"
name = "company"
priority = 1

二进制包控制

bash 复制代码

# 强制使用源码编译
uv pip install --no-binary :all: package-name

# 强制使用预编译二进制包
uv pip install --only-binary :all: package-name

# 指定特定包的二进制策略
uv pip install --only-binary=:numpy: --no-binary=:pandas: .

🔗 与其他工具集成

与PDM/Poetry项目兼容

bash 复制代码

# 安装PDM项目
uv pip install -e . --no-deps
uv sync --dev

# 安装Poetry项目
uv pip install -e .
uv sync --dev --extras all

CI/CD集成示例

yaml 复制代码

# GitHub Actions 示例
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: astral-sh/setup-uv@v3
      with:
        python-version: "3.11"
    - run: uv sync --dev
    - run: uv run pytest

预发布环境配置

bash 复制代码

# 安装预发布版本
uv pip install --pre package-name

# 允许安装alpha/beta版本
uv pip install --upgrade --pre package-name

⚡ 性能优化与最佳实践

最佳实践指南

利用缓存机制: UV 具有高效的缓存系统，避免重复下载
使用锁文件 : 始终使用 uv.lock 确保环境一致性
合理配置镜像源: 国内用户配置国内镜像大幅提升速度
按需安装二进制包: 根据需要选择源码编译或预编译二进制包

性能对比技巧

bash 复制代码

# 对比UV和pip的性能
time uv pip install -r requirements.txt
time pip install -r requirements.txt

# 清除缓存后测试
uv cache clean
pip cache purge

大型项目优化

bash 复制代码

# 分阶段安装依赖 (Dockerfile中特别有用)
# 第一阶段: 安装构建依赖
uv sync --dev --production

# 第二阶段: 仅安装运行依赖
uv sync --production

🐛 故障排除与调试

常见问题解决

bash 复制代码

# 详细日志输出
uv pip install -v package-name

# 更详细的调试信息
uv pip install -vv package-name

# 显示依赖解析树
uv pip install --dry-run --report - > report.json

# 检查环境问题
uv debug --verbose

依赖冲突解决

bash 复制代码

# 查看依赖冲突信息
uv pip check

# 强制重新安装所有依赖
uv pip install --force-reinstall -r requirements.txt

# 忽略已安装的包
uv pip install --ignore-installed package-name

网络问题处理

bash 复制代码

# 设置超时时间
uv pip install --timeout 60 package-name

# 设置重试次数
uv pip install --retries 3 package-name

# 使用代理
export UV_HTTP_PROXY=http://proxy.example.com:8080
export UV_HTTPS_PROXY=http://proxy.example.com:8080

📚 学习资源与进阶

官方资源

进阶主题

自定义解析策略: 学习如何配置依赖解析行为
插件开发: 了解如何为 UV 开发扩展功能
源码编译: 从源码编译 UV 以获得最新特性
集成测试: 在复杂项目中实施 UV 的测试策略

迁移指南

bash 复制代码

# 从 requirements.txt 迁移到 pyproject.toml
uv init
uv add -r requirements.txt

# 从 Pipenv 迁移
uv pip install -r Pipfile --dev

# 从 Poetry 迁移
uv pip install -r pyproject.toml --dev