which-profiler 0.1.0

Which Python profiler fits your workload? Filter by focus, attach mode, and more; get a runnable command.

which-profiler

Which Python profiler fits your workload? Filter by focus, attach mode, and more; get a runnable command.

What it does

A filtered catalog: describe your workload (what you care about, attach vs launch, target Python) and which-profiler narrows the options and ranks the profilers by measured overhead. Each entry prints a copy-paste-runnable uv-based command & useful information.

Install

uvx which-profiler            # run without installing
uv tool install which-profiler

Only runtime dependency is typer. Runs on Python 3.10+.

Usage

which-profiler                          # interactive: one question, ranked catalog
which-profiler --nosy                   # interactive: also asks attach/python/native/view/rate
which-profiler --all                    # full landscape (incompatible tools tagged, not hidden)
which-profiler --focus time --python 3.15
which-profiler pytest                   # bare console-command target
which-profiler python -m my_module      # same, python-invocation form
which-profiler --focus memory -- script.py --arg   # script target after --
which-profiler --pid 12345              # attach-capable tools only
which-profiler --tool py-spy pytest     # exactly this tool (py-spy or py_spy both work)
which-profiler --focus time --view flamegraph --run pytest   # build + run top pick
which-profiler --focus time --json      # machine-readable, no prompts

The talk

Come see "uvx which-profiler: Which Profiler, When?" at EuroPython 2026:

EuroPython 2026, Kraków

📍 Room S2

📅 Wednesday, 15 July 2026

🕐 15:25

👉 https://ep2026.europython.eu/session/uvx-which-profiler-which-profiler-when/

Potential profilers to include in the future

• line_profiler
• Austin
• Yappi
• Fil
• Guppy3

Development

Setup via mise:

mise run install

mise run fix
mise run check
mise run test       # uv run pytest in dev venv (.venv, pinned to .python-version)
mise run test-all   # full matrix: root tests on 3.10-3.15 + examples tests on 3.14

test-all runs scripts/test-matrix.sh, which tests each supported Python in its own isolated venv under .venvs/py<version>/ (gitignored) so the shared dev .venv is never resynced to a different interpreter. It prints a python -> pass/fail/skip summary table at the end; 3.15 (still prerelease) degrades a dependency-install failure to a recorded skip instead of a hard failure.

Where the numbers come from

Overhead ranking is based on a benchmark from 2026-07-13: ThinkPad X1 Carbon Gen5, all samplers forced to 100 Hz for parity, median-of-7 repeats, over a tight numeric loop and a call-dense workload. The CLI (and --json) only show the coarse category (negligible/low/moderate/high); reproducible scripts and further measurements will come later.