Introducing 'stargazers': A Tool to Understand Your GitHub Audience

Building and maintaining an open-source project involves more than just writing code. Understanding who is interested in your work—your stargazers and forkers—can provide invaluable insights into your community’s growth, reach, and potential. Where are they located? What other projects do they star? Answering these questions helps tailor communication, prioritize features, and build stronger connections.

Years ago, the team at Cockroach Labs shared a fascinating analysis in their post, “What Can We Learn from Our GitHub Stars?”. They correlated star growth with events like press mentions and conference talks, demonstrating the power of understanding your audience dynamics. While incredibly insightful, replicating their analysis required significant effort, dealing directly with the GitHub API, managing rate limits, and processing large amounts of data.

Inspired by their work and the need for an easier solution, I’m excited to introduce stargazers, a modern CLI tool designed to make analyzing your GitHub audience simple and accessible.

What is stargazers?

stargazers is a Python-based command-line tool that helps you:

1. Fetch Stargazers or Forkers: Easily retrieve a complete list of users who have starred or forked any public GitHub repository (or multiple repositories at once).
2. Gather Rich Metadata: Automatically collect public profile information for each user, including their name, company, location, bio, follower count, and public repository count.
3. Output to CSV: Save the collected data to a well-structured CSV file, perfect for further analysis in spreadsheets or data analysis tools.
4. Get Quick Summaries: Instantly see key statistics directly in your terminal, such as the top locations of your stargazers or forkers.
5. Handle Rate Limits: The tool intelligently manages GitHub API rate limits, pausing and retrying when necessary. Using an optional GITHUB_TOKEN environment variable significantly speeds up the process for larger repositories by leveraging higher authenticated request limits (5,000/hour vs. 60/hour).

How to Use It

Installation is straightforward using pip:

# Install from PyPI (assuming it's published)
# pip install stargazers

# Or install directly from GitHub (latest main)
pip install git+https://github.com/wdm0006/stargazers.git

# Or clone and install in editable mode for development
# git clone https://github.com/wdm0006/stargazers.git
# cd stargazers
# pip install -e .

Once installed, you can run it directly from your shell:

# Fetch stargazers for one or more repositories
stargazers owner/repo1 owner/repo2

# Fetch forkers
forkers owner/repo1

For a single repository like wdm0006/pygeohash, the output will be saved to wdm0006_pygeohash_stargazers.csv (or _forkers.csv). If you analyze multiple repositories, the results are combined into all_stargazers.csv or all_forkers.csv with an added repo column.

Here’s an example of the terminal output:

Fetching stargazers for: wdm0006/pygeohash
Requesting: https://api.github.com/repos/wdm0006/pygeohash/stargazers with params {'per_page': 100, 'page': 1}
Response status: 200
Fetched 26 stargazers in this batch.
Total stargazers fetched: 26
Fetching user metadata |████████████████████| 26/26 [100%]
Fetched metadata for 26 users.
Saving DataFrame with 26 rows to wdm0006_pygeohash_stargazers.csv

Saved 26 users to wdm0006_pygeohash_stargazers.csv

Top Locations:
United States    10
India            3
Germany          2
Canada           2
...

The resulting CSV contains columns like login, name, company, location, email, bio, followers, public_repos, starred_at (or forked_at), and repo.

Get Started

Understanding your community is key to fostering a successful open-source project. The stargazers tool aims to lower the barrier to gaining these insights.

Check out the repository, give it a star (meta, I know!), and try it on your own projects:

➡️ github.com/wdm0006/stargazers

Let me know what you think! Issues and pull requests are welcome.