ScreenshotNeo

BlogHow-to

How to Fix Incorrect Scaling and Resolution in Chromium Headless Screenshots

Fix blurry, oversized, or wrongly sized Chromium headless screenshots by separating viewport, virtual screen, device scale factor, and capture timing.

By the ScreenshotNeo team30 September 20269 min read

How to Fix Incorrect Scaling and Resolution in Chromium Headless Screenshots

Incorrect Chromium screenshot size usually comes from mixing four different layers: the requested window or screenshot dimensions, the page’s CSS viewport, the virtual display and device scale factor, and the moment capture occurs. Measure each layer separately before changing flags.

A reliable debugging sequence is:

  1. Record the exact browser binary, version, headless mode, automation library, screenshot API, operating system or container, and launch arguments.
  2. Measure window.innerWidth, window.innerHeight, devicePixelRatio, screen dimensions, and the output bitmap dimensions.
  3. Use --window-size=WIDTH,HEIGHT for the target capture size.
  4. Use virtual-screen configuration or CDP screen emulation only when the page must behave as if it runs on a particular display.
  5. Treat loading and rendering timing as a separate problem from resolution.

Why Chromium screenshots have several sizes

A screenshot can have a requested size in CSS pixels and a different bitmap size in physical pixels. A page can also see a virtual screen whose size and scale factor differ from the screenshot command. Finally, a screenshot can have the right dimensions but capture an incomplete page because fonts, lazy images, timers, or network requests were still running.

Measure the viewport, virtual display, timing, and output bitmap as separate layers.
Measure the viewport, virtual display, timing, and output bitmap as separate layers.
Layer What it controls How to inspect or set it
Screenshot or window bounds The requested capture area --window-size=WIDTH,HEIGHT
CSS viewport What responsive CSS and JavaScript see window.innerWidth, window.innerHeight; automation viewport APIs
Virtual display Screen size, scale factor, orientation, work area, and multiple displays --screen-info, CDP Emulation.addScreen
Bitmap output The actual PNG, JPEG, or WebP pixel dimensions Read image metadata after capture
Capture timing Which page state is rendered into the bitmap --timeout, --virtual-time-budget, waits in your automation library

Start with a reproducible diagnostic

Save the exact command and environment before trying fixes. Chromium’s headless packaging is version-sensitive: precompiled headless shell binaries have been distributed as chrome-headless-shell through Chrome for Testing since M118, and the old Headless implementation was removed from the Chrome binary in M132. On current Chrome, --headless=old has no effect. See the Chromium Headless README.

google-chrome --version
which google-chrome chromium chromium-browser chrome-headless-shell 2>/dev/null || true
node --version
python --version

Record these values:

  • Browser name and complete version.
  • Binary path and whether it is Chrome, Chromium, or chrome-headless-shell.
  • Headless mode and every command-line flag.
  • Puppeteer, Playwright, Selenium, or CDP version.
  • Expected CSS viewport dimensions.
  • Expected output pixel dimensions.
  • Actual output dimensions and a minimal URL that reproduces the issue.

Measure the page’s CSS viewport and scale

Run this JavaScript in the page or through your automation protocol:

JSON.stringify({
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
  outerWidth: window.outerWidth,
  outerHeight: window.outerHeight,
  devicePixelRatio: window.devicePixelRatio,
  screen: {
    width: screen.width,
    height: screen.height,
    availWidth: screen.availWidth,
    availHeight: screen.availHeight
  },
  visualViewport: window.visualViewport ? {
    width: window.visualViewport.width,
    height: window.visualViewport.height,
    scale: window.visualViewport.scale
  } : null
}, null, 2)

Compare those values with the image’s metadata. If the CSS viewport is correct but the bitmap is exactly two or three times larger, investigate the device scale factor or virtual screen. If the bitmap is correct but the page layout is wrong, investigate the viewport. If both are correct but content is missing, investigate timing.

Fix the CLI screenshot path

