入门

官方文档：https://docs.astral.sh/uv/getting-started/

中文文档：https://hellowac.github.io/uv-zh-cn/

参考文档：https://www.cnblogs.com/wang_yb/p/18635441

安装uv

推荐使用官方安装脚本，无需预先安装 Python，uv 是独立的 Rust 二进制文件。

安装：

# 官方推荐方式（自动安装到 ~/.local/bin）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip 安装（若已有 pip）
pip install uv

# 验证安装
uv --version

更新/卸载：

# 更新uv
uv self update

# 卸载uv
rm -f ~/.local/bin/uv
rm -rf ~/.local/share/uv

核心概念

理解 uv 的三层模型，可以更清晰地规划你的环境策略：

ℹ️ 关键文件：pyproject.toml

声明项目元数据和依赖，uv.lock 是跨平台确定性锁文件（提交到 Git），.python-version 指定项目 Python 版本。

Python版本管理

安装Python

uv 内置 Python 版本管理。所有版本独立存储，互不干扰。

# 查看所有可安装版本
uv python list
uv python list --all-versions

# 安装指定版本
uv python install 3.12
uv python install 3.11 3.10 3.9   # 同时安装多个
uv python install 3.13t               # 安装 Free-threaded 版本

# 查看已安装版本
uv python list --only-installed

# 卸载某个版本
uv python uninstall 3.9

支持的版本矩阵：

版本切换

uv 采用就近查找原则：当前目录 .python-version → 父目录逐级查找 → 全局默认。

# 在当前命令临时指定版本
uv run --python 3.11 python script.py
uv run --python 3.10 -c "import sys; print(sys.version)"

# 为当前目录/项目固定版本（写入 .python-version）
uv python pin 3.12
cat .python-version     # 输出: 3.12

# 用指定版本创建虚拟环境
uv venv --python 3.11 .venv

# 查看当前环境使用的 Python
uv python find
uv run python --version

ℹ️ 版本指定格式：3.12（最新补丁）、3.12.3（精确版本）、cpython@3.12（明确实现）、pypy@3.10（PyPy）

版本锁定

在 pyproject.toml 中声明版本约束

