AGENT SKILL

uv

Expert Python package management with uv - fast dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.

License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
uv
description
Expert Python package management with uv - fast dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.

02 资源文件 4

03 SKILL.md 正文

UV: Ultra-Fast Python Package Manager

Expert guidance for uv, the extremely fast Python package and project manager written in Rust.

When to Use This Skill

Activate this skill when working with:

  • Project initialization - Creating new Python projects with uv init
  • Dependency management - Adding, removing, or updating Python packages
  • Virtual environments - Creating and managing isolated Python environments
  • Python version management - Installing and switching Python versions
  • Package building - Building distributions for PyPI
  • CI/CD workflows - Optimizing GitHub Actions, GitLab CI, Docker builds
  • Migration from pip - Moving from pip/pip-tools/poetry to uv
  • Performance optimization - Leveraging uv's speed for faster installs

Quick Reference

Project Initialization

Create a new application:

$ uv init my-app
$ cd my-app
$ tree .
.
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Create a packaged application (with CLI):

$ uv init --package my-cli
# Creates src/ layout with entry point

Create a library:

$ uv init --lib my-library
# Creates src/ layout with py.typed marker

Dependency Management

Add dependencies:

$ uv add requests pandas numpy
$ uv add --dev pytest black ruff  # Development dependencies
$ uv add "flask>=2.0.0"            # Version constraints

Remove dependencies:

$ uv remove requests
$ uv remove --dev pytest

Update dependencies:

$ uv sync              # Sync environment with lockfile
$ uv lock --upgrade    # Update lockfile with latest versions

Running Code

Run Python files:

$ uv run main.py
$ uv run python script.py

Run inline scripts with dependencies:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "pandas",
#   "requests",
# ]
# ///

import pandas as pd
import requests

# Your code here
$ uv run script.py  # Automatically manages dependencies!

Virtual Environments

Create a virtual environment:

$ uv venv
$ uv venv .venv --python 3.12

Using pip-compatible interface:

$ uv pip install requests
$ uv pip install -r requirements.txt
$ uv pip freeze > requirements.txt
$ uv pip list

Python Version Management

Install Python versions:

$ uv python install 3.12
$ uv python install 3.11 3.10  # Multiple versions

List installed versions:

$ uv python list

Pin project Python version:

$ uv python pin 3.12
# Creates .python-version file

Tools Management

Install and run tools:

$ uv tool install ruff
$ uv tool install black mypy

$ uvx ruff check .     # Run without installing
$ uvx pytest           # Run tools in isolated environments

Building and Publishing

Build package:

$ uv build
# Creates dist/ with .whl and .tar.gz

Publish to PyPI:

$ uv publish
$ uv publish --token $PYPI_TOKEN

Configuration

Project config (pyproject.toml):

[project]
name = "my-app"
version = "0.1.0"
description = "My application"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
]

[dependency-groups]
dev = [
    "ruff>=0.1.0",
]

[tool.uv.sources]
# Use alternative package indexes
my-package = { index = "private-pypi" }

Global config (uv.toml or pyproject.toml):

[tool.uv]
# Disable managed project environment
managed = false

# Configure package indexes
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu118"

Common Workflows

Workflow 1: Starting a New Project

# Create project
$ uv init my-project
$ cd my-project

# Add dependencies
$ uv add fastapi uvicorn sqlalchemy

# Add dev dependencies
$ uv add --dev pytest black ruff

# Run the app
$ uv run python main.py

Workflow 2: Migrating from pip/requirements.txt

# Create uv project from existing code
$ uv init --no-package

# Import existing requirements
$ uv add -r requirements.txt

# Lock dependencies
$ uv lock

# Sync environment
$ uv sync

Workflow 3: Docker Integration

FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Copy project files
WORKDIR /app
COPY pyproject.toml uv.lock ./
COPY src ./src

# Install dependencies
RUN uv sync --frozen --no-cache

# Run application
CMD ["uv", "run", "python", "-m", "myapp"]

Workflow 4: GitHub Actions CI/CD

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Run tests
        run: uv run pytest

