Python UV 包管理工具：比 pip 快 10-100 倍的现代依赖管理方案

python-uv by 89jobrien/steve

1 周安装量

4 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/89jobrien/steve --skill python-uv

Python Web框架开发开发运维

🇨🇳中文介绍

Python UV 包管理

核心原则

UV 是现代 Python 依赖管理的标准。 它提供确定性解析，速度比 pip 快 10-100 倍，并内置虚拟环境管理。

何时使用此技能

设置新的 Python 项目
管理 Python 依赖项
运行 .py 文件和命令
运行 Python 工具，如 pytest 和 ruff
为 Python 应用程序创建 Dockerfile
Python 项目的 CI/CD 流水线
从 pip/poetry 迁移到 UV

为什么选择 UV 而非其他方案

速度对比（20 个依赖项，冷安装）：
- pip install: 120-180 秒
- uv sync: 15-20 秒（快 10 倍）

使用缓存时：
- pip install（缓存）: 60-90 秒
- uv sync（缓存）: 2-5 秒（快 30 倍）

额外优势：
- 确定性解析（锁文件保证精确版本）
- 内置虚拟环境管理
- 对 Docker 缓存友好（分离下载/安装阶段）
- 直接兼容 pip
- 跨平台锁文件

标准工作流

项目设置

# 初始化新项目（创建 pyproject.toml）
uv init

# 或者将 UV 添加到已有 pyproject.toml 的项目中
uv lock  # 从 pyproject.toml 生成 uv.lock

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

标准 Dockerfile 结构

FROM python:3.12-slim AS builder

WORKDIR /app

# 从官方镜像复制 UV（始终保持最新）
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# 首先复制依赖文件（利用层缓存）
COPY pyproject.toml uv.lock ./

# 使用缓存挂载进行安装（快速重建）
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
    uv sync --frozen

# 在依赖项之后复制源代码（对缓存友好）
COPY src/ ./src/

# ... 构建的其余部分

关键：不同场景使用不同标志

开发（本地）：
  uv sync          # 如果不同步，可能会更新 uv.lock

CI/Docker（生产环境）：
  uv sync --frozen # 如果 uv.lock 与 pyproject.toml 不匹配，则失败

为什么在 Docker/CI 中使用 --frozen：
- 确保锁文件已提交且是最新的
- 防止构建期间依赖项静默更改
- 构建失败 = 锁文件漂移（有意的安全措施）
- 保证可重现的构建

使用 UV 的多阶段构建

# 阶段 1：构建器（包含用于测试的开发依赖项）
FROM python:3.12-slim AS builder

WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# 安装所有依赖项（包括开发依赖项）
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
    uv sync --frozen

# 复制源代码和测试
COPY src/ ./src/
COPY tests/ ./tests/

# 在构建期间运行测试
RUN uv run pytest tests/

# 构建 wheel 包
RUN uv build

# 阶段 2：运行时（仅生产依赖项）
FROM python:3.12-slim

WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# 仅安装运行时依赖项
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
    uv sync --frozen --no-dev --no-install-project

