UV Project Management Skill

UV Project Management

Quick reference for UV project setup, dependencies, and lockfiles.

When to Use This Skill

| Use this skill when... | Use a focused sibling instead when... | |---|---| | Running uv init, uv add, uv remove, uv lock, or uv sync for everyday dependency management | Running a script or one-off command — use uv-run | | Authoring or editing pyproject.toml [project] and [tool.uv] sections | Wiring git/path/editable deps or workspace inheritance — use uv-advanced-dependencies | | Bootstrapping a new single-package Python project | Splitting a repo into multi-package workspaces — use uv-workspaces |

When This Skill Applies

Initializing new Python projects (uv init)
Adding, removing, or updating dependencies (uv add, uv remove)
Managing lockfiles (uv lock)
Syncing project environments (uv sync)
Configuring pyproject.toml

For running scripts, see uv-run skill.

Quick Reference

Project Initialization

# Create new project with complete structure
uv init my-project
cd my-project

# Initialize in existing directory
uv init

# Initialize with specific Python version
uv init --python 3.11 my-app

Dependency Management

# Add dependencies
uv add requests
uv add 'flask>=2.0'
uv add 'django>=4.0,<5.0'

# Add development dependencies
uv add --dev pytest pytest-cov black

# Add optional dependency groups
uv add --group docs sphinx sphinx-rtd-theme

# Remove dependencies
uv remove requests flask

# Migrate from requirements.txt
uv add -r requirements.txt

Lockfile Operations

# Create/update lockfile (uv.lock)
uv lock

# Lock with upgraded packages
uv lock --upgrade-package requests
uv lock --upgrade

# Lock without installing (CI/CD)
uv lock --frozen

Environment Synchronization

# Sync environment to lockfile
uv sync

# Sync without updating lockfile
uv sync --frozen

# Error if lockfile is out of date
uv sync --locked

Project Structure

UV projects follow this standard structure:

my-project/
├── pyproject.toml      # Project metadata and dependencies
├── uv.lock            # Locked dependency versions
├── .venv/             # Virtual environment (auto-created)
├── README.md
└── src/
    └── my_project/
        └── __init__.py

Generated pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

[build-system]
requires = ["uv_build>=0.9.2,<0.10.0"]
build-backend = "uv_build"

Common Workflows

Starting a New Project

uv init my-app && cd my-app
uv add ruff pytest
uv run pytest

Adding Multiple Dependencies

# Production dependencies
uv add fastapi uvicorn 'pydantic>=2.0'

# Development tooling
uv add --dev pytest pytest-cov ruff ty

# Documentation
uv add --group docs sphinx mkdocs-material

Updating Dependencies

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

# Update all dependencies
uv lock --upgrade

# Sync after update
uv sync

Key Features

Fast: 10-100x faster than pip
Deterministic: Lockfile ensures reproducible installs
Automatic: Creates and manages virtual environments
Modern: Uses pyproject.toml for configuration
Compatible: Works with pip, Poetry, and other tools

References

Official docs: https://docs.astral.sh/uv/
GitHub: https://github.com/astral-sh/uv
Detailed guide: See REFERENCE.md in this skill directory

Agent Skills: UV Project Management

Install this agent skill to your local

Skill Files