How to Capture a Full-Page Screenshot from the Command Line

A full-page screenshot captures the entire scrollable document, including content below the initial viewport. With Playwright CLI, run:

playwright-cli open https://example.com
playwright-cli screenshot --full-page --filename=full-page.png

The first command opens the target page in the current headless browser session. The second captures the full scrollable page and saves a PNG. A normal screenshot may capture only the visible viewport; --full-page is the important distinction.

What “full page” captures

Full-page mode captures the webpage canvas from its top through the document’s scrollable bottom. It does not capture browser chrome, the operating-system desktop, the URL bar, or other windows. The result is one image whose height is based on the document rather than the current window.

Pages with lazy loading, sticky headers, animations, infinite scroll, or content that changes during capture need extra preparation. Inspect the output and adjust waits or page behavior when necessary; no browser tool can guarantee identical results for every site.

Playwright CLI: the simplest repeatable command

1. Install and open a page

Install Playwright using its current installation instructions, then start a CLI session and navigate:

playwright-cli open https://example.com

The CLI is headless by default. The screenshot command operates on the page currently open in that session. See the Playwright CLI screenshot reference for the current command syntax.

2. Capture the whole document

playwright-cli screenshot --full-page --filename=full-page.png

Use a predictable path in automation:

mkdir -p artifacts
playwright-cli screenshot --full-page --filename=artifacts/example-full.png

3. Choose an image format

Playwright infers the image type from the filename extension when --type is omitted:

playwright-cli screenshot --full-page --filename=page.png
playwright-cli screenshot --full-page --filename=page.jpeg
playwright-cli screenshot --full-page --filename=page.webp

PNG is lossless and useful for visual diffs. JPEG is smaller for photographic pages. WebP is useful when your downstream system accepts it.

4. Capture device pixels with --hires

playwright-cli screenshot --full-page --hires --filename=full-page.png

--hires captures device pixels instead of CSS pixels. This can produce a sharper, larger file. Playwright warns that coordinates in a high-resolution image no longer line up directly with CSS-pixel mouse-command coordinates.

Playwright API: a script for repeatable jobs

Use the API when screenshots run in a build, test, documentation job, or scheduled process. The documented JavaScript pattern is:

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'full-page.png', fullPage: true });
  await browser.close();
})();

Save this as screenshot.js, install Playwright for your project, and run node screenshot.js. The Playwright screenshots guide and Page API reference document full-page capture and image options.

Prepare dynamic pages before capture

Navigation finishing does not always mean every visual element is ready. In a script, wait for a selector that proves the important content exists, wait for a known delay when a page has a short animation, or prepare the page so lazy content is loaded before calling screenshot. Keep the preparation specific to the site: a page that continuously appends items may never reach a stable bottom.

Alternative command-line tools

shot-scraper

The shot-scraper 0.14.3 manual documents this setup:

pip install shot-scraper
shot-scraper install

Then capture a page:

shot-scraper https://example.com -o full-page.png

In that documented version, the browser defaults to 1280 pixels wide and 780 pixels high. If --height is omitted, the output is full-page length. Set dimensions explicitly when your workflow needs a stable viewport:

shot-scraper https://example.com --width 1440 --height 900 -o page.png

If you omit an output name, shot-scraper derives one from the URL and adds a numeric suffix when that file already exists. Its manual also describes GitHub Actions use. Because these details refer to version 0.14.3, check the current manual if a flag differs in a later release: shot-scraper 0.14.3 documentation.

Chrome Headless

Chrome documents a viewport screenshot command:

chrome --headless --screenshot --window-size=412,892 https://example.com

This sets a finite window size. The cited Chrome reference does not document a full-scrollable-page flag for --screenshot, so do not treat this command as equivalent to Playwright’s --full-page. Chrome also documents --timeout, --virtual-time-budget, and --print-to-pdf for different capture needs. Check the flags supported by your installed Chrome version; the reference was last updated 2024-10-21 UTC: Chrome Headless command-line reference.

Choosing a method

Need	Recommended route	Reason
One-off full-page CLI capture	Playwright CLI	Explicit --full-page flag and filename control
Reusable application code	Playwright API	fullPage: true fits an existing automation job
Python-oriented CLI or GitHub Actions	shot-scraper	Full-page output when height is omitted in version 0.14.3
Viewport screenshot or PDF	Chrome Headless	Documented window-size and PDF flags, but no cited full-page image flag
Hosted API with browser setup handled	ScreenshotNeo	Clean shots, only clean shots billed, and a $5 paid plan

