[toc]

Python现代化包管理工具UV

简介

uv 是由 Astral 公司（开发 Ruff 的团队）使用 Rust 语言编写的 Python 包管理和环境管理工具。它是 2024-2026 年 Python 生态中最热门的工具，正在逐步成为事实上的标准。

核心定位

uv 的目标是统一 Python 工具链，用一个工具替代：

pip（包安装）
pip-tools（依赖锁定）
virtualenv / venv（虚拟环境）
pyenv（Python 版本管理）
twine（包发布）

核心优势

特性	说明
极速	Rust 编写，比 pip 快 10-100 倍
原生 Workspace 支持	Monorepo 多包管理是内置功能
Python 版本管理	自动下载、管理 Python 版本，无需手动安装
PEP 621 兼容	完全兼容现代 `pyproject.toml` 标准
跨平台锁定	`uv.lock` 文件确保团队环境完全一致
项目即环境	自动管理虚拟环境，无需手动激活

5 分钟快速上手

bash

# 创建并进入项目
uv init try-uv && cd try-uv

# 添加依赖
uv add requests

# 直接运行 Python 代码（自动在虚拟环境中执行）
uv run python -c "import requests; print(requests.__version__)"

就这么简单，无需手动创建虚拟环境，无需手动激活，一切都是自动的。

与其他包管理工具的对比

uv vs pip

维度	pip	uv
速度	慢（Python 实现）	极快（Rust 实现）
虚拟环境	需手动创建和激活	自动管理
Python 版本	需手动安装	自动下载管理
依赖锁定	无原生支持	`uv.lock` 原生支持
Workspace	不支持	原生支持

uv vs Poetry

维度	Poetry	uv
成熟度	⭐⭐⭐⭐⭐ 非常成熟（2018年发布）	⭐⭐⭐⭐ 快速成熟中（2024年发布）
速度	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 极快
PEP 621 兼容	⭐⭐⭐ 部分兼容（有自己的配置格式）	⭐⭐⭐⭐⭐ 完全兼容
Workspace	⭐⭐⭐⭐ 支持良好	⭐⭐⭐⭐⭐ 原生内置
社区生态	⭐⭐⭐⭐⭐ 最大	⭐⭐⭐⭐ 快速增长
2026 年趋势	维护模式	活跃开发，成为标准

选择建议：

新项目：直接选 uv
已有 Poetry 项目：Poetry 仍然稳定可用，但迁移到 uv 成本很低
追求速度：选 uv
需要复杂依赖冲突处理：Poetry 经验更丰富

uv vs Conda

维度	Conda	uv
定位	数据科学环境管理	Python 包管理
非 Python 包	支持（C/C++ 库）	不支持
速度	慢	极快
虚拟环境	支持	支持
包来源	Conda 仓库 + PyPI	PyPI

选择建议：

纯 Python 项目：选 uv
需要 C/C++ 依赖（如 CUDA）：选 Conda 或结合使用

与 pyproject.toml 的关系

关于 pyproject.toml 的详细说明，可参考 Python统一构建配置PyProject.toml文件。

PEP 621 标准

pyproject.toml 是现代 Python 项目的标准配置文件，uv 完全兼容这个标准。

最小示例

toml

[project]
name = "my-project"
version = "0.1.0"
description = "我的项目"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.135.0",
    "uvicorn>=0.41.0",
]

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

uv 扩展配置

uv 在兼容 PEP 621 的基础上，增加了自己的配置段：

toml

# Workspace（Monorepo）配置
[tool.uv.workspace]
members = ["packages/*"]

# 本地包源配置
[tool.uv.sources]
my-local-package = { workspace = true }

# 镜像源配置
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

关键原则：uv 不修改 pyproject.toml 的标准格式，只在 [tool.uv.*] 下添加扩展配置。

安装

Windows 安装

方式一：PowerShell 安装（推荐）

注意以管理员权限运行 PowerShell。

powershell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

方式二：手动下载

访问 https://github.com/astral-sh/uv/releases/latest
下载 uv-x86_64-pc-windows-msvc.zip
将压缩包解压后，存放到一个目录中（目录路径不能包含中文字符）。该目录就是 uv 的安装目录。
将安装目录添加到Windows系统的环境变量 PATH 中。

验证安装

bash

uv --version
# 输出：uv 0.12.23 (xxxxxx 2026-10-03)

Linux / macOS 安装

bash

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

# macOS
brew install uv

# 验证
uv --version

安装后配置（国内镜像）

创建配置文件加速下载：

Windows: %APPDATA%\uv\uv.tomlLinux/macOS: ~/.config/uv/uv.toml

toml

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

常用命令

项目初始化

bash

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

# 初始化当前目录为 uv 项目
uv init

Python 版本管理

bash

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

# 查看已安装的 Python
uv python list