# pyproject.toml
[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.11"       # 最低版本要求
# requires-python = ">=3.11,<3.13"  # 范围约束
dependencies = [
    "fastapi>=0.100",
    "uvicorn",
]

✅ 最佳实践：将 .python-version 文件提交到 Git，让团队成员和 CI/CD 使用完全相同的 Python 版本。uv.lock 同样应该提交。

环境隔离

虚拟环境

每个项目拥有独立的 .venv，依赖完全隔离。uv 会自动检测并激活当前目录下的虚拟环境。

# 创建虚拟环境（默认在 .venv/）
uv venv
uv venv --python 3.12                      # 指定 Python 版本
uv venv /path/to/myenv                     # 自定义路径

# 激活 / 停用
source .venv/bin/activate
deactivate

# 无需激活，直接用 uv run 在隔离环境中运行
uv run python script.py
uv run pytest
uv run --isolated python script.py       # 完全隔离（不继承系统包）

# 在特定虚拟环境中安装包
uv pip install requests --python /path/to/myenv/bin/python

💡 推荐：优先使用 uv run 而非手动 source activate。uv run 会自动找到并使用当前项目的虚拟环境，更加安全可靠。

项目管理（推荐工作模式）

uv 的项目模式类似 Poetry，以 pyproject.toml 为中心，是多项目隔离的最佳实践。

# 新建项目（自动生成 pyproject.toml、.python-version、src/）
uv init my-project
cd my-project

# 在现有目录初始化
uv init
uv init --app                    # 应用程序模板
uv init --lib                    # 库模板（带 src/ 布局）
uv init --script myscript.py     # 单文件脚本（带内联依赖）

多项目目录结构示例：

~/projects/
├── project-a/         # Python 3.12，FastAPI 项目
│   ├── .python-version   # → 3.12
│   ├── pyproject.toml
│   ├── uv.lock
│   └── .venv/            # 独立环境，互不干扰
├── project-b/         # Python 3.11，数据科学项目
│   ├── .python-version   # → 3.11
│   ├── pyproject.toml
│   ├── uv.lock
│   └── .venv/
└── project-c/         # Python 3.10，遗留项目
    ├── .python-version   # → 3.10
    └── .venv/

✅ 每个项目的 .venv 完全独立。cd 进哪个目录，uv run 就使用哪个环境，无需任何手动切换操作。

典型工作流

新项目从0开始：

# 1. 创建项目
uv init my-api && cd my-api

# 2. 锁定 Python 版本
uv python pin 3.12

# 3. 添加依赖（自动更新 pyproject.toml 和 uv.lock）
uv add fastapi uvicorn pydantic

# 4. 添加开发依赖
uv add --dev pytest ruff mypy

# 5. 运行项目
uv run uvicorn main:app --reload

# 6. 提交到 Git
git add pyproject.toml uv.lock .python-version
git commit -m "init project"

克隆已有项目：

git clone https://github.com/xxx/project && cd project

# 一键同步：自动安装 Python + 创建 venv + 安装依赖
uv sync

# 含开发依赖
uv sync --dev

# 直接运行（uv 会自动 sync）
uv run python main.py

依赖管理

添加依赖

# 添加依赖
uv add requests
uv add "django>=4.2"
uv add "numpy>=1.24,<2.0"

# 添加可选依赖组
uv add --dev pytest black ruff       # 开发组
uv add --group docs sphinx mkdocs    # 自定义分组

# 从 Git / 本地路径安装
uv add "git+https://github.com/user/repo"
uv add --editable ../my-local-lib    # 可编辑安装

# 删除依赖
uv remove requests

# 升级依赖
uv lock --upgrade-package requests    # 升级单个
uv lock --upgrade                      # 升级全部
uv sync                                # 应用到环境

# 从 requirements.txt 迁移
uv add -r requirements.txt

锁文件与可复现环境

uv.lock 是跨平台的确定性锁文件，记录所有依赖的精确版本和哈希值。

# 生成/更新锁文件（不安装）
uv lock

# 根据锁文件严格安装（CI/CD 推荐）
uv sync --frozen                     # 不允许更新锁文件
uv sync --no-dev                     # 不安装开发依赖（生产用）

# 导出 requirements.txt（兼容其他工具）
uv export -o requirements.txt
uv export --no-dev -o requirements-prod.txt

# 查看依赖树
uv tree
uv tree --depth 2

✅ Git 策略：uv.lock 应提交到版本控制（确保复现性），但 .venv/ 应写入 .gitignore。

全局工具管理（替代 pipx）

uv 内置 pipx 功能，每个工具安装在独立的隔离环境中，不污染全局。

# 安装全局工具
uv tool install ruff
uv tool install black
uv tool install httpie
uv tool install --python 3.11 some-tool  # 指定版本

# 临时运行（不安装，使用完即销毁）
uvx ruff check .
uvx black --check .
uvx --from httpie http GET https://api.example.com

# 管理工具
uv tool list                # 查看已安装工具
uv tool upgrade ruff        # 升级工具
uv tool upgrade --all       # 升级所有工具
uv tool uninstall black     # 卸载工具

速查

命令速查

实用技巧 & 进阶用法

内联脚本依赖（PEP 723）：

uv 支持在单文件脚本中声明依赖，无需项目目录：

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.11"
# dependencies = ["requests", "rich"]
# ///

import requests
from rich import print

data = requests.get("https://api.github.com").json()
print(data)
uv run my_script.py    # uv 自动创建临时环境并安装依赖
chmod +x my_script.py && ./my_script.py  # 也可直接执行

Workspace 多包管理（Monorepo）：

# 根目录 pyproject.toml
[tool.uv.workspace]
members = ["packages/*", "services/*"]
uv sync --package my-service      # 仅同步某个子包
uv run --package my-service pytest  # 在子包中运行命令

国内镜像源 & 环境变量：

# 自定义缓存目录（默认 ~/.cache/uv）
export UV_CACHE_DIR=/data/uv-cache

# 设置国内镜像源（加速下载）
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
# 或在 pyproject.toml 中配置：
# [[tool.uv.index]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 离线模式（使用缓存）
uv sync --offline

# 显示详细输出
uv sync -v

CI/CD 最佳实践（GitHub Actions）：

# .github/workflows/test.yml
- uses: astral-sh/setup-uv@v4
  with:
    version: "latest"

- name: Install dependencies
  run: uv sync --frozen --no-dev

- name: Run tests
  run: uv run pytest

缓存管理：

uv cache dir       # 查看缓存目录
uv cache info      # 查看缓存大小
uv cache clean     # 清理所有缓存
uv cache prune     # 清理旧版本缓存（保留当前使用的）

迁移参考

ℹ️ uv 的 uv pip 子命令完全兼容 pip 接口，可作为直接替代使用，同时享受 10~100× 的速度提升。