badgie illustration


What is Badgie?

Badgie adds badges to your project. 'Nuff said!

How to Badgie

Install Badgie:

pip install badgie

Add Badgie tags:

<!-- BADGIE TIME -->

Run Badgie:

badgie -w

Listen to what Badgie has to say:

$ badgie -w
Hi, I'm Badgie! Let's add some badges! 🐦

- adding a pre-commit-enabled badge
- adding a brettops-tool badge
- adding a gitlab-latest-release badge
- adding a gitlab-coverage-report badge
- adding a gitlab-pipeline-status badge
- adding a code-style-black badge
- adding a code-style-prettier badge

That's like 7 badges! Good job! 🐦

Check your README. It's now overrun with badges. Too many badges to handle:

<!-- BADGIE TIME -->

[![brettops tool](](
[![pipeline status](](
[![coverage report](](
[![latest release](](
[![code style: black](](
[![code style: prettier](](


They look like this:

brettops tool pipeline status coverage report latest release pre-commit code style: black code style: prettier

You just got badged by Badgie!

Why Badgie?

Adding badges to repositories is frustrating. It takes so much fiddling to get them set up, and you have to do it over and over again for every repository you create. Because of this, many projects don't have badges and probably never will.

The thing is, the whole internet WANTS you to have badges:

  • Badges let you know what's going on with a project at a glance,

  • They let others know that you care about your project, and

  • They just look awesome!

Don't worry. You don't have to live without badges anymore. Now there's Badgie!

How does Badgie work?

Badgie is different because Badgie doesn't like asking for anything.

Starting from your project's working directory, Badgie attempts to reconstruct what your repository is, where it came from, and what information is interesting about it:

  • Badgie sifts through files, URLs, and anything else, and returns a list of findings.

  • Badgie matches findings to badges it knows about, and returns badges unique to your project.

  • Badgie adds more badges as your project grows or Badgie learns more.

  • Badgie also keeps existing badges fresh!

What badges does Badgie badge?

Visit the Badges page to see all the badges Badgie knows about.

Pre-commit hook

Badgie has a pre-commit hook, so you can get fresh badges on every commit.

Add the following to a .pre-commit-config.yaml file. Note the empty rev tag:

  - repo:
    rev: ""
      - id: badgie

Run pre-commit autoupdate to pin to the latest version:

pre-commit autoupdate

Run pre-commit directly or install as a hook:

# directly

# as a Git hook
pre-commit install
git commit -m "..."


Badge style

Badgie keeps up with the trends and knows that not everyone likes the flat style. Badgie supports any style supported by Simply pass the -s / --style option when calling Badgie:

badgie -w -s for-the-badge

Now your badges are more different:

brettops tool pipeline status coverage report latest release pre-commit code style: black code style: prettier

Thanks, Badgie!

Badgie caveats

Badgie makes decisions on the assumption that you do sensible things with your repository structure. It does not try to work around bad practices.


Visit the GitLab repo.


Badgie would not be possible without and their high quality, omnipresent, infinitely customizable badges.

Badgie's file detection code was inspired by the identify library.