GitHub Readme Stats: Dynamic GitHub Profile Cards
/github-readme-stats
GitHub Readme Stats turns a GitHub username into an SVG card of commits, stars, and pull requests you can drop straight into a profile README. The cards themselves still work well and render fast, but the project carries a stop-sign in its own README: it's no longer maintained, and the maintainers point you to a fork instead. Treat it as a snapshot of a good idea rather than a tool to build new automation on.
Dynamically generated GitHub profile stat cards
GitHub Readme Stats is a serverless API that generates SVG cards showing a GitHub user's stats, top languages, or pinned repos, meant to be embedded as an image in a markdown README. You point an <img> tag at an endpoint like api/pin or api/top-langs with a username query parameter, and the service returns a rendered card on the fly. It also renders WakaTime coding-time cards and GitHub Gist pins using the same URL-parameter approach.
Available card types and what they track
- ✓Stats card with commits, stars, PRs, issues, and follower counts, where individual stats can be hidden or added via the &hide= and &show= query parameters.
- ✓A letter-grade rank (S through C) computed from a weighted percentile across commits, PRs, reviews, issues, stars, and followers, using the exponential and log-normal distributions — the exact formula lives in src/calculateRank.js.
- ✓Top Languages card with five layout options — normal, compact, donut, donut-vertical, and pie — plus size_weight/count_weight parameters to rank by bytes, repo count, or a mix.
- ✓Pin cards for repos beyond GitHub's own 6-pin limit, and separate Gist pin cards, both driven by the same api/pin and api/gist endpoints.
- ✓A WakaTime card for coding-time stats, pulled from a public WakaTime profile.
- ✓Built-in theme presets (dark, radical, merko, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, dracula, and more) plus per-element hex color overrides.
- ✓Card text ships in a long list of locales beyond English, selectable with a single &locale= parameter.
Adding stats cards to your GitHub README
Embedding a card is one line of markdown: an image tag pointed at https://github-readme-stats.vercel.app/api?username=yourname, swapped for api/top-langs, api/pin, or api/gist depending on which card you want. Every visual property is a query-string parameter, not a config file — add &show_icons=true for icons, &theme=dracula (or radical, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, merko) for a built-in palette, or hand-pick title_color, text_color, icon_color, bg_color, and border_color as hex values for a custom look. Layout has its own switches too: the Top Languages card takes &layout=compact, donut, donut-vertical, or pie, and &size_weight / &count_weight let you rank languages by byte count, repo count, or a blend of both. For automatic dark/light switching without JavaScript, GitHub's own #gh-dark-mode-only / #gh-light-mode-only URL suffix or a <picture> element with prefers-color-scheme does the job, or you can just use the built-in transparent theme.
Deploying your own instance for reliability
The public instance at github-readme-stats.vercel.app is shared infrastructure, not something you provision — the README calls it best-effort and warns it can slow down or fail under rate limits and traffic spikes. Self-hosting means forking the repo and deploying it to your own Vercel project (or another host) with your own GitHub API token as an environment variable, which also makes your private-repo stats available, since the public instance only ever reads public ones. You can set a CACHE_SECONDS environment variable on your own deployment to refresh cards more often than the built-in defaults (24 hours for the stats card, 6 days for top languages, 10 days for pin cards, 2 days for gist cards). The alternative the maintainers point to is generating cards through a GitHub Actions workflow straight into your profile repository, which sidesteps a live endpoint entirely.
Strengths
- ✓Getting a first card live takes zero backend code — one markdown image line hitting the public instance and you have a working stats card immediately; self-hosting only becomes necessary later, for private repos or reliability.
- ✓Customization runs deep: hex colors for every card element, five language-card layouts, a long list of stats toggles, and translated card text in many locales.
- ✓The rank/percentile math is documented and points straight at the source file that implements it, rather than being a black box you have to trust.
- ✓One project covers more than plain stats — repo pins past GitHub's 6-pin limit, Gist pins, and a WakaTime card, all through the same URL-parameter pattern.
Known limitations and caveats
- △The project is explicitly marked no longer maintained in its own README, with users redirected to a third-party fork.
- △The shared public Vercel instance is described by the maintainers themselves as best-effort and prone to slowdowns or failures during rate-limit spikes.
- △Private-repo and private-org stats never show up unless you self-host with your own token — the hosted endpoint only reads public data.
- △The Top Languages card only looks at your first 100 non-forked repositories and can't see language usage from commits you made in other people's repos, both acknowledged as GitHub API limitations in the docs.
- △New theme submissions are no longer accepted — the maintainers paused adding themes to cut maintenance work, so you're limited to the existing built-in set (or manual color overrides).
Active alternatives and the maintained fork
Frequently asked questions
GitHub Readme Stats is no longer maintained — its own README carries a notice saying the repository is archived and pointing users to GitHub Stats Extended, an actively maintained fork with additional features, as the successor project.
GitHub Readme Stats only reads public repository data on its shared public instance. To include private repositories, you need to deploy your own instance (for example on Vercel) using your own GitHub API token, which the service then uses to fetch your private stats directly.
The public GitHub Readme Stats instance at github-readme-stats.vercel.app is shared by everyone embedding a card, and the maintainers describe it as best-effort — it can slow down or fail during rate-limit pressure or traffic spikes. Caching helps, but self-hosting your own instance is the fix the README recommends for reliability.
Self-hosting GitHub Readme Stats means forking the repository and deploying your own copy to Vercel (or another Node-friendly host) with your own GitHub API token set as an environment variable. That gives you your own rate limit, access to private repos, and a CACHE_SECONDS variable to control how often cards refresh.
GitHub Stats Extended is the actively maintained fork that GitHub Readme Stats' own README now recommends switching to, described as adding features and improved stability on top of the original, archived project. GitHub Readme Stats itself is no longer receiving updates.
GitHub Readme Stats offers several client-side methods for switching themes: employ the built-in transparent theme, configure bg_color to utilize a color with a transparent alpha channel, append to the image URL GitHub's #gh-dark-mode-only or #gh-light-mode-only tag, or implement an HTML <picture> element that uses the prefers-color-scheme media feature.
The problem it solves
Markdown READMEs are static text — they can't run code or hit an API on their own, so there's no native way to show a live commit count or a rank badge that updates itself. GitHub Readme Stats solves that specific gap for one surface: the special profile-repository README GitHub renders on a user's profile page, where a stale wall of text is the alternative to a generated image that a server refreshes on each request.
Best use cases
- •Adding a live stats card to a personal GitHub profile README instead of a static bio.
- •Pairing a WakaTime card with a stats card to show both GitHub activity and actual coding time on one profile.
- •Pinning more repositories than GitHub's own 6-slot limit allows.
- •Dropping a top-languages donut or pie chart into a README to visualize a tech stack at a glance.
Who should try it — and who should skip
Worth wiring up if you already have a GitHub profile README and want a stats card without writing a backend — paste a markdown line, pick a theme, and you're done. The catch is real: this specific repo is unmaintained. Skip it, or at least don't build anything you depend on around it, if you need guaranteed uptime, private-repo numbers straight from the public endpoint, or ongoing bug fixes — for any of those, go straight to self-hosting or to the actively maintained fork the README itself recommends.
Related repositories
Is github-readme-stats worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of github-readme-stats.