uv 使用指南#

什么是 uv？#

uv 是一个用 Rust 编写的 Python 包安装器和解析器。它的设计初衷是替代 pip、pip-tools 和 virtualenv，但随着版本的迭代，它现在已经具备了替代 poetry（项目管理）、pyenv（Python 版本管理）和 pipx（工具管理）的能力。

核心特点：

• 极速：比 pip 快 10-100 倍。
• 全能：一个工具搞定 Python 安装、虚拟环境、依赖管理、工具运行。
• 兼容：兼容 pyproject.toml 标准。

1. 安装 uv#

uv 提供了多种安装方式，推荐使用官方的独立安装脚本，这样升级和管理更方便。

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

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

1
pip install uv

1
uv --version

2. 项目管理 (Modern Workflow)#

这是 uv 目前最推荐的使用方式，类似于 poetry 或 npm 的体验。

1
# 创建一个新项目
2
uv init my-project
3
cd my-project

1
# 添加依赖
2
uv add requests
3

4
# 添加开发依赖 (例如 pytest)
5
uv add --dev pytest

1
[[tool.uv.index]]
2
name = "tencent"
3
url = "https://mirrors.cloud.tencent.com/pypi/simple/" # 腾讯云镜像源

1
# Linux/macOS：用 vim 打开（若文件不存在会自动创建）
2
vim ~/.config/uv/config.toml
3
# Windows：用记事本打开
4
Write-Host $env:USERPROFILE
5

6

7
notepad %USERPROFILE%\.config\uv\config.toml

1
# 阿里云镜像（推荐，稳定性好）
2
[registries.pypi]
3
index = "https://mirrors.aliyun.com/pypi/simple/"

1
# 推荐使用清华源
2
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"'>> ~/.bashrc
3

4
# 或者用阿里源
5
# echo 'export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple/"' >> ~/.bashrc
6

7
# 让配置立即生效
8
source ~/.bashrc

1
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"

1
uv sync

1
# 运行脚本
2
uv run main.py
3

4
# 运行工具
5
uv run pytest

1
uv sync

3. Python 版本管理#

uv 内置了 Python 版本管理功能，这意味着你不再需要安装 pyenv 或 conda 来管理不同的 Python 版本。

1
# 列出可用的 Python 版本
2
uv python list
3

4
# 安装特定版本的 Python
5
uv python install 3.12
6

7
# 为当前项目指定 Python 版本
8
uv python pin 3.11

当你运行 uv run 或 uv sync 时，uv 会自动下载并使用项目指定的 Python 版本。

这个也可以用镜像，不然走github国内很慢 很简单

1
UV_PYTHON_INSTALL_MIRROR
2

3
https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/

linux的话

1
export UV_PYTHON_INSTALL_MIRROR="https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/"

4. 脚本支持 (Script Support)#

uv 对单文件脚本的支持非常出色。你可以在脚本顶部声明依赖，uv 会自动下载并运行，且不会污染全局环境。

创建一个 example.py：

1
# /// script
2
# requires-python = ">=3.11"
3
# dependencies = [
4
#     "requests<3",
5
#     "rich",
6
# ]
7
# ///
8

9
import requests
10
from rich.pretty import pprint
11

12
resp = requests.get("https://peps.python.org/api/peps.json")
13
data = resp.json()
14
pprint([(k, v["title"]) for k, v in data.items()][:10])

直接运行：

1
uv run example.py

uv 会自动解析头部元数据，创建一个临时环境并安装依赖，然后执行脚本。

5. 工具管理 (Tool Management)#

类似于 pipx，uv 可以安装和运行全局的 Python 命令行工具。

1
# 临时运行一个工具 (例如 ruff)
2
uvx ruff check .
3
# 或者
4
uv tool run ruff check .
5

6
# 安装一个工具到全局
7
uv tool install black

6. 兼容 pip 的接口 (Legacy Interface)#

如果你不想改变现有的工作流，只想利用 uv 的速度，可以使用它的 pip 兼容接口。

1
# 创建虚拟环境
2
uv venv
3

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

7
# 激活环境 (Windows)
8
.venv\Scripts\activate
9
# 激活环境 (macOS/Linux)
10
source .venv/bin/activate
11

12
# 安装依赖 (替代 pip install)
13
uv pip install requests
14

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

18
# 生成锁定文件 (替代 pip-compile)
19
uv pip compile pyproject.toml -o requirements.txt

总结#

uv 正在以惊人的速度重塑 Python 的开发体验。它不仅解决了”慢”的问题，更重要的是它试图统一碎片化的 Python 工具链。

迁移建议：

• 新项目：直接使用 uv init 和 uv add 的工作流。
• 老项目：可以先用 uv pip 替代 pip 加速安装，时机成熟后迁移到 pyproject.toml 管理。
• 脚本：强烈推荐使用 uv run 运行带依赖声明的单文件脚本。