# 固定项目 Python 版本（会在项目根目录生成 .python-version 文件）
uv python pin 3.12

uv python pin 会在项目根目录生成 .python-version 文件，内容为指定的 Python 版本号。建议将该文件提交到 git，确保团队成员使用相同的 Python 版本。

虚拟环境管理

关于 Python 虚拟环境的概念和其他管理工具，可参考 Python虚拟环境笔记。

bash

# 创建虚拟环境（默认在项目根目录创建 .venv，自动使用项目指定的 Python）
uv venv

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

# 指定虚拟环境路径
uv venv my-env

依赖管理

bash

# 安装依赖（根据 pyproject.toml）
uv sync

# 添加依赖
uv add requests
uv add "fastapi>=0.135.0"

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

# 删除依赖
uv remove requests

# 生成锁定文件
uv lock

# 升级依赖
uv upgrade
uv upgrade fastapi

运行命令

bash

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

# 在虚拟环境中运行模块
uv run uvicorn main:app

# 运行临时工具（自动创建隔离的临时环境，用完即弃）
uvx ruff check .
# uvx 等价于 uv tool run，用于一次性运行某个 CLI 工具

包构建与发布

bash

# 构建包
uv build

# 发布到 PyPI
uv publish

全局工具管理

uv 可以像 pipx 一样全局安装和管理 Python CLI 工具（如 ruff、black、mypy 等）：

bash

# 安装全局工具（安装到独立的隔离环境）
uv tool install ruff

# 运行工具（无需先安装，首次自动下载并缓存）
uv tool run ruff check .
# 或使用简写
uvx ruff check .

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

# 升级工具
uv tool upgrade ruff

# 卸载工具
uv tool uninstall ruff

# 查看工具安装目录
uv tool dir

与手动 pip install 全局安装的区别：uv tool 会将每个工具安装到独立的隔离环境，避免依赖冲突。

pip 兼容命令

为了方便从 pip 迁移，uv 提供了一组 pip 兼容接口：

bash

# 等价于 pip install
uv pip install requests

# 等价于 pip list
uv pip list

# 等价于 pip show
uv pip show fastapi

# 等价于 pip freeze（导出当前环境所有包）
uv pip freeze > requirements.txt

# 编译依赖（pip-tools 的 pip-compile 功能）
uv pip compile requirements.in -o requirements.txt

这些是 uv 为兼容 pip 工作流提供的子命令，在你完全切换到 uv 原生命令（uv add、uv sync）之前可以作为过渡使用。

其他实用命令

bash

# 查看依赖树
uv tree

# 限制依赖树深度
uv tree --depth 2

# 反向依赖树（查看哪些包依赖了指定包）
uv tree --invert fastapi

# 导出为 requirements.txt 格式（用于兼容其他工具）
uv export --format requirements-txt -o requirements.txt

# 清理 uv 缓存
uv cache clean

常用场景

场景一：单项目开发

bash

# 1. 创建项目
uv init my-project
cd my-project

# 2. 添加依赖
uv add fastapi uvicorn

# 3. 编写代码...

# 4. 运行
uv run python main.py

场景二：Monorepo（多包项目）

项目结构：

my-monorepo/
├── pyproject.toml          # 根配置
├── uv.lock                 # 锁定文件
├── packages/
│   ├── core/               # 核心库
│   │   ├── pyproject.toml
│   │   └── src/
│   │       └── core/
│   │           ├── __init__.py
│   │           └── utils.py
│   └── api/                # API 服务
│       ├── pyproject.toml
│       └── src/
│           └── api/
│               ├── __init__.py
│               └── main.py

根 pyproject.toml：

toml

[project]
name = "my-monorepo"
version = "1.0.0"
requires-python = ">=3.12"

[tool.uv.workspace]
members = ["packages/*"]

[tool.uv.sources]
core = { workspace = true }

packages/api/pyproject.toml：

toml

[project]
name = "api"
version = "1.0.0"
dependencies = [
    "core",           # 自动解析为本地 workspace 包
    "fastapi>=0.135.0",
]

开发流程：

bash

cd my-monorepo

# 一键安装所有包和依赖
uv sync

# 运行 API 服务
uv run --directory packages/api python -m api.main

# 给 API 添加新依赖
uv add requests --directory packages/api

场景三：团队协作

bash

# 新成员加入
git clone <仓库>
cd project

# 一键同步环境（自动创建 .venv，安装所有依赖）
uv sync

# 开始开发
uv run python main.py

关键：uv.lock 文件必须提交到 git，它记录了所有依赖的精确版本，确保团队环境一致。

场景四：无全局 Python 环境

uv 最大的特点是不需要手动安装 Python：

bash

# 电脑上没有 Python？没关系！
uv python install 3.12

# 创建项目
uv init my-project

# uv 自动使用下载的 Python
uv sync

这对于 CI/CD 和新机器初始化特别有用。

