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

See Also

• uv-run - Running scripts, temporary dependencies, PEP 723
• uv-python-versions - Managing Python interpreter versions
• uv-workspaces - Monorepo and multi-package projects
• uv-advanced-dependencies - Git, path, and constraint dependencies
• uv-tool-management - Installing CLI tools globally
• python-testing - Running tests with pytest
• python-code-quality - Linting and formatting with ruff

References

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