github: github.com/astral-sh/u…

官网: astral.sh/blog/uv-uni…

UV 是一个由 Astral 公司用 Rust 开发的高性能 Python 包管理工具，旨在提供比传统 pip 更快的包安装和依赖管理体验。本文将介绍 UV 的基础用法和最佳实践。

1. 核心特性

1. 速度与功能

   • uv比pip快10-100倍，支持安装和管理Python版本。
   • 提供项目管理功能，包括依赖管理、锁文件、工作空间等。
   • 支持运行单文件脚本，并管理其依赖环境。

2. 安装与更新

   • 通过官方提供的安装脚本或PyPI安装uv。
   • 安装后，uv可以自更新到最新版本。

3. 项目管理

   • uv可以初始化项目，添加依赖，运行检查工具。
   • 支持构建和发布项目，即使项目不是用uv管理的。

4. 工具管理

   • 通过uvx命令运行工具，支持临时环境。
   • 可以安装工具并提供可执行文件。

5. Python管理

   • 安装多个Python版本，并在不同版本间快速切换。
   • 下载所需的Python版本，创建虚拟环境，并指定使用特定版本。

6. 脚本支持

   • 管理单文件脚本的依赖和环境。
   • 添加内联元数据以声明依赖，运行脚本时自动安装。

7. 兼容性与迁移

   • 提供与pip兼容的接口，支持无缝迁移。
   • 编译通用需求文件，创建虚拟环境，同步锁定需求。

2. 基础命令

2.1 环境管理

bash
 代码解读
复制代码
# 创建虚拟环境
uv venv

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

# 激活环境（Windows）
.venv\Scripts\activate

2.2 包管理

bash
 代码解读
复制代码
# 添加依赖（会更新 pyproject.toml）
uv add flask
uv add --dev pytest

# 安装依赖（不更新配置文件）
uv pip install flask

# 从项目配置安装
uv pip install .

2.3 依赖同步

bash
 代码解读
复制代码
# 同步项目依赖
uv sync

# 更新依赖
uv sync --upgrade

# 更新特定包
uv sync --upgrade-package flask

3. 项目最佳实践

3.1 新项目初始化

bash
 代码解读
复制代码
# 1. 创建项目目录
mkdir my-project && cd my-project

# 2. 创建虚拟环境
uv venv --python 3.11

# 3. 激活环境
.venv\Scripts\activate

# 4. 添加依赖
uv add flask fastapi
uv add --dev pytest black

# 5. 同步依赖
uv sync

3.2 配置文件示例

toml
 代码解读
复制代码
# pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.11"
dependencies = [
    "flask",
    "fastapi"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]

3.3 团队协作流程

1. 克隆项目后：

bash
 代码解读
复制代码
uv venv
.venv\Scripts\activate
uv sync

2. 添加新依赖时：

bash
 代码解读
复制代码
uv add new-package
uv sync  # 更新锁文件
git add pyproject.toml uv.lock

3. CI/CD 环境：

bash
 代码解读
复制代码
uv sync --locked  # 确保可重现的构建

4. UV vs pip 命令对比

5. 版本管理

5.1 通过配置文件

toml
 代码解读
复制代码
# pyproject.toml
[project]
requires-python = ">=3.9,<3.11"

5.2 通过命令行

bash
 代码解读
复制代码
# 创建特定版本环境
uv venv --python 3.9

# 使用 .python-version 文件
echo "3.9.7" > .python-version

6. 最佳实践总结

1. 依赖管理：

   • 使用 uv add 添加新依赖
   • 使用 uv sync 同步项目依赖
   • 总是提交 uv.lock 到版本控制

2. 环境管理：

   • 每个项目使用独立虚拟环境
   • 明确指定 Python 版本要求
   • 使用 --dev 分离开发依赖

3. 团队协作：

   • 统一使用 pyproject.toml
   • 保持锁文件更新
   • CI/CD 中使用 --locked 标志

结论

UV 通过现代化的设计和高性能实现，显著提升了 Python 项目的依赖管理体验。它不仅保持了与 pip 的兼容性，还带来了更快的安装速度和更好的依赖解析能力。对于新项目，强烈推荐使用 UV 作为默认的包管理工具。