termfetch

A neofetch-style profile card for your GitHub README — your photo as coloured terminal art on the left, live GitHub stats on the right, rendered to a single self-contained SVG.

Why termfetch?

• No image service at view time. The result is a static SVG committed to your repository.
• Your design, not a preset badge. Use your own photo, fields, colours, crop, and character set.
• Live without being fragile. A scheduled GitHub Action refreshes the card; README visitors never spend your API quota and never see an outage from a third-party renderer.
• Portable. The output is one self-contained SVG that works in GitHub READMEs and anywhere else an image can be embedded.

Quickstart

python -m pip install termfetch
git clone https://github.com/saivarun1410/termfetch
cd termfetch

termfetch --config examples/config.json --out card.svg

Prefer an isolated CLI install? Use pipx install termfetch or uv tool install termfetch. To work from a checkout before installing, run python -m pip install -e ..

Then in your README:

![](card.svg)

--no-fetch skips the GitHub API entirely if you just want to iterate on the art.

Configuration

Everything lives in one JSON file.

{
  "github": "saivarun1410",
  "image": "assets/me.jpg",
  "imageCrop": [630, 0, 780, 780],
  "imageCols": 52,
  "charset": "blocks",
  "theme": "github-dark",
  "panelAlign": "middle",
  "sections": [
    {
      "title": "{{username}}@github",
      "fields": [
        ["Name", "{{name}}"],
        ["Member for", "{{uptime}}"],
        ["Editor", "Neovim"]
      ]
    }
  ]
}

Image

Choosing a charset.

• halfblocks — sharpest. Every cell is ▀, with the glyph painting the upper pixel and a background rect the lower one, so vertical resolution is doubled for the same card width. Use this if the art looks blocky; the cost is file size, since a photograph has few neighbouring cells that can merge.
• blocks ( ░▒▓█) — keeps a visible terminal texture while letting colour carry the image. Much smaller output, noticeably coarser.
• ascii ( .:-=+*#%@) — looks the most like real neofetch output, but it maps brightness to character density, so a backlit photo where the subject is darker than the background comes out as a hole. Good for logos and high-key images, risky for portraits.
• solid — every cell █. Clear, but reads as pixel art rather than terminal art.

File size. A halfblocks card is a few hundred KB; blocks is a few tens. Raising colorStep helps only slightly on photographs — the cost is the per-cell geometry, not repeated colours — so reducing imageCols is the effective lever if size matters.

Cropping. The card looks best framed on a face. Find the pixel coordinates however you like — this snippet prints a labelled grid over your image:

from PIL import Image, ImageDraw
im = Image.open("assets/me.jpg"); d = ImageDraw.Draw(im)
for x in range(0, im.width, 200):  d.line([(x,0),(x,im.height)], fill="cyan", width=4); d.text((x+6,6), str(x), fill="cyan")
for y in range(0, im.height, 200): d.line([(0,y),(im.width,y)], fill="magenta", width=4); d.text((6,y+6), str(y), fill="magenta")
im.show()

Layout and theme

Data

Available template variables: {{username}}, {{name}}, {{bio}}, {{location}}, {{company}}, {{blog}}, {{repos}}, {{stars}}, {{forks}}, {{followers}}, {{following}}, {{languages}}, {{created}}, {{uptime}}, {{today}}.

A field is dropped when its value resolves to nothing, or when it still references a variable there was no data for — so an unset bio leaves no dangling label, and --no-fetch renders a clean card rather than one covered in literal {{bio}} text. Fields can also be plain strings for a full-width line with no key column.

Keeping it current

name: refresh-card
on:
  schedule: [{ cron: "0 5 * * *" }]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install pillow
      - run: python -m termfetch --config config.json --out card.svg
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add card.svg
          git diff --cached --quiet || { git commit -m "Refresh profile card"; git push; }

GITHUB_TOKEN is optional but raises the API rate limit from 60 requests/hour per IP to 5,000, which matters if you use languageMode: "bytes".

How it works

1. Sample. The image is cropped, resized to the character grid, and each cell becomes a character picked from a luminance ramp plus the cell's average colour.
2. Quantise. Colours are snapped to a coarser grid so runs of neighbouring cells share a value and collapse into one SVG span. This is most of the difference between a 60 KB file and a 300 KB one.
3. Position every glyph explicitly. SVGs embedded in a README render as images, so webfonts never load and the viewer's monospace fallback is whatever their OS provides. Relying on the font's own advance width would let columns drift apart on some machines, so each span carries an absolute x.

Limitations

• Character cells are assumed to be 0.6× as wide as they are tall. That holds for the fonts in the stack; a wildly different fallback would shear the art slightly.
• Colour is per character cell, so effective resolution is imageCols × about 0.6 × imageCols. Portraits work; fine detail and text in the source image do not.
• Stats come from the public REST API, so private repositories and private contributions are not counted.

Development

python -m pip install -e '.[dev]'
pytest -q

Contributions are welcome. See CONTRIBUTING.md for the development and pull request checklist, and CHANGELOG.md for release notes.

Licence

MIT — see LICENSE. The example photograph is not covered by it; replace it with your own.