1. How Visitor Counters Work Inside GitHub
Standard websites track traffic using client-side JavaScript tags such as Google Analytics, Plausible, or PostHog. GitHub profile READMEs, however, are strictly sanitized Markdown documents. For security and anti-cross-site-scripting (XSS) reasons, GitHub strips all <script> tags and interactive embeds.
Instead, profile tracking relies on dynamic SVG pixel requests:
- A user navigates to your profile at
github.com/your-username. - GitHub encounters an image tag pointing to a counter endpoint (e.g.
https://komarev.com/ghpvc/?username=...). - Instead of loading directly from the external URL, GitHub routes the request through its secure, anonymizing asset proxy: GitHub Camo (
camo.githubusercontent.com). - Camo requests the asset from the counter API, passing request headers.
- The counter service increments the unique visitor count in its Redis/PostgreSQL database and returns an SVG badge with HTTP headers specifying
Cache-Control: max-age=0, no-cacheso subsequent views trigger real-time updates.
2. Complete Configuration & URL Syntax
The most widely trusted open-source visitor counter for GitHub is maintained by Anton Komarev. Here is the complete production syntax:
<!-- Standard Markdown Embed --> 
Supported Query Parameters
| Parameter | Default | Description & Example |
|---|---|---|
username | Required | Your exact GitHub handle (case-sensitive). |
color | blue | Right-hand badge hex color without # (e.g., cc785c). |
style | flat | Visual shape: for-the-badge, flat-square, or plastic. |
label | PROFILE VIEWS | Custom left-side text. Use + or %20 for spaces. |
base | 0 | Starting offset if migrating from an existing counter service. |
3. Perfect Alignment with Shields.io Badges
A common aesthetic flaw is placing a rounded flat visitor badge alongside square for-the-badge technology shields. This creates jarring height discrepancies. To align your visitor badge seamlessly into a header capsule:
<p align="center"> <img src="https://komarev.com/ghpvc/?username=yourhandle&color=cc785c&style=flat-square&label=VISITORS" alt="Visitor Counter" /> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome" /> <img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License" /> </p>
4. Avoiding Inflation & Handling Camo Caching
Two issues frequently perplex developers using visitor badges:
Why does the counter count my own refreshes?
Most free counting services use basic IP hashing with a 24-hour deduplication window. If you test your profile by editing and refreshing, your local IP will only be counted once per day. However, if you switch networks (cellular to Wi-Fi), a new view will register.
Why did my counter get stuck?
Occasionally GitHub Camo caches an image for up to 300 seconds if the counter server fails to send strict no-storeheaders. If your counter lags behind real visits, wait 5 minutes; it will catch up once Camo's TTL invalidates.
5. Building a Private Counter with Cloudflare Workers
If you want 100% control over your metrics without relying on third-party public infrastructure, you can deploy a zero-cost Cloudflare Worker with KV storage. The worker intercepts the Camo request, increments an atomic key in KV, and returns a dynamic SVG response with custom SVG font kerning in under 15 milliseconds.
Generate Harmonious Badges with ProfileCrest
ProfileCrest automatically synchronizes your visitor counter badge style, colors, and dimensions with your tech stack badges.
🚀 Open ProfileCrest Generator