Modern Python

Guide for modern Python tooling and best practices, based on trailofbits/cookiecutter-python.

When to Use This Skill

• Creating a new Python project or package
• Setting up pyproject.toml configuration
• Configuring development tools (linting, formatting, testing)
• Writing Python scripts with external dependencies
• Migrating from legacy tools (when user requests it)

When NOT to Use This Skill

• User wants to keep legacy tooling: Respect existing workflows if explicitly requested
• Python < 3.11 required: These tools target modern Python
• Non-Python projects: Mixed codebases where Python isn't primary

Anti-Patterns to Avoid

Avoid	Use Instead
[tool.ty] python-version	[tool.ty.environment] python-version
uv pip install	uv add and uv sync
Editing pyproject.toml manually to add deps	uv add <pkg> / uv remove <pkg>
hatchling build backend	uv_build (simpler, sufficient for most cases)
Poetry	uv (faster, simpler, better ecosystem integration)
requirements.txt	PEP 723 for scripts, pyproject.toml for projects
mypy / pyright	ty (faster, from Astral team)
[project.optional-dependencies] for dev tools	[dependency-groups] (PEP 735)
Manual virtualenv activation (source .venv/bin/activate)	uv run <cmd>
pre-commit	prek (faster, no Python runtime needed)

Key principles:

• Always use uv add and uv remove to manage dependencies
• Never manually activate or manage virtual environments, use uv run for all commands
• Use [dependency-groups] for dev/test/docs dependencies, not [project.optional-dependencies]

Decision Tree