For a static capture where the target screenshot dimensions are the main requirement, use a positive integer width and height with --window-size. Chrome’s documented example pairs that flag with --screenshot; the default output filename is screenshot.png. See the Chrome Headless command-line documentation.

google-chrome \
  --headless \
  --disable-gpu \
  --window-size=412,892 \
  --screenshot=shot.png \
  https://developer.chrome.com/

Use plain positive integers. Values such as 1280px, missing commas, zero, negative numbers, or a nonnumeric height are invalid. Chromium’s current headless command handler rejects malformed or nonpositive values and can ignore them, leaving a default size in effect. Always inspect the produced image rather than assuming the flag was accepted.

Check the output dimensions

identify shot.png
# or, with Python and Pillow:
python - <<'PY'
from PIL import Image
im = Image.open('shot.png')
print(im.size)
PY

If your requested width and height are 1280 by 720 but the file is 2560 by 1440, the page may be rendered with a device scale factor of 2. That can be correct for a high-density virtual display; it is not evidence that the CSS viewport is wrong.

Set the CSS viewport in automation

When using Puppeteer, set the viewport explicitly and then verify it inside the page. Keep viewport dimensions and screenshot options conceptually separate.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  args: ['--window-size=1280,720']
});
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 1 });
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
console.log(await page.evaluate(() => ({
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
  devicePixelRatio: window.devicePixelRatio
})));
await page.screenshot({ path: 'shot.png', fullPage: false });
await browser.close();

With Playwright, the equivalent is:

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({
  viewport: { width: 1280, height: 720 },
  deviceScaleFactor: 1
});
const page = await context.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle' });
await page.screenshot({ path: 'shot.png' });
await browser.close();

Do not use both a library-level viewport and a conflicting command-line size without checking the result. The browser can start with one window size while the automation context emulates another viewport.

When to use virtual screen configuration

Use a virtual screen when the page must respond to display characteristics such as screen size, scale factor, orientation, work area, or multiple monitors. Chrome documents that headless mode uses a configurable virtual screen independent of physical displays. Current virtual-screen configuration is version-sensitive and is documented for stable Chrome releases starting with version 142.

The command-line --screen-info option describes virtual displays. In a running browser, the DevTools Protocol provides Emulation.addScreen and Emulation.removeScreen for dynamic monitor scenarios. Chrome documents these features for Puppeteer and CDP workflows. Use them only when you need display-aware behavior; they are unnecessary for a single fixed bitmap.

google-chrome \
  --headless \
  --screen-info='{"workArea":{"x":0,"y":0,"width":1920,"height":1080},"devicePixelRatio":2}' \
  --window-size=1280,720 \
  --screenshot=shot.png \
  https://example.com

The exact accepted --screen-info schema depends on the browser build. Check that build’s documentation and log output before relying on a complex multi-display configuration. If your only requirement is a 1280 by 720 image, start with --window-size=1280,720 and an explicit automation device scale factor.

Understand device scale factor and apparent zoom

window.devicePixelRatio expresses the relationship between CSS pixels and device pixels. A value of 2 commonly produces a bitmap twice as wide and twice as tall for the same CSS viewport. It also changes how raster assets and media queries behave.

Correct dimensions do not guarantee a complete page; readiness controls what gets captured.
Correct dimensions do not guarantee a complete page; readiness controls what gets captured.

Debug in this order:

  1. Record devicePixelRatio from the page.
  2. Record virtual-screen scale information if you configured a screen.
  3. Compare CSS viewport dimensions with bitmap dimensions.
  4. Only then change deviceScaleFactor or virtual-screen scale.

Changing page CSS, applying a transform, or shrinking content to compensate for a bitmap ratio hides the cause and can break responsive layouts. Set the scale at the browser or emulation layer when you need a specific pixel density.

Separate resolution from capture timing

A screenshot with the right dimensions can still look wrong because capture happened too early. Chrome’s --timeout flag defines the maximum wait before capture even if loading continues. The --virtual-time-budget flag advances timer-driven page code. Both affect page state, not intended resolution.

