Live stats cards are one of the most popular profile README additions. They're images generated on the fly from your public GitHub data, so they update themselves without you editing the README. This guide covers the most widely used cards, how to customise them, and what to do when one breaks.
In every example, replace YOUR_USERNAME with your GitHub username.
Note: the public github-readme-stats instance (github-readme-stats.vercel.app) is currently paused by its host, so its stats, top-languages and pin cards show as broken images. Self-host it (see below) or use MakeReadme's own cards, which the generator adds for you:<img src="https://makereadme.prabathoff.workers.dev/api/stats?user=YOUR_USERNAME&theme=tokyonight" alt="GitHub stats" height="165" />
<img src="https://makereadme.prabathoff.workers.dev/api/top-langs?user=YOUR_USERNAME&theme=tokyonight" alt="Top languages" height="165" />
<img src="https://makereadme.prabathoff.workers.dev/api/pin?repo=OWNER/REPO&theme=tokyonight" alt="Repository" />GitHub stats card
From the open-source github-readme-stats project. It shows total stars, commits, pull requests, issues and contributions, with a rank:
<img src="https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=tokyonight&hide_border=true" alt="GitHub stats" height="165" />Useful options:
theme=:tokyonight,radical,dracula,github_dark,onedark,gruvbox,defaultand many more.show_icons=trueadds icons next to each stat.hide_border=trueremoves the outline, which looks cleaner on both GitHub themes.hide=hides specific stats, e.g.hide=issues,contribs.count_private=trueincludes private contributions. GitHub only exposes them if you've enabled Private contributions on your profile's contribution graph.
Top languages card
From the same project, it shows which languages make up most of your public code:
<img src="https://github-readme-stats.vercel.app/api/top-langs/?username=YOUR_USERNAME&layout=compact&langs_count=8&theme=tokyonight&hide_border=true" alt="Top languages" height="165" />layout=compact is the tidiest. Use exclude_repo= to leave out forks of large projects or generated code that would skew the result.
Putting two cards side by side
Give both images the same height and wrap them in a centred paragraph:
<p align="center">
<img src="https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=tokyonight&hide_border=true" alt="Stats" height="165" />
<img src="https://github-readme-stats.vercel.app/api/top-langs/?username=YOUR_USERNAME&layout=compact&theme=tokyonight&hide_border=true" alt="Languages" height="165" />
</p>On narrow screens such as the GitHub mobile app, they wrap onto two lines automatically.
Contribution streak
GitHub Readme Streak Stats shows your current streak, longest streak and total contributions:
<img src="https://streak-stats.demolab.com/?user=YOUR_USERNAME&theme=tokyonight&hide_border=true" alt="GitHub streak" />Trophies
github-profile-trophy awards trophies for stars, commits, followers and more:
<img src="https://github-trophies.vercel.app/?username=YOUR_USERNAME&theme=flat&no-frame=true&row=1&column=7" alt="Trophies" />row and column control the grid. A single row of six or seven fits most layouts.
Contribution graph
Show your year of activity as a coloured grid, with any hex colour in the path:
<img src="https://ghchart.rshah.org/F97316/YOUR_USERNAME" alt="Contribution graph" width="100%" />Repository pin cards
Show a featured repository as a card with its description, language and stars:
<a href="https://github.com/YOUR_USERNAME/REPO">
<img src="https://github-readme-stats.vercel.app/api/pin/?username=YOUR_USERNAME&repo=REPO&theme=tokyonight&hide_border=true" alt="REPO" />
</a>Profile view counter
<img src="https://komarev.com/ghpvc/?username=YOUR_USERNAME&label=PROFILE+VIEWS&color=F97316&style=flat-square" alt="Profile views" />It counts every time the image loads, so treat the number as a rough indicator rather than unique visitors.
When a card won't load or won't update
The image is broken or shows an error
These services are free, public deployments, and they're used by a huge number of profiles. They sometimes hit GitHub API rate limits or their host's usage limits, and cards fail until the limit resets. Options:
- Wait and try again. Most outages are temporary.
- Self-host. github-readme-stats, streak stats and the trophy project can all be deployed to your own free Vercel account with your own GitHub token. You then use your deployment's URL instead of the public one. Each project's README has a one-click deploy guide.
- Keep a text fallback: a sentence about your work still reads well if an image is missing.
The numbers are out of date
GitHub serves README images through its caching proxy, and the cards themselves cache results for a few hours to save API calls. Updates usually appear within a day. github-readme-stats accepts a cache_seconds parameter on self-hosted deployments.
The numbers look too low
By default only public activity counts. Enable private contributions on your profile, and remember that commits only count if they're made with an email address linked to your GitHub account.
Design tips
- Pick one theme and use it for every card. Mixed themes look messy.
hide_border=trueblends cards into both light and dark GitHub. - Two or three cards are plenty. Your projects should still be the focus.
- Check your profile on GitHub's mobile app too.
💡 The MakeReadme generator adds matching stats, languages, streak, trophies and graph cards in one theme, with a live preview. Try it →
Want a bigger picture of your year? Try GitHub Wrapped.
