uv —— 极速 Python 包与项目管理器

概述

uv 是由 Ruff 团队使用 Rust 开发的极速 Python 包与项目管理器，可替代 pip、pip-tools、virtualenv、poetry 等多种工具。其速度比 pip 快 10-100 倍，同时提供虚拟环境管理、项目依赖锁定、Python 版本管理等一站式能力。

安装 uv

Windows（PowerShell）

irm https://astral.sh/uv/install.ps1 | iex

Linux / macOS

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

安装完成后，重启终端即可使用 uv 命令。执行 uv --version 验证安装是否成功。

配置国内镜像源

uv 不使用 pip 的配置文件，而是通过环境变量或 uv 自身的配置文件来设置镜像源。

方法一：环境变量（推荐）

Windows（PowerShell）

[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://mirrors.cernet.edu.cn/pypi/web/simple", "User")

或在系统环境变量中手动添加：

变量名:  UV_INDEX_URL
变量值:  https://mirrors.cernet.edu.cn/pypi/web/simple

Linux / macOS

echo 'export UV_INDEX_URL=https://mirrors.cernet.edu.cn/pypi/web/simple' >> ~/.bashrc
source ~/.bashrc

如果使用 zsh，将 ~/.bashrc 替换为 ~/.zshrc。

方法二：配置文件

创建 uv.toml 文件：

  • Windows: %APPDATA%\uv\uv.toml
  • Linux / macOS: ~/.config/uv/uv.toml
[[index]]
url = "https://mirrors.cernet.edu.cn/pypi/web/simple"
default = true

常用国内镜像源

镜像源 URL
清华源 https://pypi.tuna.tsinghua.edu.cn/simple
阿里源 https://mirrors.aliyun.com/pypi/simple
中科大源 https://pypi.mirrors.ustc.edu.cn/simple
教育网源 https://mirrors.cernet.edu.cn/pypi/web/simple

项目管理（推荐工作流）

uv 提供类似 Poetry 的现代项目管理能力，通过 pyproject.toml 和 uv.lock 管理依赖。

创建新项目

# 在当前目录初始化项目，指定 Python 版本
uv init . --python 3.11

# 在新目录中创建项目
uv init my-project --python 3.11

添加 / 移除依赖

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

# 移除依赖
uv remove requests

同步环境

# 根据 uv.lock 同步虚拟环境（无 lock 文件则从 pyproject.toml 生成）
uv sync

运行脚本

# 在项目环境中运行命令
uv run python main.py
uv run pytest

虚拟环境管理

创建虚拟环境

# 在当前目录创建 .venv
uv venv

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

# 指定路径
uv venv /path/to/venv --python 3.12

激活虚拟环境

# Linux / macOS
source .venv/bin/activate

# Windows（CMD）
.venv\Scripts\activate

# Windows（PowerShell）
.venv\Scripts\Activate.ps1

删除虚拟环境

# 直接删除 .venv 目录即可
rm -rf .venv

pip 兼容命令

如果已习惯 pip 的工作方式，uv 提供了完全兼容的 uv pip 子命令。

安装包

# 安装单个包
uv pip install requests

# 安装指定版本
uv pip install "requests>=2.28,<3.0"

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

# 从 pyproject.toml 安装
uv pip install -e .

卸载包

uv pip uninstall requests

列出已安装的包

uv pip list

冻结依赖

# 导出当前环境的精确版本
uv pip freeze > requirements.txt

编译依赖

# 将松散约束编译为精确版本锁文件
uv pip compile requirements.in -o requirements.txt

Python 版本管理

uv 可以自动下载和管理 Python 解释器，无需手动安装。

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

# 列出已安装的 Python 版本
uv python list

# 查看当前使用的 Python 路径
uv python find

常用命令速查

场景 命令
创建项目 uv init . --python 3.11
添加依赖 uv add requests
添加开发依赖 uv add pytest --dev
同步环境 uv sync
运行脚本 uv run python main.py
安装包（pip 风格） uv pip install requests
批量安装 uv pip install -r requirements.txt
卸载包 uv pip uninstall requests
列出包 uv pip list
升级包 uv pip install --upgrade requests
安装 Python uv python install 3.11
查看版本 uv --version

与 pip 的速度对比

得益于 Rust 实现和并行下载解析机制，uv 在以下场景中比 pip 快 10-100 倍：

  • 依赖解析（使用 PubGrub 算法）
  • 包下载（并行 + 缓存复用）
  • 虚拟环境创建（无子进程开销）

从 pip 迁移到 uv

  1. 安装 uv：按上文方法安装
  2. 保留原有虚拟环境：uv 可直接操作现有的 .venv
  3. 命令替换：将 pip install 替换为 uv pip install，其余命令同理
  4. 逐步升级：可以从 uv pip 风格开始，后续再迁移到 uv add / uv sync 的项目管理模式

扩展阅读