What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
In Puppeteer v25.12.0, set headless: 'shell' to launch the separate chrome-headless-shell binary; headless: true launches Chrome’s newer headless mode. Use Shell when its behavior fits your automation and you want the mode Puppeteer describes as currently more performant for tasks that do not need the complete Chrome feature set. The two modes are not interchangeable in every workload, so validate the browser features your task depends on.
What the Headless Shell settings control
There are two distinct layers of configuration: install-time settings control how Puppeteer obtains the Shell binary, while launch options control which browser Puppeteer runs and how it runs it. Changing an install-time setting does not by itself select Shell for a particular browser launch.
Install-time configuration
The chrome-headless-shell section of Puppeteer configuration has three documented settings:
| Setting | What it controls | Environment override |
|---|---|---|
downloadBaseUrl |
URL prefix used for browser downloads. It must include a protocol and must not end with a trailing slash. | PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL |
skipDownload |
Whether to skip downloading the Shell binary during installation. | PUPPETEER_CHROME_HEADLESS_SHELL_SKIP_DOWNLOAD or PUPPETEER_SKIP_CHROME_HEADLESS_SHELL_DOWNLOAD |
version |
The Shell version to acquire. By default, Puppeteer pins the version for the current Puppeteer release. | PUPPETEER_CHROME_HEADLESS_SHELL_VERSION |
These settings affect acquisition and versioning of the binary; they are not runtime launch switches.
#1 Best Overall
Runtime launch options
headless: 'shell'selects Headless Shell.headless: trueselects the newer headless Chrome implementation.argspasses additional browser command-line arguments.executablePathpoints Puppeteer at a specific executable.channelselects an installed Chrome release channel.ignoreDefaultArgsremoves Puppeteer’s default arguments entirely or filters selected ones. Use it carefully because changing defaults can affect browser startup and behavior.
Puppeteer guarantees compatibility only with its bundled browser. An externally managed executable or channel may work, but can introduce version or behavior mismatches.
Launch Chrome Headless Shell
Install the puppeteer package, which normally downloads Chrome for Testing and a chrome-headless-shell binary. Then use headless: 'shell' in the launch call. This complete Node.js example opens a page, waits for navigation, reads its title, and closes the browser even if an error occurs:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: 'shell',
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}
})();Run it with node after installing the package. If you use an ES module project, adapt the import syntax to that project’s module configuration; the launch option remains the same.
Adding launch arguments
Pass additional browser flags in args. For example, enable GPU acceleration only if the environment supports it and your task needs it:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →const browser = await puppeteer.launch({
headless: 'shell',
args: ['--enable-gpu'],
});Puppeteer’s troubleshooting guidance says Headless Shell requires --enable-gpu to enable GPU acceleration in headless mode. This does not mean every deployment has usable GPU hardware or drivers; verify that in the target environment.
Choose between Shell and newer headless Chrome
The choice is about implementation and workload compatibility, not a universal speed setting. Puppeteer characterizes Shell as currently more performant for automation that does not need Chrome’s complete feature set, but publishes no benchmark figure in the documentation basis for this article.
| Consideration | headless: 'shell' |
headless: true |
|---|---|---|
| Browser implementation | Separate chrome-headless-shell binary; the mode formerly known as old headless. |
Chrome’s newer headless mode. |
| Feature fit | Does not match regular Chrome completely. Test the capabilities your automation needs. | Use when your task requires the newer Chrome headless implementation; still validate the behavior you depend on. |
| Performance evidence | Puppeteer describes it qualitatively as currently more performant for automation not needing the complete Chrome feature set; no numeric benchmark is stated. | No comparative benchmark is stated. |
| GPU acceleration | Requires --enable-gpu for GPU acceleration in headless mode, according to Puppeteer’s troubleshooting guidance. |
Do not assume identical GPU behavior; test the target setup. |
For workloads involving screenshots, rendering, or browser APIs, compare actual output and required features on the same application rather than assuming one mode is a drop-in replacement for the other.
Install and version the browser deliberately
The version mapping is release-sensitive. Puppeteer v25.12.0 maps to Chrome for Testing 154.0.8037.57; treat that as a dated mapping for that release, not a standing requirement for newer Puppeteer versions. Check the supported-browser mapping for the release installed in your project.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
puppeteerordinarily downloads its corresponding Chrome for Testing browser and Headless Shell during installation.- If a package manager blocks install scripts, the browser download may not happen. Allow the required install step or provide a browser installation yourself.
puppeteer-coredoes not download a browser. When using it, arrange a compatible browser and provideexecutablePathor a supportedchannelas appropriate.- When setting
versionmanually or using an external executable, keep the browser aligned with the Puppeteer release and test it; external binaries are not guaranteed to work.
Configure display and GPU behavior
For headless display layouts, Puppeteer documents the --screen-info switch and runtime screen methods including Browser.addScreen, Browser.removeScreen, and Browser.screens. The --screen-info switch is available only in headless mode. Headful Chrome uses the platform’s physical screens instead. Use these options only when your automation needs multiple or specifically configured screens, and confirm API availability against the Puppeteer version in use.
Security: avoid routine use of --no-sandbox
Chrome’s sandbox helps protect the host from untrusted web content. Puppeteer strongly discourages disabling it. Prefer configuring a usable sandbox in your deployment; treat --no-sandbox only as a last-resort workaround when the content being opened is absolutely trusted, not as a routine speed, container, or convenience flag.
Troubleshooting common setup failures
Shell executable is missing after installation
Check whether installation scripts were blocked and whether the Shell download was skipped through configuration or either skip-download environment override. If you need Puppeteer to manage the download, allow its install step and remove the skip setting. With puppeteer-core, provide a browser yourself and set an explicit executable path or channel.
The selected browser fails to launch or behaves unexpectedly
Confirm that your Puppeteer package and browser binary are compatible. Prefer the bundled browser and consult the supported-browser mapping for your installed Puppeteer version. If you chose executablePath, channel, or a custom Shell version, test against that exact executable rather than assuming support.
Recommended Free Tools
GPU acceleration is unavailable
For Headless Shell, include --enable-gpu if GPU acceleration is needed, then verify that the host has the necessary GPU and driver support. The flag enables the browser-side option; it cannot supply missing hardware or drivers.
Sandbox errors in a Linux deployment
Do not immediately add --no-sandbox. First configure the environment so Chrome can use its sandbox. Only consider disabling it when the page content is absolutely trusted and you accept the reduced protection.
Screen configuration has no effect
Check that the browser is running headless. Puppeteer’s --screen-info option is for headless mode; headful Chrome uses physical platform screens.
Custom flags cause startup or automation regressions
Review the exact values in args and whether ignoreDefaultArgs has removed a required Puppeteer default. Restore defaults first, then add or filter arguments one at a time so the option responsible is identifiable.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Or skip the browser setup
If the goal is to capture a web page rather than control a local Puppeteer browser, ScreenshotNeo offers a screenshot API and MCP server. A single GET request can return an image or PDF, with capture options documented at ScreenshotNeo’s API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie banners and consent interfaces, newsletter popups, and chat widgets are removed before capture; each of those steps can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; responses identify the page verdict and billing status in headers.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents, including Claude, Cursor, and other MCP clients. - The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Frequently Asked Questions
What does “old headless” mean in Puppeteer?
It is the former name for the implementation now selected with headless: 'shell'.
Does --enable-gpu guarantee GPU acceleration?
No. Puppeteer identifies it as the required flag for Headless Shell GPU acceleration, but the environment must also support GPU use.
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.
