uv-package-manager

用途

UV Package Manager 技能用于掌握 UV 这一 Python 包管理工具，覆盖快速依赖安装、虚拟环境创建以及现代 Python 项目工作流。资料称其依赖安装速度比 pip 快 10-100 倍。

适用时机

资料列出以下使用场景：

快速依赖安装（比 pip 快 10-100 倍）
虚拟环境管理：轻松创建和管理 venv
项目初始化：快速启动新的 Python 项目
依赖解析：可靠、可复现的依赖树
锁文件管理：确保跨机器环境一致
Python 版本管理：安装和切换 Python 版本

资料建议在以下情况避免使用：需要 pip 兼容的遗留系统（罕见）、基于 Conda 的科学计算环境、预装 pip 工作流的 Docker 镜像。

安装

资料提供以下安装命令：

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew
brew install uv

# pip (if needed)
pip install uv

主要能力

1. 项目初始化

uv init my-project
cd my-project
uv init
uv init --python 3.11

创建的项目结构包含 .python-version、pyproject.toml、README.md 以及 src/ 目录。

2. 虚拟环境管理

uv venv
uv venv --python 3.11
uv venv .venv-test
source .venv/bin/activate
.venv\Scripts\activate
source .venv/Scripts/activate

Python 版本管理命令：

uv python list
uv python install 3.12
uv python pin 3.11

3. 依赖管理

添加依赖：

uv add pandas
uv add numpy scipy matplotlib
uv add "pandas>=2.0,<3.0"
uv add --dev pytest pytest-cov ruff
uv add --optional ml tensorflow torch
uv add git+https://github.com/user/repo.git
uv add --editable ../my-local-package

移除依赖：

uv remove pandas
uv remove --dev pytest

同步依赖：

uv sync
uv sync --dev
uv sync --extra ml
uv sync --all-extras

4. 锁文件管理

uv.lock 在 uv add/uv sync 时自动生成，包含精确版本以保证可复现性。

uv lock
uv lock --python 3.11
uv lock --upgrade
uv lock --upgrade-package pandas

资料给出锁文件结构示例（自动生成，不应手动编辑），包含 version、requires-python 以及 [[package]] 条目（name、version、source、dependencies）。

5. 运行脚本与命令

uv run python script.py
uv run python -m pytest
uv run --python 3.11 python script.py
uv run pytest tests/
uv run ruff check src/
uv run black src/
uv run mypy src/

6. pip 兼容模式

uv pip install pandas numpy
uv pip install -r requirements.txt
uv pip install -e .
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
uv pip freeze > requirements.txt
uv pip show pandas

使用方式与完整示例

资料提供多个完整示例脚本：

示例 1：新项目初始化脚本，包含 uv init、uv python pin、添加核心与开发依赖、创建目录结构、生成 .gitignore 并运行测试。
示例 2：从 pip 迁移到 UV 的脚本，备份 requirements、初始化项目、逐行迁移依赖与开发依赖、执行 uv sync --dev。
示例 3：CI/CD 流水线（GitHub Actions），使用 astral-sh/setup-uv@v4，在 Python 3.10/3.11/3.12 矩阵中执行 lint、类型检查、测试、覆盖率上传与构建。
示例 4：多环境管理脚本，为多个 Python 版本创建独立虚拟环境并跨环境运行测试。
示例 5：workspace-hub 项目设置脚本，包含标准依赖、目录结构、conftest.py 与 CLAUDE.md 生成。

最佳实践

资料列出以下实践：

版本固定：使用 uv python pin 3.11，在 pyproject.toml 中使用版本范围（如 requires-python = ">=3.10,<3.13"）。
锁文件卫生：将 uv.lock 提交到版本控制，定期 uv lock --upgrade，提交前用 git diff uv.lock 审查变更。
依赖分组：在 pyproject.toml 中通过 [project.optional-dependencies] 组织 dev、viz、ml 等分组，并在 [tool.uv] 中配置 dev-dependencies。
脚本配置：在 [project.scripts] 与 [tool.uv.scripts] 中定义 CLI 与任务脚本（test、lint、format、typecheck、all）。
性能提示：默认并行安装、设置 UV_CACHE_DIR 全局缓存、uv sync --offline 离线模式、uv sync --no-dev --no-extras 最小安装。

常用命令参考

资料给出命令表：uv init（初始化项目）、uv venv（创建虚拟环境）、uv add <pkg>（添加依赖）、uv add --dev <pkg>（添加开发依赖）、uv remove <pkg>（移除依赖）、uv sync（安装所有依赖）、uv lock（更新锁文件）、uv run <cmd>（在 venv 中运行命令）、uv python list（列出 Python 版本）、uv python install（安装 Python 版本）、uv pip install（pip 兼容模式）、uv build（构建包）、uv publish（发布到 PyPI）。

适用场景与限制

适用场景包括需要快速依赖安装、可复现依赖树、跨机器一致环境、多 Python 版本管理的 Python 项目，以及从 pip 迁移和 CI/CD 集成。限制方面，资料建议在需要 pip 兼容的遗留系统、基于 Conda 的科学计算环境、预装 pip 工作流的 Docker 镜像中避免使用。资料未提供关于收费、价格或平台支持范围的更多信息。

资源

UV 文档：https://docs.astral.sh/uv/
UV GitHub：https://github.com/astral-sh/uv
迁移指南：https://docs.astral.sh/uv/guides/migration/
pyproject.toml 规范：https://packaging.python.org/en/latest/specifications/pyproject-toml/