README Coverage Badger

Generates a coverage badge using and the service. Your README file is then updated with the generated badge.

automatically generates your project's coverage badge using the service, and then updates your README


There are so many excellent coverage badge generation tools out there, why do we need another one? Well, at the time of writing this package (circa early 2021), all the existing tools (for example, coverage-badge) I had come across ended at generating SVG/PNG files/strings/Base64 images. What you do with this remains entirely up to you.

Now, it is often much easier to simply use online services such as and These services are free for open source projects, but require a monthly subscription for private repos. Many times, we work on private repos, and we wanna be able to automatically have coverage badges in our READMEs. What if you are unable to pay such subscription fees, or maybe you don't want to use a SaaS? Your solution becomes to generate your own badge!

This is where this project comes in. It automatically generates your project's coverage badge using the service, and then updates your README accordingly, in just one command! That's all it does, resonating with the Unix philosophy of doing one thing and doing it well. The main idea for this came from istanbul-badges-readme, which does exactly the same thing for JavaScript projects. You will see that these two projects have quite a lot in common.

After using istanbul-badges-readme, I searched for a python alternative but couldn't find anything suitable. The closest I found was coverage-badge, and if you look at this project's code, you will see a lot of similarities with coverage-badge!

If what you're looking for is a powerful, general purpose badge generation tool for your projects, then you should probably check out projects like anybadge and genbadge.


  • automatically generates your project's coverage badge using the service, and then updates your project's README with the newly generated badge
  • simple CLI tool (readme-cov) with helpful messages
  • tested on python 3.6 to 3.9 with coverage ≥ 84%
  • free software: BSD-3-Clause license
  • generates different colours depending on the coverage percentage. Optionally generate plain colour (green) regardless of percentage
  • minimal external dependencies – this tool only has 2 external dependencies; (obviously!) and colorama (for cross-platform coloured terminal output)


pip install readme-coverage-badger


Note: Before using the tool, ensure that you insert a string of the form ![Code Coverage]() or ![Code Coverage](anything here) in your project's README.

readme-cov [-h] [-v] [-p]

optional arguments:
  -h, --help     show the help message and exit
  -v, --version  show program's version number and exit
  -p, --plain    Plain colour mode. Standard green badge.

The tool operates on the basis of the following assumptions:

  • you have a or README file at the root of your project
  • your README file is in markdown format. I know, some Pythonistas prefer restructuredtext! Sadly, this isn't supported (yet)
  • Somewhere in your your README is a string in the form: ![Code Coverage]() or ![Code Coverage](anything here). This is what gets updated in-place (using re.sub()) when the script runs.
  • the script is called from the root of your project repo, which has already configured, and the coverage already updated (you have already run your tests prior to running the script)
  • If the coverage badge in your README file is already up to date, your README file won't be updated, you will only be notified