uv-python-project

name	uv-python-project
description	Work on Python projects with uv. Use for repositories with pyproject.toml, uv.lock, package directories, dependency groups, .venv environments, uv sync/run/add/remove/lock workflows, or project-level tests and validation.

uv Python Projects

Scope

Default to uv for project management and command execution.

• Applies to project-owned Python code: pyproject.toml, uv.lock, .venv, package directories, dependency groups, extras, tests, and tools.
• Prefer uv-python-script for standalone single-file scripts with PEP 723 inline dependencies.

Rules

• Prefer uv run, uv sync, uv add, uv remove, uv lock, uv format, and uv check over direct system python3, pip, or ad hoc virtualenv commands.
• Do not run project Python code with system python3 unless the project explicitly documents that path.
• Do not use python3 -m py_compile as the project check.
• Preserve existing project configuration. Do not introduce uv metadata, dependency groups, or lockfile changes unless needed for the task.
• Match the project's declared Python version and write modern Python for that version. Do not downgrade syntax for an unrelated system Python.
• Match requires-python and write modern Python for that version, such as match, str | None, list[str], and Path-based filesystem code. Add a focused CLI library such as click when it makes parsing clearer than handwritten plumbing.

Commands

Inspect the project first:

uv --version
uv tree

Install or refresh the environment when needed:

uv sync
uv sync --all-groups

Run project commands through uv:

uv run python -m pytest
uv run pytest
uv run <tool> <args>

Manage dependencies through uv:

uv add <package>
uv add --dev <package>
uv remove <package>
uv lock

Follow existing dependency groups, extras, and lockfile conventions.

Format and Check

Use uv's project-aware commands when available:

uv format
uv format --check
uv check

If the project already uses specific tools, run them through uv:

uv run ruff check .
uv run mypy .
uv run basedpyright
uv run pytest

Prefer documented validation commands over generic guesses. Report the exact uv commands run and whether they passed.