uv 使用指南

uv 是一个用 Rust 编写的 Python 包管理与项目管理工具，特点是快、兼容 pip、支持虚拟环境和锁文件。

1. 安装 uv

1.1 Linux / macOS 一键安装

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

安装完成后，重新打开终端或执行：

source ~/.bashrc
# zsh 用户可用：source ~/.zshrc
uv --version

2. 常见命令

2.1 初始化项目

# 在当前目录初始化 uv 项目
uv init .

执行后会生成 pyproject.toml 等基础文件。

2.2 同步依赖

# 同步 pyproject.toml 中的依赖到虚拟环境
uv sync

2.3 指定 Python 版本同步

# 同步指定虚拟环境的 Python 版本
uv sync --python=3.12

3. 依赖与运行

3.1 依赖管理

# 添加依赖
uv add requests

# 删除依赖
uv remove requests

# 升级某个依赖
uv add "requests@latest"

3.2 执行命令

# 在项目环境中运行脚本
uv run python main.py

# 运行工具
uv run pytest
uv run ruff check .

4. Python 版本管理

uv 可以管理和使用不同 Python 版本。

# 安装 Python 版本
uv python install 3.12

# 查看可用 Python
uv python list

在项目中指定 Python 版本（示例）：

uv venv --python 3.12

5. 锁文件与可复现安装

# 生成或更新锁文件
uv lock

# 严格按锁文件安装（CI 推荐）
uv sync --frozen

6. 与 pip 兼容用法

如果你暂时不想切换项目结构，也可以用 uv 当 pip 的高速替代：

# 创建虚拟环境
uv venv

# 激活虚拟环境（bash/zsh）
source .venv/bin/activate

# 安装依赖（兼容 pip 习惯）
uv pip install -r requirements.txt

# 导出依赖
uv pip freeze

7. 配置国内源（可选）

在 pyproject.toml 中添加（示例）：

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

extra-index-url = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://pypi.mirrors.ustc.edu.cn/simple/",
]