Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Python CLI & GitHub Action to generate high-quality SVG statistics cards for your GitHub profile README. Customizable, fast, and dependency-free generation.

License

NotificationsYou must be signed in to change notification settings

stn1slv/github-stats-cards

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

A Python CLI tool that generates beautiful GitHub stats cards as SVG images for your profile README.

Python 3.13+License: MITTests

Features

  • 🎨50+ Built-in Themes - Choose from a variety of beautiful color schemes
  • 📊Comprehensive Stats - Stars, commits, PRs, issues, reviews, and more
  • 🔤Top Languages Card - Show your most used programming languages with 5 layouts
  • 🚀Top Contributions Card - Show your impact on external repositories with rank levels
  • ⚖️Smart Weighting - Preset rankings (balanced, expertise, diversity) for language stats
  • 📐Aligned Layouts - Compact top-langs card matches stats card width (467px)
  • 🔧Highly Customizable - Customize colors, layout, and content
  • 🚀GitHub Actions Ready - Perfect for automated daily/weekly updates
  • 🎯Local Generation - No external service dependencies
  • 🌐Internationalization - Support for multiple languages (English included)

📚 Documentation

Installation

Using uv (recommended)

uv pip install -e.

Using pip

pip install -e.

Note: This project usesuv for all Python execution, testing, and package management. All examples in this documentation useuv commands.

Running Without Installation

You can run the application directly without installing it usinguv run:

# Run as a Python moduleuv run python -m src.cli stats -u your-username -o stats.svg# Or using the shorter formuv run python -m src stats -u your-username -o stats.svg

Important: Don't forget to set your GitHub token:

export GITHUB_TOKEN=ghp_your_token_hereuv run python -m src.cli stats -u your-username -o stats.svg

Or pass it directly:

uv run python -m src.cli stats -u your-username -o stats.svg --token ghp_your_token_here

Quick Start

Set up your GitHub token

Create a Personal Access Token (PAT) withread:user scope:https://github.com/settings/tokens/new

export GITHUB_TOKEN=ghp_your_token_here

Generate your cards

# GitHub stats carduv run github-stats-card stats -u your-username -o stats.svg# Top languages carduv run github-stats-card top-langs -u your-username -o top-langs.svg# Top contributions carduv run github-stats-card contrib -u your-username -o contrib.svg

Usage

The CLI provides two main commands:

  • stats - Generate GitHub stats card
  • top-langs - Generate top languages card
  • contrib - Generate top contributions card

GitHub Stats Card

# Generate with default themeuv run github-stats-card stats -u octocat -o stats.svg# Use a specific themeuv run github-stats-card stats -u octocat -o stats.svg --theme vue-dark# Show icons and hide borderuv run github-stats-card stats -u octocat -o stats.svg --show-icons --hide-border

Top Languages Card

# Generate with default layout (normal)uv run github-stats-card top-langs -u octocat -o top-langs.svg# Compact layout (467px width, matches stats card)uv run github-stats-card top-langs -u octocat -o top-langs.svg --layout compact# Donut chart with dark themeuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --layout donut --theme vue-dark --hide-border# Hide specific languagesuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --hide"HTML,CSS,Makefile" --langs-count 8# Balanced weighting preset (70% size, 30% repo count)uv run github-stats-card top-langs -u octocat -o top-langs.svg \  --weighting balanced# Pie chart with bytes displayuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --layout pie --stats-format bytes

Top Contributions Card

# Generate with default themeuv run github-stats-card contrib -u octocat -o contrib.svg# Top 5 contributions with dark themeuv run github-stats-card contrib -u octocat -o contrib.svg --theme vue-dark --limit 5# Exclude specific repositories or use wildcardsuv run github-stats-card contrib -u octocat -o contrib.svg \  --exclude-repo"awesome-*,facebook/react"

Advanced Options

Stats Card:

# Hide specific statsuv run github-stats-card stats -u octocat -o stats.svg --hide stars,prs# Show additional statsuv run github-stats-card stats -u octocat -o stats.svg --show reviews,discussions_started# Include all commits (not just current year)uv run github-stats-card stats -u octocat -o stats.svg --include-all-commits# Custom colorsuv run github-stats-card stats -u octocat -o stats.svg \  --title-color ff6e96 \  --text-color f8f8f2 \  --bg-color 282a36# Gradient backgrounduv run github-stats-card stats -u octocat -o stats.svg \  --bg-color"90,ff0000,00ff00,0000ff"

Top Languages Card:

