How to Add a Contribution Graph to Your GitHub Profile README
Step-by-step guide to adding beautiful contribution graphs to your GitHub profile README — activity graphs, 3D contribution charts, snake animations, and custom visualizations.
GitHub's default contribution graph — the green squares on your profile page — shows your activity over the past year. But you can add richer, more visual contribution data directly to your profile README: activity graphs with trend lines, 3D isometric contribution charts, snake animations that eat your contribution squares, and heatmaps that show your most active times.
This guide covers the four most widely used contribution graph tools, how to add each one, and how to choose the right one for your profile.
Why Add a Contribution Graph to Your README?
GitHub's built-in contribution graph is located below the fold on your profile — visitors need to scroll past your pinned repositories to see it. Embedding a contribution visualization in your README moves this signal to the top of your profile, where it is immediately visible.
For developers with strong activity histories, this is worth doing. For developers whose public contribution history does not reflect their real activity (because most work is in private repositories), embedding an additional contribution widget is usually not worth the visual space.
Before adding a contribution graph, ask: does my public contribution history accurately represent my activity? If yes, make it visible. If not, a written note ("Most of my contributions are in private repositories") is more accurate than a sparse graph.
Tool 1: GitHub Activity Graph (ashutosh00710)
The most popular contribution activity graph for GitHub profile READMEs. Generates a line chart showing your contribution activity over the past year with customizable themes and colors.
Basic Usage
Replace yourusername with your GitHub username. The graph renders immediately — no GitHub Actions setup required.
Configuration Parameters
| Parameter | Description | Example |
|-----------|-------------|---------|
| username | Your GitHub username | yourusername |
| theme | Visual theme | github-compact, react, dracula, tokyo-night |
| bg_color | Background color hex | 0D1117 |
| color | Line and point color | 58A6FF |
| line | Line color | 58A6FF |
| point | Point color | FFFFFF |
| area | Show area under curve | true |
| hide_border | Remove border | true |
| custom_title | Override graph title | My+Contributions |
Dark Mode Version
Available Themes
Popular theme options:
github-compact— Matches GitHub's native dark UIreact— Blue/dark, popular in frontend developer profilesdracula— Purple/pink with dracula color schemetokyo-night— Blue/purple Tokyo Night colorsmerko— Green/dark terminal aestheticgruvbox— Earthy, retro color scheme
Browse all themes in the repository documentation.
Dark/Light Mode Adaptive Version
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github-readme-activity-graph.vercel.app/graph?username=yourusername&bg_color=0D1117&color=58A6FF&line=58A6FF&point=FFFFFF&area=true&hide_border=true">
<source media="(prefers-color-scheme: light)" srcset="https://github-readme-activity-graph.vercel.app/graph?username=yourusername&theme=github-compact">
<img alt="Activity Graph" src="https://github-readme-activity-graph.vercel.app/graph?username=yourusername&theme=github-compact">
</picture>
Tool 2: GitHub Readme Stats Contribution Graph
The anuraghazra/github-readme-stats project — best known for its stats cards — also generates a contribution stats card that you may already be using. For contribution-specific visualizations, the activity graph (Tool 1) is more visually distinctive, but if you already use github-readme-stats, the consistency is a reasonable argument for staying within that ecosystem.
Stats Card with Contribution Data
The include_all_commits=true and count_private=true parameters tell the service to include private repository contributions (where accessible via your token) and commits before the current year.
Tool 3: Snake Contribution Animation (Platane/snk)
The snake contribution animation takes your contribution graph and animates a snake eating the squares. It is the most visually distinctive contribution visualization and requires a GitHub Actions workflow to generate and host the SVG.
Setup Steps
Step 1: Create the workflow file .github/workflows/snake.yml in your profile repository (yourusername/yourusername):
name: Generate Snake Animation
on:
schedule:
- cron: '0 0 * * *' # Daily at midnight UTC
workflow_dispatch: # Manual trigger
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Platane/snk/svg-only@v3
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
dist/github-snake.svg
dist/github-snake-dark.svg?palette=github-dark
- uses: crazy-max/ghaction-github-pages@v4
with:
target_branch: output
build_dir: dist
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Step 2: Commit the workflow file and trigger it manually from the Actions tab (or wait for the daily schedule to run).
Step 3: After the workflow completes, embed the generated SVG in your README:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yourusername/yourusername/output/github-snake-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/yourusername/yourusername/output/github-snake.svg">
<img alt="GitHub contribution grid snake animation" src="https://raw.githubusercontent.com/yourusername/yourusername/output/github-snake.svg">
</picture>
Replace all three instances of yourusername with your actual GitHub username.
How the Snake Animation Updates
The snake animation regenerates on the daily cron schedule (midnight UTC). Each run fetches your current contribution graph and animates the snake over it. The SVG is committed to the output branch of your profile repository, and the raw.githubusercontent.com URL always serves the latest version.
To trigger a manual update immediately after setup, go to your profile repository → Actions → "Generate Snake Animation" → "Run workflow."
Tool 4: 3D Contribution Chart (yoshi389111)
The 3D isometric contribution chart is the most visually striking option — it renders your contribution history as a 3D bar chart where each day's contributions become a pillar of proportional height.
Unlike the other tools, the 3D contribution chart requires either GitHub Actions or manual generation. The tool runs as a Node.js script that generates an SVG or PNG from your GitHub contribution data.
GitHub Actions Setup
Step 1: Create .github/workflows/profile-3d.yml:
name: GitHub-3D-Profile
on:
schedule:
- cron: "0 18 * * *" # Runs daily at 18:00 UTC
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
name: generate-github-3d-profile
steps:
- uses: actions/checkout@v4
- uses: yoshi389111/github-profile-3d-contrib@0.7.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
USERNAME: ${{ github.repository_owner }}
- name: Commit & Push
run: |
git config user.email "action@github.com"
git config user.name "GitHub Action"
git add -A .
git commit -m "Generated 3D contribution profile"
git push
Step 2: After the first run completes, the 3D SVG is committed to your repository. Reference it in your README:
The tool generates multiple variants (green, seasonal, night rainbow, etc.) at different paths in profile-3d-contrib/. Check the directory after the first run to see which variants were generated.
Customization Options
Set environment variables in the workflow to customize the output:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
USERNAME: ${{ github.repository_owner }}
SETTING_JSON: |
{
"MAX_REPOS": 10,
"SETTING_TYPE": "green-anime"
}
Available SETTING_TYPE values:
green— Classic green GitHub style (static)green-anime— Animated green variantnight-rainbow— Colorful night themenight-rainbow-anime— Animated colorful variantgitblock— Alternative block style
Choosing the Right Contribution Visualization
| Tool | Setup | Updates | Visual Style | Best For | |------|-------|---------|--------------|----------| | Activity Graph | URL embed | Live | Line chart | Simple, immediate, no setup | | GitHub Stats | URL embed | Live | Card with stats | Already using github-readme-stats | | Snake Animation | GitHub Actions | Daily | Animated snake | Maximum visual impact | | 3D Chart | GitHub Actions | Daily | 3D isometric | Unique, eye-catching profiles |
Choose Activity Graph if you want something that works immediately with no setup and looks clean and professional.
Choose Snake Animation if you want the most widely recognized contribution animation and are willing to set up a GitHub Actions workflow.
Choose the 3D Chart if you want a genuinely distinctive profile that stands out from the majority of developer profiles.
Skip contribution graphs entirely if your public contribution history does not accurately reflect your actual activity. A sparse graph creates a worse impression than no graph.
Placement in Your README
Contribution graphs work best at the bottom of your README, after your bio, project showcase, and skills section. Placing them at the top prioritizes decoration over content; placing them at the bottom rewards visitors who read through your profile with a visual closing element.
The snake animation, in particular, is conventionally placed at the very bottom as a footer element. It has enough visual interest to function as a satisfying page ending.
Troubleshooting
Graph shows no contributions: Check that your GitHub username is spelled correctly (case-sensitive). If you have few public contributions, the graph may appear nearly empty — this is accurate.
Snake animation workflow fails: The most common cause is insufficient permissions. Check that the workflow has write permissions for the repository (Settings → Actions → General → Workflow permissions → "Read and write permissions").
3D chart shows old data: GitHub caches contribution data. If the chart was generated but shows outdated information, trigger the workflow manually and wait a few minutes for the cache to update.
Activity graph returns an error: The github-readme-activity-graph.vercel.app service has occasional downtime. Check the service's GitHub repository for status updates.
Frequently Asked Questions
Does adding a contribution graph affect my GitHub profile SEO?
No. Contribution graphs are images — search engines read only the alt text, not the visual content. The SEO value of your profile comes from the text content of your README, not from embedded widgets.
Can I show private repository contributions in these graphs?
The Activity Graph and some GitHub Readme Stats configurations can include private contributions when you authenticate with a personal access token. The Snake Animation and 3D Chart use the public GitHub contributions API, which includes contributions to private repositories that are counted (but not revealed) in your public profile graph.
How do I remove a contribution graph from my README?
Delete the markdown image syntax from your README for URL-based graphs, or delete the workflow file and generated SVG for GitHub Actions-based graphs. The changes take effect immediately after committing.
Contribution graphs add a visual layer to your profile that many developers find engaging. Start with the Activity Graph (no setup required) and upgrade to the Snake Animation or 3D Chart when you want more visual impact. Our AI README Generator creates the text foundation of your profile — add your contribution visualization on top.