shot-scraper — Headless Chrome Screenshots from CLI

Quick Use

1. pip install shot-scraper && shot-scraper install
2. shot-scraper https://url --selector .target -o out.png
3. Batch via YAML: shot-scraper multi shots.yml

Intro

shot-scraper is Simon Willison's CLI wrapper around Playwright that captures screenshots of any URL via headless Chrome — full page, element selector cropping, JS injection, batch YAML configs, automated GitHub Actions cron snapshots for tracking page changes over time. Best for: documentation screenshots, visual regression tests, OG image generation, scheduled scraping of public pages. Works with: any OS, Python 3.10+. Setup time: 3 minutes.

Install + first shot

pip install shot-scraper
shot-scraper install   # downloads Chromium

# Full-page screenshot
shot-scraper https://tokrepo.com -o tokrepo.png

Element + selector

# Just the hero section
shot-scraper https://tokrepo.com --selector ".hero" -o hero.png

# Wait for an element to appear before capturing
shot-scraper https://tokrepo.com --wait-for "document.querySelector('.assets').children.length > 5"

Inject JS before screenshot

# Hide cookie banner, then shoot
shot-scraper https://example.com \
  --javascript "document.querySelector('.cookie-banner').remove()" \
  -o cleaned.png

Batch YAML config

# shots.yml
- url: https://tokrepo.com
  output: home.png
  width: 1280
  height: 800

- url: https://tokrepo.com/en/packs
  output: packs.png
  selector: ".arsenal"
  width: 1200

- url: https://tokrepo.com/en/authors
  output: authors.png
  full_page: true

shot-scraper multi shots.yml

GitHub Actions cron for change tracking

# .github/workflows/snapshot.yml
on:
  schedule: [{ cron: "0 8 * * *" }]
jobs:
  snap:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install shot-scraper && shot-scraper install
      - run: shot-scraper multi shots.yml
      - run: git add . && git diff --cached --stat && git commit -m "Daily snapshot $(date +%F)" && git push

FAQ

Q: shot-scraper vs raw Playwright? A: shot-scraper is the 80% case in 1 line. Use Playwright directly when you need authentication flows, complex form fills, or multi-step navigation. shot-scraper wraps Playwright so falling back is one step away.

Q: Can it capture HTML too, not just images? A: Yes — shot-scraper html https://example.com -o page.html saves rendered HTML after JS. Combine with --javascript to run scrape logic before extraction. Useful for SPA scraping.

Q: Cookies / auth? A: Pass --auth auth.json with a Playwright storage state file. Generate the state file once via shot-scraper auth https://example.com which opens a real browser for you to log in. After that, automated shots run authenticated.

Source & Thanks

Built by Simon Willison. Licensed under Apache-2.0.

simonw/shot-scraper — ⭐ 1,700+