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

> Learn how to customize number formats in GitHub Readme Stats using the number_format parameter. Switch between short (k) and long notation for your stats.

- Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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.

```markdown
![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`:

```markdown
![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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/stats.js) and pass the `number_format` option:

```javascript
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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/fmt.js) rounds the abbreviated values.

```markdown
![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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/repo.js)** and **[`src/cards/gist.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/fmt.js).
- The formatting configuration applies across multiple card types, including the main stats card ([`src/cards/stats.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/stats.js)), repository cards ([`src/cards/repo.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/repo.js)), and gist cards ([`src/cards/gist.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/repo.js) and gist cards in [`src/cards/gist.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/stats.js) handles the parameter identically whether deployed on Vercel or a custom Node.js server.