Chrome headless screenshots from the command line

You don't need Puppeteer to get a PNG out of Chrome. Every command below was run with Chrome 155. Here is what each flag really does, and where the command line runs out.

The one-liner

google-chrome --headless --screenshot https://example.com

This writes screenshot.png to the current directory. On macOS the binary is "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; on Windows it's chrome.exe; Chromium installs it as chromium or chromium-browser. Without a window size the image comes out at an odd 780×493 (an 800×600 window minus the space headless still reserves), so always set one:

google-chrome --headless --screenshot=shot.png --window-size=1280,800 --hide-scrollbars https://example.com

--screenshot=FILE picks the file name. A .jpg extension gives a JPEG; anything else is PNG. --hide-scrollbars stops a scrollbar eating 15px at the right.

Retina (2x) screenshots

google-chrome --headless --screenshot=hi.png --window-size=1280,800 --force-device-scale-factor=2 https://example.com

Output is 2560×1600: the layout is still 1280px wide, rendered at twice the pixel density.

Dark mode

google-chrome --headless --screenshot=dark.png --window-size=1280,800 --blink-settings=preferredColorScheme=0 https://example.com

preferredColorScheme=0 makes prefers-color-scheme: dark match (1 is light). Pages without dark-mode CSS look the same.

Wait for JavaScript to finish

google-chrome --headless --screenshot=app.png --window-size=1280,800 --virtual-time-budget=5000 https://example.com

Single-page apps often come out blank or half-loaded, because Chrome shoots as soon as the load event fires. --virtual-time-budget=5000 lets the page run 5 seconds of virtual time (timers fast-forward, so it's usually quicker than 5 real seconds) before the capture. --timeout=MS is the blunt version: shoot after that many real milliseconds even if the page is still loading.

PDF instead of PNG

google-chrome --headless --print-to-pdf=page.pdf --no-pdf-header-footer https://example.com

--no-pdf-header-footer removes the date, title, URL and page numbers Chrome prints otherwise (older versions called it --print-to-pdf-no-header). The paper size defaults to US Letter. There's no flag for A4 or margins: the page sets them with CSS, e.g. @page { size: A4; margin: 1cm }. For a local file use a file:/// URL: --print-to-pdf=out.pdf file:///home/me/invoice.html.

Many URLs in a loop

while read -r url; do
  name=$(echo "$url" | sed 's|https*://||; s|[^A-Za-z0-9]|_|g')
  google-chrome --headless --screenshot="$name.png" --window-size=1280,800 --hide-scrollbars "$url"
done < urls.txt

Each call starts and stops a whole browser (about a second each). For hundreds of URLs, a script that keeps one browser open (Puppeteer, Playwright) is much faster.

What the command line can't do

• Full-page screenshots: there is no --full-page flag. The usual workaround is a very tall window (--window-size=1280,6000), which gives you exactly 6000px: blank space under a short page, a cut-off long page. For a real full-page capture you need the DevTools protocol (Puppeteer's fullPage: true), or our full-page screenshot tool.
• One element, clicks, logins, cookie banners, waiting for a selector: none of these have flags. Use Puppeteer or Playwright.
• --headless=old is gone: old headless mode was split out into a separate chrome-headless-shell binary, and --headless now means the new mode, which renders like normal Chrome.
• Running as root / in Docker: Chrome refuses to start without --no-sandbox. Only use it for pages you trust.
• Boxes instead of text: missing fonts. On Debian/Ubuntu: apt install fonts-noto-cjk fonts-noto-color-emoji.
• The dbus and GPU errors in the output (Failed to call method: org.freedesktop...) are harmless on servers. Look for the "bytes written to file" line.

The same thing without installing Chrome

If you just need images or PDFs from a script, cron job or CI, Shotmint runs the browser and supports what the flags don't (full page with lazy images, element selectors, ad and cookie-banner blocking):

curl -o full.png -H "X-API-Key: $SHOTMINT_KEY" \
  "https://shotmint.creasework.com/v1/screenshot?url=https://example.com&full_page=true&device_scale_factor=2&dark_mode=true&block_ads=true"

curl -o page.pdf -H "X-API-Key: $SHOTMINT_KEY" \
  "https://shotmint.creasework.com/v1/pdf?url=https://example.com&format=A4"

Chrome flag	Shotmint
--window-size=1280,800	width=1280&height=800
--force-device-scale-factor=2	device_scale_factor=2
--blink-settings=preferredColorScheme=0	dark_mode=true
--virtual-time-budget / --timeout	wait_until=networkidle, delay= (ms, up to 10000)
--screenshot=x.jpg	format=jpeg&quality=80 (or webp)
--print-to-pdf --no-pdf-header-footer	/v1/pdf, with format=A4|Letter and landscape
(no flag)	full_page=true, selector=, hide_selectors=, block_ads=true

When the command line is enough

For a one-off picture of a page, a quick PDF of a local HTML file, or a cron job that shoots a dashboard at a fixed size, the flags above are all you need. Once you want full pages, elements or many URLs, move to a script or an API. No code at all: the website screenshot tool and URL to PDF.