---

name: python-tooling description: "Use when managing Python packages, virtual environments, or linting and formatting Python code" allowed-tools: [Bash(uv*), Bash(ruff*), Read, Glob] version: 1.0.0 author: ykotik license: MIT

Python Tooling

When to Use

• Installing Python packages or creating virtual environments
• Running Python scripts with dependency isolation
• Linting Python code for errors, style issues, or import sorting
• Formatting Python code consistently
• Managing Python project dependencies (pyproject.toml)
• Auto-fixing Python lint issues

Tools

Tool	Purpose	Structured output
uv	Ultra-fast Python package manager and venv tool (Rust, 10-100x faster than pip)	N/A (status messages)
Ruff	Extremely fast Python linter + formatter (Rust, replaces black + flake8 + isort)	--output-format json for JSON

Patterns

Create a virtual environment

uv venv

Create venv with specific Python version

uv venv --python 3.12

Install packages into current venv

uv pip install requests pandas numpy

Install from requirements.txt

uv pip install -r requirements.txt

Run a script with auto-managed dependencies

uv run --with requests --with beautifulsoup4 script.py

Run a script with inline dependencies (PEP 723)

uv run script.py

Where script.py has:

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests", "rich"]
# ///

Initialize a new Python project

uv init myproject
cd myproject
uv add requests

Add a dependency to pyproject.toml

uv add fastapi uvicorn

Add a dev dependency

uv add --dev pytest pytest-cov

Lint Python code with JSON output

ruff check --output-format json .

Lint and show only errors (no warnings)

ruff check --select E .

Auto-fix all fixable lint issues

ruff check --fix .

Format Python code

ruff format .

Check formatting without changing files

ruff format --check .

Lint specific rules (e.g., unused imports + isort)

ruff check --select F401,I .

Pipelines

New project → install deps → lint → format

uv init myproject && cd myproject
uv add requests fastapi
ruff check --fix .
ruff format .

Each stage: uv scaffolds project and installs deps, Ruff fixes lint issues, Ruff formats code.

Lint → count issues by rule

ruff check --output-format json . | jq 'group_by(.code) | map({rule: .[0].code, count: length}) | sort_by(-.count)'

Each stage: Ruff lints to JSON, jq aggregates issue counts by rule code.

Install from lockfile → run tests

uv sync && uv run pytest -v

Each stage: uv installs exact locked dependencies, runs pytest in the managed environment.

Prefer Over

• Prefer uv over pip / pip3 for package installation — 10-100x faster, better dependency resolution
• Prefer uv over python -m venv for virtual environments — faster creation, better Python version management
• Prefer Ruff over black + flake8 + isort — single tool replaces all three, 10-100x faster
• Prefer uv run over global installs for one-off scripts — isolated environment, no pollution

Do NOT Use When

• Project uses poetry or pdm with an existing lockfile — respect the existing toolchain, don't switch mid-project
• Project has a Makefile or justfile with established lint/format commands — use those instead
• Need to publish to PyPI — uv can build but twine or flit may be expected by the project