shot-scraper

TLDR

Take a screenshot of a webpage

$ shot-scraper [https://example.com]

Take a screenshot with custom dimensions

$ shot-scraper [https://example.com] -w [800] -h [600] -o [output.png]

Capture a specific element by CSS selector

$ shot-scraper [https://example.com] -s '[.header]' -o [header.png]

Take a screenshot with JavaScript execution before capture

$ shot-scraper [https://example.com] --javascript "[document.body.style.backgroundColor = 'white']"

Take a retina screenshot (2x scale)

$ shot-scraper [https://example.com] --retina -o [output.png]

Wait for element before taking screenshot

$ shot-scraper [https://example.com] --wait-for "[document.querySelector('.loaded')]"

Save as JPEG with quality setting

$ shot-scraper [https://example.com] -o [output.jpg] --quality [80]

Interactive mode to manually navigate before capture

$ shot-scraper [https://example.com] --interactive

shot-scraper URL [options]
shot-scraper install
shot-scraper javascript URL script [options]
shot-scraper pdf URL [options]
shot-scraper accessibility URL [options]
shot-scraper har URL [options]

DESCRIPTION

shot-scraper is a command-line utility for taking automated screenshots of websites, built on Playwright. It can capture full pages, specific elements, or execute JavaScript before capturing. The tool is designed for documentation, automated testing, and web scraping workflows.
Beyond screenshots, shot-scraper can execute JavaScript on pages and return results, generate PDFs, export accessibility trees, and capture HAR (HTTP Archive) files. It integrates well with CI/CD pipelines, particularly GitHub Actions, for generating regularly updated screenshots.
Before first use, run shot-scraper install to download the required browser binaries.

PARAMETERS

-o, --output FILE

Output filename. Use - for stdout.

-w, --width PIXELS

Browser viewport width. Default: 1280.

-h, --height PIXELS

Browser viewport height. Default: full page.

-s, --selector SELECTOR

CSS selector to capture instead of full page.

--selector-all SELECTOR

Capture all elements matching the selector.

--padding PIXELS

Add padding around selected elements.

--js-selector EXPRESSION

JavaScript expression to filter elements.

--wait MS

Milliseconds to wait after page load.

--wait-for EXPRESSION

Wait until JavaScript expression is truthy.

-j, --javascript CODE

Execute JavaScript before taking screenshot.

--quality PERCENT

Save as JPEG with specified quality (1-100).

--retina

Use device scale factor of 2.

--scale-factor N

Custom device pixel ratio.

--omit-background

Transparent background (PNG only).

-b, --browser NAME

Browser to use: chromium, firefox, webkit, chrome.

--browser-arg ARG

Pass command-line argument to browser.

--user-agent STRING

Custom User-Agent header.

-i, --interactive

Pause for manual interaction before capture.

--bypass-csp

Bypass Content-Security-Policy restrictions.

--log-requests FILE

Log HTTP requests as newline-delimited JSON.

--timeout MS

Timeout in milliseconds before failing.

CAVEATS

Requires Python and Playwright browser binaries (installed via shot-scraper install). Screenshots default to 1280px width and full page height, which can result in large files for long pages. JavaScript execution timing may require adjustment with --wait or --wait-for for dynamically loaded content.

HISTORY

shot-scraper was created by Simon Willison and first released in 2022. It was designed to automate documentation screenshots and web scraping tasks using Playwright's browser automation capabilities. The tool gained popularity for generating automated screenshots in CI/CD pipelines, with notable users including Reuters for data dashboards. Development continues actively with regular releases adding new features.