uv 基础入门

HSXISAWD2026/3/20大约 9 分钟

uv 基础入门

从零开始掌握极速 Python 包管理器

uv 概述

什么是 uv？

uv 是由 Astral 公司开发的极速 Python 包和项目管理器，使用 Rust 语言编写。它的设计目标是成为一个统一的 Python 工具链，能够替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具。

uv 的核心特性

特性	描述
极速性能	比 pip 快 10-100 倍，采用并行下载和智能缓存
统一工具链	一个工具管理包、项目、虚拟环境、Python 版本
确定性构建	跨平台锁文件确保一致的依赖解析
现代标准	完全支持 PEP 517/518/621/660 等标准
pip 兼容	提供 `uv pip` 命令，完全兼容 pip 接口
零配置	智能默认配置，开箱即用
跨平台	支持 Linux、macOS、Windows

uv 的诞生背景

Python 包管理工具的演进经历了多个阶段：

时间线：
2008    easy_install (setuptools)
2011    pip 发布
2016    pipenv 发布
2018    poetry 发布
2019    pdm 发布
2024    uv 发布 (Astral)

痛点：
- pip 速度慢，无锁文件
- 工具碎片化 (pip + venv + pyenv + pipx)
- 依赖解析不确定
- 跨平台一致性差

uv 由 Astral 公司开发，该公司也是极速 Python Linter Ruff 的开发者。他们的目标是用 Rust 重写 Python 工具链，提供极致的性能和统一的开发体验。

安装 uv

独立安装（推荐）

独立安装会将 uv 安装为系统级工具，不依赖于任何 Python 环境。

macOS / Linux

# 使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装特定版本
curl -LsSf https://astral.sh/uv/0.4.0/install.sh | sh

Windows

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

# 或使用 winget
winget install --id=astral-sh.uv -e

使用包管理器安装

# Homebrew (macOS/Linux)
brew install uv

# Cargo (如果你有 Rust 环境)
cargo install --git https://github.com/astral-sh/uv uv

使用 pip/pipx 安装

# pip (需要 Python 环境)
pip install uv

# pipx (隔离安装)
pipx install uv

验证安装

# 检查版本
uv --version
# uv 0.4.x

# 查看帮助
uv --help

更新 uv

# 自我更新（独立安装方式）
uv self update

# 更新到特定版本
uv self update 0.4.0

# 如果是 pip 安装
pip install --upgrade uv

卸载 uv

# 独立安装方式卸载
# Linux/macOS - 删除二进制文件和数据目录
rm ~/.cargo/bin/uv
rm -rf ~/.local/share/uv

# Windows - 删除以下目录
# %USERPROFILE%\.cargo\bin\uv.exe
# %LOCALAPPDATA%\uv

核心概念

工作模式

uv 支持两种主要的工作模式：

项目结构

uv 项目的标准结构：

myproject/
├── .venv/                    # 虚拟环境（自动创建）
│   ├── bin/ (或 Scripts/)
│   ├── lib/
│   └── pyvenv.cfg
├── src/                      # 源代码目录
│   └── myproject/
│       ├── __init__.py
│       └── main.py
├── tests/                    # 测试目录
│   └── test_main.py
├── pyproject.toml            # 项目配置（核心文件）
├── uv.lock                   # 依赖锁文件（自动生成）
├── .python-version           # Python 版本固定（可选）
└── README.md

pyproject.toml 结构

[project]
name = "myproject"
version = "0.1.0"
description = "A sample project"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [
    { name = "Your Name", email = "you@example.com" }
]
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
    "mypy>=1.0",
]
docs = [
    "sphinx>=6.0",
    "sphinx-rtd-theme",
]

[project.scripts]
myproject = "myproject.main:cli"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
# uv 特定配置
dev-dependencies = [
    "pytest>=7.0",
    "ruff>=0.1.0",
]

快速上手

创建新项目

# 创建应用项目
uv init myapp
cd myapp

# 查看生成的文件
ls -la
# .python-version
# pyproject.toml
# README.md
# hello.py

生成的 pyproject.toml：

[project]
name = "myapp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

添加依赖

# 添加运行时依赖
uv add requests
uv add "flask>=2.0"
uv add httpx aiohttp  # 一次添加多个

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

# 添加可选依赖组
uv add --optional docs sphinx sphinx-rtd-theme

# 从 URL 或 Git 添加
uv add git+https://github.com/user/repo.git
uv add git+https://github.com/user/repo.git@v1.0.0

运行代码

# 运行 Python 脚本
uv run python hello.py

# 运行模块
uv run python -m myapp

# 运行已安装的命令
uv run pytest
uv run ruff check .

# 运行时指定额外依赖
uv run --with rich python -c "from rich import print; print('Hello!')"

同步环境

# 同步依赖到虚拟环境
uv sync

# 同步包括开发依赖
uv sync --dev

# 同步特定的可选依赖组
uv sync --extra docs

# 冻结同步（严格按锁文件安装）
uv sync --frozen

管理锁文件

# 更新锁文件
uv lock

# 升级所有依赖到最新兼容版本
uv lock --upgrade

# 升级特定依赖
uv lock --upgrade-package requests

# 查看依赖树
uv tree

pip 兼容模式

uv 提供了完整的 pip 兼容接口，方便从 pip 迁移或在特定场景使用。

基本命令对照

pip 命令	uv 命令
`pip install requests`	`uv pip install requests`
`pip install -r requirements.txt`	`uv pip install -r requirements.txt`
`pip install -e .`	`uv pip install -e .`
`pip uninstall requests`	`uv pip uninstall requests`
`pip list`	`uv pip list`
`pip freeze`	`uv pip freeze`
`pip show requests`	`uv pip show requests`

