Free tools Windows power users keep installed
One-click scans. No signup required.
In current Puppeteer, launch Chrome without a visible window with await puppeteer.launch({ headless: true }). That is the default, and it selects new headless Chrome. Use headless: 'shell' when you specifically want the separate chrome-headless-shell binary, or headless: false to open a visible browser for debugging.
What Puppeteer headless mode means
Headless means the browser runs without displaying its usual user interface; Puppeteer still starts and controls a browser process. Puppeteer supports Chrome and Firefox through the DevTools Protocol or WebDriver BiDi, and runs headless by default. See Puppeteer’s overview.
As an Amazon Associate I earn from qualifying purchases.
Choose the right headless setting
| Setting | Browser mode | When to use it | Trade-off |
|---|---|---|---|
headless: true |
New headless Chrome | General headless automation; this is the documented default. | It is distinct from the older shell implementation. |
headless: 'shell' |
The separate chrome-headless-shell binary |
Automation that does not need the full Chrome feature set. | Its behavior does not completely match regular Chrome. Puppeteer says it can be more performant for suitable tasks, but provides no universal benchmark. |
headless: false |
Visible, headful Chrome | When you need to watch the page or investigate behavior visually. | This is not headless; devtools: true also forces visible mode. |
These settings and caveats are documented in Puppeteer’s headless-mode guide and LaunchOptions reference. Avoid choosing shell mode solely on an assumption that it is always faster.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsInstall Puppeteer and launch Chrome
For a local project, install the full puppeteer package. Its installation normally downloads a compatible Chrome for Testing browser and chrome-headless-shell. The minimal headless launch is:
#1 Best Overall
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
console.log(await page.title());
} finally {
await browser.close();
}
})();Save it as shot.js and run node shot.js. The finally block closes Chrome even if navigation or page work fails. Replace headless: true with headless: 'shell' or headless: false to select the other modes.
For an ES module project, import Puppeteer instead: import puppeteer from 'puppeteer';. The browser launch and cleanup pattern is otherwise the same.
Rank #2
Use the bundled browser or manage one yourself
Bundled Puppeteer browser
For the simplest setup, use puppeteer and its downloaded browser. Puppeteer guarantees compatibility with the browser version it downloads and recommends this pairing. Package managers sometimes block install scripts, preventing browser download; if that happened, install it explicitly with npx puppeteer browsers install. See the installation guide.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →External browser or puppeteer-core
puppeteer-core is the library-only package: it does not download Chrome and is intended for remote browsers or setups where browser management is external. With puppeteer-core, provide an executablePath or channel when launching. For example, adapt the path to the Chrome binary installed in your environment:
const puppeteer = require('puppeteer-core');
const browser = await puppeteer.launch({
executablePath: '/path/to/chrome',
headless: true,
});Puppeteer works best with its corresponding Chrome for Testing build and does not guarantee compatibility with other browser versions. See PuppeteerNode.launch(). As a version-specific reference, Puppeteer v25.12.0 lists Chrome for Testing 154.0.8037.57; browser mappings change with Puppeteer releases, so check the supported-browser table for the version you install: Supported browsers.
Debug a page by making Chrome visible
If a page behaves unexpectedly and you need to inspect what Chrome displays, launch with headless: false. Puppeteer’s debugging guide also documents slowMo to slow operations so you can follow them:
const browser = await puppeteer.launch({
headless: false,
slowMo: 100,
});Use a nonzero delay only while debugging; it adds time to automated actions. When you have identified the issue, switch back to the appropriate headless mode.
Troubleshoot launch and rendering failures
- Puppeteer cannot find Chrome: A package manager may have blocked install scripts. Run
npx puppeteer browsers install, or configure the external browser path or channel for a separately managed browser. - Chrome exits immediately on Linux: Check that required shared libraries and system dependencies are installed for your distribution. Puppeteer’s troubleshooting guide lists dependencies and related platform issues.
- Chrome cannot create its sandbox: Resolve the host’s sandbox configuration rather than routinely disabling the sandbox. Puppeteer strongly discourages the
--no-sandboxargument because Chrome’s sandbox protects the host from untrusted web content. - Shell-mode GPU acceleration is unavailable: For
chrome-headless-shell, Puppeteer documents--enable-gpuas necessary for GPU acceleration. This is a shell-specific caveat, not a general requirement for every headless Chrome launch. - The page differs between modes: Confirm whether you selected new headless Chrome or
'shell'; the shell does not fully match regular Chrome. Switch toheadless: falseto inspect the page visually.
Or skip the browser setup
If your task is simply to capture a website screenshot rather than control a browser session, ScreenshotNeo returns an image or PDF from one GET request. For example, save this as shot.webp (replace the URL with the page you need):
Best Value
- Used Book in Good Condition
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options. Before capture, it accepts consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides screenshot, page-info and PDF tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month—no card required.
Frequently Asked Questions
Does headless mode mean Puppeteer does not start Chrome?
No. Chrome still runs as a browser process; headless means it has no visible UI.
Can I use Puppeteer headless mode with a browser other than Chrome?
Puppeteer supports Chrome and Firefox, but the launch modes described here distinguish new headless Chrome from the separate Chrome headless-shell binary.
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.
