UV.md

Starting a new Python project

Create a new project:

uv init my-ai-app
cd my-ai-app

Project structure:

my-web-app/
├── .gitignore
├── .python-version    # Pins Python version
├── README.md
├── hello.py
└── pyproject.toml     # Modern Python packaging

Add Dependencies:

# Production Dependencies
uv add openai fastapi

# Optional Dependencies (Extras)
uv add --optional feature-name sqlalchemy

# Development Dependencies
uv add --dev pytest ruff

Run

uv run hello.py

---

UV automatically creates the venv, installs dependencies, and generates uv.lock for reproducible builds.

Working with existing projects

Clone and sync:

git clone https://github.com/org/project.git
cd project
uv sync

uv sync creates the venv and installs exact versions from uv.lock for identical team setups.

Production deployments (exclude dev dependencies):

uv sync --no-dev

Python version management

Built-in Python version management (replaces pyenv):

# Install Python versions
uv python install 3.12
uv python install 3.11 3.12 3.13  # Multiple at once

# Pin project to specific version
uv python pin 3.12  # Creates .python-version

# List available versions
uv python list

Automatic Python installation: UV installs missing Python versions during uv sync.

Development vs production dependencies

UV uses modern dependency groups following PEP 735:

[project]
name = "my-app"
dependencies = [
    "fastapi>=0.100.0",
    "sqlalchemy>=2.0.0",
]

[dependency-groups]
dev = [
    "pytest>=7.4.0",
    "black>=23.0.0",
]

Managing dependency groups:

uv add --dev pytest black        # Add to dev group
uv sync                          # Install everything
uv sync --no-dev                 # Production only

Essential commands

Most common UV commands:

# Project setup
uv init myproject           # Create new project
uv add requests             # Add dependency
uv remove requests             # Remove dependency
uv sync                     # Install from lockfile

# Running code
uv run script.py    # Run in project environment
uv run pytest              # Run tests

# Python management
uv python install 3.12     # Install Python version
uv python pin 3.12         # Set project Python

# Tool usage
uvx black .                # Run tool temporarily
uv tool install ruff       # Install tool globally

# Package management (pip-compatible)
uv pip install requests  # Direct pip replacement
uv pip install -r requirements.txt

New project flow

uv init my-project
cd my-project
code .

uv add fastapi uvicorn
uv add --dev pytest
uv add --dev ruff

git init
git add .
git commit -m "Initial commit"

# Create new repo with GitHub CLI
gh repo create my-project --private --source=. --remote=origin --push