uv 入门教程 -- Python 包与环境管理工具

在 Python 开发中，包管理和环境隔离是每个开发者都会遇到的问题。

无论是 pip 的缓慢、virtualenv 的繁琐，还是 conda 的臃肿，uv 都让开发者们期待一个更高效的解决方案。

什么是 uv？

uv 是由 Astral 公司开发的一款 Rust 编写的 Python 包管理器和环境管理器，它的主要目标是提供比现有工具快 10-100 倍的性能，同时保持简单直观的用户体验。

uv 可以替代 pip、virtualenv、pip-tools 等工具，提供依赖管理、虚拟环境创建、Python 版本管理等一站式服务。

安装 uv

在 macOS 上安装

推荐使用 Homebrew 安装：

brew install uv

或者使用官方安装脚本：

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

在 Linux 上安装

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

在 Windows 上安装

使用 Winget：

winget install uv

或者使用官方安装脚本：

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

安装完成后，验证安装是否成功：

uv --version

输出内容类似如下，表明安装成功：

uv 0.8.14 (Homebrew 2025-08-28)

基本使用指南

1. 管理 Python 版本

uv 可以轻松管理多个 Python 版本，无需额外安装 pyenv 等工具。

查看可用的 Python 版本：

uv python list

输出结果类似如下：

cpython-3.14.0rc2-macos-aarch64-none                 <download available>
cpython-3.14.0rc2+freethreaded-macos-aarch64-none    <download available>
cpython-3.13.7-macos-aarch64-none                    <download available>
cpython-3.13.7+freethreaded-macos-aarch64-none       <download available>
cpython-3.12.11-macos-aarch64-none                   <download available>
cpython-3.11.13-macos-aarch64-none                   <download available>
cpython-3.10.18-macos-aarch64-none                   <download available>
cpython-3.9.23-macos-aarch64-none                    <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3
cpython-3.8.20-macos-aarch64-none                    <download available>
pypy-3.11.13-macos-aarch64-none                      <download available>

安装特定版本的 Python：

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

设置全局默认 Python 版本：

uv python default 3.12

2. 管理虚拟环境

创建并激活虚拟环境：

# 创建名为 .venv 的虚拟环境（默认）
uv venv

# 激活环境（macOS/Linux）
source .venv/bin/activate

# 激活环境（Windows）
.venv\Scripts\activate

在项目中指定 Python 版本：

# 为当前项目固定 Python 3.11
uv python pin 3.11

这会创建 .python-version 文件，标识项目所需的 Python 版本。

3. 包管理

安装包：

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

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

安装包到开发环境：

uv pip install --dev pytest

升级包：

uv pip upgrade requests

卸载包：

uv pip uninstall requests

导出依赖：

# 导出当前环境的依赖
uv pip freeze > requirements.txt

# 导出生产环境依赖（排除开发依赖）
uv pip freeze --production > requirements.txt

4. 项目管理

uv 支持 pyproject.toml 格式的项目管理，这是现代 Python 项目的标准配置文件。

初始化一个新项目：

uv init my_project
cd my_project

这会创建基本的项目结构和 pyproject.toml 文件。

安装项目的依赖：

uv sync

这个命令会根据 pyproject.toml 和 requirements.txt 安装所有依赖，类似于 pip install -e . 但更高效。

uv 的优势

  • 速度极快：由于使用 Rust 编写，uv 的性能远超 pip 和其他包管理工具，安装依赖的速度可以提升 10-100 倍。
  • 功能集成：集成语法分析、依赖解析、包安装、环境管理和 Python 版本管理于一体，无需再安装和学习多个工具。
  • 确定性构建：uv 会生成 uv.lock 文件，确保在任何环境中都能安装完全相同的依赖版本，避免 "在我机器上能运行" 的问题。
  • 与现有工具兼容：uv 可以处理 requirements.txt 和 pyproject.toml，可以无缝替代现有工作流中的 pip。

迁移到 uv

如果你正在使用其他工具，可以轻松迁移到 uv：

对于使用 pip + virtualenv 的项目：

# 创建并激活 uv 虚拟环境
uv venv
source .venv/bin/activate

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

对于使用 pip-tools 的项目：

uv pip compile requirements.in -o requirements.txt
uv pip sync

对于使用 poetry 或 pdm 的项目：

# 直接使用现有的 pyproject.toml
uv sync