GitHub Readme Stats — User Guide

1. Quick Start

GitHub Readme Stats generates dynamic SVG cards that display GitHub statistics (stars, commits, language usage, pinned repos, gists, WakaTime time-tracking) for embedding directly in your README. Each card is rendered server-side as an SVG and served through five Vercel serverless endpoints. The cards animate on load, support 70+ themes, and respond to a rich set of URL query parameters.

Key features:

• Stats card with rank circle, total stars, commits, PRs, issues, reviews
• Pinned repository card (single repo, with stars, forks, and language)
• Top languages card with five layouts (normal, compact, donut, donut-vertical, pie)
• WakaTime time-tracking card (per-language coding time, two layouts)
• Gist preview card
• 70+ built-in themes including dark, radical, tokyonight, dracula, gruvbox, nord, catppuccin_mocha, github_dark, plus per-element color overrides
• 50+ locales for card titles and stat labels
• Tunable cache control via the cache_seconds query parameter
• Rank algorithm computed in-card (no external rank service)

Prerequisites: any place that renders Markdown and embeds external SVGs (GitHub README, GitLab, GitHub profile, Hashnode, Dev.to, personal site).

One-line usage — embed the stats card for any GitHub username:

![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)

The hosted instance lives at https://github-readme-stats.vercel.app.

Tip

All five card endpoints follow the same shape — https://github-readme-stats.vercel.app/api/<endpoint>?username=<your-handle>. Once you know the parameter pattern you can compose any card variant from the URL alone, no client code required.

What to try next:

• Pick a theme from the catalog in section 4
• Hide stats you don't care about with hide=
• Switch the language card to donut or pie with layout=
• Self-host the API on your own Vercel account if you want unlimited rate

2. Installation

GitHub Readme Stats is consumed in two modes:

1. As a remote SVG — the typical case. You embed an <img> URL in Markdown. No installation, no dependencies. Skip to section 3.
2. As a self-hosted API — fork the repo, deploy to Vercel (or run the bundled Express adapter), set a GitHub Personal Access Token, point your README at your own domain. This section covers that path.

2.1 System requirements

2.2 Self-host on Vercel

Fork + Deploy

# 1. Fork https://github.com/anuraghazra/github-readme-stats on GitHub
# 2. In your fork's Vercel project, set environment variables:
#    PAT_1 = ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 3. Deploy. Vercel auto-detects api/*.js and exposes the endpoints.

Local Express server

git clone https://github.com/anuraghazra/github-readme-stats.git
cd github-readme-stats
npm install
echo "PAT_1=ghp_yourpat" > .env
node express.js

Server running on port 9000

The Express adapter exposes the same five routes under /api:

2.3 Verify your install

curl "http://localhost:9000/api?username=anuraghazra" -o stats.svg
file stats.svg

stats.svg: SVG Scalable Vector Graphics image

If the response says Missing params "username", your route is working but you forgot the query string. If you see No GitHub API tokens found, your .env was not loaded — see section 6.

Important

The official public instance lives at github-readme-stats.vercel.app. It is shared and rate-limited. If your card stops loading on a high-traffic README, host your own — that is the official recommendation in the in-card error secondary message: "You can deploy own instance or wait until public will be no longer limited".

Warning

Tokens must be classic Personal Access Tokens with public_repo scope (or repo for private contributions). The fine-grained token model is not referenced in the source — stick with classic PATs.

2.4 Configuration via environment variables

Self-hosted deployments read the following environment variables:

Note

WHITELIST, GIST_WHITELIST, and EXCLUDE_REPO are split on commas. There is no JSON form; one string, comma-separated, no spaces.

3. Configuration

GitHub Readme Stats has no config file. Every setting is a URL query parameter, applied per card. The full reference is in section 4; here is the minimum you need to think about up front.

3.1 The five endpoints

https://github-readme-stats.vercel.app/api?username=USERNAME
https://github-readme-stats.vercel.app/api/pin?username=USERNAME&repo=REPO
https://github-readme-stats.vercel.app/api/top-langs?username=USERNAME
https://github-readme-stats.vercel.app/api/wakatime?username=USERNAME
https://github-readme-stats.vercel.app/api/gist?id=GIST_ID

