Guide · Open source
How to use github-readme-stats: embed a GitHub stats card
Updated · written with AI from the project's own documentation and checked against our catalogue data
github-readme-stats is an open-source project that generates small images of GitHub statistics, such as stars, commits, pull requests and issues, for any username. You add a link to the image in your profile README and it updates as the stats change. This guide shows you how to embed a card, customise which stats appear, and what to know before relying on it.
GitHub Readme Statsanuraghazra/github-readme-stats · ★ 79.9k · MIT Install options & downloads Quick start
- 1Open your profile README. Go to the repository named after your username and edit the README.md file.
- 2Paste the card markdown. Add the image markdown from this guide and replace the username with yours.
- 3Choose which stats to hide or show. Append &hide= or &show= with comma-separated values to the URL.
- 4Enable icons if you want them. Add &show_icons=true to the query string.
- 5Commit and check the preview. Save the change and view your profile to confirm the card renders.
- 6Self-host for reliability or private stats. Clone the repository and deploy your own instance with a GitHub token if you need private data or more reliable output.
Add a GitHub stats card to your profile README
Copy the markdown below into your profile README and change the username value to your own GitHub username. The card is an image served from the project's public API, wrapped in a link back to the project.
[](https://github.com/anuraghazra/github-readme-stats)Hide or show individual stats
Use the hide parameter to remove specific stats from the card. Pass a comma-separated list after &hide=. To add extra stats, use the show parameter in the same way.
- Hide options: stars, commits, prs, issues, contribs
- Show options: reviews, discussions_started, discussions_answered, prs_merged, prs_merged_percentage
Turn on icons
Add &show_icons=true to the query string to display icons next to the stats.
Understand what the default card includes
By default the card only counts public repositories. To show private statistics, the project says you need to deploy your own instance with your own GitHub API token. The README also notes that the public Vercel instance is best-effort and can be unreliable because of rate limits and traffic spikes.
Ranks run from S (top 1%) to C (everyone). The rank is based on a weighted percentile across commits, pull requests, reviews, issues, stars and followers, and the circle around the rank shows 100 minus the global percentile.
Deploy your own instance
For reliable cards, or to include private repository statistics, the README recommends self-hosting. The source describes deploying on Vercel or other platforms, and using a GitHub Actions workflow that generates cards inside your profile repository. The first step in the self-hosted route is creating a Personal Access Token (PAT). Clone the project with the command below to get the source.
- Self-hosted on Vercel or another platform
- GitHub Actions workflow in your profile repository
git clone https://github.com/anuraghazra/github-readme-statsCheck the project status before you start
The README states that this repository is no longer maintained. It recommends GitHub Stats Extended, an actively maintained fork with additional features, or GitHub Readme Stats Action. Treat this guide as a reference to how the original tool works, and consider those successors for new setups.
What people use it for
- Showing commit, pull request and issue counts on a GitHub profile README
- Hiding stats you do not want visible, such as contributions or pull requests
- Adding review and merged pull request counts to a profile card
- Generating a stats card through a GitHub Actions workflow in your profile repository
Frequently asked questions
Is github-readme-stats free?
The source material here lists the project licence as MIT. The public instance is provided by the project, and the README describes it as best-effort, so reliability is not guaranteed.
Does github-readme-stats show private repositories?
Not on the default public instance. The README says the default card covers only public repositories, and private statistics require deploying your own instance with your own GitHub API token.
Why is my github-readme-stats card not loading?
The README says the public Vercel instance can be unreliable due to rate limits and traffic spikes. It recommends self-hosting or using the GitHub Actions workflow for reliable cards.
What are the requirements to use github-readme-stats?
For the basic card, you only need a GitHub username and a markdown file such as your profile README. Self-hosting requires deploying a small serverless app with a GitHub token, as the project's guidance describes.
Is github-readme-stats still maintained?
No. The README says the repository is no longer maintained and points to GitHub Stats Extended and GitHub Readme Stats Action as successor projects.
What are alternatives to github-readme-stats?
The README names GitHub Stats Extended and GitHub Readme Stats Action as successors. Other comparable projects listed for this entry are github-stats.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use github-readme-stats if you want to understand how generated GitHub stat cards work or you are comfortable deploying your own small serverless app. Pick GitHub Stats Extended or GitHub Readme Stats Action for a setup that is actively maintained, and for anyone who needs private repository statistics without managing their own deployment.
Install options & downloads