Overview

GitHub ReadMe Stats is an open-source project designed to generate dynamic SVG images that display a user's GitHub statistics. These images can be embedded directly into GitHub profile READMEs, project documentation, or personal websites, offering a visual summary of a developer's activity and contributions. The tool retrieves data from the GitHub API and renders it into customizable cards, which can include metrics such as total stars, commits, pull requests, issues, contributions, and top programming languages.

The primary use case for GitHub ReadMe Stats is to enhance developer profiles on GitHub. By integrating these statistical cards, developers can present a concise, real-time overview of their coding engagement and skill set. This can be beneficial for personal branding, demonstrating productivity to potential collaborators or employers, and simply tracking personal coding milestones. The project supports various themes and customization options, allowing users to tailor the appearance of the cards to match their aesthetic preferences or blend with their profile's design.

Integration is achieved by embedding a simple image URL into a Markdown file. The URL parameters control which statistics are displayed, the card's theme, and other visual properties. For example, a user can choose to display their overall stats, a list of their most used languages, or a commit streak. The service operates by processing these URL requests and returning an SVG image. For users requiring greater control over rate limits or specific data handling, the project also provides instructions for self-hosting the application.

While GitHub provides some built-in profile customization features and activity graphs, tools like GitHub ReadMe Stats offer a more consolidated and visually distinct presentation of aggregated metrics. It is particularly useful for developers who want to highlight specific achievements or patterns in their coding behavior that might not be immediately apparent from GitHub's default interface. The flexibility of its API-driven approach and the open-source nature of the project have contributed to its widespread adoption within the developer community for personalizing online presences.

The project is maintained by the community and continuously updated, reflecting changes in GitHub's API and user requests for new features or themes. Its reliance on standard web technologies (SVG, HTTP GET requests) makes it compatible with virtually any platform that can display images, extending its utility beyond just GitHub READMEs to blogs, portfolios, and other digital spaces where developers might want to showcase their work.

Key features

  • Dynamic SVG Generation: Generates real-time SVG images based on GitHub profile data, ensuring statistics are always up-to-date.
  • Customizable Statistics Cards: Offers various card types, including overall stats, top languages, and commit streaks, each configurable to display specific metrics.
  • Extensive Theming Options: Provides a wide array of built-in themes and allows for custom color schemes to match personal branding or profile aesthetics.
  • URL Parameter Control: All customization, from displayed stats to themes, is controlled via simple URL query parameters, making integration straightforward.
  • Language Exclusion/Inclusion: Users can specify which programming languages to include or exclude from the top languages card, refining the displayed skill set.
  • Private Contribution Support: Option to include private contributions in statistics, providing a more comprehensive view of activity (requires specific GitHub token scope).
  • API Rate Limit Handling: Manages GitHub API rate limits, with self-hosting options available for users needing higher limits or more control.
  • Cache Management: Implements caching mechanisms to optimize performance and reduce redundant API calls.
  • Open-Source and Self-Hostable: The entire project is open-source, allowing for community contributions and the option to host an instance on a private server for full control, as detailed in the GitHub ReadMe Stats documentation.
  • Compact Layout Options: Provides options to render cards in a compact layout, useful for saving space on a README.

Pricing

GitHub ReadMe Stats is a free and open-source project. There are no direct costs associated with using the service as hosted by the maintainers or by self-hosting. Users should be aware of potential costs related to hosting infrastructure if they opt to self-host the application, such as server costs or cloud service fees. As of 2026-05-28, the project maintains its free and open-source status.

Service Level Features Cost (as of 2026-05-28)
Public Instance Use Dynamic SVG generation, all customization options, community support Free
Self-Hosted Instance Dynamic SVG generation, all customization options, full control over rate limits, custom deployments Free (plus user's own hosting infrastructure costs)

Common integrations

  • GitHub Profile READMEs: The primary integration point, allowing developers to embed statistical cards directly into their main profile page using Markdown image syntax. Refer to the GitHub ReadMe Stats project page for examples.
  • Project Documentation: Useful for showcasing project maintainers' or contributors' stats within a project's README.md or other Markdown documentation files.
  • Personal Websites/Blogs: Developers can embed the generated SVG images into their personal portfolios or blogs to display their GitHub activity.
  • Developer Portfolios: Used in online portfolios to provide a dynamic and visually appealing summary of a developer's open-source contributions.

Alternatives

  • Shields.io: Provides a wide range of customizable badges for various services and statistics, often used for project status and metrics.
  • GitHub Profile Trophy: Generates SVG trophies based on GitHub achievements, offering a gamified way to display profile accomplishments.
  • GitHub Streak Stats: Specifically focuses on displaying a user's current and longest GitHub contribution streaks.

Getting started

To get started with GitHub ReadMe Stats, you primarily need to embed an image URL into your GitHub README file. The URL structure allows for various customizations through query parameters. Below is a basic example for displaying your GitHub stats card.

### Hi there 👋

I'm a passionate developer interested in open-source.

<a href="https://github.com/anuraghazra/github-readme-stats">
  <img src="https://github-readme-stats.vercel.app/api?username=YOUR_GITHUB_USERNAME&show_icons=true&theme=radical" />
</a>

<!-- Replace YOUR_GITHUB_USERNAME with your actual GitHub username -->

<!-- You can also add a top languages card: -->
<a href="https://github.com/anuraghazra/github-readme-stats">
  <img src="https://github-readme-stats.vercel.app/api/top-langs/?username=YOUR_GITHUB_USERNAME&layout=compact&theme=dracula" />
</a>

In this example:

  • Replace YOUR_GITHUB_USERNAME with your actual GitHub username.
  • show_icons=true adds icons next to the stats.
  • theme=radical applies the 'radical' theme to the card. Many other themes are available, as listed in the GitHub ReadMe Stats documentation.
  • For the top languages card, layout=compact uses a more condensed layout, and theme=dracula applies the 'dracula' theme.

After adding this Markdown snippet to your README.md file in your GitHub profile repository (a repository named after your GitHub username), commit the changes, and the dynamic stats card will appear on your profile. For advanced customization, including private contributions or custom themes, consult the official GitHub ReadMe Stats documentation, which provides comprehensive details on all available parameters and self-hosting instructions. For broader context on how GitHub itself handles profile READMEs, refer to GitHub's official guide on managing profile READMEs.