How to Capture a Full Webpage in Chrome Using the Command Line
Use Chrome’s headless command for a viewport screenshot, CDP for a full-page image, or Chrome’s print option for a PDF. Includes runnable examples and troubleshooting.
Direct answer: Chrome’s --headless --screenshot command captures a screenshot at the requested viewport dimensions. For an image that extends beyond the viewport, use Chrome DevTools Protocol (CDP) and call Page.captureScreenshot with captureBeyondViewport: true. Chrome’s command-line reference does not document a dedicated full-page screenshot flag. If a printable document is sufficient, use --print-to-pdf.
“Full webpage” can mean either the visible browser area or the entire document from top to bottom. Pick the method based on the artifact you need: viewport image, full-page image, or PDF.
1. Capture a viewport screenshot with Chrome’s command line
This is the shortest built-in option. It saves screenshot.png in the current working directory, using the dimensions requested with --window-size:
chrome --headless --screenshot --window-size=1280,900 https://example.com/On systems where Chrome has a different executable name or location, substitute its path. For example, the executable may be called google-chrome, google-chrome-stable, or chromium. Check with which google-chrome, which chromium, or the equivalent for your shell and operating system.
This command is useful for a quick image of a chosen browser viewport. A larger --window-size requests larger dimensions; it does not guarantee that Chrome will capture the page’s entire document. The screenshot option and window-size usage are described in the Chrome Headless documentation.
2. Capture beyond the viewport with the Chrome DevTools Protocol
For a full-page image, connect to Chrome through CDP and request Page.captureScreenshot with captureBeyondViewport: true. The protocol response contains base64-encoded image data; decode it and write the bytes to a file. The CDP method and parameters are documented in the Page.captureScreenshot protocol reference.
CDP is a protocol, not a universal shell command: the exact command-line syntax depends on the client that connects to Chrome. A robust implementation should launch or connect to the Chrome version you intend to use, enable the Page domain, issue the capture command, decode the returned data, and save it with an extension matching the selected format. Verify client syntax against that client’s documentation and protocol compatibility with your installed Chrome.
CDP capture choices
captureBeyondViewport: trueasks Chrome to capture content outside the current viewport.formatselects an image format such as PNG, JPEG, or WebP, where supported by the protocol and client.- Use PNG when preserving sharp text and edges matters; choose JPEG or WebP when a smaller image is more useful and lossy compression is acceptable.
- CDP returns encoded image data. A client must decode that response before writing a normal image file.
For compatibility, consult the live protocol reference and test against the Chrome version installed in your environment. Protocol clients can expose different option names or response shapes.
3. Save the page as a PDF
If your goal is a printable or shareable document rather than a raster image, Chrome provides a direct PDF option:
chrome --headless --print-to-pdf --no-pdf-header-footer https://example.com/This writes a PDF, not a PNG, JPEG, or WebP image. Chrome documents both flags in its Headless CLI reference. You can cap how long Chrome waits before it captures with --timeout=<milliseconds>, for example:
chrome --headless --print-to-pdf --no-pdf-header-footer --timeout=10000 https://example.com/A timeout is a maximum wait, not proof that a dynamic page has finished loading. Pages that fetch content after load may still be incomplete when the capture happens.
4. Choose the right method
| Method | Output | Capture extent | Best for |
|---|---|---|---|
--headless --screenshot |
PNG screenshot | Requested viewport dimensions | A quick capture without writing a CDP client |
CDP Page.captureScreenshot |
PNG, JPEG, or WebP image data | Can extend beyond the viewport with captureBeyondViewport |
A full-page image or programmatic capture control |
--print-to-pdf |
Print layout across document pages | A printable document rather than one tall image |
5. Make captures more reliable
- Confirm the browser executable. Use the Chrome or Chromium binary installed on the machine, and ensure the invoking user can run it.
- Use an explicit URL. Include the scheme, such as
https://, and quote URLs that contain shell-sensitive characters. - Choose image versus document output. Use CDP for a full-page image; use the print flag when a paginated PDF meets the requirement.
- Account for dynamic content. The CLI timeout only caps the wait. It cannot tell whether a site’s asynchronous content is ready.
- Check the result file. Confirm the output exists, has nonzero size, and opens in an image viewer or PDF reader. Run the command from a known working directory so the output location is clear.
- Keep Chrome and the CDP client compatible. Browser protocol behavior and client interfaces can vary by version; check the live protocol documentation when upgrading.
6. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
chrome: command not found |
The executable is not on PATH, or it has another name. |
Find the installed Chrome/Chromium executable and invoke it by its full path or actual command name. |
| The screenshot shows only the top portion of the page | The basic CLI screenshot is a viewport capture, not a documented full-document capture. | Use a CDP client and set captureBeyondViewport: true. |
| The PDF or screenshot contains incomplete dynamic content | The page had not finished rendering when Chrome captured it; the timeout is only a wait cap. | Increase the timeout where appropriate, or use automation that waits for a page-specific readiness condition before issuing the capture. |
| No file appears where expected | The command wrote to the process’s current working directory, or the browser failed before writing. | Check the shell’s current directory, inspect Chrome’s error output, and retry with a writable working directory. |
| The CDP command fails or has unexpected parameters | The client syntax or protocol version does not match the installed Chrome. | Check the client’s command format and the live CDP Page domain reference; confirm that the client sends the boolean captureBeyondViewport parameter. |
| The saved image cannot be opened | Base64 response text may have been written as text, decoded incorrectly, or saved with the wrong extension. | Decode the CDP response to bytes and make the filename extension match the selected image format. |
7. Performance, reliability, and cost considerations
A viewport screenshot is generally the least involved option because it uses Chrome’s built-in CLI flag. A beyond-viewport capture adds a CDP connection and response decoding step. Very long pages can produce large image files and take longer to render or encode; choose the output format based on the size and visual fidelity you need. PDF output can break content across pages according to print layout, so it is not a substitute for one continuous image.
For repeatable automation, make browser version, executable path, capture dimensions, and readiness conditions explicit. Do not treat a command completing or a timeout expiring as evidence that every page element loaded correctly. The research references do not establish universal timing, file-size, or cost benchmarks, so measure those in the environment and on the pages you capture.
8. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request can return an image or PDF, including full-page captures with lazy images loaded. Its clean-capture steps accept cookie banners and remove 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use tools such as take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo API documentation for parameters and configuration.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/ -o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com/"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
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 import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does Chrome have a --full-page screenshot flag?
The cited official Headless CLI reference does not document a dedicated full-page screenshot flag. Use CDP’s captureBeyondViewport option for a beyond-viewport image.
Can I use a larger window size to get the whole page?
--window-size sets requested screenshot dimensions, but it does not guarantee a full-document capture. Page length and browser behavior vary.
Will --timeout wait until a page is fully ready?
No. It caps the wait before capture; it does not verify that a page’s scripts, images, or delayed content have finished loading.
Should I use PDF or an image?
Use PDF for a printable, paginated document. Use CDP when the required deliverable is a full-page image.