# Exclude specific repositoriesuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --exclude-repo"repo1,repo2"# Exclude using wildcards or repo-only namesuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --exclude-repo"awesome-*,mule-*"# Use weighting presetsuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --weighting balanced# Options: size-only, balanced, expertise, diversity# Custom weighting (manual control)uv run github-stats-card top-langs -u octocat -o top-langs.svg \  --size-weight 0.5 --count-weight 0.5# Custom width and colorsuv run github-stats-card top-langs -u octocat -o top-langs.svg \  --card-width 400 \  --title-color ff6e96 \  --text-color f8f8f2 \  --bg-color 282a36

All Options

Runuv run github-stats-card stats --help oruv run github-stats-card top-langs --help for complete option lists.

Stats Card Options:

  • Basic: username, token, output, theme
  • Display: show-icons, hide-border, hide-title, hide-rank, hide/show stats
  • Commits: include-all-commits, commits-year
  • Colors: title-color, text-color, icon-color, bg-color, border-color, ring-color
  • Layout: card-width, line-height, border-radius
  • Formatting: number-format, number-precision, locale, custom-title
  • Other: rank-icon, disable-animations, text-bold

Top Languages Card Options:

  • Basic: username, token, output, theme
  • Display: hide-border, hide-title, hide-progress
  • Layout: layout (normal/compact/donut/donut-vertical/pie), card-width, border-radius
  • Languages: langs-count, hide (languages), exclude-repo (supports wildcards like "awesome-*")
  • Ranking: weighting (size-only/balanced/expertise/diversity), size-weight, count-weight
  • Colors: title-color, text-color, bg-color, border-color
  • Other: stats-format (percentages/bytes), custom-title, disable-animations

Top Contributions Card Options:

  • Basic: username, token, output, theme
  • Display: hide-border
  • Limits: limit (default: 10), exclude-repo (supports wildcards and repo-only names)
  • Colors: title-color, text-color, bg-color, border-color
  • Other: custom-title, card-width, border-radius, disable-animations

Weighting Presets:

  • size-only (default) - 100% code size, 0% repo count
  • balanced - 70% code size, 30% repo count (recommended)
  • expertise - 50% code size, 50% repo count
  • diversity - 40% code size, 60% repo count

Available Themes

Here are some popular themes:

  • default - Clean and professional
  • dark - Dark mode friendly
  • radical - Bold and colorful
  • vue /vue-dark - Vue.js inspired
  • tokyonight - Tokyo Night theme
  • dracula - Dracula theme
  • gruvbox - Gruvbox theme
  • monokai - Monokai theme
  • github_dark - GitHub dark theme
  • nord - Nord theme
  • catppuccin_mocha /catppuccin_latte - Catppuccin themes

See all 50+ themes

GitHub Actions Integration

Method 1: Using as a Custom Action (Recommended)

The easiest way to use this project in GitHub Actions is as a custom action:

Security Best Practice: Always pin actions to a specific version tag or commit SHA rather than using@main. This prevents supply-chain attacks where a compromised repository could inject malicious code into your workflows.

name:Update GitHub Statson:schedule:    -cron:'0 0 * * *'# Daily at midnight UTCworkflow_dispatch:# Manual triggerjobs:update-stats:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4# Generate stats card      -name:Generate GitHub Stats Carduses:stn1slv/github-stats-card@v1.0.0# Always pin to a specific version or commit SHA for securitywith:card-type:statsusername:${{ github.repository_owner }}token:${{ secrets.GITHUB_TOKEN }}output:img/github-stats.svgtheme:vue-darkshow-icons:truehide-border:trueinclude-all-commits:true# Generate top languages card      -name:Generate Top Languages Carduses:stn1slv/github-stats-card@v1.0.0# Always pin to a specific version or commit SHA for securitywith:card-type:top-langsusername:${{ github.repository_owner }}token:${{ secrets.GITHUB_TOKEN }}output:img/top-langs.svgtheme:vue-darklayout:compacthide-border:truelangs-count:8weighting:balanced# Commit and push changes      -name:Commit and push if changedrun:|          git config --local user.email "github-actions[bot]@users.noreply.github.com"          git config --local user.name "github-actions[bot]"          git add img/*.svg          git diff --staged --quiet || git commit -m "Update GitHub stats [skip ci]"          git push

Available Action Inputs

Common inputs:

  • card-type (required) - Type of card:stats,top-langs, orcontrib
  • username (required) - GitHub username
  • token (required) - GitHub Personal Access Token
  • output (required) - Output SVG file path
  • theme - Theme name (default:default)
  • hide-border - Hide card border (default:false)
  • hide-title - Hide card title (default:false)
  • custom-title - Custom card title
  • title-color,text-color,bg-color,border-color - Custom colors
  • card-width - Card width in pixels
  • border-radius - Border radius (default:4.5)
  • disable-animations - Disable CSS animations (default:false)

