How to Customize Number Format (Short vs Long) in GitHub Readme Stats

GitHub Readme Stats provides a number_format query parameter that lets you switch between compact "k" notation (default) and full numeric values for repository statistics.

The anuraghazra/github-readme-stats repository generates dynamic SVG cards displaying GitHub statistics, and you can customize number format github readme stats displays using built-in configuration options. By default, the cards abbreviate large numbers like 1,000 as "1k", but the underlying source code exposes flags to display exact counts instead.

Understanding Number Format Options

The stats card supports two distinct display modes for numeric values such as stars, forks, commits, and pull requests:

• short (default): Displays compact notation like 1k, 12.3k, or 1m for values ≥ 1000
• long: Displays full numeric values like 1000, 12345, or 1000000 without abbreviation

The short format utilizes the kFormatter function to produce human-readable abbreviations, while the long format renders the raw integer values directly.

How to Configure Number Formatting

You can control the display format via URL parameters when embedding cards or through options when using the library programmatically.

Via URL Query Parameter

Append number_format=long to your stats card URL to display full numbers. The default value is short when the parameter is omitted.

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

For the compact default style, either omit the parameter or explicitly set number_format=short:

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

Via Programmatic API

When rendering cards server-side or in custom scripts, import renderStatsCard from src/cards/stats.js and pass the number_format option:

import { renderStatsCard } from "github-readme-stats/src/cards/stats.js";

const svg = renderStatsCard(userStats, {
  number_format: "long"
});

According to the source code in src/cards/stats.js, the function defaults to "short" when no number_format option is provided.

Controlling Decimal Precision

When using the short format, you can fine-tune the number of decimal places with the number_precision parameter (accepts values 0–2). This controls how kFormatter in src/common/fmt.js rounds the abbreviated values.

![GitHub Stats](https://github-readme-stats.vercel.app/api?username=octocat&number_format=short&number_precision=2)

Setting number_precision=2 displays values like 12.34k instead of 12k, while 0 forces whole numbers only.

Source Code Implementation

The formatting logic resides in specific modules within the repository.

In src/cards/stats.js, the renderStatsCard function reads the number_format option and determines whether to abbreviate each statistic. When the format is "long", the code uses the raw numeric value; otherwise, it invokes kFormatter to generate the compact string.

The kFormatter implementation lives in src/common/fmt.js. This utility function accepts a number and precision value, returning formatted strings like "1k" or "12.3k" depending on the magnitude of the input.

The same formatting options also affect repository and gist cards. Both src/cards/repo.js and src/cards/gist.js import and utilize kFormatter for displaying star and fork counts, meaning the number_format parameter influences these card types as well.

Summary

• GitHub Readme Stats defaults to short number format, displaying compact "k" notation for values ≥ 1000.
• Set number_format=long in your URL or API options to display full, unabbreviated numeric values.
• Adjust decimal precision in short mode using number_precision (0–2), which controls the kFormatter output in src/common/fmt.js.
• The formatting configuration applies across multiple card types, including the main stats card (src/cards/stats.js), repository cards (src/cards/repo.js), and gist cards (src/cards/gist.js).

Frequently Asked Questions

What is the default number format in GitHub Readme Stats?

The default value is short, as defined in src/cards/stats.js. This means all numeric statistics appear in abbreviated notation (for example, 1k instead of 1000) unless you explicitly set number_format=long.

Can I use long format with decimal precision?

No, the number_precision parameter only affects the short format. When number_format is set to long, the code renders raw integer values without decimal formatting, ignoring any precision settings passed to kFormatter.

Does the number_format parameter affect all card types?

Yes, the formatting logic extends beyond the main stats card. Both repository cards in src/cards/repo.js and gist cards in src/cards/gist.js respect the number_format option when displaying star and fork statistics, utilizing the same kFormatter utility from src/common/fmt.js.

How do I format numbers when self-hosting the API?

When self-hosting, pass the number_format option directly to the renderStatsCard function in your server code, or include the query parameter in your request URLs. The implementation in src/cards/stats.js handles the parameter identically whether deployed on Vercel or a custom Node.js server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}