Python 包管理 uv 详解
============================

uv 是 Astral 公司（Ruff 的作者）用 Rust 开发的新一代 Python 包管理
工具，号称比 pip 快 10-100 倍，目标是替代 pip、poetry、pipenv 等。

一、安装与初始化
----------------

# 安装 uv（官方推荐方式）
# pip install uv
# 或者使用独立安装脚本：
# curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version

# 初始化新项目
uv init myproject
# 创建项目目录和基础文件结构
# uv 会自动生成 pyproject.toml

# 初始化脚本文件
uv init --script hello.py
# 生成一个带依赖声明的 Python 脚本

二、pyproject.toml 配置
------------------------

# uv 使用标准的 pyproject.toml 格式
"""
[project]
name = "myproject"
version = "0.1.0"
description = "使用 uv 管理的 Python 项目"
requires-python = ">=3.9"
dependencies = [
"requests>=2.31.0",
"click>=8.1.0",
"pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
"pytest>=7.4.0",
"ruff>=0.1.0",
]
"""

三、依赖管理核心命令
--------------------

# 添加依赖（自动更新 pyproject.toml）
uv add flask
# uv 会解析依赖树并生成 uv.lock 文件

# 添加指定版本依赖
uv add "pydantic>=2.5.0,<3.0.0"

# 添加开发依赖
uv add --dev pytest pytest-cov

# 添加可选依赖组
uv add --group docs sphinx

# 安装项目所有依赖
uv sync
# 自动创建虚拟环境并安装所有依赖

# 仅安装生产依赖
uv sync --no-dev

# 移除依赖
uv remove flask

四、uv 的 pip 兼容接口
-----------------------

# uv 提供了 pip 命令的完全替代品
# 安装包
uv pip install requests

# 安装 requirements.txt
uv pip install -r requirements.txt

# 导出已安装包列表
uv pip freeze > requirements.txt

# 查看已安装包
uv pip list

# 显示包信息
uv pip show flask

# pip 接口的速度比原生 pip 快 10-50 倍
# 在 CI/CD 环境中效果尤其明显

五、虚拟环境管理
----------------

# uv 自动管理虚拟环境，无需手动创建
# 但也可以显式操作：

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

# 指定 Python 版本创建
uv venv --python 3.11

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

# 在虚拟环境中直接执行命令
uv run python script.py

# 在临时环境中执行
uv run --with flask flask run

六、锁定文件
------------

# uv.lock 是跨平台的锁定文件，确保可重复安装
# 使用精确哈希值锁定所有传递依赖
# 必须提交到版本控制系统

# 锁定依赖版本
uv lock

# 查看锁定文件中的依赖树
uv tree

# 检查依赖是否有安全漏洞
uv audit

七、性能对比与优势
------------------

# uv 的性能优势来自 Rust 实现和优化算法：
# · 依赖解析速度比 poetry 快 20-50 倍
# · 安装速度比 pip 快 10-100 倍
# · 使用全局缓存避免重复下载

# 全局缓存管理
uv cache dir # 查看缓存目录
uv cache clean # 清理所有缓存
uv cache prune # 清理未使用的缓存条目

八、与其他工具的互操作
----------------------

# uv 可以与其他工具配合使用：
# 依据 requirements.txt 创建锁文件
uv pip compile requirements.txt -o requirements.lock

# 使用 uv 作为 nox 或 tox 的后端
# pip install nox && nox 会自动使用 uv

# 在 Docker 中使用 uv 加速构建
"""
FROM python:3.11-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen
COPY . .
CMD ["uv", "run", "python", "main.py"]
"""

# uv 代表了 Python 包管理的未来方向，极速体验让
# 开发者从等待依赖安装的焦虑中彻底解放出来。