UV包管理器 — UV超快Python包管理¶

# 方法1：官方安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方法2：Homebrew（macOS）
brew install uv

# 方法3：pip（不推荐，但也能用）
pip install uv

# 验证安装
uv --version  # 应该显示 uv 0.11.x

# 配置国内镜像（加速下载）
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 加到 ~/.bashrc 永久生效

# ===== uv pip 模式（兼容 pip 命令） =====
uv pip install requests          # 安装包（比 pip 快 10-100x）
uv pip install -r requirements.txt  # 从 requirements.txt 安装
uv pip uninstall requests        # 卸载包
uv pip list                      # 列出已安装包
uv pip freeze > requirements.txt # 导出依赖
uv pip compile requirements.in -o requirements.txt  # 编译锁定依赖

# 创建新项目
uv init my-project              # 创建项目目录和 pyproject.toml
cd my-project

# 生成的文件结构：
# my-project/
# ├── pyproject.toml    # 项目配置
# ├── src/
# │   └── my_project/
# │       └── __init__.py
# └── README.md

# 添加依赖（自动更新 pyproject.toml 和 uv.lock）
uv add requests                 # 添加运行时依赖
uv add pandas numpy             # 一次添加多个
uv add --dev pytest ruff        # 添加开发依赖
uv add "requests>=2.31,<3.0"   # 指定版本范围

# 移除依赖
uv remove requests

# 同步环境（根据 uv.lock 安装精确版本）
uv sync                         # 安装所有依赖
uv sync --frozen                # CI 用：不更新 lock 文件

# 运行命令
uv run python main.py           # 在项目环境中运行
uv run pytest                   # 运行测试
uv run ruff check .             # 运行代码检查

# 安装 Python（替代 pyenv）
uv python install 3.12          # 安装 Python 3.12
uv python install 3.11 3.12     # 安装多个版本
uv python list                  # 列出可用版本
uv python list --installed      # 列出已安装版本

# 切换项目 Python 版本
uv python pin 3.12              # 固定项目用 3.12

# 升级 Python 补丁版本（0.10+ 稳定特性）
uv python upgrade               # 升级到最新补丁版本

# 运行一次性工具（不安装到全局）
uvx ruff check .                # 临时运行 ruff
uvx black .                     # 临时运行 black
uvx cowsay "hello"              # 临时运行任何工具

# 全局安装工具
uv tool install ruff            # 全局安装 ruff
uv tool install httpie           # 全局安装 httpie
uv tool list                    # 列出已安装工具
uv tool upgrade ruff            # 升级工具
uv tool uninstall ruff          # 卸载工具

# 创建虚拟环境
uv venv                        # 创建 .venv（默认名）
uv venv --python 3.12          # 指定 Python 版本
uv venv my-env                 # 指定环境名

# 激活环境（传统方式，uv run 不需要手动激活）
source .venv/bin/activate       # Linux/macOS
.venv\Scripts\activate          # Windows

# pyproject.toml（根目录）
[tool.uv.workspace]
members = ["packages/*"]       # 定义工作区成员

# packages/core/pyproject.toml
[project]
name = "my-core"
dependencies = []

# packages/api/pyproject.toml
[project]
name = "my-api"
dependencies = ["my-core"]     # 引用工作区内的包

# 工作区命令
uv workspace list              # 列出工作区成员
uv workspace dir               # 显示工作区根目录

# Dockerfile
FROM python:3.12-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# 复制项目文件
COPY pyproject.toml uv.lock ./

# 安装依赖（用 frozen 确保与 lock 一致）
RUN uv sync --frozen --no-dev

# 复制源码
COPY src/ src/

# 运行
CMD ["uv", "run", "python", "-m", "myapp"]

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5       # 官方 Action
      - run: uv sync --frozen              # 安装依赖
      - run: uv run pytest                 # 运行测试
      - run: uv run ruff check .           # 代码检查

# 从 requirements.txt 迁移
uv init                        # 初始化项目
uv add $(cat requirements.txt) # 批量添加依赖

# 从 Poetry 迁移
# uv 可以读取 pyproject.toml 中的 [project] 部分
# Poetry 2.0+ 支持 PEP 621，格式基本兼容
# 手动调整后运行 uv sync 即可

# ===== 项目管理 =====
uv init project-name           # 创建新项目
uv add package                 # 添加依赖
uv add --dev package           # 添加开发依赖
uv remove package              # 移除依赖
uv sync                        # 同步环境
uv lock                        # 更新 lock 文件
uv run command                 # 在项目环境运行命令

# ===== Python 管理 =====
uv python install 3.12         # 安装 Python
uv python list                 # 列出版本
uv python pin 3.12             # 固定版本

# ===== 工具管理 =====
uvx tool-name                  # 临时运行工具
uv tool install tool-name      # 全局安装工具
uv tool list                   # 列出工具

# ===== pip 兼容 =====
uv pip install package         # 安装包
uv pip install -r req.txt      # 从文件安装
uv pip list                    # 列出包
uv pip freeze                  # 导出依赖

# ===== 环境管理 =====
uv venv                        # 创建虚拟环境
uv venv --python 3.12          # 指定版本

# ===== 缓存管理 =====
uv cache clean                 # 清除缓存
uv cache dir                   # 显示缓存目录