Chrome Headless Screenshot PDFs vs PNGs: Which Format to Use for Web Pages
Choose PNG for a screenshot image and PDF for a document. Compare Chrome Headless flags, output behavior, timing, and common fixes.
Use PNG when you need a screenshot image; use PDF when you need a document containing the rendered page. Chrome Headless has separate flags for these outputs: --screenshot saves a PNG, while --print-to-pdf saves a PDF. Neither is universally better. Choose based on what you will do with the result.
This guide uses Chrome’s documented command-line options. The examples assume Chrome or Chromium is installed and available as chrome; replace that command with the executable path for your system if needed. See the Chrome Headless command-line reference for version-specific details.
1. Choose the output by the deliverable
| Need | Choose | Reason |
|---|---|---|
| An image to view, embed, or process as pixels | PNG | --screenshot captures the page as an image. |
| A PDF copy of the rendered page | --print-to-pdf creates a document. |
|
| A particular visible browser viewport | PNG | Set the viewport deliberately with --window-size. |
| A print-style document with page layout | The output is a PDF; decide whether its print headers and footers should appear. |
This is a decision about output type and layout. Chrome’s reference documents how to produce each file; it does not claim one format is faster, smaller, or higher quality in every case.
2. Capture a PNG screenshot
Run Chrome Headless with --screenshot and the page URL. The file is written to the current working directory by default. Specify viewport dimensions when the screenshot must match a particular layout.
chrome --headless --window-size=1440,1000 --screenshot=page.png https://example.comTo capture a different viewport, change the width and height. The viewport affects responsive layout and the visible screenshot area, so use the dimensions expected by the consumer of the image. A viewport screenshot is not automatically a full-page capture.
3. Save the rendered page as a PDF
Use --print-to-pdf when the desired result is a PDF document. The optional --no-pdf-header-footer flag suppresses the print header and footer, which can include the date, URL, and page number.
chrome --headless --print-to-pdf=page.pdf --no-pdf-header-footer https://example.comOn older Chrome versions, the reference notes that the option may instead be named --print-to-pdf-no-header. If Chrome reports an unknown option, check the version and use the flag supported by that executable.
4. Control when capture happens
A page may still be loading or changing when Chrome reaches its capture point. The documented --timeout option sets the maximum wait before screenshot or PDF capture, even if the page is still loading. For content that depends on page time, --virtual-time-budget advances virtual time.
chrome --headless --timeout=10000 --window-size=1440,1000 --screenshot=page.png https://example.comchrome --headless --virtual-time-budget=5000 --print-to-pdf=page.pdf https://example.comUse a timeout appropriate to the page and environment, and allow virtual time when the page’s own timed behavior needs to run. A longer wait cannot guarantee that every third-party resource or asynchronous application state will settle; diagnose the page’s actual load behavior if output is incomplete.
5. Understand the practical differences
PNG: screenshot as an image
- Choose it when a downstream tool expects image pixels, such as an image preview or image-processing step.
- Plan the viewport size because it influences responsive layout and the captured area.
- Use a different image format only if your workflow specifically requires it; the Chrome flag documented here produces a screenshot PNG.
PDF: rendered page as a document
- Choose it when the deliverable must be a PDF file.
- Decide whether print headers and footers belong in the document; suppress them with the supported no-header-footer option when appropriate.
- Check the resulting document for page breaks and print layout if pagination matters to the reader.
Do not select based on an assumed universal quality or performance advantage. The cited Chrome reference gives output flags and timing controls, not comparative benchmarks.
6. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| No output file appears | The command ran from a different working directory, the executable failed, or the destination path is not writable. | Check Chrome’s exit output, inspect the current directory, and provide an explicit output filename in a writable location. |
| The screenshot has the wrong layout or dimensions | The viewport was omitted or differs from the intended device size. | Set --window-size=WIDTH,HEIGHT explicitly and recapture. |
| Content is missing or stale | The page had not finished rendering when capture began. | Set a suitable --timeout; if page behavior depends on time, consider --virtual-time-budget. Recheck whether the page relies on external resources or asynchronous state. |
| PDF contains an unwanted URL, date, or page number | Print header and footer are enabled. | Use --no-pdf-header-footer where supported. On older versions, try the documented legacy spelling --print-to-pdf-no-header. |
| Chrome rejects a command-line option | The installed Chrome version does not support that spelling or option. | Check the installed version against Chrome’s current command-line reference; use the legacy PDF header option only where the version requires it. |
| PDF pagination does not match the screen view | A PDF is a document output and may use print layout and page breaks. | Review the PDF as a document and adjust the page’s print styles if you control the site. |
7. Performance, reliability, and cost considerations
Chrome’s documented controls relevant to waiting are --timeout and --virtual-time-budget. These help define when a capture proceeds, but the reference does not provide a speed comparison between PNG and PDF. Avoid estimating run time or output size from format alone; page complexity, resource loading, and environment affect the actual result.
For repeatable captures, keep viewport dimensions and timing options explicit, use stable target URLs, and check that the expected file was produced. When running captures in automation, handle Chrome process failures and verify the output before passing it downstream. A timeout bounds waiting; it does not make a page’s content deterministic.
There is no special physical product required by this format choice. The documented workflows create digital files with Chrome Headless.
8. Or skip the browser setup
For a hosted screenshot API, ScreenshotNeo returns a screenshot or PDF from one GET request. Its API accepts common screenshot API parameter names, which can make switching easier. See the ScreenshotNeo API documentation for options and configuration.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', new Uint8Array(await res.arrayBuffer()));Replace YOUR_API_KEY with your key. The API can return PNG, JPEG, WebP, or PDF; configure the requested output according to the documentation. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture, and each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; responses indicate the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots monthly with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for 1,000 free screenshots a month, with no card required.
9. FAQ
Does Chrome Headless make a PDF and PNG with the same flag?
No. Use --screenshot for a PNG screenshot and --print-to-pdf for PDF output.
Which should I choose for a web page archive?
Choose based on how the archive will be consumed: PNG for an image record, PDF for a document copy.
Can I omit the URL and date printed on a PDF?
Yes, with --no-pdf-header-footer on versions that support it; older versions may use --print-to-pdf-no-header.
Does a longer timeout guarantee a complete capture?
No. It allows more time before capture, but cannot guarantee that a page’s external resources or asynchronous updates will complete successfully.
