AgentSkillsCN

uv-package-manager

jstack

SKILL.md
--- frontmatter
name: uv-package-manager
description: Manage Python projects and dependencies using UV, the ultra-fast Rust-based package manager. Use when creating Python projects, managing dependencies, or running Python scripts.

UV Package Manager Skill

When to Activate

Activate this skill when:

  • •Creating new Python projects
  • •Adding or removing dependencies
  • •Running Python scripts or tools
  • •Managing virtual environments
  • •Setting up Python version management

Why UV?

  • •10-100x faster than pip (Rust implementation)
  • •Unified tool - replaces pip, pip-tools, poetry, pyenv, virtualenv
  • •Reliable - lock files for reproducible builds
  • •Modern - built for current Python workflows

Quick Commands

bash
# Project Management
uv init                      # Create new project
uv init --package my-lib     # Create installable package

# Dependencies
uv add requests              # Add dependency
uv add --dev pytest          # Add dev dependency
uv remove package-name       # Remove dependency

# Running Code
uv run script.py             # Run Python script
uv run pytest                # Run installed tool
uv run python -m module      # Run module

# Environment
uv sync                      # Sync dependencies
uv sync --frozen             # Sync without updating lock
uv lock                      # Update lock file
uv python install 3.12       # Install Python version

Creating Projects

bash
# Standard project
uv init my-project
cd my-project

# Package project (for libraries)
uv init --package my-library

# Specify Python version
uv init --python 3.11

Created Structure

code
my-project/
├── .python-version    # Python version
├── pyproject.toml     # Project config
├── .venv/             # Virtual environment (auto-created)
└── hello.py           # Sample script

Adding Dependencies

bash
# Basic add
uv add requests fastapi uvicorn

# With version constraints
uv add "django>=4.2,<5.0"
uv add "requests==2.31.0"
uv add "fastapi[all]"

# Dev dependencies
uv add --dev pytest black ruff mypy

# From git
uv add --git https://github.com/user/repo --branch develop

Running Scripts

bash
# Run Python script
uv run script.py

# Run with arguments
uv run script.py --input data.csv

# Run dev tools
uv run pytest tests/ -v
uv run black .
uv run ruff check .

# Run with temporary dependency
uv run --with httpx fetch_data.py

# Start Python REPL
uv run python

Virtual Environment

UV automatically manages virtual environments:

bash
# Created automatically on first use
uv sync          # First sync
uv add package   # First package add
uv run script.py # First run

# Manual creation
uv venv
uv venv --python 3.11

# Manual activation (rarely needed)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Lock Files

bash
# Generate/update lock file
uv lock

# Sync from lock (normal)
uv sync

# Sync without updating (CI/CD)
uv sync --frozen

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

# ALWAYS commit these files:
# - pyproject.toml
# - uv.lock
# - .python-version

Python Version Management

bash
# List available versions
uv python list

# Install specific version
uv python install 3.12

# Set project version
echo "3.12" > .python-version

Migration from pip

bash
# Import requirements.txt
uv init my-project
cd my-project
uv add -r requirements.txt

# Import dev requirements
uv add --dev -r requirements-dev.txt

Common pyproject.toml

toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.20.0",
]

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

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

Best Practices

DO ✅

  • •Commit uv.lock and .python-version
  • •Use semantic versioning for dependencies
  • •Use --dev for development tools
  • •Use uv run instead of manual activation
  • •Use --frozen in CI/CD

DON'T ❌

  • •Commit .venv/ directory
  • •Use * for version constraints
  • •Mix pip and uv in same project
  • •Skip lock file updates after changes

Troubleshooting

bash
# Clear cache
uv cache clean

# Verbose mode for debugging
uv --verbose add package

# Regenerate lock
uv lock
uv sync

Related Resources

See AgentUsage/uv_usage.md for complete documentation including:

  • •Docker integration patterns
  • •Workspace support for monorepos
  • •CI/CD configuration
  • •Detailed migration guides