Set the requested dimensions, then verify what Chrome actually used. A Selenium screenshot’s size can differ because the browser window was not resized, the page’s CSS viewport differs from the outer window, or device scaling changes the image’s pixel dimensions. Check all three before changing settings.
Measure the window, viewport, and screenshot separately
Do not assume that --window-size alone proves the screenshot will have those pixel dimensions. Record these values after Chrome starts:
As an Amazon Associate I earn from qualifying purchases.
- WebDriver window size: the dimensions Selenium reports for the browser window.
- Page viewport:
window.innerWidthandwindow.innerHeight, which describe the page’s CSS viewport. - Raster size: the actual width and height of the saved PNG or other image file.
Also log window.devicePixelRatio and window.screen.width/height. They help distinguish a viewport mismatch from device-scale or emulation effects. Chrome DevTools documents device metrics overrides that can affect page-visible screen and viewport values as well as device scale factor: Chrome DevTools Protocol: Emulation.setDeviceMetricsOverride.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsSet and verify the headless Chrome window size
- Pass an explicit size when creating the Chrome session. ChromeDriver’s options documentation demonstrates the
window-size=1000,800argument form: ChromeDriver capabilities. - Read the size after startup. Use Selenium’s window-management API to inspect or set the window dimensions: Selenium WebDriver drivers and window management.
- Compare the page metrics with the file’s pixel dimensions. If the window value is wrong, investigate whether the option reached Chrome and whether the driver applied it. If the CSS viewport is wrong, adjust the effective window or deliberately use device emulation. If the CSS values match but the image pixels do not, investigate scaling.
Runnable Python diagnostic
This diagnostic sets a requested window size, prints the observed window and page metrics, and saves a screenshot. It is a documented-API pattern, not a guarantee that every operating system or runtime will produce identical image dimensions.
#1 Best Overall
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1440,900")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print("webdriver window:", driver.get_window_size())
print("page metrics:", driver.execute_script("""
return {
innerWidth: window.innerWidth,
innerHeight: window.innerHeight,
screenWidth: window.screen.width,
screenHeight: window.screen.height,
devicePixelRatio: window.devicePixelRatio
}
"""))
driver.save_screenshot("page.png")
finally:
driver.quit()Inspect page.png with an image viewer or image-metadata tool and compare its pixel width and height with the printed values. Selenium documents both reading window dimensions and taking screenshots of the current browsing context: Selenium WebDriver documentation.
Choose desktop sizing or device emulation intentionally
For an ordinary desktop viewport
Start with the explicit Chrome window argument and Selenium’s window-management API. Verify the observed window and page values rather than treating the configured value as proof of the effective viewport.
Rank #2
For a simulated device viewport
Use Chrome DevTools Protocol device metrics when you specifically need to emulate a device. Emulation.setDeviceMetricsOverride can override width, height, device scale factor, screen dimensions, and mobile emulation. Some protocol parameters are marked experimental; use the protocol supported by the Chrome version you run. This is a different control from resizing an ordinary desktop browser window.
Check headless mode and browser-driver versions
Chrome’s headless documentation shows --headless=new for Selenium and a command-line example combining --screenshot with --window-size: Chrome Headless mode. The documentation introduces new Headless in Chrome 112 and explains that it creates, but does not display, platform windows.
Selenium’s Chrome-specific guidance says the Chrome browser and ChromeDriver versions should match at the major-version level: Selenium on Chrome. Check the actual Chrome, ChromeDriver, Selenium, and operating-system versions when diagnosing a mismatch.
User-submitted reports illustrate why version and platform details matter, but do not establish a universal current bug. A 2023 report concerned Chrome/ChromeDriver 110 and a requested 1920×1080 size; a 2025 report described Linux, Chrome 137.0.7151.68-1, Selenium 4.33, and a reported window around 800×600: 2023 Selenium issue and 2025 Selenium issue. Treat these as clues for matching your environment, not evidence that current headless Chrome always ignores the size flag.
Wait for the page state you intend to capture
Screenshot timing can affect what content appears, but waiting does not itself change the viewport dimensions. In Selenium, wait for the page state your test needs—such as a specific element becoming visible—before calling save_screenshot. For Chrome’s command-line screenshot option, the headless documentation describes capture after page load and options involving a timeout or virtual-time budget.
Troubleshoot by comparing observed values
get_window_size()is not the requested size: confirm that the Chrome option was added to the options object passed to the driver, inspect session startup and driver behavior, then check browser and driver versions.- Window size looks right but
innerWidth/innerHeightdo not: the page’s effective viewport is not the same as the reported outer window dimensions. Check the effective window configuration and whether device metrics or mobile emulation are active. - CSS viewport values match but the image pixel dimensions differ: inspect
devicePixelRatio, device-scale-factor overrides, and any image scaling in the capture path. - The image has the right dimensions but the wrong content: wait for the relevant page state before capturing; investigate loading or navigation timing separately from sizing.
- The mismatch appears only on a particular runtime: record Chrome, ChromeDriver, Selenium, operating system, requested dimensions, all observed metrics, and saved image dimensions. Compare like-for-like before concluding that a flag is ignored.
Or skip the browser setup
If you need a clean website capture rather than a Selenium browser session, ScreenshotNeo returns an image or PDF from one GET request. Its API supports PNG, JPEG, or WebP output and PDF capture. The cookie-banner, popup, and chat-widget cleanup can be turned off step by step; the service says bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. It also offers an MCP server with screenshot, page-info, and PDF tools for AI agents. Plans include 1,000 shots per month free with no card; paid plans start at $5 for 3,000 shots. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSign up for 1,000 free screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