Stats card inputs:

  • show-icons - Show icons next to stats (default:false)
  • hide-rank - Hide rank circle (default:false)
  • include-all-commits - Include all commits, not just current year (default:false)
  • hide - Comma-separated stats to hide

Top-langs card inputs:

  • layout - Layout style:normal,compact,donut,donut-vertical,pie (default:normal)
  • langs-count - Number of languages to show (default:5)
  • hide-progress - Hide progress bars (default:false)
  • weighting - Weighting preset:size-only,balanced,expertise,diversity
  • exclude-repo - Comma-separated repos to exclude
  • hide - Comma-separated languages to hide

Top-contributions card inputs:

  • limit - Number of repositories to show (default:10)
  • exclude-repo - Comma-separated repos to exclude

Method 2: Direct CLI Installation

Create.github/workflows/update-stats.yml:

name:Update GitHub Statson:schedule:    -cron:'0 0 * * *'# Daily at midnight UTCworkflow_dispatch:# Manual triggerjobs:update-stats:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4            -name:Set up Pythonuses:actions/setup-python@v5with:python-version:'3.13'            -name:Install uvrun:pip install uv            -name:Install github-stats-cardrun:uv pip install --system -e .            -name:Generate GitHub Stats Cardsenv:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}run:|          # Stats card - Dark theme          github-stats-card stats \            --username ${{ github.repository_owner }} \            --output img/github-stats-dark.svg \            --theme vue-dark \            --show-icons \            --hide-border \            --include-all-commits          # Stats card - Light theme          github-stats-card stats \            --username ${{ github.repository_owner }} \            --output img/github-stats-light.svg \            --theme vue \            --show-icons \            --hide-border \            --include-all-commits          # Top languages card - Dark theme (compact layout, 467px width)          github-stats-card top-langs \            --username ${{ github.repository_owner }} \            --output img/top-langs-dark.svg \            --theme vue-dark \            --layout compact \            --hide-border \            --langs-count 8 \            --weighting balanced          # Top languages card - Light theme (compact layout, 467px width)          github-stats-card top-langs \            --username ${{ github.repository_owner }} \            --output img/top-langs-light.svg \            --theme vue \            --layout compact \            --hide-border \            --langs-count 8 \            --weighting balanced            -name:Commit and push if changedrun:|          git config --local user.email "github-actions[bot]@users.noreply.github.com"          git config --local user.name "github-actions[bot]"          git add img/*.svg          git diff --staged --quiet || git commit -m "Update GitHub stats [skip ci]"          git push

GitHub Enterprise Server Support

This tool is compatible with GitHub Enterprise Server and other GitHub platforms. Use environment variables to configure custom API endpoints:

