简单的UV使用教程

这个教程涵盖了 UV 的主要功能。随着 UV 的快速发展，建议查看官方文档获取最新信息：uv 中文文档

安装UV

安装 UV
macOS 和 Linux

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

# 或者使用 pip
pip install uv

Windows

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

# 或者使用 pip
pip install uv

升级

# 使用自身上升级命令（1.0版本以上）
uv self update

# 或使用旧的升级命令
uv pip install --upgrade uv

📍 创建全局 uv.toml 的路径

你需要根据操作系统，在指定目录创建一个新的文本文件，并命名为 uv.toml。

操作系统	全局配置文件完整路径	如何快速打开/创建
Windows	%APPDATA%\uv\uv.toml	1. 按 Win+R，输入 %APPDATA%\uv 并回车。2. 在打开的文件夹内，新建文本文档，重命名为 uv.toml。
macOS / Linux	~/.config/uv/uv.toml	在终端执行：mkdir -p ~/.config/uv && nano ~/.config/uv/uv.toml

🛠️ 创建并配置文件的步骤
打开或创建文件：使用上表的方法，在正确的位置创建一个名为 uv.toml 的纯文本文件。

编辑文件内容：将以下配置粘贴进去（以清华大学源为例）：

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

# 可选的附加配置：设置并行下载数以提高速度
concurrent-downloads = 8

# 可选：如果你想设置安装相关的其他参数，正确字段是 `[pip]`
# [pip]
# jobs = 8  # `jobs` 参数在 `[pip]` 字段下是有效的

Python 版本管理

查看可用的 Python 版本

uv python list

安装特定 Python 版本

# 安装最新 Python 3.12
uv python install 3.12

# 安装特定小版本
uv python install 3.11.5

# 安装预览版
uv python install 3.13-dev

使用特定 Python 版本

# 为当前项目指定 Python 版本
uv python pin 3.12

# 查看当前项目使用的 Python 版本
uv python show

依赖管理

从 requirements.txt 安装依赖

基本安装

uv pip install -r requirements.txt

同步依赖（类似 pip-sync）

# 同步虚拟环境中的包，使其与 requirements.txt 完全一致
uv pip sync requirements.txt

安装开发依赖

uv pip install -r requirements-dev.txt

生成 requirements.txt

从当前环境生成

uv pip freeze > requirements.txt

生成带哈希值的锁定文件

uv pip compile pyproject.toml -o requirements.lock

生成特定平台的依赖

# 只生成当前平台需要的依赖
uv pip compile pyproject.toml --platform linux-x86_64

创建和更新依赖

添加新包

uv pip install pandas

# 添加到 requirements.txt
uv pip install pandas && uv pip freeze > requirements.txt

更新所有包

uv pip compile --upgrade pyproject.toml

更新特定包

uv pip install "pandas>=2.0.0"

项目管理

初始化新项目

# 创建新项目目录
mkdir my-project
cd my-project

# 初始化项目（会创建 pyproject.toml）
uv init

# 或使用指定 Python 版本初始化
uv init --python 3.12

创建虚拟环境

# 在当前目录创建虚拟环境
uv venv

# 指定虚拟环境名称
uv venv .venv

# 使用特定 Python 版本
uv venv --python 3.12

激活虚拟环境

Linux/macOS:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

在虚拟环境中使用 uv

# 激活虚拟环境后，安装依赖
uv pip install -r requirements.txt

# 或直接使用 uv run 运行命令
uv run python script.py

常用命令

安装相关

# 安装单个包
uv pip install package-name

# 安装指定版本
uv pip install "package-name==1.0.0"

# 安装并添加到 pyproject.toml
uv add package-name

# 安装开发依赖
uv add --dev black

依赖解析

# 解析依赖树
uv pip tree

# 检查过时的包
uv pip list --outdated

# 显示包信息
uv pip show package-name

清理和维护

# 清理缓存
uv cache clean

# 删除包
uv pip uninstall package-name

# 修复损坏的环境
uv pip check

工作流示例

示例 1：从现有 requirements.txt 开始

# 1. 克隆项目
git clone project-url
cd project

# 2. 创建虚拟环境
uv venv

# 3. 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate     # Windows

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

# 5. 运行项目
uv run python main.py

示例 2：从头创建新项目

# 1. 创建项目目录
mkdir new-project
cd new-project

# 2. 初始化项目
uv init --python 3.11

# 3. 添加依赖
uv add fastapi
uv add --dev pytest

# 4. 安装依赖
uv pip install

# 5. 生成 requirements.txt
uv pip freeze > requirements.txt

示例 3：同步生产环境

# 1. 在生产服务器上创建虚拟环境
uv venv --python 3.11

# 2. 激活环境
source .venv/bin/activate

# 3. 同步精确版本
uv pip sync requirements.lock

# 4. 启动应用
uv run gunicorn app:app

与 pip 对比的优势

速度更快：UV 比 pip 快 10-100 倍
内置虚拟环境管理：无需额外安装 virtualenv
更好的依赖解析：更快的依赖解析和冲突检测
跨平台一致性：更好的跨平台依赖管理
一体化工具：集成了 pip、pip-tools、virtualenv 等功能

提示和技巧

使用 UVX 运行工具（类似 npx）：

# 无需安装即可运行 Python 工具
uvx black .

并行安装：

# UV 默认并行安装，可通过 --no-parallel 禁用
uv pip install --no-parallel -r requirements.txt

离线模式：

# 使用缓存的包
uv pip install --offline package-name

仅安装当前平台依赖：

uv pip install --platform-current

故障排除

清除缓存解决问题：

uv cache clean

详细日志：

uv pip install -v package-name

强制重新安装：

uv pip install --reinstall package-name

配置

UV 的配置文件位于：

Linux/macOS: ~/.config/uv/uv.toml
Windows: %APPDATA%\uv\uv.toml

示例配置：

toml

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

[tool.uv]
# 总是升级包
upgrade = true

# 并行下载数
concurrent-downloads = 8

[tool.uv]
# 缓存目录
cache-dir = "~/.cache/uv"