Every endpoint returns Content-Type: image/svg+xml. Errors render as a "Something went wrong!" card so your README never breaks.

3.2 Universal options

These parameters work on every card:

Tip

Boolean parameters accept the strings true and false (case-insensitive). Anything else is treated as undefined, falling back to the default. So hide_border=1 will not work — use hide_border=true.

4. Core Usage

4.1 Stats card — /api

The flagship card. Shows a rank circle on the left and a stats column on the right.

![Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)

What it shows by default

• Total Stars Earned
• Total Commits (last year)
• Total PRs
• Total Issues
• Contributed to (last year)

Stats card-specific parameters

Rank algorithm. The rank letter (S, A+, A, A-, B+, B, B-, C+, C) is computed in-card from your commits, PRs, issues, reviews, stars, and followers using a weighted exponential-CDF / log-normal-CDF combination. Weights are: stars 4, PRs 3, commits 2, issues 1, reviews 1, followers 1. The percentile shown when rank_icon=percentile is the same value used to pick the letter.

Recipe — show merged PRs and reviews, hide issues

![Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show=prs_merged,prs_merged_percentage,reviews&hide=issues)

Recipe — count all commits ever, with icons and a custom title

![Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&include_all_commits=true&show_icons=true&custom_title=My+GitHub+Highlights)

Note

include_all_commits=true triggers a separate REST call to https://api.github.com/search/commits (Cloak preview header). It costs an extra GitHub API hit per render and is more likely to rate-limit on high-traffic READMEs.

4.2 Pinned repo card — /api/pin