Edge cases and page preparation

• Lazy images: content may load only after scrolling. Trigger the page’s loading behavior or use a service that loads lazy images as part of capture.
• Sticky navigation: a fixed header can appear repeatedly or cover content. Hide it with page preparation or a hide-selector option where supported.
• Infinite scroll: there may be no final height. Define a stopping condition such as an item count or maximum scroll distance.
• Animations and clocks: animated banners can produce different pixels on every run. Disable them with custom CSS or wait for a stable state.
• Authentication: provide the required session cookies or headers in the browser job; never hard-code secrets in a committed script.
• Very tall documents: inspect memory use and output dimensions. Split captures or create a PDF when one enormous bitmap is impractical.
• PDF versus image: a PDF is a paginated document, not a PNG/JPEG/WebP screenshot. Chrome’s --print-to-pdf and Playwright’s separate PDF command serve that use case.

Or skip the browser setup

ScreenshotNeo provides a hosted website screenshot API and MCP server. It can capture full pages, load lazy images, remove cookie and consent banners, newsletter popups and chat widgets before the shot, and return PNG, JPEG, WebP or PDF. The API also supports selectors, dark mode, device presets, retina scale, waits, custom CSS and JavaScript, headers, cookies, user agents, geolocation, blocking rules, caching, signed links, asynchronous jobs, bulk capture and usage reporting. See the ScreenshotNeo API documentation for the available options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

import 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}`);

Cookie banners, popups and chat widgets are removed before the shot. Bot checks, blank pages and failed loads are never billed, and response headers report the page verdict and billing status. An MCP server lets AI agents such as Claude and Cursor take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

Troubleshooting

Symptom	Likely cause	Fix
Only the visible viewport is saved	Full-page mode was omitted	Use --full-page in the CLI or fullPage: true in the API.
Images or sections are missing	Lazy loading has not been triggered	Scroll or wait for the relevant selector before capture; verify the resulting file.
Output changes on every run	Animation, rotating content, ads, or time-dependent code	Disable animation with CSS, block unstable resources, or capture after a deterministic wait.
Capture times out	Slow page, blocked resource, or endless loading	Set a bounded timeout, wait for a meaningful selector instead of “everything,” and inspect network dependencies.
Text is blurry	Image is rendered at CSS-pixel scale	Use Playwright’s high-resolution option or a retina/device scale setting, then account for larger files.
Coordinates no longer match	High-resolution output uses device pixels	Translate coordinates from CSS pixels before issuing mouse commands.
File is unexpectedly huge	Long page, high scale, or lossless format	Use WebP or JPEG where acceptable, reduce scale, or split the document.
Chrome command does not include below-the-fold content	--window-size only sets the viewport	Use Playwright full-page capture or shot-scraper’s documented full-page behavior.

Performance, reliability and cost

• Performance: Full-page images take longer and use more memory as document height and pixel scale increase. Reuse a browser in scripted jobs when possible and avoid unnecessary high-resolution output.
• Reliability: Pin tool versions in automation, set explicit waits, save artifacts, and compare dimensions or hashes when visual consistency matters. Dynamic websites can change independently of your command.
• Cost: Local Playwright, Chrome, and shot-scraper costs are your machine or CI runtime. A hosted API trades browser maintenance for per-capture billing. ScreenshotNeo bills only clean shots; bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with status in X-Page-Verdict and X-Billed headers.

FAQ

Does full-page mean a screenshot of the browser window?

No. It means the webpage’s scrollable document, without browser chrome or the desktop.

Can I capture a full page as JPEG or WebP?

Yes. Playwright CLI infers the format from a .jpeg or .webp filename when the type is omitted.

Is Chrome’s --window-size a full-page option?

No. The documented example sets a finite viewport. Use a tool with an explicit full-page feature for the complete document.

When should I use a PDF instead?

Use PDF when pagination, selectable text, or print margins matter. Use an image for a pixel-oriented preview, visual diff, or social card.

How do I capture many URLs without maintaining browsers?

Use a hosted screenshot API such as ScreenshotNeo, which also offers bulk capture and asynchronous jobs.