场景五：PyCharm 集成

打开项目：PyCharm 自动识别 pyproject.toml
配置解释器：Settings → Python Interpreter → 选择 .venv\Scripts\python.exe
同步依赖：修改 pyproject.toml 后，点击 "Sync project"
Workspace 支持：uv 的 workspace 让 PyCharm 正确理解 Monorepo 结构，避免 import 报错

场景六：从 Poetry / pip 迁移

从 Poetry 迁移：

bash

# 1. 初始化 uv 项目
uv init

# 2. 将 Poetry 依赖转换为 uv 依赖
uv add $(poetry export -f requirements.txt --without-hashes | sed 's/==/>=/')

# 3. 同步并生成 uv.lock
uv sync

# 4. 验证迁移结果
uv run python -c "import your_package; print('迁移成功')"

从 pip + requirements.txt 迁移：

bash

# 1. 初始化 uv 项目
uv init

# 2. 导入现有 requirements.txt
uv add -r requirements.txt

# 3. 生成 uv.lock
uv lock

# 4. 提交 uv.lock 和 pyproject.toml 到 git
git add pyproject.toml uv.lock
git commit -m "迁移至 uv"

迁移后可以删除的文件：poetry.lock、requirements.txt（如果有）、setup.py、setup.cfg（如果已迁移到 pyproject.toml）。

场景七：Script 内联元数据（PEP 723）

uv 支持在单个 Python 脚本中声明依赖，无需创建项目：

python

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///
import requests
from rich import print as rprint

resp = requests.get("https://api.github.com/repos/astral-sh/uv")
rprint(f"[bold green]Stars:[/bold green] {resp.json()['stargazers_count']}")

运行方式：

bash

# uv 自动读取脚本中的元数据，创建临时环境并运行
uv run script.py

这非常适合单文件脚本、演示代码、自动化任务等场景，无需维护 pyproject.toml。

最佳实践

提交 uv.lock：确保团队环境一致
使用 Workspace：Monorepo 项目必用，替代 pip install -e
配置国内镜像：加速依赖下载
不手动激活虚拟环境：用 uv run 代替手动激活（Linux: source .venv/bin/activate，Windows: .venv\Scripts\activate）。uv 会自动处理环境切换，避免忘记激活导致的"明明装了却找不到"的问题。
固定 Python 版本：uv python pin 3.12 避免版本漂移，生成的 .python-version 文件要一并提交到 git。

总结

uv 是 2024-2026 年 Python 生态中最值得投资的工具。它解决了 Python 长期以来的工具链碎片化问题，提供了：

极速的包管理体验
原生的 Monorepo 支持
自动的 Python 版本管理
与现有生态的完美兼容

对于新项目，直接选择 uv；对于已有项目，迁移成本也很低，收益明显。

Python现代化包管理工具UV ​

简介 ​

核心定位 ​

核心优势 ​

5 分钟快速上手 ​

与其他包管理工具的对比 ​

uv vs pip ​

uv vs Poetry ​

uv vs Conda ​

与 pyproject.toml 的关系 ​

PEP 621 标准 ​

最小示例 ​

uv 扩展配置 ​

安装 ​

Windows 安装 ​

方式一：PowerShell 安装（推荐） ​

方式二：手动下载 ​

验证安装 ​

Linux / macOS 安装 ​

安装后配置（国内镜像） ​

常用命令 ​

项目初始化 ​

Python 版本管理 ​

虚拟环境管理 ​

依赖管理 ​

运行命令 ​

包构建与发布 ​

全局工具管理 ​

pip 兼容命令 ​

其他实用命令 ​

常用场景 ​

场景一：单项目开发 ​

场景二：Monorepo（多包项目） ​

场景三：团队协作 ​

场景四：无全局 Python 环境 ​

场景五：PyCharm 集成 ​

场景六：从 Poetry / pip 迁移 ​

场景七：Script 内联元数据（PEP 723） ​

最佳实践 ​

总结 ​

Python现代化包管理工具UV

简介

核心定位

核心优势

5 分钟快速上手

与其他包管理工具的对比

uv vs pip

uv vs Poetry

uv vs Conda

与 pyproject.toml 的关系

PEP 621 标准

最小示例

uv 扩展配置

安装

Windows 安装

方式一：PowerShell 安装（推荐）

方式二：手动下载

验证安装

Linux / macOS 安装

安装后配置（国内镜像）

常用命令

项目初始化

Python 版本管理

虚拟环境管理

依赖管理

运行命令

包构建与发布

全局工具管理

pip 兼容命令

其他实用命令

常用场景

场景一：单项目开发

场景二：Monorepo（多包项目）

场景三：团队协作

场景四：无全局 Python 环境

场景五：PyCharm 集成

场景六：从 Poetry / pip 迁移

场景七：Script 内联元数据（PEP 723）

最佳实践

总结