![Repo](https://github-readme-stats.vercel.app/api/pin?username=anuraghazra&repo=github-readme-stats)

The card uses theme default_repocard if you don't pass theme=. Archived and template repos render a small badge in the top-right.

Warning

Private repositories return User Repository Not found (or Organization Repository Not found). The fetcher explicitly checks isPrivate and refuses to render them regardless of token scope.

4.3 Top languages card — /api/top-langs

![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=anuraghazra&layout=donut)

Layout previews

Tip

When you score a 0% language that you'd rather not show, use hide=html,css (comma-separated, no spaces). Names are matched case-insensitively.

4.4 WakaTime card — /api/wakatime

![Wakatime](https://github-readme-stats.vercel.app/api/wakatime?username=anuraghazra)

The card auto-detects three "no data" states and renders the appropriate text: WakaTime user profile not public, User doesn't publicly share detailed code statistics, or No coding activity this week.

Caution

Free public WakaTime profiles return time data only when the profile is set to public AND "Show code stats publicly" is enabled. Without both, the card renders one of the no-data messages.

4.5 Gist card — /api/gist

![Gist](https://github-readme-stats.vercel.app/api/gist?id=YOUR_GIST_ID)

The card shows the gist's primary language (calculated as the largest file by bytes), star count, and fork count. Description wraps to up to 10 lines; longer text is truncated with ....

4.6 Themes — full catalog

The repository ships 74 built-in themes. Pick by name with ?theme=<name>. Names are case-sensitive.

Light themes: default, default_repocard, transparent, gruvbox_light, solarized-light, buefy, vue, flag-india, graywhite, swift, rose, catppuccin_latte.

Dark themes (popular): dark, radical, merko, gruvbox, tokyonight, onedark, cobalt, cobalt2, synthwave, dracula, prussian, monokai, nord, nightowl, github_dark, github_dark_dimmed, aura_dark, panda, noctis_minimus, aura, apprentice, material-palenight, gotham, bear, ayu-mirage, solarized-dark, darcula, one_dark_pro, rose_pine, catppuccin_mocha, omni, react, holi, neon, blue_navy, calm_pink, calm, discord_old_blurple, outrun, ocean_dark, city_lights, algolia, slateorange, kacho_ga, yeblu, blueberry, chartreuse-dark, vue-dark, shades-of-purple, great-gatsby, vision-friendly-dark, midnight-purple, shadow_red, shadow_green, shadow_blue, jolly, maroongold, highcontrast, codeSTACKr, date_night, moltack, ambient_gradient.

Gradient backgrounds are supported. The theme ambient_gradient ships with a multi-stop gradient. To make your own, set bg_color=<angle>,<color1>,<color2>[,<color3>...] — for example bg_color=90,fffefe,fff,000. The first value is the rotation angle in degrees; the remaining hex codes (no #) are evenly spaced gradient stops.

Note

Issue #4765 tracked an older crash when a non-existent theme name was passed; that was fixed by the current default fallback. If your custom theme name produces a "Something went wrong" card, double-check spelling and capitalization.

5. Common Tasks

5.1 Embed a basic stats card

![GitHub Stats](https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE)

5.2 Side-by-side stats and languages

<a href="https://github.com/YOUR_HANDLE">
  <img height=180 src="https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&theme=tokyonight&show_icons=true" />
  <img height=180 src="https://github-readme-stats.vercel.app/api/top-langs?username=YOUR_HANDLE&theme=tokyonight&layout=compact" />
</a>

The trick is wrapping both <img> tags in a single <a> and pinning equal heights so they line up. Use raw HTML in your README — Markdown image syntax doesn't permit attributes.

5.3 Match your README to a theme

![](https://github-readme-stats.vercel.app/api?username=ME&theme=tokyonight&hide_border=true&bg_color=00000000)

bg_color=00000000 (8-digit hex with alpha 0) makes the card transparent, letting the GitHub README background show through. The shipped transparent theme uses the same trick (bg_color: ffffff00).

5.4 Drop unwanted stats

![](https://github-readme-stats.vercel.app/api?username=ME&hide=issues,contribs)

You can hide any subset of stars, commits, prs, issues, contribs, prs_merged, prs_merged_percentage, reviews, discussions_started, discussions_answered. Hiding everything AND setting hide_rank=true returns a "Could not render stats card" error — there has to be at least one stat or the rank circle.

5.5 Show your TRUE total commit count

![](https://github-readme-stats.vercel.app/api?username=ME&include_all_commits=true)

Default behaviour counts only the last year (GitHub's GraphQL contributionsCollection window). Set include_all_commits=true and the card calls the REST search-commits endpoint to total every commit you've ever authored.

5.6 Show only commits from a specific year

![](https://github-readme-stats.vercel.app/api?username=ME&commits_year=2025)

The card label updates to Total Commits (2025). Combine with hide= to build a clean "annual recap" card.

5.7 Use the rank circle as a percentile

![](https://github-readme-stats.vercel.app/api?username=ME&rank_icon=percentile)

Replaces the letter (S, A+, ..., C) with Top 12.3% — the same percentile the letter is derived from.

5.8 Combine custom colors with a theme

Theme colors are defaults. Any explicit color parameter overrides the theme:

![](https://github-readme-stats.vercel.app/api?username=ME&theme=dracula&title_color=ff79c6&icon_color=8be9fd)

The colour parameters (title_color, text_color, icon_color, bg_color, border_color, plus ring_color for the stats rank circle) all accept 3, 4, 6, or 8-digit hex without the #.

5.9 Force a longer cache

![](https://github-readme-stats.vercel.app/api?username=ME&cache_seconds=86400)

Per-card minimum and maximum:

Values you pass via cache_seconds are clamped to the per-card range above. cache_seconds=999999999 will not actually cache for that long; it will be capped at the card's max.

Important

GitHub's image proxy (Camo) caches images aggressively. Even when the upstream Cache-Control says one day, GitHub may not refetch for several hours after the first render. To force a refresh you usually need to alter the URL (add a dummy &v=2 parameter) on the README side.

5.10 Localize the card

![](https://github-readme-stats.vercel.app/api?username=ME&locale=de)

50+ locales are supported. Common ones: en, es, fr, de, pt-br, pt-pt, ja, cn, zh-tw, kr (Korean), it, ru, nl, pl, tr, vi, id, ar, hi, bn, fa, he, th, uk-ua, fil, sw, cs, sk, bg, el, ro, ca, fi, se (Swedish), no (Norwegian), np (Nepali), ml, my, ta, ur, sa, sr, sr-latn, uz, az, hu, ml. Unrecognised locales render a "Language not found" / "Locale not found" error card.

5.11 Pin a self-hosted instance

After deploying your fork, replace every github-readme-stats.vercel.app URL in your README with your-project.vercel.app (or your custom domain). Same query string, same parameters.

6. Troubleshooting

Error: Missing params "username" make sure you pass the parameters in URL

Cause: You opened the API URL without a ?username= query string.

Solution:

1. Add ?username=YOUR_HANDLE to the URL.
2. For /api/pin, also add &repo=REPO_NAME.
3. For /api/gist, use ?id=GIST_ID instead.

Prevention: Always copy the URL from a working README rather than typing it out.

Error: No GitHub API tokens found

Cause: Self-hosted instance has no PAT_* env var set.

Solution:

1. Generate a classic Personal Access Token at https://github.com/settings/tokens. Scope: public_repo for public stats, repo if you want private contributions counted.
2. Set PAT_1=ghp_xxxxxxxxxxxxxxxxxxxx in Vercel project settings (or .env for local).
3. Redeploy.

Prevention: Add at least two PATs (PAT_1, PAT_2). The retryer rotates through them on rate-limit, dramatically increasing your effective request budget.

Error: Downtime due to GitHub API rate limiting

Cause: Every PAT in your environment hit the rate limit.

Solution:

1. Wait until the next reset window (the in-card error secondary message reads "You can deploy own instance or wait until public will be no longer limited").
2. Self-host with multiple PATs.
3. Hit /api/status/pat-info on your own instance to see which PATs are exhausted/expired.

Prevention: Provision PAT_1 through PAT_5 if your README is on a high-traffic profile. Increase cache_seconds (capped at the per-card max).

Error: User Repository Not found (or Organization Repository Not found)

Cause: Either the repo doesn't exist, or it's marked private. The fetcher explicitly refuses private repos regardless of token scope.

Solution:

1. Verify spelling — repo= is the bare name, no owner/ prefix.
2. Check the repo's GitHub settings; toggle to public if appropriate.
3. For organisation-owned repos, GitHub's GraphQL returns the org wrapper — pass username=ORG_LOGIN. The card walks both user and organization paths automatically.

Prevention: Use /api/pin only for public repos.

Error: Gist not found

Cause: The gist ID is wrong, or the gist is secret.

Solution: Copy the ID from https://gist.github.com/USER/GIST_ID. Public gists only.

Error: Could not resolve to a User with the login of '<username>'

Cause: WakaTime endpoint received a username that WakaTime doesn't recognise.

Solution:

1. Confirm the user has a public WakaTime profile (or a public Wakapi profile if you set api_domain=).
2. Visit https://wakatime.com/@USER directly to verify.

Prevention: Use the WakaTime username, NOT the GitHub username. They are usually the same, but not always.

Error: Invalid username provided.

Cause: You set include_all_commits=true and the username failed GitHub's username regex (the project uses the github-username-regex package).

Solution: Drop include_all_commits or fix the username spelling.

Card stops loading on a popular README — issue #1406, #4798, #4858

Cause: GitHub's Camo proxy is caching a stale error response, or the public Vercel instance is rate-limited (issues #4867 / #3851 / #4864 track "DEPLOYMENT_PAUSED" errors when the public Vercel instance hits its serverless quota).

Solution:

1. Force a Camo refresh: append &v=2 (or any dummy parameter) to the URL in your README.
2. Switch your README to a self-hosted fork.
3. Wait a few hours and retry.

Prevention: Self-hosting is the durable fix. The public instance is shared by millions of READMEs; rate-limit churn is constant.

Languages card returns "Incorrect layout input"

Cause: layout= was set to a value other than the five supported ones.

Solution: Use exactly one of normal, compact, donut, donut-vertical, pie. Any typo (donat, peei) is rejected explicitly.

Translation string not found or '<key>' translation not found for locale

Cause: The card asked the I18n module for a key that doesn't exist in the requested locale. Usually means you passed a malformed locale= or you're rendering through a fork that's missing translations.

Solution: Use locale=en to confirm the card otherwise works, then pick a supported locale from section 5.10.

Repository pin description overflows — issue #4862

Cause: Long descriptions are truncated to three lines by default. If yours runs longer, the last line shows ... truncation.

Solution: Use description_lines_count=1 or =2 to force fewer lines, or rewrite the repo description to fit.

7. FAQ

Q: Do I need to deploy my own instance?

For low-traffic profiles, no — the public github-readme-stats.vercel.app instance is fine. For high-traffic READMEs (popular profiles, project pages, organisations), self-hosting is recommended. Issue #1406 (47 comments) and the recurring "DEPLOYMENT_PAUSED" reports are direct evidence that the public instance is sometimes saturated.

Q: Why does my star count not match my profile?

By default the stats card sums stars across the first 100 repos returned by GitHub's GraphQL (sorted by stars descending). If you have more than 100 repos the long tail isn't included. Set the env var FETCH_MULTI_PAGE_STARS=true on your self-hosted instance to fetch every page; the public instance keeps it off to manage rate-limit budget.

Q: Are private commits counted?

Last-year commit count uses contributionsCollection.totalCommitContributions, which includes private contributions only if the user has enabled "Include private contributions on my profile" on github.com. Issue #4837 tracked this behaviour. include_all_commits=true uses the public search-commits endpoint and excludes private repos entirely.

Q: Why are my colors ignored?

Color parameters expect hex codes WITHOUT the leading #. title_color=ff79c6 works; title_color=#ff79c6 does not. Invalid hex values silently fall back to the theme color, then to the default theme.

Q: Can I use this on GitLab/Hashnode/Dev.to?

Yes — anywhere that renders Markdown image syntax or HTML <img> tags will display the cards. The hosted instance returns standard SVG with permissive cache headers.

Q: How do I know if the public instance is down?

Hit https://github-readme-stats.vercel.app/api/status/up. It returns a JSON boolean (or a Shields.io-compatible response with ?type=shields). The pat-info endpoint returns valid/exhausted/expired/error status for each PAT in the running instance.

Q: How do I count reviews instead of issues?

Add show=reviews and (optionally) hide=issues. The five optional show= keys are prs_merged, prs_merged_percentage, reviews, discussions_started, discussions_answered. stars, commits, prs, issues, and contribs are always on unless you hide= them.

Q: Can I use this offline / behind a corporate proxy?

Self-host the Express adapter (node express.js) and point your README at your internal URL. The only outbound dependencies are api.github.com (GraphQL + REST) and wakatime.com (or your custom api_domain).

Q: How do I get the rank S?

S is reserved for the top tier by the rank algorithm. Roughly: very high star count, lots of merged PRs, sizable follower count, and a steady review history. The exact thresholds are computed from CDFs of the medians (50 stars, 50 PRs, 250 commits/year, 25 issues, 2 reviews, 10 followers); see the rank algorithm note in section 4.1 if you want to poke at the math yourself.

Q: Can I add a theme?

Yes — open a PR adding a new entry to themes/index.js. The repo has helper scripts (scripts/preview-theme.js, scripts/generate-theme-doc.js) and a stale-theme-PR closer that automate the housekeeping. Themes must declare title_color, icon_color, text_color, bg_color, optionally border_color. Hex without #.

Q: What's the maximum description length on the pin card?

The repo description wraps at 59 characters per line and tops out at 3 lines (the limit you can clamp with description_lines_count=). Beyond that, the renderer adds ... to the last line.

Q: Why does my WakaTime card show a different card when nothing changed?

The WakaTime card has three "no data" states it cycles through: profile-not-public, code-stats-hidden, and zero-activity-this-week. If your settings shift on the WakaTime side mid-week, the card text shifts to match.