GitHub README guide

How to add a profile views counter to your GitHub README

Add a free profile views counter (visitor badge) with flags to your GitHub profile or repo README in one line of Markdown — plus the setting GitHub needs.

Updated · takes about 2 minutes

A profile views counter — a small visitor badge in your README — shows how many people view your profile or project. Live Flag Counter gives you a Markdown snippet that works in any README: your profile README or any repository's.

One thing to know first: GitHub loads every README image through its own image proxy, which hides visitors' IP addresses for privacy. Views are counted, but they show up from GitHub's own servers (usually in the United States) instead of each visitor's country. On your own website, the same counter shows real countries.

Example of a badge flag counter showing visitor flags and counts
The badge layout with sample data — pick any layout, colours and size in the builder.

Step by step

  1. Create your counter with “Every view”

    In the builder, open Advanced and choose Every view under “How visitors are counted”. GitHub fetches the image from a few shared addresses, so “Once” would count all of GitHub as only a handful of visitors. The badge and list layouts suit READMEs well. Then click Create my counter.

  2. Copy the Markdown code

    Open the Markdown tab and click Copy. It uses the SVG image, which stays sharp on every screen.

  3. Open your README

    For your profile, open the repository that has exactly the same name as your username — GitHub shows its README.md on your profile (create it as a public repository if you don't have one yet). For a project, open its README.md. Click the pencil icon to edit.

  4. Paste the code and commit

    Paste the code where the counter should appear and click Commit changes. Reload your profile or repository to see it.

What the code looks like

This is the Markdown code. Yours contains your own counter ID instead of YOUR-ID, so always copy it from your counter's page.

[![Live Flag Counter](https://liveflagcounter.com/c/YOUR-ID.svg)](https://liveflagcounter.com/stats/YOUR-ID)

Tips for GitHub

  • We send no-cache headers, so GitHub fetches a fresh image regularly — a new view usually shows within a few minutes.
  • To centre the counter, wrap the code in <p align="center"> … </p>, which GitHub allows in READMEs.
  • Your statistics page shows total views and trends for the README. For real visitor countries, also add the counter to your website or blog.
  • Got a GitHub Pages site? That is a normal website, so use the HTML code there — its visitors show their real countries.

Questions

Why does my README counter show mostly the US flag?

GitHub's image proxy fetches the counter from GitHub's own servers, so we see their location instead of the visitor's. It is the same for every image-based counter on GitHub.

Why doesn't the number go up straight away?

GitHub can keep the image for a short time. Because we send no-cache headers it refreshes regularly — usually within a few minutes.

Should I count “Once” or “Every view” on GitHub?

Every view. All README views arrive through a few shared GitHub addresses, so with “Once (unique forever)” the counter would barely move.

Is this the same as a GitHub visitor badge or hit counter?

Yes — it counts profile or README views like a visitor badge or hit counter, and comes with a full statistics page. On your own website the same counter also shows each visitor's country flag.

Add a flag counter to GitHub

Create your free counter in seconds. No signup, no watermark, no cookies.

Create your counter

See all guides