GitHub README Badges: The Complete Guide

Badges are the small status indicators at the top of a README that communicate project health at a glance. They show build status, test coverage, latest version, licence, and more. Here is how to add them to your project.

What badges communicate

Badges tell visitors three things without them reading a single paragraph: the project is actively maintained, the tests pass, and the code meets quality standards. A row of green badges builds trust immediately.

Essential badges for any project

Build status

Show whether your CI pipeline is passing. Most CI providers generate a badge URL automatically.

![Build Status](https://github.com/your-username/your-repo/actions/workflows/ci.yml/badge.svg)

npm / PyPI version

Show the latest published version so users know what to install.

![npm version](https://img.shields.io/npm/v/your-package)
![PyPI version](https://img.shields.io/pypi/v/your-package)

Licence

Make the licence visible without scrolling to the bottom.

![Licence](https://img.shields.io/github/license/your-username/your-repo)

Test coverage

Show that your code is tested. Integrates with Codecov, Coveralls, or similar.

![Coverage](https://img.shields.io/codecov/c/github/your-username/your-repo)

Creating custom badges with shields.io

Shields.io lets you create badges for anything using a simple URL pattern:

https://img.shields.io/badge/{label}-{message}-{color}

For example, a badge showing your project uses TypeScript:

![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)

Styles

Shields.io supports several visual styles. Append ?style= to the URL:

• flat (default) — clean and simple:
• flat-square — squared corners:
• for-the-badge — larger, bolder text:
• plastic — 3D appearance:

Organising badges in your README

Place badges immediately after your project title, before the description. Group related badges together and keep the total count under 8 — too many badges create visual noise.

# My Project

![Build](https://...) ![Coverage](https://...) ![Version](https://...) ![Licence](https://...)

One-line project description here.

Dynamic badges

Shields.io can pull data from JSON endpoints, letting you create badges that update automatically. This is useful for showing metrics like downloads, stars, or custom KPIs.

https://img.shields.io/badge/dynamic/json?url=YOUR_URL&query=$.field&label=Label

Generate a README with badges included

ReadmeBot can generate a complete README for your repository that includes relevant badges based on your CI provider, package registry, and licence file. No need to look up badge URLs manually.

Works with JavaScript, Python, Rust, Java, and 20+ other languages.