使用示例

# 创建虚拟环境
uv venv

# 激活环境（必须手动激活）
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# 安装包
uv pip install flask requests

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

# 导出依赖
uv pip freeze > requirements.txt

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

pip compile 功能

uv pip compile 是 pip-tools 的替代品，用于生成锁定的依赖文件：

# requirements.in 内容
# flask>=2.0
# requests

# 编译生成 requirements.txt
uv pip compile requirements.in -o requirements.txt

# 生成的 requirements.txt 包含精确版本
# flask==3.0.0
# requests==2.31.0
# werkzeug==3.0.1
# ...

# 包含哈希值（更安全）
uv pip compile requirements.in -o requirements.txt --generate-hashes

# 同步安装
uv pip sync requirements.txt

命令参考

项目管理命令

命令	描述
`uv init`	创建新项目
`uv add <pkg>`	添加依赖
`uv remove <pkg>`	移除依赖
`uv sync`	同步依赖到环境
`uv lock`	更新锁文件
`uv run <cmd>`	在项目环境中运行命令
`uv tree`	显示依赖树
`uv build`	构建分发包
`uv publish`	发布到 PyPI

虚拟环境命令

命令	描述
`uv venv`	创建虚拟环境
`uv venv --python 3.11`	使用指定 Python 版本
`uv venv myenv`	创建到指定目录

Python 管理命令

命令	描述
`uv python install`	安装 Python 版本
`uv python list`	列出可用版本
`uv python pin`	固定项目 Python 版本
`uv python find`	查找 Python 安装
`uv python uninstall`	卸载 Python 版本

工具管理命令

命令	描述
`uvx <tool>`	临时运行工具（无需安装）
`uv tool install`	安装全局工具
`uv tool list`	列出已安装工具
`uv tool upgrade`	升级工具
`uv tool uninstall`	卸载工具
`uv tool run`	运行工具（同 uvx）

缓存管理命令

命令	描述
`uv cache clean`	清理缓存
`uv cache prune`	移除未使用的缓存
`uv cache dir`	显示缓存目录

环境变量

uv 支持多种环境变量来自定义行为：

环境变量	描述	默认值
`UV_PYTHON`	指定 Python 解释器	-
`UV_CACHE_DIR`	缓存目录位置	平台特定
`UV_NO_CACHE`	禁用缓存	false
`UV_INDEX_URL`	PyPI 索引 URL	https://pypi.org/simple
`UV_EXTRA_INDEX_URL`	额外索引 URL	-
`UV_NATIVE_TLS`	使用系统 TLS	false
`UV_OFFLINE`	离线模式	false
`UV_NO_PROGRESS`	禁用进度条	false
`UV_PYTHON_PREFERENCE`	Python 查找偏好	managed
`UV_PYTHON_DOWNLOADS`	允许下载 Python	automatic

使用示例

# 使用国内镜像
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# 指定缓存目录
export UV_CACHE_DIR=/opt/uv-cache

# 离线模式（仅使用缓存）
UV_OFFLINE=true uv sync

# 禁用进度条（CI 环境）
UV_NO_PROGRESS=true uv sync

配置文件

uv 支持通过配置文件来设置默认行为。

项目级配置 (pyproject.toml)

[tool.uv]
# 开发依赖
dev-dependencies = [
    "pytest>=7.0",
    "ruff>=0.1.0",
]

# Python 版本要求
python-version = "3.11"

# 索引配置
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-url = ["https://pypi.org/simple"]

# 排除某些包的升级
exclude-newer = "2024-01-01"

# 预发布版本
prerelease = "if-necessary"

全局配置 (uv.toml)

创建 ~/.config/uv/uv.toml（Linux/macOS）或 %APPDATA%\uv\uv.toml（Windows）：

# 全局索引设置
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 缓存设置
cache-dir = "/opt/uv-cache"

# 默认 Python 版本
python-version = "3.11"

# 并行下载数
concurrent-downloads = 50

# 连接超时（秒）
connect-timeout = 30

常见问题

Q: uv 和 pip 的区别是什么？

A: 主要区别：

方面	pip	uv
性能	较慢	极快（10-100x）
语言	Python	Rust
锁文件	无（需 pip-tools）	内置
虚拟环境	需要 venv/virtualenv	内置
Python 管理	需要 pyenv	内置
依赖解析	回溯算法	SAT 求解器

Q: uv 能完全替代 pip 吗？

A: 在大多数场景下可以。uv 提供了 uv pip 命令来兼容 pip 接口。但某些高级 pip 功能可能暂时不支持，建议查看官方文档的兼容性列表。

Q: 如何在 CI/CD 中使用 uv？

A: 示例 GitHub Actions 配置：

- name: Install uv
  uses: astral-sh/setup-uv@v3

- name: Install dependencies
  run: uv sync --frozen

- name: Run tests
  run: uv run pytest

Q: uv 的缓存占用多大？

A: 取决于项目数量。可以使用 uv cache prune 清理未使用的缓存，或 uv cache clean 完全清理。

Q: 如何使用国内镜像源？

A: 有多种方式：

# 1. 命令行参数
uv pip install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 2. 环境变量
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# 3. 配置文件 (pyproject.toml)
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

总结

uv 代表了 Python 包管理的未来方向：

性能革命 - Rust 带来的极致速度
统一体验 - 一个工具解决所有问题
现代设计 - 符合最新 Python 打包标准
渐进迁移 - pip 兼容模式降低迁移成本

学习路径推荐

下一步

项目管理与工作流 - 深入项目管理功能
虚拟环境管理 - 掌握环境隔离