Puppeteer runs Chrome headlessly by default: the browser works without showing a window. In the current API, headless: true selects Chrome’s newer headless mode, while headless: 'shell' selects the separate chrome-headless-shell binary. Use the newer mode when you want behavior aligned with regular Chrome; consider shell for automation that does not need Chrome’s complete feature set. Set headless: false when you need to see the browser during debugging.
What headless mode means in Puppeteer
Headless mode means browser automation without a visible browser interface; it does not mean Puppeteer skips the browser engine. Puppeteer controls Chrome or Firefox through the DevTools Protocol or WebDriver BiDi. Common uses include UI testing, form submission, screenshots, PDF generation, tracing, and crawling single-page applications. See the Puppeteer overview.
As an Amazon Associate I earn from qualifying purchases.
In the current LaunchOptions reference, headless defaults to true. That selects Chrome’s newer headless mode. Set it to false to show Chrome’s UI, or to 'shell' to use the older headless implementation through a separate binary.
Recommended Free Tools
How to choose between Puppeteer’s modes
| Setting | What it launches | When to use it |
|---|---|---|
headless: true |
Chrome’s newer headless mode, using the regular Chrome code path. | Use for the default choice when compatibility with regular Chrome behavior and its feature set matters. |
headless: 'shell' |
The separate chrome-headless-shell binary, representing the old headless mode. |
Consider it for automation that does not need the complete Chrome feature set and where performance matters; check your workflow for compatibility. |
headless: false |
Chrome with its visible browser UI. | Use while developing or debugging when you need to observe what the browser displays. |
Puppeteer describes shell as currently more performant for some automation tasks that do not need the full feature set, but it does not publish a numerical speed advantage or a benchmark methodology. Treat performance as workload-dependent rather than assuming a fixed speedup. The headless modes guide also cautions that shell does not completely match regular Chrome behavior.
#1 Best Overall
Launch Puppeteer in each mode
With the puppeteer package installed, the following runnable example captures a page screenshot. Change the headless value to compare modes. The first run may take longer if Puppeteer needs to download its browser binaries.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
headless: true, // true, 'shell', or false
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'example.png', fullPage: true });
} finally {
await browser.close();
}For visible debugging, use headless: false. Puppeteer’s launch options also include slowMo, which slows operations to make them easier to observe. The API documents that devtools: true forces headful mode. Check the launch options reference for the installed version’s exact options.
What changed, and what to check when upgrading
Puppeteer’s changelog records that v22.0.0, dated February 5, 2024, enabled the newer headless mode by default. It also records that v21.10.0 began downloading chrome-headless-shell by default for old-headless mode. If an older script relied on the default or explicitly selected a mode, review its launch configuration after upgrading. Explicitly setting headless: true or 'shell' makes the intended behavior clear. The browser outcome can still depend on the Puppeteer/browser pairing you install. See the Puppeteer changelog.
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 →Install and manage the browser
Installing puppeteer downloads a compatible Chrome for Testing and a chrome-headless-shell binary. Use puppeteer-core when connecting to a remote browser or managing the browser yourself; it does not download Chrome. When you manage the browser, the installation guide says to provide an explicit executablePath or an appropriate channel. Follow the installation guide and check it against the Puppeteer version pinned by your project, since browser support and API details can change.
Compare modes for your workload
There is no universal performance winner. To decide whether shell fits your automation, run the same tasks in both modes under the same environment, then evaluate the results that matter to your application.
- Check behavioral compatibility on the pages and browser features your tests depend on.
- Measure the workload you actually run rather than relying on a general speed claim.
- Consider whether a visible UI is needed to diagnose failures; headful mode can make browser behavior easier to inspect.
The official Puppeteer guide provides a qualitative performance characterization for shell, not a measured comparison. Any speed conclusion for your own workload requires a like-for-like comparison.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting headless launches
The browser launches in a mode you did not expect
Inspect the headless value passed to puppeteer.launch() and whether the script depends on the default. Set true, 'shell', or false explicitly to make the requested mode unambiguous. If using a managed browser, verify its pairing with your installed Puppeteer version.
A page behaves differently in shell
Shell is a separate binary and does not fully match regular Chrome. Retry with headless: true to check whether the difference is specific to shell, then keep the mode that is compatible with your required behavior.
You cannot see what the browser is doing
Set headless: false to display Chrome. You can also use Puppeteer’s slowMo launch option to make actions easier to follow, or enable devtools: true, which forces headful mode.
Puppeteer cannot find a browser you manage yourself
If you use puppeteer-core or otherwise manage the browser binary, configure executablePath or an appropriate channel as described in the installation guide. The puppeteer package, by contrast, downloads compatible browser binaries during installation.
Or skip the browser setup
If your goal is simply to capture a website, ScreenshotNeo offers a one-request screenshot API:
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for the available parameters. Cookie banners are accepted and removed before capture, along with supported consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. ScreenshotNeo also provides an MCP server for AI agents, with tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan.
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.
