UV 包管理工具

概述

uv 是一个用 Rust 编写的 Python 包管理工具，提供快速的依赖解析和虚拟环境管理。本指南介绍其核心概念和常用操作。

核心概念

pyproject.toml

项目配置文件，定义项目元信息和依赖。结构如下：

[project]
name = "project-name"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.9"
dependencies = [
    "package-name>=1.0.0",
    "another-package>=2.0.0",
]

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[[tool.uv.index]]
url = "https://pypi.example.com/simple"
default = true

uv.lock

锁定文件，记录所有依赖的确切版本和来源。自动生成，不需手动编辑。

version = 1
revision = 3
requires-python = ">=3.12"

[[package]]
name = "package-name"
version = "1.2.3"
source = { registry = "https://pypi.example.com/simple" }
dependencies = [
    { name = "dependency-name" },
]

.venv

虚拟环境目录。包含隔离的 Python 解释器和已安装的包。路径：.venv/lib/pythonX.Y/site-packages/

常用命令

初始化项目

uv init --python 3.12

创建基础的 pyproject.toml 和 .python-version 文件。不会扫描代码或自动检测依赖，需要手动添加。 --python 指定 python 版本，可选。

添加依赖

# 添加单个依赖
uv add package-name

# 添加多个依赖
uv add package1 package2 package3

# 添加特定版本
uv add "package-name>=1.0.0"

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

操作流程：

解析依赖及其子依赖
下载所有必需的包
安装到虚拟环境
更新 pyproject.toml（添加到 dependencies）
更新 uv.lock（锁定所有包的确切版本）

删除依赖

# 删除单个依赖
uv remove package-name

# 删除多个依赖
uv remove package1 package2

操作流程：

从虚拟环境卸载包及其孤立依赖
从 pyproject.toml 中移除
更新 uv.lock

同步依赖

# 根据 pyproject.toml 和 uv.lock 同步环境
uv sync

# 如果虚拟环境不存在，自动创建
uv sync

此命令用于：

新环境初始化
从 pyproject.toml 更新后重新同步
确保本地环境与锁定文件一致

升级依赖

# 升级所有依赖到最新版本
uv sync --upgrade

# 升级特定依赖
uv add package-name@latest

创建虚拟环境

# 手动创建虚拟环境（通常不需要，uv 会自动创建）
uv venv

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

运行命令

# 在虚拟环境中运行 Python
uv run python script.py

# 运行已安装的工具
uv run pytest tests/

# 运行 pip 命令
uv run pip list

查看已安装的包

# 显示特定包的信息
uv pip show package-name

# 列出所有已安装的包
uv pip list

锁定依赖

# 生成或更新 uv.lock 文件
uv lock

# 更新时刷新所有版本
uv lock --upgrade

工作流程示例

新项目初始化

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

# 2. 添加依赖
uv add requests fastapi

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

# 4. 创建虚拟环境并同步
uv sync

# 5. 运行代码
uv run python main.py

结果文件结构：

my-project/
├── pyproject.toml       # 项目配置
├── uv.lock              # 依赖锁定
├── .venv/               # 虚拟环境
├── .python-version      # Python 版本
└── src/
    └── main.py

从现有 requirements.txt 迁移

# 1. 初始化项目
uv init --python 3.12

# 2. 编辑 pyproject.toml，将 requirements.txt 中的依赖复制到 dependencies
# 示例：
# requirements.txt:
#   requests>=2.0.0
#   flask>=1.0.0
#
# pyproject.toml:
#   dependencies = [
#       "requests>=2.0.0",
#       "flask>=1.0.0",
#   ]

# 3. 同步依赖
uv sync

# 4. 验证
uv pip list

# 5. 删除 requirements.txt（可选）
rm requirements.txt

团队协作

# 开发者 A 添加新依赖
uv add new-package

# 提交更改
git add pyproject.toml uv.lock
git commit -m "Add new-package"
git push

# 开发者 B 拉取更改后
git pull

# 更新本地环境
uv sync

pyproject.toml vs uv.lock

文件	作用	手动编辑	版本精度
`pyproject.toml`	声明项目依赖范围	✓ 推荐	宽松（如 `>=1.0.0`）
`uv.lock`	记录确切版本	✗ 不推荐	精确（如 `1.2.3`）

最佳实践：

编辑 pyproject.toml 管理依赖
提交 uv.lock 到版本控制系统
不手动编辑 uv.lock

虚拟环境管理

虚拟环境位置

默认位置：.venv

查看虚拟环境信息：

# 列出虚拟环境中的包
uv pip list

# 查看特定包的详情
uv pip show package-name

删除虚拟环境

# 删除虚拟环境
rm -rf .venv

# 重新创建
uv sync

虚拟环境是可完全重建的，删除后运行 uv sync 会根据 uv.lock 重新安装。

多 Python 版本

# 为特定 Python 版本创建虚拟环境
uv venv --python 3.11

# 查看可用的 Python 版本
uv python list

常见操作问题

问题：`uv add` 是否重新安装已有的包？

如果虚拟环境中已存在该包的旧版本，uv add 会：

删除旧版本
安装新版本（取决于 pyproject.toml 中的版本指定）

问题：`uv add` 是否需要 requirements.txt？

不需要。uv add 不会读取 requirements.txt，需要手动添加依赖或编辑 pyproject.toml。

问题：如何使用自定义的 PyPI 源？

在 pyproject.toml 中配置：

[[tool.uv.index]]
url = "https://pypi.example.com/simple"
default = true

问题：如何只更新特定的包？

# 更新特定包到最新版本
uv add package-name@latest

# 或编辑 pyproject.toml 中的版本号，再运行
uv sync

问题：虚拟环境未激活，如何运行代码？

使用 uv run 自动激活虚拟环境：

uv run python main.py

# 不需要
# source .venv/bin/activate
# python main.py

总结命令速查表

任务	命令
初始化项目	`uv init`
添加依赖	`uv add package-name`
删除依赖	`uv remove package-name`
同步环境	`uv sync`
升级所有依赖	`uv sync --upgrade`
运行代码	`uv run python script.py`
查看已安装包	`uv pip list`
创建虚拟环境	`uv venv`
删除虚拟环境	`rm -rf .venv`
查看包信息	`uv pip show package-name`
生成锁文件	`uv lock`