Environment Variables:

  • GITHUB_API_URL - Custom REST API base URL (default:https://api.github.com)
  • GITHUB_GRAPHQL_URL - Custom GraphQL endpoint URL (default:https://api.github.com/graphql)

Usage Examples:

# Using with GitHub Enterprise Serverexport GITHUB_API_URL="https://github.enterprise.com/api/v3"export GITHUB_GRAPHQL_URL="https://github.enterprise.com/api/graphql"export GITHUB_TOKEN=ghp_your_enterprise_tokenuv run github-stats-card stats -u your-username -o stats.svg

In GitHub Actions:

-name:Generate GitHub Stats Carduses:stn1slv/github-stats-card@mainenv:GITHUB_API_URL:https://github.enterprise.com/api/v3GITHUB_GRAPHQL_URL:https://github.enterprise.com/api/graphqlwith:card-type:statsusername:your-usernametoken:${{ secrets.GHE_TOKEN }}output:stats.svg

Note: If onlyGITHUB_API_URL is set, the GraphQL endpoint will automatically be constructed as${GITHUB_API_URL}/graphql. You can override this by explicitly settingGITHUB_GRAPHQL_URL.

Then add to your README:

##My GitHub Stats<divalign="center">  <picture><source media="(prefers-color-scheme: dark)" srcset="img/github-stats-dark.svg"><source media="(prefers-color-scheme: light)" srcset="img/github-stats-light.svg"><img alt="GitHub Stats" src="img/github-stats-dark.svg">  </picture>    <picture><source media="(prefers-color-scheme: dark)" srcset="img/top-langs-dark.svg"><source media="(prefers-color-scheme: light)" srcset="img/top-langs-light.svg"><img alt="Top Languages" src="img/top-langs-dark.svg">  </picture></div>

Development

Setup

# Clone the repositorygit clone https://github.com/yourusername/github-stats-card.gitcd github-stats-card# Install with dev dependenciesuv pip install -e".[dev]"

Run Tests

uv run pytest

Code Formatting

# Format codeuv run black src tests# Lintuv run ruff check src tests# Type checkuv run mypy src

Programmatic Usage (Python API)

You can use the library programmatically in your Python projects:

Stats Card

fromsrc.github.fetcherimportfetch_statsfromsrc.rendering.statsimportrender_stats_cardfromsrc.core.configimportStatsCardConfig# Fetch statsstats=fetch_stats(username="octocat",token="ghp_your_token")# Create configurationconfig=StatsCardConfig(theme="vue-dark",show_icons=True,hide_border=True,include_all_commits=True,)# Render SVGsvg=render_stats_card(stats,config)# Save to filewithopen("stats.svg","w")asf:f.write(svg)

Top Languages Card

fromsrc.github.langs_fetcherimportfetch_top_languagesfromsrc.rendering.langsimportrender_top_languagesfromsrc.core.configimportLangsCardConfig# Fetch language stats with balanced weightinglangs=fetch_top_languages(username="octocat",token="ghp_your_token",size_weight=0.7,# 70% code sizecount_weight=0.3# 30% repo count)# Create configuration (compact layout uses 467px width by default)config=LangsCardConfig(theme="vue-dark",layout="compact",hide_border=True,langs_count=8,)# Render SVGsvg=render_top_languages(langs,config)# Save to filewithopen("top-langs.svg","w")asf:f.write(svg)

Top Contributions Card

fromsrc.github.fetcherimportfetch_contributor_statsfromsrc.rendering.contribimportrender_contrib_cardfromsrc.core.configimportContribCardConfig,ContribFetchConfig# Fetch contributor statsfetch_config=ContribFetchConfig(username="octocat",token="ghp_your_token",limit=10)stats=fetch_contributor_stats(fetch_config)# Create configurationconfig=ContribCardConfig(theme="vue-dark",limit=5)# Render SVGsvg=render_contrib_card(stats,config)# Save to filewithopen("contributions.svg","w")asf:f.write(svg)

Configuration Objects

All configuration is done through dataclasses:

StatsCardConfig - 20 fields including:

  • theme: Theme name (str)
  • show_icons: Display icons (bool)
  • hide_border: Hide card border (bool)
  • hide: List of stats to hide (list[str])
  • show: List of additional stats to show (list[str])
  • include_all_commits: Include commits from all years (bool)
  • custom_title: Custom card title (str | None)
  • title_color,text_color,icon_color,bg_color: Custom colors (str | None)
  • And more...

LangsCardConfig - 15 fields including:

  • theme: Theme name (str)
  • layout: Layout type - "normal", "compact", "donut", "donut-vertical", "pie" (str)
  • hide_border: Hide card border (bool)
  • langs_count: Number of languages to display (int)
  • hide: List of languages to hide (list[str])
  • exclude_repo: List of repos to exclude (list[str])
  • size_weight,count_weight: Ranking weights (float)
  • And more...

Creating Config from CLI Args

You can also create configurations from CLI-style arguments:

fromsrc.core.configimportStatsCardConfig# From keyword arguments (like CLI options)config=StatsCardConfig.from_cli_args(theme="vue-dark",show_icons=True,hide_border=True,hide="stars,prs",# comma-separated stringcustom_title="My Stats")

Architecture

The project is organized into focused sub-packages:

Core (src/core/):

  • config.py - Centralized configuration and CLI parsing logic
  • constants.py - Centralized constants and magic numbers
  • exceptions.py - Exception hierarchy
  • i18n.py - Internationalization support
  • utils.py - Shared utility functions

GitHub (src/github/):

  • client.py - Authenticated GitHub API client (REST/GraphQL)
  • fetcher.py - GitHub user statistics retrieval
  • langs_fetcher.py - GitHub language statistics retrieval
  • rank.py - User rank calculation algorithm

Rendering (src/rendering/):

  • base.py - Base SVG card "envelope" and styling
  • stats.py - Stats card SVG renderer
  • langs.py - Top languages card SVG renderer
  • icons.py - SVG icon definitions
  • themes.py - Theme definitions (50+ themes)
  • colors.py - Color parsing and utilities

CLI (src/):

  • cli.py - Command-line interface orchestration
  • __main__.py - Python module entry point

Credits

Inspired bygithub-readme-stats by@anuraghazra.

This project is a Python CLI reimplementation designed for local generation and GitHub Actions usage.

License

MIT License - seeLICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

Python CLI & GitHub Action to generate high-quality SVG statistics cards for your GitHub profile README. Customizable, fast, and dependency-free generation.

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Packages

No packages published
[8]ページ先頭
©2009-2026 Movatter.jp