google-chrome \
  --headless \
  --window-size=1440,900 \
  --timeout=10000 \
  --virtual-time-budget=5000 \
  --screenshot=shot.png \
  https://example.com

For automation, wait for the condition that represents readiness:

await page.goto(url, { waitUntil: 'networkidle0', timeout: 30000 });
await page.waitForSelector('#main-content', { visible: true, timeout: 10000 });
await page.evaluate(() => document.fonts ? document.fonts.ready : null);
await page.screenshot({ path: 'shot.png', fullPage: true });

Lazy-loaded images may require scrolling or an application-specific readiness signal. A timeout does not guarantee that every image, font, animation, or client-side request has completed.

Common symptoms and fixes

Symptom Likely cause Fix
Bitmap is exactly 2× or 3× larger Device scale factor or virtual display scale Compare devicePixelRatio with output dimensions; set the intended scale explicitly.
Responsive layout uses the wrong breakpoint CSS viewport differs from window size Inspect innerWidth; set the automation viewport directly.
Requested size is ignored Malformed --window-size syntax Use WIDTH,HEIGHT with positive integers and check logs.
Screenshot is correct size but blank Capture occurred before navigation or rendering finished Wait for navigation, a selector, fonts, and required application state.
Images are missing below the fold Lazy loading depends on scrolling or intersection observers Scroll through the page or trigger the site’s documented loading path before capture.
Old headless flags have no effect Running Chrome M132 or later Use current headless mode or the separately distributed chrome-headless-shell.
Page changes between runs Animations, timers, ads, or network responses Freeze or disable animation where appropriate, use a deterministic wait, and control virtual time.
Full-page shot has unexpected width Full-page capture uses document dimensions rather than the viewport Measure document scroll width separately and avoid treating full-page output as a viewport screenshot.

Performance, reliability, and cost

Performance

  • Use one browser process with reused pages or contexts for batches instead of launching Chrome for every URL.
  • Choose the smallest viewport and scale factor that meet your output requirement.
  • Disable unnecessary animation and third-party requests in controlled test environments.
  • Wait for a specific readiness condition instead of using an unnecessarily long fixed delay.
  • For full-page captures, account for image decoding, lazy loading, fonts, and the larger bitmap in memory.

Reliability

  • Pin or record the browser build, automation library, and flags.
  • Log viewport, device scale factor, screen information, URL, timing settings, and output dimensions with each failure.
  • Use a minimal reproduction URL and compare a normal headful run with headless output when behavior diverges.
  • Do not infer a resolution problem from a visually incomplete page until timing and network state are checked.

Cost

Local Chromium has infrastructure and maintenance costs but no per-shot API charge. Hosted screenshot services generally price captures, bandwidth, or browser runtime differently, so compare the billing unit that matches your workload. If failed loads and bot checks are a significant part of a pipeline, check whether those attempts are billable.

Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server when you want a clean image without maintaining Chromium launch flags. The API accepts one GET request and returns PNG, JPEG, WebP, or PDF. Read the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Before capture, ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether the shot was billed. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Why is my headless Chrome screenshot twice the expected size?

Check devicePixelRatio and virtual-screen scale first. A CSS viewport of 1280 by 720 with a scale factor of 2 can produce a 2560 by 1440 bitmap.

How do I set the viewport size for a Chromium screenshot?

For the CLI, use --window-size=WIDTH,HEIGHT. In Puppeteer or Playwright, set the context or page viewport and verify window.innerWidth inside the page.

Should I use --timeout to fix blurry screenshots?

No. --timeout changes when capture occurs. Blurriness or a pixel-size ratio usually points to scale factor, image decoding, fonts, or output processing.

When do I need --screen-info?

Use it when the page must behave as though it is on a particular virtual display. A fixed screenshot size usually only needs an explicit window or viewport size.

What should I include in a Chromium scaling bug report?

Include the browser build and binary, operating system or container, headless mode, flags, automation and CDP versions, expected and actual CSS viewport values, device pixel ratio, output dimensions, and a minimal reproduction.