pytest-local-badge

Our badges:

Session badges (regenerated every pytest run):

Package-metadata badges (rendered from the installed dist's classifiers / METADATA)

Custom

Self-hosted pytest & package badges — tests, coverage, skipped, xfailed, warnings, duration, last-run, plus version/python/license/maturity/os and more pulled straight from your installed dist's metadata. No shields.io, no Codecov, no third-party uptime to depend on — just SVG files committed alongside your code.

Why?

Shiny badges in your README are great. But the usual recipe — a hosted shield service reading numbers from a hosted CI provider — falls apart the moment you:

• Work on a private repo the badge service can't see.
• Run on internal CI behind a VPN.
• Don't want a third-party SVG endpoint loading every time someone opens your README.
• Want badges that work offline (think air-gapped environments, local docs builds, PDFs).

pytest-local-badge skips the round-trip. Every test run regenerates plain SVG files next to your source. Commit them. Reference them with a normal relative path. Done.

Install

Just the test-count badge:

pip install pytest-local-badge

With the coverage badge (pytest-cov pulled in automatically):

pip install "pytest-local-badge[cov]"

Quick start

Tell pytest where to drop the SVGs:

pytest --cov=my_package --local-badge-output-dir=badges/

You'll get:

badges/
├── tests.svg       # e.g. "tests | 142"  (or "139/142" if some fail)
├── coverage.svg    # e.g. "coverage | 87%"
├── skipped.svg     # e.g. "skipped | 3"
├── xfailed.svg     # e.g. "xfailed | 1"
├── warnings.svg    # e.g. "warnings | 0"
├── duration.svg    # e.g. "duration | 4.2s"
└── last-run.svg    # e.g. "last run | 2026-03-14 09:26 UTC"

All seven session badges are generated by default; narrow the set with --local-badge-generate (see below).

Package metadata badges

Pass --local-badge-package=YOUR_DIST to also render badges sourced from the installed distribution's metadata (importlib.metadata):

pytest --local-badge-output-dir=badges/ --local-badge-package=my_package

That adds (when the corresponding classifier / metadata field is present):

badges/
├── my-package-version.svg           # e.g. "version | 1.2.3"        (md["Version"])
├── my-package-python.svg            # e.g. "python | 3.10 | 3.11"   (Programming Language :: Python :: X.Y classifiers)
├── my-package-requires-python.svg   # e.g. "python | >=3.10"        (md["Requires-Python"])
├── my-package-implementation.svg    # e.g. "implementation | CPython | PyPy"
├── my-package-license.svg           # e.g. "License | MIT"          (License :: ... classifier)
├── my-package-maturity.svg          # e.g. "status | beta"          (Development Status :: N - ...)
├── my-package-framework.svg         # e.g. "framework | Pytest"     (Framework :: X)
├── my-package-os.svg                # e.g. "OS | Linux | MacOS"     (Operating System :: ... classifiers; "OS Independent" wins if set)
├── my-package-typed.svg             # only if `Typing :: Typed` is set
└── my-package-private.svg           # only if `Private :: Do Not Upload` is set

Repeat the flag for more than one distribution — each gets its own set of files, prefixed with the PEP 503-canonical name:

pytest --local-badge-output-dir=badges/ \
       --local-badge-package=my_lib \
       --local-badge-package=my_cli

Disable any of them by listing only the ones you want via --local-badge-generate:

# Get version + license, skip the python-versions enumeration in favour of Requires-Python:
pytest --local-badge-output-dir=badges/ \
       --local-badge-package=my_package \
       --local-badge-generate status cov version license requires-python

Then in your README.md:

![Tests](badges/tests.svg)
![Coverage](badges/coverage.svg)
![Skipped](badges/skipped.svg)
![XFailed](badges/xfailed.svg)
![Warnings](badges/warnings.svg)
![Duration](badges/duration.svg)
![Last run](badges/last-run.svg)

<!-- if you used --local-badge-package=my_package -->
![Version](badges/my-package-version.svg)
![Python](badges/my-package-python.svg)
![License](badges/my-package-license.svg)
![OS](badges/my-package-os.svg)

Custom badges (--local-badge-custom)

Sometimes you want a badge for a value that isn't a pytest stat or a classifier — a git commit, a deploy timestamp, an arbitrary number computed by a CI step. Three input channels feed the same LABEL | MESSAGE shape, designed to be glued together in shell scripts:

# 1. CLI — repeatable, simplest for one-offs and loops:
pytest --local-badge-output-dir=badges/ \
       --local-badge-custom "commit=$(git rev-parse --short HEAD)" \
       --local-badge-custom "branch=$(git rev-parse --abbrev-ref HEAD):lightgrey" \
       --local-badge-custom "deployed=2026-06-08T14:32 UTC"

The syntax is LABEL=MESSAGE[:COLOR]. The trailing :COLOR is parsed only when COLOR is a known palette name (brightgreen, green, yellowgreen, yellow, orange, red, lightgrey, blue) or a #hex literal — otherwise it's part of the message. So deployed=2026-06-08T14:32:00Z keeps the timestamp intact; the colour defaults to blue.

# 2. File — JSON list or JSONL (auto-detected). Best for CI scripts
#    that generate many badges:
pytest --local-badge-output-dir=badges/ --local-badge-custom-file=badges/custom.json

[
  {"label": "commit", "message": "abc1234"},
  {"label": "deploy", "message": "2026-06-08T14:32 UTC", "color": "yellow"},
  {"label": "build SHA", "message": "abc1234", "color": "#ff8800", "slug": "sha"}
]

…or the JSONL form, which is friendlier to append-driven CI scripts (jq -nc ... >> file.jsonl in a loop):

# comments and blank lines are skipped
{"label": "commit", "message": "abc1234"}
{"label": "deploy", "message": "2026-06-08T14:32 UTC", "color": "yellow"}

The parser tries json.loads over the whole file first; on JSONDecodeError it falls back to line-by-line.

# 3. Environment variables — drop into a GitHub Actions `env:` block
#    with zero CLI changes:
PYTEST_LOCAL_BADGE_CUSTOM_COMMIT=abc1234 \
PYTEST_LOCAL_BADGE_CUSTOM_BUILD_SHA="def5678:#ff8800" \
   pytest --local-badge-output-dir=badges/

The PYTEST_LOCAL_BADGE_CUSTOM_<LABEL> prefix is stripped, the rest is lowercased and _ → -, so ..._BUILD_SHA becomes label build-sha (and file build-sha.svg).

Merge order: env → file → CLI. The same slug from a later source overrides the earlier one — handy when a file holds your defaults and you want one CLI override per-run.

Empty messages are skipped silently by default — lets --local-badge-custom "commit=$(git rev-parse --short HEAD 2>/dev/null)" work in tarball checkouts where the subshell returns empty. Pass --local-badge-custom-strict to flip that to a hard error in CI.

Reserved labels (tests, coverage, skipped, xfailed, warnings, duration, last-run) can't be used — they would silently overwrite the built-in session badges. Use the file form's slug field if you need to rename around a collision.

Make it permanent

Add it to your pyproject.toml so every pytest run keeps the badges in sync:

[tool.pytest.ini_options]
addopts = "--cov=my_package --local-badge-output-dir=badges/"

…and commit the badge directory. The diff is tiny (an SVG only changes when the numbers change) and lives forever in your repo's history.

Command-line options

--no-local-badge                 Disable the plugin for this run.
--local-badge-output-dir DIR     Where to write the SVGs. (Required to activate.)
--local-badge-generate {cov,duration,framework,implementation,last-run,
                        license,maturity,os,private,python,requires-python,
                        skipped,status,typed,version,warnings,xfailed} [...]
                                 Which badges to generate. Defaults to all of them.
                                 Package-metadata badges (version, python, license,
                                 maturity, framework, implementation, typed, private,
                                 requires-python, os) only fire when --local-badge-package
                                 is also set.
--local-badge-package PACKAGE    Installed distribution name to read metadata from.
                                 Repeat the flag for more than one package.
--local-badge-custom 'LABEL=MESSAGE[:COLOR]'
                                 Render an arbitrary 'LABEL | MESSAGE' badge.
                                 Repeatable. Trailing ':COLOR' must be a palette
                                 name or `#hex`; otherwise the whole value is the
                                 message and colour defaults to blue.
--local-badge-custom-file PATH   Read custom badges from a JSON list or JSONL file
                                 (auto-detected). Repeatable.
--local-badge-custom-strict      Treat empty MESSAGE values as errors rather than
                                 silently skipping them.
--local-badge-duration-max SECONDS
                                 Duration "budget" for the `duration` badge. When
                                 set, colour thresholds scale proportionally — e.g.
                                 `--local-badge-duration-max=60` gives brightgreen
                                 ≤ 6 s, orange ≤ 60 s, red > 60 s. Without it, the
                                 default absolute scale applies.

Badge colour scale

Most badges colour-grade by ratio (pass rate, coverage, or skipped/xfailed fraction of the suite). warnings and duration use absolute thresholds instead — see the Supported badges table. The ratio scale:

"No data" is reserved for genuinely missing input (no tests collected, pytest-cov produced no report) — a real 0% renders red, not grey.

Supported badges

Session badges (always on)

These read from the live pytest session, no extra flags required.

Package-metadata badges (opt in with --local-badge-package)

Read from the installed distribution's METADATA via importlib.metadata. Each file is prefixed with the package's canonical name, e.g. my-package-version.svg. Badges only render when the underlying classifier / field is actually present — no empty placeholders.

Pick which ones to render with --local-badge-generate, e.g.:

# Just the basics, no package badges:
pytest --local-badge-output-dir=badges/ --local-badge-generate status cov warnings

# Session badges plus version + license for the installed dist:
pytest --local-badge-output-dir=badges/ \
       --local-badge-package=my_package \
       --local-badge-generate status cov version license

By default all badges are listed under --local-badge-generate. Session badges always run when the plugin is active; package badges additionally require --local-badge-package to be set.

How it compares

If you're already happy with a hosted service, keep using it. If "another SaaS dependency for a handful of SVGs" feels excessive — this plugin is for you.

Contributing

Issues and PRs welcome: https://github.com/IljaOrlovs/pytest-local-badge

git clone https://github.com/IljaOrlovs/pytest-local-badge
cd pytest-local-badge
pdm install

# Measure coverage of the plugin itself, then regenerate the committed
# badges with that data. We need `coverage run` (not just `pytest --cov`)
# because the plugin is imported by pytest *before* pytest-cov starts
# measuring, which would otherwise leave module-level code uncounted.
# CI enforces 100% via `--fail-under=100`.
pdm run coverage erase
pdm run coverage run -m pytest
pdm run coverage combine
pdm run coverage report -m --fail-under=100
# Pipe the same data into pytest-cov so the coverage badge reflects the
# real 100%, not the partial number you'd get from `pytest --cov` alone.
pdm run pytest --cov=pytest_local_badge --cov-append

pdm run ruff check ./src ./test
pdm run pyright

Acknowledgements

The bundled verdana_11px_normal.json character-width table comes from anafanafo (MIT). It's the same table shields.io uses to size their badges, so locally generated badges line up visually with their hosted siblings. See NOTICE for attribution details.

License

MIT — see LICENSE.