How to Set a Custom Viewport Size for Chrome Headless Screenshots

Use Chrome’s --window-size=WIDTH,HEIGHT flag with --headless and --screenshot. For example, this captures at 412 by 892 pixels:

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

Replace 412,892 with the width and height you need, in pixels. Chrome saves screenshot.png in the current working directory by default. The flag sets the browser window dimensions for the capture; it does not, by itself, configure a complete device emulation profile. See the Chrome Headless command-line reference.

1. Capture a page at a custom size from the command line

1. Find the Chrome executable available on your system. Depending on the installation, it may be named chrome, google-chrome, or something else.
2. Run the command with --headless, --screenshot, and --window-size=WIDTH,HEIGHT.
3. Put the page URL after the flags. Use a complete URL, including https://.
4. Look for screenshot.png in the command’s current working directory.

chrome --headless --screenshot --window-size=1365,768 https://example.com/

In this example, the browser window is 1365 pixels wide and 768 pixels high. The official documentation uses 412 by 892 as an example; that is an example size, not a recommended universal viewport.

If Chrome is not on your PATH, call its installed executable directly. The exact path depends on your operating system and installation. You can also choose an output path with Chrome’s screenshot option:

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

Check the command-line reference for the current supported syntax and options: Chrome Headless command-line reference.

2. Choose dimensions that match the question you are answering

Pick dimensions based on the page layout or test you need to inspect. For example, a narrow width can help reveal mobile layout breakpoints, while a wider one can show a desktop layout. These are viewport dimensions, not a guarantee that Chrome will behave exactly like a physical phone or monitor.

Goal	What to set	What to keep in mind
Inspect a particular responsive layout	The target CSS viewport width and height	Choose values relevant to the layout breakpoint or bug under investigation.
Compare two page layouts	The same dimensions for both captures	Keep other capture conditions consistent too, such as URL state and readiness.
Test a device-like layout	A viewport size, plus any required emulation settings in an automation workflow	--window-size alone is not a complete device profile.
Test a virtual display or multiple screens	Screen configuration options, if supported by your Chrome version	This is a separate, advanced setup; it is not required for an ordinary screenshot.

Do not assume that a larger window size creates a full-page screenshot. A viewport-sized capture and a full-page capture are different requirements. Use current documentation for your Chrome automation method and check the result against the Chrome version you run.

3. Bound how long Chrome waits before capturing

The Chrome CLI supports --timeout as a maximum wait, in milliseconds, before --screenshot proceeds. For example:

chrome --headless --screenshot --window-size=1280,900 --timeout=5000 https://example.com/

This sets a five-second upper bound before capture proceeds. A timeout is not proof that the application has finished rendering. A page may still be loading data, fonts, images, or other resources when the capture happens. For pages whose visual state depends on application logic, inspect the result and use a browser automation workflow with a readiness condition suited to that page.

4. Use automation when captures need to be repeatable

Chrome documents Puppeteer as an option for launching and controlling Headless Chrome. Use the direct CLI command for a one-off capture; use an automation library when your workflow needs repeatable browser control, page-specific readiness, or a larger capture process. See the Chrome Headless overview and the current Puppeteer documentation for its viewport API and launch options.

Before adopting an automation script, confirm the precise viewport method and defaults against the version of Puppeteer you install. Keep the browser version, viewport dimensions, URL, and readiness condition stable when comparing screenshots.

5. Know when you need virtual screen configuration

--window-size is the basic choice for a screenshot at a chosen width and height. Chrome also documents virtual-screen configuration for cases such as screen-scale or multi-monitor testing. Its --screen-info option configures the initial virtual screen; Chrome DevTools Protocol provides Emulation.addScreen and Emulation.removeScreen for changing virtual screens while Chrome is running.

Chrome documents this virtual-screen feature as available in stable releases starting with Chrome 142. It is an advanced display-testing path, not a requirement for the single-window command above. See Configure virtual screens in Headless mode.

6. Identify which Headless Chrome you are running

Chrome’s current Headless mode uses the unified Chrome implementation. The Headless overview says the mode was updated in Chrome 112. Starting with Chrome 132, the former separate Headless implementation is available as the standalone chrome-headless-shell binary. If captures differ between environments, record the actual binary and version before comparing behavior; two binaries described as Headless may not be the same implementation.

Read Chrome Headless mode for Chrome’s version notes.

7. Common problems and fixes

Symptom	Likely cause	What to do
Chrome reports that the command is not found	The executable is not on PATH, or has another name.	Find the installed Chrome binary and run it by its full path or actual executable name.
No screenshot appears where expected	The command saves to its current working directory, or the process could not complete.	Check the directory from which you ran the command, inspect Chrome’s error output, and set an explicit screenshot path if supported by your CLI version.
The screenshot has the wrong dimensions	The width and height may be reversed, mistyped, or the command may be invoking a different binary.	Use --window-size=WIDTH,HEIGHT, then confirm the executable and inspect the saved image dimensions.
The layout does not look like a phone	Window dimensions alone do not establish a complete device emulation profile.	Use an automation workflow and configure the device-related behavior your test requires. Consult that tool’s current documentation.
The capture shows a loading state or missing content	The timeout elapsed before the page reached the visual state you expected, or the page needs application-specific readiness.	Treat --timeout as a maximum wait, not a readiness guarantee. Validate the page state and use a suitable readiness condition for dynamic pages.
The capture is not full-page	A viewport size controls the window dimensions; it does not establish a verified full-page capture method.	Use a current full-page capture workflow documented for your automation tool and Chrome version.
Different machines produce different captures	They may use different Chrome versions or binaries, or differ in page state and capture timing.	Record the binary and version; standardize the URL, dimensions, and page readiness conditions before comparing results.

8. Performance, reliability, and cost

For a single local capture, the CLI has few setup steps: invoke Chrome with the desired size and URL. Larger dimensions can produce larger image files and require more rendering work, especially on complex pages. The exact time and output size depend on the page and environment; this guide makes no benchmark claims.

For reliable comparisons, keep the Chrome binary and version, viewport dimensions, target URL, and page state consistent. A bounded timeout prevents an indefinite wait in the documented capture flow, but it cannot make a dynamic page ready. If a page depends on delayed content, validate that content in the resulting image.

The command-line approach uses your installed Chrome. If you instead use a screenshot service, check its pricing and billing rules against your volume and capture requirements.

9. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. A GET request can return an image or PDF. For a WebP screenshot at a custom viewport, pass the viewport dimensions as query parameters; see the ScreenshotNeo API documentation for the available parameters.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://example.com",
        "width": 412,
        "height": 892,
    },
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
  width: '412',
  height: '892',
});
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', res);

With ScreenshotNeo, cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.

The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan. Learn about ScreenshotNeo, then sign up for 1,000 free screenshots a month, with no card.

Frequently asked questions

Does --window-size set device pixel ratio?

The cited Chrome CLI documentation establishes window dimensions; it does not establish a complete device profile. Configure and verify any additional emulation behavior your test requires using current automation documentation.

Is 412 by 892 the standard mobile size?

No. It is the size in Chrome’s documented example. Choose dimensions that match your own layout or test case.

Does --timeout wait until the page is fully loaded?

It is a maximum wait before capture proceeds. It does not guarantee that every page-specific task or visual element has completed.

Can I use --window-size for multi-monitor testing?

For virtual screen and multi-monitor scenarios, Chrome documents a separate screen configuration path. Check the version requirements and setup in its virtual screen guide.