laurigates 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