Modern Python Development

Use this guide when creating new Python projects, configuring pyproject.toml, setting up development tools, writing scripts with dependencies, or migrating from legacy tooling.

Tool Stack

Critical Anti-Patterns

Never do these:

• •uv pip install <package> → Use uv add <package> instead
• •Manually edit dependencies in pyproject.toml → Use uv add / uv remove
• •Use Poetry → Use uv instead
• •Create requirements.txt → Use pyproject.toml with dependency groups
• •Manually activate virtualenv → Use uv run for all commands
• •Use setup.py or setup.cfg → Use pyproject.toml exclusively

Project Setup

New Package

uv init --package myproject
cd myproject
uv add --group dev ruff
uv add --group test pytest pytest-cov
uv sync

New Script (PEP 723)

uv init --script myscript.py --python 3.12

Running Commands

Always use uv run instead of activating environments:

uv run python src/myproject/main.py
uv run pytest
uv run ruff check .
uv run ruff format .

Dependency Management

# Add runtime dependency
uv add requests

# Add dev dependency
uv add --group dev ruff

# Add test dependency
uv add --group test pytest

# Remove dependency
uv remove requests

# Update all dependencies
uv lock --upgrade

# Sync environment
uv sync

Additional Resources

For detailed configuration and advanced usage:

• •pyproject.toml configuration
• •Ruff configuration
• •uv command reference
• •Testing with pytest
• •PEP 723 scripts
• •Security setup
• •Migration checklist
• •prek pre-commit hooks
• •Dependabot configuration