GitHub README badges: which ones are worth adding

Badges are the small status images near the top of a README: build passing, latest version, license. A row of three to five tells a visitor at a glance that the project is maintained, installable and safe to depend on. A wall of fifteen is noise sitting on top of the one paragraph that actually explains the project.

How a badge works

A badge is an image, usually an SVG served from a URL that renders the current value, wrapped in a link to wherever the value can be checked. In Markdown:

[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)

The image URL keeps the value current, and the link lets a skeptical reader verify it. Most badge services, including Shields.io, work this way.

Badges worth adding

• Build status. Every GitHub Actions workflow has a badge at https://github.com/OWNER/REPO/actions/workflows/WORKFLOW.yml/badge.svg. A passing build is the quickest signal that the project still works.
• Latest version. From your registry: https://img.shields.io/npm/v/PACKAGE for npm, https://img.shields.io/pypi/v/PACKAGE for PyPI, https://img.shields.io/crates/v/CRATE for crates.io. It shows the project ships.
• License. https://img.shields.io/github/license/OWNER/REPO. Many companies can’t adopt a dependency until someone has checked this.
• Downloads. https://img.shields.io/npm/dm/PACKAGE for monthly npm downloads. Real usage persuades more than stars, once the number is respectable.
• Test coverage. Codecov and Coveralls both provide one. Worth it when the number is one you are proud of.
• Supply-chain security. The OpenSSF Scorecard badge reports how the repo scores on security practices. It matters more the deeper your project sits in other people’s dependency trees.
• Where to get help. A Discord or Discussions badge tells people a question will get answered somewhere.

Badges to skip

• Star count. A low number advertises low adoption, and GitHub already shows the count at the top of the page.
• Anything that is always red. A failing badge you have stopped fixing is worse than no badge.
• Badges for tools you don’t really use. A code-quality grade you configured once and never looked at again.
• A second row. If the badges wrap onto another line, cut until they don’t, and don’t let them push the one-paragraph pitch off the first screen. See README best practices for the rest of that screen.

README stats cards belong on profiles

Searches for "GitHub README stats" usually mean the cards from projects like github-readme-stats, which show a person’s commits, top languages and streaks. Those belong on your profile README, the special repository named after your username. On a project README they tell visitors about you instead of about the project.

The RepoRanker badge

A repo listed on RepoRanker gets a README badge showing its best first-page position on the board, such as "#4 in Go", and falls back to the star count when it isn’t on a first page. Owners find the Markdown on their repo’s RepoRanker page when signed in with GitHub. It is one of the few badges that tells a visitor where a project stands among others rather than only about itself.

List your repo for free to get the badge.

Related: GitHub README best practices · How to get more GitHub stars · How to promote your GitHub repo.