benchdiff 0.1.0

CLI benchmarking tool with rich terminal output and markdown export.

benchdiff

A CLI benchmarking tool with rich terminal output and markdown export.

Installation

pip install benchdiff

Usage

Create a file named bench_*.py and define a __benchmarks__ list:

# bench_strings.py

words = ["hello", "world", "foo", "bar"]


def concat():
    result = ""
    for w in words:
        result += w


def join():
    "".join(words)


def format_string():
    "%s %s %s %s" % tuple(words)


def fstring():
    f"{words[0]} {words[1]} {words[2]} {words[3]}"


__benchmarks__ = [
    ("String concatenation", [concat, join]),
    ("String formatting", [format_string, fstring]),
]

Run benchmarks:

benchdiff benchmarks/

╭──────────────────────────────── benchdiff ────────────────────────────────╮
│                                                                           │
│   Benchmark                 Min         Median        Max          ×      │
│  ───────────────────────────────────────────────────────────────────────  │
│   String concatenation                                                    │
│     concat                78.333ns     80.833ns     97.750ns    1.711x    │
│     join                  44.250ns     47.250ns     53.125ns    1.000x    │
│   String formatting                                                       │
│     format_string        103.834ns    110.417ns    114.708ns    1.464x    │
│     fstring               75.000ns     75.417ns     76.083ns    1.000x    │
│                                                                           │
│   * times in nanoseconds, lower is better                                 │
│ ───────────────────────────────────────────────────────────────────────── │
│   Python      3.14.2                                                      │
│   Platform    macOS-26.3.1                                                │
│   CPU         Apple M3 Pro                                                │
│   Rounds      5 × 1,000 calls                                             │
│   Date        2026-05-08 10:05:59                                         │
╰───────────────────────────────────────────────────────────────────────────╯

CLI options

benchdiff [PATH] [OPTIONS]

Arguments:
  PATH    Path to search for bench_*.py files [default: .]

Options:
  --repeat    Number of measurement loops [default: 5]
  --times     Number of calls per measurement [default: 1000]
  --markdown  Output as GFM markdown table
  --help      Show this message and exit.

Markdown output

benchdiff benchmarks/ --markdown

Benchmark	Min	Median	Max	×
String concatenation
concat	81.000ns	89.583ns	95.541ns	1.795x
join	43.041ns	49.917ns	50.709ns	1.000x
String formatting
format_string	106.875ns	110.125ns	113.292ns	1.572x
fstring	68.709ns	70.041ns	74.250ns	1.000x

times in nanoseconds, lower is better

Python 3.14.2 · macOS-26.3.1 · Apple M3 Pro · 5 × 1,000 rounds · 2026-05-08 10:05:59