GitHub Avatar Crawler

GitHub Avatar Crawler is a small command-line tool that crawls a GitHub user profile, visits followers and/or following lists, and downloads profile avatars into a local avatars/ folder. It supports both structured and flat output layouts, optional GitHub bearer-token authentication for better request reliability, and a configurable crawl depth so you can collect just a profile's avatar or explore multiple layers of connected accounts.

Features

• Download avatars from a target GitHub profile
• Crawl followers, following, or both
• Choose between a structured folder tree or a flat output folder
• Configure crawl depth
• Optional GitHub bearer token support
• Basic request retry handling with polite delays
• Colored terminal output for clearer progress feedback

Requirements

• Python 3.8 or newer
• requests
• beautifulsoup4
• colorama is optional, but recommended for colored output

Installation

Install the Python dependencies:

pip install requests beautifulsoup4 colorama

Usage

Run the script:

python main.py

Then follow the prompts:

1. Enter a valid GitHub username.
2. Optionally provide a GitHub bearer token.
3. Choose whether to crawl followers, following, or both.
4. Set the crawl depth.
5. Pick the output format.

Output Formats

Structured folder tree

Creates nested folders under avatars/<username>/ so each discovered user is grouped by relationship and depth.

Flat folder

Creates a single avatars/<username>/flatlist/ folder with all downloaded avatars in one place.

How It Works

1. The script loads the target GitHub profile page.
2. It extracts the og:image meta tag to fetch the avatar.
3. It collects profile links from follower or following pages.
4. It repeats the process up to the selected depth.
5. Avatars are saved locally as .jpg files.

Project Structure

github-avatar-crawler-main/
|-- main.py
|-- README.md
|-- LICENSE
|-- requirements.txt
`-- avatars/

Notes

• The crawler uses GitHub public profile pages and may be affected by rate limits or layout changes on GitHub.
• Using a bearer token can help reduce request failures during longer crawls.
• A depth of 0 downloads only the target user's avatar.
• The script stops gracefully when you press Ctrl+C.

License

This project is licensed under the MIT License. See LICENSE for details.

Author

Ashish Kumar