uv 完整使用指南

uv 是一个由 Astral 开发的高性能 Python 包管理和项目管理工具，旨在提供极速且统一的 Python 开发体验。它整合了 pip、poetry、pyenv 和 virtualenv 的核心功能。

---

1. 安装与更新

安装

• Windows (PowerShell):

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

• macOS / Linux:

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

更新

uv self update

---

2. 项目管理 (Project)

初始化项目

• 在当前目录初始化: uv init .
• 创建新项目文件夹: uv init my-project
• 指定 Python 版本: uv init --python 3.10
• 初始化为库 (Library): uv init --lib

依赖管理

• 添加依赖: uv add requests
• 添加开发依赖: uv add --dev ruff
• 指定版本范围: uv add "requests>=2.31.0"
• 从 Git 安装: uv add git+https://github.com/requests/requests.git
• 从本地路径安装: uv add ./path/to/local_package
• 移除依赖: uv remove requests
• 同步依赖: uv sync (根据 pyproject.toml 强制同步 .venv 状态)

运行项目

• 运行脚本: uv run main.py
• 运行模块: uv run -m my_module
• 带临时依赖运行: uv run --with pandas analysis.py (无需先 add 即可测试)

---

3. Python 版本管理 (Python)

uv 可以自动下载并管理不同版本的 Python 解释器。

• 列出已安装/可用的版本: uv python list
• 安装指定版本: uv python install 3.11
• 查找解释器路径: uv python find
• 固定项目版本: uv python pin 3.10.1 (创建 .python-version 文件)
• 卸载版本: uv python uninstall 3.10

---

4. 虚拟环境管理 (Venv)

uv 默认在项目根目录的 .venv 文件夹中管理环境。

• 创建环境: uv venv
• 指定 Python 创建: uv venv --python 3.12
• 激活环境:
  • Windows: .venv\Scripts\activate
  • macOS/Linux: source .venv/bin/activate

---

5. 全局工具管理 (Tool)

uv 可以安装独立于项目的全局 Python 工具，互不干扰。

• 安装工具: uv tool install ruff
• 运行工具: uv tool run ruff check . (如果未安装会下载临时运行)
• 列出已安装工具: uv tool list
• 卸载工具: uv tool uninstall ruff
• 更新工具: uv tool upgrade --all

---

6. 配置镜像源与索引 (Index)

临时使用镜像

uv add requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

项目持久化配置 (pyproject.toml)

在文件末尾添加：

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

全局持久化配置

在 uv 的全局配置文件中设置（Windows 通常在 %APPDATA%\uv\uv.toml）：

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

---

7. 脚本元数据支持 (PEP 723)

uv 支持直接在单个 Python 脚本头部声明依赖，方便分享。

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///

import requests
from rich import print
# ... 代码内容

运行方法: uv run script.py (它会自动创建临时环境安装依赖并运行)

---

8. 缓存与清理

• 查看缓存路径: uv cache dir
• 清理所有缓存: uv cache clean
• 清理特定包缓存: uv cache prune

---

9. 常用技巧 (Tips)

• 导出 requirements.txt: uv export --format requirements-txt > requirements.txt
• 流水线加速: 在 CI/CD 中使用 uv sync --frozen 保证环境一致性。
• 离线安装: uv sync --offline (前提是缓存中已存在包)。
• 查看依赖树: uv tree (清晰展示包之间的嵌套关系)。