# 从构建器安装构建好的 wheel 包
COPY --from=builder /app/dist/*.whl ./
RUN uv pip install *.whl && rm *.whl

ENV PATH="/app/.venv/bin:$PATH"
ENTRYPOINT ["python", "-m", "myapp"]

pyproject.toml 结构

[project]
name = "myproject"
version = "0.1.0"
description = "项目描述"
requires-python = ">=3.12"
dependencies = [
    "boto3~=1.40.52",      # 运行时依赖
    "pydantic>=2.0.0,<3.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",       # 开发/测试依赖
    "mypy>=1.8.0",
    "ruff>=0.1.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
# UV 特定配置（可选）

问：我应该在什么时候使用 pip 而不是 UV？
答：很少。UV 能更快地处理所有 pip 用例。
    例外：无法安装 UV 的遗留系统。

问：如何从 pip/requirements.txt 迁移？
答：1. 创建包含依赖项的 pyproject.toml
    2. 运行：uv lock
    3. 运行：uv sync
    4. 删除 requirements.txt

问：如何从 poetry 迁移？
答：1. UV 读取 pyproject.toml（兼容 poetry 格式）
    2. 运行：uv lock（生成 uv.lock）
    3. 运行：uv sync
    4. 可选地删除 poetry.lock

问：何时使用 uv sync 与 uv sync --frozen？
答：开发：uv sync（灵活）
   CI/Docker：uv sync --frozen（严格）

问：如何处理私有包？
答：uv add package --index-url https://private.pypi/simple/
   或者在 pyproject.toml 的 [tool.uv.sources] 中配置

- name: 安装 UV
  uses: astral-sh/setup-uv@v1

- name: 安装依赖项
  run: uv sync --frozen

- name: 运行测试
  run: uv run pytest tests/

- name: 类型检查
  run: uv run mypy src/

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: uv-lock-check
        name: 检查 uv.lock 是否同步
        entry: uv lock --check
        language: system
        pass_filenames: false

❌ 为新 Python 项目使用 pip
   → UV 更快、更可靠

❌ 在 Docker/CI 中不使用 --frozen
   → 依赖项静默漂移，构建不可重现

❌ 提交时不包含 uv.lock
   → 失去可重现性，每台机器安装结果不同

❌ 手动管理 venv（python -m venv）
   → UV 自动处理

❌ 在 UV 中使用 requirements.txt
   → 使用 pyproject.toml（现代标准）

❌ 在 .gitignore 中忽略 uv.lock
   → 锁文件必须提交以保证可重现性

✅ 对所有 Python 依赖管理使用 `uv`
✅ 在所有 CI/Docker 场景中使用 --frozen
✅ 将 uv.lock 与 pyproject.toml 一起提交
✅ 让 UV 管理虚拟环境
✅ 在 Docker 中使用缓存挂载以提高速度

与其他技能的集成

version-pinning : 用于约束策略（~= 与 >=）
docker-multistage : UV 与多阶段模式集成
version-currency : uv.lock 是版本验证的权威来源
container-boundary : UV venv 是容器本地的，而非宿主机

锁文件作为单一事实来源

uv.lock 文件包含：
- 每个依赖项（包括传递依赖）的精确版本
- 用于完整性验证的 SHA256 哈希值
- 每个包的源 URL
- 平台特定的解析结果

这提供了：
- 跨机器/时间的可重现构建
- 通过篡改检测（哈希）实现的安全性
- 可审计性（确切知道安装了哪些内容）
- 版本验证（参见 version-currency 技能）

UV 使 Python 依赖管理现代化。

旧方式（pip）：
- 安装速度慢
- 非确定性解析
- 手动管理 venv
- requirements.txt（元数据有限）

新方式（UV）：
- 快速安装（快 10-100 倍）
- 确定性解析（锁文件）
- 自动管理 venv
- pyproject.toml（丰富的元数据）

对于任何新的 Python 项目：从 UV 开始。
对于现有项目：迁移到 UV。

--frozen 标志是你在 CI/Docker 中的安全网。
永远不要在没有它的情况下发布。

🇺🇸English

Python UV Package Management

Core Principle

UV is the modern standard for Python dependency management. It provides deterministic resolution, 10-100x speed improvement over pip, and built-in virtual environment management.

When to Use This Skill

Setting up new Python projects
Managing Python dependencies
Running .py files and commands
Running python tools like pytest and ruff
Creating Dockerfiles for Python applications
CI/CD pipelines for Python
Migrating from pip/poetry to UV

Why UV Over Alternatives

Speed comparison (20 dependencies, cold install):
- pip install: 120-180 seconds
- uv sync: 15-20 seconds (10x faster)

With cache:
- pip install (cached): 60-90 seconds
- uv sync (cached): 2-5 seconds (30x faster)

Additional benefits:
- Deterministic resolution (lockfile guarantees exact versions)
- Built-in virtual environment management
- Docker cache-friendly (separate download/install phases)
- Drop-in pip compatibility
- Cross-platform lockfiles

Standard Workflow

Project Setup

# Initialize new project (creates pyproject.toml)
uv init

# Or add UV to existing project with pyproject.toml
uv lock  # Generate uv.lock from pyproject.toml

Daily Development

# Install all dependencies (creates/updates venv)
uv sync

# Install without dev dependencies
uv sync --no-dev

# Add runtime dependency
uv add boto3>=1.40.0

# Add dev dependency
uv add --dev pytest>=8.0.0

# Remove dependency
uv remove boto3

# Update lockfile (resolve latest within constraints)
uv lock --upgrade

# Run command in virtual environment
uv run pytest tests/
uv run python -m myapp
uv run mypy src/

Lockfile Management

# Generate/update lockfile
uv lock

# Update all dependencies to latest (within constraints)
uv lock --upgrade

# Update specific package
uv lock --upgrade-package boto3

# Verify lockfile is in sync (CI check)
uv lock --check

Docker Integration Pattern

Standard Dockerfile Structure

FROM python:3.12-slim AS builder

WORKDIR /app

# Copy UV from official image (always current)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Copy dependency files FIRST (layer caching)
COPY pyproject.toml uv.lock ./

# Install with cache mount (fast rebuilds)
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
    uv sync --frozen

# Copy source code AFTER dependencies (cache-friendly)
COPY src/ ./src/

# ... rest of build

The --frozen Discipline

CRITICAL: Different flags for different contexts

Development (local):
  uv sync          # May update uv.lock if out of sync

CI/Docker (production):
  uv sync --frozen # FAILS if uv.lock doesn't match pyproject.toml

Why --frozen in Docker/CI:
- Ensures lockfile is committed and current
- Prevents silent dependency changes during build
- Build failure = lockfile drift (intentional safety)
- Reproducible builds guaranteed

Multi-Stage with UV

# STAGE 1: Builder (with dev deps for testing)
FROM python:3.12-slim AS builder

WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Install ALL dependencies (including dev)
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
    uv sync --frozen

# Copy source and tests
COPY src/ ./src/
COPY tests/ ./tests/

# Run tests during build
RUN uv run pytest tests/

# Build wheel
RUN uv build

# STAGE 2: Runtime (production deps only)
FROM python:3.12-slim

WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Install ONLY runtime dependencies
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv,sharing=locked \
    uv sync --frozen --no-dev --no-install-project

# Install built wheel from builder
COPY --from=builder /app/dist/*.whl ./
RUN uv pip install *.whl && rm *.whl

ENV PATH="/app/.venv/bin:$PATH"
ENTRYPOINT ["python", "-m", "myapp"]

pyproject.toml Structure

[project]
name = "myproject"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.12"
dependencies = [
    "boto3~=1.40.52",      # Runtime deps
    "pydantic>=2.0.0,<3.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",       # Dev/test deps
    "mypy>=1.8.0",
    "ruff>=0.1.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
# UV-specific configuration (optional)

Decision Framework

Q: When should I use pip instead of UV?
A: Rarely. UV handles all pip use cases faster.
   Exception: Legacy systems that can't install UV.

Q: How do I migrate from pip/requirements.txt?
A: 1. Create pyproject.toml with dependencies
   2. Run: uv lock
   3. Run: uv sync
   4. Delete requirements.txt

Q: How do I migrate from poetry?
A: 1. UV reads pyproject.toml (poetry format compatible)
   2. Run: uv lock (generates uv.lock)
   3. Run: uv sync
   4. Optionally remove poetry.lock

Q: When to use uv sync vs uv sync --frozen?
A: Development: uv sync (flexible)
   CI/Docker: uv sync --frozen (strict)

Q: How to handle private packages?
A: uv add package --index-url https://private.pypi/simple/
   Or configure in pyproject.toml [tool.uv.sources]

CI/CD Patterns

GitHub Actions

- name: Install UV
  uses: astral-sh/setup-uv@v1

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

- name: Run tests
  run: uv run pytest tests/

- name: Type check
  run: uv run mypy src/

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: uv-lock-check
        name: Check uv.lock is in sync
        entry: uv lock --check
        language: system
        pass_filenames: false

Anti-Patterns

❌ Using pip for new Python projects
   → UV is faster and more reliable

❌ Not using --frozen in Docker/CI
   → Silent dependency drift, unreproducible builds

❌ Committing without uv.lock
   → Loses reproducibility, different installs per machine

❌ Manual venv management (python -m venv)
   → UV handles this automatically

❌ Using requirements.txt with UV
   → Use pyproject.toml (modern standard)

❌ Ignoring uv.lock in .gitignore
   → Lockfile MUST be committed for reproducibility

✅ `uv` for all Python dependency management
✅ --frozen in all CI/Docker contexts
✅ Commit uv.lock alongside pyproject.toml
✅ Let UV manage virtual environments
✅ Use cache mounts in Docker for speed

Integration with Other Skills

version-pinning : Use for constraint strategy (~= vs >=)
docker-multistage : UV integrates with multi-stage pattern
version-currency : uv.lock is authoritative for version verification
container-boundary : UV venv is container-local, not host

Lockfile as Source of Truth

The uv.lock file contains:
- Exact version of every dependency (including transitive)
- SHA256 hashes for integrity verification
- Source URLs for each package
- Platform-specific resolutions

This provides:
- Reproducible builds across machines/time
- Security via tamper detection (hashes)
- Auditability (know exactly what's installed)
- Version verification (see version-currency skill)

Meta-Principle

UV modernizes Python dependency management.

Old way (pip):
- Slow installs
- Non-deterministic resolution
- Manual venv management
- requirements.txt (limited metadata)

New way (UV):
- Fast installs (10-100x)
- Deterministic resolution (lockfile)
- Automatic venv management
- pyproject.toml (rich metadata)

For any new Python project: Start with UV.
For existing projects: Migrate to UV.

The --frozen flag is your CI/Docker safety net.
Never ship without it.

Weekly Installs

Repository

89jobrien/steve

GitHub Stars

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPass SocketFail SnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

147,400 周安装

Python UV 包管理工具：比 pip 快 10-100 倍的现代依赖管理方案

🇨🇳中文介绍

Python UV 包管理

核心原则

何时使用此技能

为什么选择 UV 而非其他方案

标准工作流

项目设置

相关 Skills

日常开发

锁文件管理

Docker 集成模式

标准 Dockerfile 结构

--frozen 规范

使用 UV 的多阶段构建

pyproject.toml 结构

决策框架

CI/CD 模式

GitHub Actions

预提交钩子

反模式

与其他技能的集成

锁文件作为单一事实来源

元原则

🇺🇸English

Python UV Package Management

Core Principle

When to Use This Skill

Why UV Over Alternatives

Standard Workflow

Project Setup

Daily Development

Lockfile Management

Docker Integration Pattern

Standard Dockerfile Structure

The --frozen Discipline

Multi-Stage with UV

pyproject.toml Structure

Decision Framework

CI/CD Patterns

GitHub Actions

Pre-commit Hook

Anti-Patterns

Integration with Other Skills

Lockfile as Source of Truth

Meta-Principle

最新 Skills