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 errorsUse await puppeteer.launch({ headless: true }) to run Puppeteer with new headless Chrome and no visible browser window. In current Puppeteer, headless: 'shell' selects the separate chrome-headless-shell binary, while headless: false opens visible Chrome. Headless mode hides the UI; it does not remove the browser process.
Run Puppeteer in headless mode
Puppeteer runs headless by default. Setting the option explicitly makes the intended mode clear, especially when you later switch between headless Chrome, the shell binary, and visible Chrome. The following complete example opens a page, prints its title, and closes the browser even if an error occurs.
const puppeteer = require('puppeteer');
(async () => {
let browser;
try {
browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
if (browser) await browser.close();
}
})();Save this as index.js, install Puppeteer with npm install puppeteer, then run node index.js. The puppeteer package normally downloads a compatible Chrome for Testing browser and chrome-headless-shell during installation. See the official installation guide for setup details.
Choose the right headless mode
| Option | What it runs | Use it when | Important consideration |
|---|---|---|---|
headless: true |
New headless Chrome; the documented default. | You want general-purpose Puppeteer automation without a visible window. | This is distinct from the shell binary. See Puppeteer’s headless modes guide and LaunchOptions. |
headless: 'shell' |
The separate chrome-headless-shell implementation. |
Your automation does not need the complete Chrome feature set and the shell’s workload-dependent performance tradeoff suits it. | Its behavior does not completely match regular Chrome; Puppeteer provides no universal comparative benchmark. See the headless modes guide. |
headless: false |
Visible, headful Chrome. | You need to inspect the page or debug what the browser is doing. | This is not headless mode. Setting devtools: true also forces headless: false. See LaunchOptions. |
Choose based on browser behavior and feature coverage first, then visibility and workload needs. Do not assume shell mode is always faster: its performance advantage is described for automation tasks that do not require Chrome’s complete feature set.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
Use a separately managed browser when needed
Prefer Puppeteer’s bundled browser unless you have a reason to manage Chrome separately. Puppeteer guarantees compatibility with the browser version it downloads, but does not guarantee other versions. The supported-browser mapping changes with releases: Puppeteer v25.12.0 lists Chrome for Testing 154.0.8037.57. Treat that as a version-specific mapping, not a permanent Chrome requirement. Check the supported browsers page for the mapping relevant to your installed release.
When you supply your own browser executable, pass its path through executablePath or select a channel with channel. With puppeteer-core, which does not download Chrome, one of those choices is required. That package is intended for remote browsers or environments where browser installation is managed separately. See PuppeteerNode.launch().
Rank #2
const puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
headless: true,
executablePath: '/path/to/chrome'
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}
})();Replace /path/to/chrome with the actual browser executable for your environment. Browser availability, path, and version compatibility are your responsibility when you choose this setup.
Debug a page with the browser visible
If a page behaves differently than expected in headless mode, relaunch visibly to inspect it. Puppeteer’s debugging guide recommends setting headless: false; slowMo can slow browser operations so you can follow them.
const browser = await puppeteer.launch({
headless: false,
slowMo: 100
});Use visible mode as a debugging aid, then return to headless mode for unattended runs if that better matches your deployment.
Fix common launch failures
Puppeteer cannot find Chrome
Package managers or deployment systems may block install scripts, leaving the Puppeteer package present but its browser missing. Install the browser explicitly with npx puppeteer browsers install, as described in the installation documentation. If you use puppeteer-core, install or provision the browser yourself and provide its executable path or channel.
Chrome exits on Linux
Check that the host has the shared libraries and system dependencies Chrome needs. Puppeteer’s troubleshooting guide lists dependencies by distribution and discusses sandbox configuration. Resolve missing dependencies or the underlying sandbox issue rather than adding flags blindly.
Do not treat --no-sandbox as a routine fix
Chrome’s sandbox helps protect the host from untrusted web content. Puppeteer strongly discourages disabling it with --no-sandbox; investigate the host’s sandbox configuration and dependencies instead. Only consider a change to sandboxing after understanding the security implications for your specific environment.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- Used Book in Good Condition
GPU acceleration with the shell binary
If you use headless: 'shell' and need GPU acceleration, Puppeteer documents the shell-specific --enable-gpu flag. This is not a general requirement for every headless Chrome launch. See the troubleshooting guide.
Or skip the browser setup
If your task is simply to capture a web page rather than automate a browser session, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Here is a cURL example; see the ScreenshotNeo documentation for API options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp- Cookie and consent banners are accepted like a visitor, and 60+ known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Each response indicates the page verdict and billing status in headers.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents using Claude, Cursor, or another MCP client. - The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Puppeteer need Chrome installed separately?
The regular puppeteer installation downloads a browser; puppeteer-core does not.
Does headless: 'shell' behave exactly like Chrome?
No. Puppeteer says shell behavior does not completely match regular Chrome.
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.
