Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If Chrome’s command-line screenshot is missing, blank, too small, or captured before the page finished rendering, first verify four things: the exact Chrome executable, the arguments actually received, the process’s current working directory, and the installed Chrome version. Chrome’s documented --screenshot flag writes screenshot.png to the process’s current working directory; --window-size=WIDTH,HEIGHT sets the viewport and --timeout=MILLISECONDS limits how long Chrome waits before capturing.
Use the diagnostic sequence below rather than adding random flags. It separates a launch problem from a file-location problem, viewport or timing issue, and advice written for an older Headless implementation.
Run a known-good command first
Use a simple public URL and an explicit viewport. Replace the executable name or path with the Chrome or Chromium binary installed on your machine.
Linux
google-chrome --headless --screenshot --window-size=1365,768 --timeout=10000 https://example.comSome Linux installations call the binary chromium or chromium-browser. Use the name that resolves on your system.
#1 Best Overall
macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless --screenshot --window-size=1365,768 --timeout=10000 https://example.comIf Chrome is installed elsewhere, substitute that path and keep the quotes around paths containing spaces.
Windows PowerShell
& "C:Program FilesGoogleChromeApplicationchrome.exe" --headless --screenshot --window-size=1365,768 --timeout=10000 https://example.comThe installation path can differ between system-wide and per-user installations. PowerShell’s call operator (&) is needed when the executable path is quoted.
After the command exits, look for screenshot.png in the launching process’s current working directory, not necessarily in Downloads or beside the Chrome executable. The official reference documents this default and the two capture switches: Chrome Headless command-line reference.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchFind out what actually ran
Check the executable and version
Confirm that the command invokes the browser version you think it does. A script, IDE, scheduled task, container image, or shell alias can resolve a different binary than an interactive terminal.
- On Linux or macOS, resolve the command with your shell’s normal command-location facility and run the binary with its version option.
- On Windows, inspect the resolved application path and run that executable’s version option.
- Record the complete command, operating system, Chrome version, and console output before changing flags.
Chromium’s switch guidance recommends opening chrome://version in the relevant Chrome instance. Its “Command Line” field shows the effective arguments, which is useful when a launcher or an already-running process has changed what you supplied. See Run Chromium with command-line switches. Switches are developmental interfaces and can change or disappear, so do not assume an old blog post still matches your build.
Rank #2
Check for an already-running instance
If Chrome was already open, your launcher may have connected to an existing process instead of starting a fresh one. Do not assume this is the cause without evidence: compare the command you typed with the command shown in chrome://version, then close the test instance or use a separately managed profile and repeat the test.
Locate the missing file
Prove the working directory
The screenshot destination is relative to the process’s current working directory. Print that directory immediately before launching Chrome.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →pwdIn PowerShell, use:
Get-LocationRun Chrome from a directory where the launching user can create files, then list that directory after Chrome exits. When the command runs from an IDE, service, scheduler, Docker entrypoint, or CI runner, inspect that component’s working-directory setting instead of assuming it is your terminal directory.
Check write access
A process can start successfully yet fail to create screenshot.png because its working directory is read-only or owned by another user. Test file creation there with the same account that launches Chrome. Correct the directory or account configuration first. The documented command-line reference establishes the default filename and location; it does not define one universal custom-output-path syntax for every Chrome build, so do not invent a path flag based on an unrelated tool.
Fix viewport and timing problems
Unexpected dimensions
Add an explicit size:
google-chrome --headless --screenshot --window-size=1920,1080 https://example.com--window-size=WIDTH,HEIGHT controls the capture viewport. If you need a different result, change both numbers and verify the image dimensions rather than judging by a preview that may scale it.
The page is captured too early
Use a bounded wait:
google-chrome --headless --screenshot --timeout=15000 https://example.comThe value is in milliseconds. Chrome captures after the maximum wait even if loading is unfinished; increasing it therefore does not guarantee that a site’s asynchronous data, fonts, animations, or client-side application has settled. If a page still looks incomplete, capture a simpler test URL and compare the result, then collect the URL, command, version, and output when investigating the site-specific behavior. The available command-line documentation does not establish a universal flag that waits for every framework’s “finished rendering” event.
Blank or partially rendered images
A blank image can result from an application that has not rendered by the timeout, a page that behaves differently without a visible UI, or a launch/runtime problem. Work through the following checks in order:
- Capture
https://example.comwith the known-good command. If it works, the original URL needs page-specific investigation. - Increase
--timeouttemporarily and compare the image. Treat any improvement as evidence about timing, not proof that a particular delay is universally correct. - Verify the viewport with
--window-size. - Check
chrome://versionand the browser’s console output for the effective command line and version. - Run from a writable working directory under the same user and runtime that failed.
Account for Chrome Headless version changes
Headless behavior is version-sensitive. Chrome’s current documentation notes a major change in Chrome 112: Headless mode began creating platform windows without displaying them, while retaining other Chrome functionality. Older tutorials may describe a separate Headless implementation or recommend switches that are no longer needed. Start with the current Chrome Headless mode documentation and record your installed version before adapting legacy commands.
Do not treat a command copied from an old Headless Shell article as a drop-in fix for current Chrome. Compare its assumptions with the current command-line reference and remove flags that your version does not document.
Container and sandbox checks
When Chrome runs in a container, verify the runtime user, writable directories, shared-memory and display-related configuration used by your image, and the exact binary version. The Headless Chrome Shell guidance says --no-sandbox is unnecessary when a container is properly configured with a user. It is not a universal screenshot repair and disabling a security boundary should not be your first response to a missing image. See Headless Chrome shell for the documented container-user note.
Free tools Windows power users keep installed
One-click scans. No signup required.
Symptom-to-fix checklist
| Symptom | Most useful evidence | Next action |
|---|---|---|
| No file appears | Working directory, write test, exit output | Run from a known writable directory and look there for screenshot.png. |
| File is in an unexpected place | pwd or Get-Location from the launching process |
Change the script, IDE, service, or scheduler working directory. |
| Image is the wrong size | Effective command in chrome://version |
Set --window-size=WIDTH,HEIGHT explicitly. |
| Image is incomplete | URL type, timeout value, version, and before/after images | Test a longer bounded --timeout; investigate page-specific asynchronous rendering. |
| Command behaves unlike documentation | Chrome version and effective command line | Use current Headless documentation instead of legacy instructions. |
| Container launch fails | Container user, filesystem permissions, binary version, logs | Fix the runtime user and filesystem first; do not add --no-sandbox reflexively. |
Make the diagnosis reproducible
For a bug report or team handoff, include:
- Operating system and whether the process runs locally, in a container, CI runner, service, or scheduler.
- The exact executable path and complete command, with secrets removed.
- Chrome version and the command line shown by
chrome://version. - The URL type (static page, client-rendered application, authenticated page, or other) and the timeout and viewport values.
- The launching directory, its permissions, whether any file was created, and the complete stderr/stdout output.
- Whether a simple public URL succeeds with the same binary.
This information distinguishes a file-location failure from a timing or page-rendering problem without guessing at the cause.
Or skip the browser setup
If you need repeatable screenshots in scripts rather than a local Chrome diagnosis, ScreenshotNeo is the first managed option to try: it removes common consent banners and other clutter before capture, bills only clean shots, and has the lowest paid plan listed here.
One GET request returns a PNG, JPEG, WebP, or PDF. The API accepts a URL and access key; the complete documentation is at ScreenshotNeo API documentation.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before the shot; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether the request was billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients, so an AI agent can request captures without managing a browser process.
Options for jobs that outgrow a one-line capture
- Full-page capture loads lazy images; CSS-selector element capture, dark mode, 12 device presets, arbitrary viewports, and retina scale handle layout variants.
- PDF output supports paper size, margins, landscape orientation, and page ranges.
- Custom CSS and JavaScript, pre-capture clicks, hidden selectors, waits for a selector, delay, or network idle, and blocking of ads, trackers, requests, or resource types address page-specific rendering.
- Custom headers, cookies, user agent, Authorization, timezone, geolocation, transparent backgrounds, image resizing, and a selectable cache TTL cover controlled environments.
- Signed links work in public
<img>tags; asynchronous jobs can call signed webhooks; bulk capture accepts 100 URLs per call. - A usage API and OpenAPI specification support monitoring and integration. Parameter names used by other screenshot APIs also work, easing migration.
Plans
| Plan | Included shots | Listed price |
|---|---|---|
| Free | 1,000 per month | No card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Every feature is available on every plan, and yearly billing gives two months free. Start with 1,000 free screenshots a month with no card, then move to paid plans starting at $5 for 3,000 shots if your workload requires it.
Frequently Asked Questions
Which details matter most when a screenshot failure cannot be reproduced?
The exact executable path, complete arguments, operating system, Chrome version, launching directory, runtime type, URL, timeout, viewport, and console output let another person reproduce the same process instead of testing a different setup.
Where should I check whether a switch was actually applied?
Open chrome://version in the Chrome instance involved and inspect its Command Line field; it shows the effective arguments rather than only what a shortcut or script intended to pass.
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.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →
