一篇文章，让你完全掌握 uv

一篇文章，让你完全掌握 uv

简介

uv 是由 Astral 开发的极速 Python 包和项目管理工具，用 Rust 编写。它可以替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具。

核心特性

• 极速：比 pip 快 10-100 倍
• 统一工具：一个工具管理包、项目、Python 版本
• 自动管理 Python：无需手动安装 Python
• 兼容性好：完全兼容 pip

安装 uv

Windows (PowerShell)

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

macOS/Linux

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

使用 pip 安装

pip install uv

Python 版本管理

安装 Python

安装最新版本

uv python install

安装特定版本

# 安装单个版本
uv python install 3.12

# 安装多个版本
uv python install 3.11 3.12 3.13

安装替代实现

# 安装 PyPy
uv python install [email protected]

安装默认可执行文件

# 同时安装 python 和 python3 命令
uv python install --default

查看 Python 版本

# 列出所有可用和已安装的 Python 版本
uv python list

# 仅列出已安装的版本
uv python list --only-installed

升级 Python（实验性）

# 升级特定版本到最新补丁版本
uv python upgrade 3.12

# 升级所有 uv 管理的 Python 版本
uv python upgrade

重新安装 Python

# 重新安装所有已安装的 Python 版本
uv python install --reinstall

自动下载机制

uv 会在需要时自动下载 Python：

# 即使没有 Python 3.12，也会自动下载
uvx [email protected] -c "print('hello world')"

# 创建虚拟环境时自动安装 Python
uv venv

使用现有 Python

# 强制使用系统 Python
uv --no-managed-python pip install requests

虚拟环境管理

创建虚拟环境

# 使用默认 Python 创建
uv venv

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

# 指定环境名称
uv venv myenv

激活虚拟环境

Windows (PowerShell):

.venv\Scripts\activate

macOS/Linux:

source .venv/bin/activate

包管理

安装包

# 安装单个包
uv pip install requests

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

# 指定版本
uv pip install "requests>=2.28.0"

卸载包

uv pip uninstall requests

列出已安装的包

uv pip list

生成依赖文件

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

# 编译依赖（锁定版本）
uv pip compile requirements.in -o requirements.txt

同步环境

# 确保环境与 requirements.txt 完全一致
uv pip sync requirements.txt

项目管理

初始化项目

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

# 在现有目录初始化
uv init

添加依赖

# 添加运行时依赖
uv add requests

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

移除依赖

uv remove requests

运行项目

# 运行 Python 脚本
uv run script.py

# 运行模块
uv run -m pytest

运行工具

使用 uvx 运行工具

# 临时运行工具（无需安装）
uvx ruff check .

# 指定工具版本
uvx [email protected] black .

# 指定 Python 版本
uvx --python 3.12 httpie

脚本运行

运行单文件脚本

创建 script.py：

# /// script
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

运行：

uv run script.py

配置

全局配置

配置文件位置：

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

示例配置：

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

[pip]
no-cache = true

项目配置

在项目根目录创建 pyproject.toml：

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "requests>=2.28.0",
    "rich>=13.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

常用命令速查

命令	说明
uv python install	安装 Python
uv python list	列出 Python 版本
uv venv	创建虚拟环境
uv pip install <包>	安装包
uv pip list	列出已安装的包
uv init	初始化项目
uv add <包>	添加依赖
uv run <脚本>	运行脚本
uvx <工具>	运行工具
uv sync	同步项目依赖
uv lock	生成锁文件

迁移指南

从 pip 迁移

# 1. 安装 uv
pip install uv

# 2. 创建虚拟环境
uv venv

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

# 4. 之后使用 uv pip 替代 pip
uv pip install requests

从 poetry 迁移

# 读取 pyproject.toml 并安装依赖
uv sync

最佳实践

1. 使用项目模式

# 初始化项目而不是手动管理虚拟环境
uv init my-project
cd my-project
uv add requests
uv run python main.py

2. 锁定依赖版本

# 使用 uv.lock 确保可重现构建
uv lock
uv sync

3. 开发依赖分离

# 分离生产和开发依赖
uv add requests
uv add --dev pytest ruff

4. 使用脚本元数据

在单文件脚本中声明依赖：

# /// script
# dependencies = ["requests"]
# ///

性能对比

操作	pip	uv	提升
安装 Flask	~5s	~0.5s	10x
冷缓存安装	~30s	~2s	15x
解析依赖	~20s	~0.5s	40x

常见问题

禁用自动 Python 下载

export UV_PYTHON_DOWNLOADS=never

使用国内镜像

uv pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple requests

查看详细日志

uv -v pip install requests

资源链接

• 官方文档: https://docs.astral.sh/uv/
• GitHub: https://github.com/astral-sh/uv
• 更新日志: https://github.com/astral-sh/uv/releases

注意事项

1. Python 发行版：uv 使用 python-build-standalone 项目的 Python 发行版
2. 实验性功能：某些功能（如 python upgrade）仍在预览阶段
3. 兼容性：uv 与 pip 完全兼容，可以无缝迁移
4. 自动管理：uv 会自动下载和管理 Python 版本，无需手动干预