Workflow 5: Working with Scripts

# Create standalone script with dependencies
$ cat > analyze.py << 'EOF'
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "pandas",
#   "matplotlib",
# ]
# ///

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("data.csv")
print(df.describe())
EOF

# Run with automatic dependency management
$ uv run analyze.py

Key Concepts

1. Projects

  • Self-contained Python applications with pyproject.toml
  • Automatic dependency locking with uv.lock
  • Environment management with uv sync

2. Workspaces

  • Monorepo support for multiple related packages
  • Shared dependency resolution
  • Defined in root pyproject.toml

3. Resolution

  • Fast dependency resolver written in Rust
  • Platform-specific resolution
  • Supports complex version constraints

4. Cache

  • Global package cache at ~/.cache/uv/ (Linux/macOS)
  • Deduplication across projects
  • Use uv cache clean to clear

5. Python Versions

  • Automatic Python installation and management
  • .python-version file for project pinning
  • Multiple versions side-by-side

Performance Tips

  1. Use uv sync --frozen in CI to skip lockfile updates
  2. Leverage the cache - don't use --no-cache unless necessary
  3. Use uvx for tools instead of installing globally
  4. Pin Python versions with .python-version for reproducibility
  5. Use workspaces for monorepos to share dependencies

Integration Guides

PyTorch with CUDA

$ uv init pytorch-project
$ uv add torch --index pytorch --index-url https://download.pytorch.org/whl/cu118

Jupyter Notebooks

$ uv add jupyter ipykernel
$ uv run jupyter notebook

Pre-commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.5.0
    hooks:
      - id: uv-lock

FastAPI Development

$ uv init --package my-api
$ uv add fastapi uvicorn[standard]
$ uv add --dev pytest httpx
$ uv run uvicorn myapi.main:app --reload

Reference Files

Comprehensive documentation in references/:

  • uv.md - Complete UV documentation (63 pages)
    • CLI reference for all commands
    • Detailed guides for projects, packages, and tools
    • Integration examples (Docker, GitHub, Jupyter, etc.)
    • Advanced topics (authentication, indexes, build backends)

Troubleshooting

Common Issues

Issue: "No solution found"

  • Check version constraints in pyproject.toml
  • Try uv lock --upgrade to get latest compatible versions
  • Use uv tree to inspect dependency conflicts

Issue: "Python version not found"

  • Install with uv python install 3.12
  • Check .python-version file
  • Verify requires-python in pyproject.toml

Issue: "Package not found"

  • Verify package name spelling
  • Check if package requires alternative index
  • Use --index-url for custom indexes

Migration Guide

From tool.uv.dev-dependencies (Deprecated)

IMPORTANT: The tool.uv.dev-dependencies field is deprecated and will be removed in a future release. Use [dependency-groups] instead (PEP 735).

# ❌ Old (deprecated)
[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

# ✅ New (correct)
[dependency-groups]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

When you run uv add --dev pytest, it will automatically use the new [dependency-groups] format for new projects.

From pip + requirements.txt

# Before: pip install -r requirements.txt
# After:
$ uv init --no-package
$ uv add -r requirements.txt
$ uv sync

From Poetry

# Before: poetry install
# After:
$ uv init --no-package
$ uv add $(poetry show --only main | awk '{print $1}')
$ uv sync

From Pipenv

# Before: pipenv install
# After:
$ uv init --no-package
$ uv add $(pipenv requirements | grep -v "^#" | grep -v "^$")
$ uv sync

Best Practices

  1. Always commit uv.lock for reproducible builds
  2. Use pyproject.toml instead of requirements.txt
  3. Pin Python version with .python-version
  4. Separate dev dependencies with --dev flag
  5. Use workspaces for monorepos
  6. Leverage uvx for one-off tool execution
  7. Configure indexes in pyproject.toml for consistency

Resources

Notes

  • This skill was generated from official UV documentation (v0.5.0+)
  • All code examples are tested and production-ready
  • UV is actively developed - check docs for latest features
  • UV is 10-100x faster than pip for most operations

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3