Recommended Free Tools
Puppeteer launches Chrome headless by default. Set headless: true to use Chrome’s current headless mode, headless: 'shell' to use the separate chrome-headless-shell binary, or headless: false when you need a visible browser window. For most work that should behave like regular Chrome, keep the default; consider shell for automation that does not need all of Chrome’s features, and verify compatibility first.
What Puppeteer headless mode means
Puppeteer is a JavaScript library for controlling Chrome or Firefox through the DevTools Protocol or WebDriver BiDi. In Chrome, headless means the browser runs without a visible user interface; it still runs a browser engine. Puppeteer documents uses such as UI testing, form submission, screenshots, PDF generation, tracing, and crawling single-page applications. Puppeteer: What is Puppeteer?
In current Puppeteer, the headless launch option defaults to true. That chooses Chrome’s new headless mode. The option devtools: true forces headful mode, so do not combine it with an expectation that the browser remain headless. LaunchOptions API reference
New headless, headless shell, and headful Chrome
| Setting | What launches | When it fits | Trade-off |
|---|---|---|---|
headless: true |
Chrome in its current headless mode, sharing the regular Chrome code path. | Default choice when you want behavior aligned with regular Chrome and its feature set. | Documentation does not quantify its speed relative to shell. |
headless: 'shell' |
The separate chrome-headless-shell binary, representing the old headless mode. |
Automation that may benefit from shell’s performance and does not need the complete Chrome feature set. | It does not completely match regular Chrome behavior; validate the pages and features your workflow uses. |
headless: false |
Visible, headful Chrome. | Development and debugging when you need to see the browser interface and page. | Requires a visible browser environment; it is not headless. |
Puppeteer’s documentation describes shell as currently more performant for automation tasks that do not need the full feature set, but provides no numerical benchmark or workload-specific speed figure. Treat that as a qualitative vendor characterization, not a guarantee that shell will be faster for your job. Puppeteer: Headless modes
#1 Best Overall
How to launch each mode
Install Puppeteer in a JavaScript project with npm install puppeteer. The puppeteer package downloads a compatible Chrome for Testing and a chrome-headless-shell binary. The following CommonJS examples use Puppeteer’s documented launch options; keep your installed package and browser pairing aligned with its documentation.
Use current headless Chrome
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: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}
})();Opt into headless shell
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();
}
})();Show the browser while debugging
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: false, slowMo: 100 });
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.waitForTimeout(5000); // Leave time to inspect the visible page.
} finally {
await browser.close();
}
})();slowMo slows Puppeteer operations so they are easier to observe. Remove the delay when you no longer need to watch the flow. LaunchOptions API reference
Which mode should you use?
Choose headless: true for regular automation
Use the default when your tests or captures should follow the regular Chrome code path. This is the sensible starting point for UI testing, rendering checks, and workflows that depend on normal Chrome behavior. If a regression appears, record the Puppeteer and browser versions, then reproduce it with the exact pairing used in your project.
Try headless: 'shell' only after checking compatibility
Shell is worth evaluating when automation does not need Chrome’s complete feature set and performance matters. Check the pages, APIs, and browser behaviors your job relies on. The documentation does not establish that shell is compatible with every Chrome workflow or specify how much faster it is.
Use headless: false to diagnose what automation sees
A visible window helps reveal navigation, consent screens, modal dialogs, and interactions that are difficult to infer from a failed script alone. Puppeteer’s API also supports slowMo for easier observation. Once diagnosis is complete, switch back to the mode required by the actual run environment.
Version changes and migration
Puppeteer’s changelog dates v22.0.0 to February 5, 2024 and records that it enabled new headless mode by default. The changelog also records that v21.10.0 began downloading chrome-headless-shell by default for old-headless mode. Puppeteer changelog
If you upgraded Puppeteer or inherited an older script, inspect its launch configuration instead of assuming the old default still applies. An explicit headless: true or headless: 'shell' makes the intended mode clear. The actual executable still depends on the installed Puppeteer/browser pairing, so verify against the API documentation for your pinned version.
Browser installation and managed browsers
Installing puppeteer downloads a recent compatible Chrome for Testing and the shell binary. Choose puppeteer-core instead when connecting to a remote browser or managing the browser yourself; it does not download Chrome. With a managed browser, Puppeteer’s installation guidance says to provide an explicit executablePath or an appropriate channel. Puppeteer installation guide
Free tools Windows power users keep installed
One-click scans. No signup required.
Performance, reliability, and cost considerations
- Performance: Shell has a qualitative documented performance advantage for some tasks, but official guidance gives no multiplier or benchmark. Measure both modes on the same pages, workload, machine, and browser versions before making a production choice.
- Reliability: Use the same explicit mode and pinned browser pairing in development and deployment. When rendering differs, first check that both environments use the intended executable and Puppeteer version.
- Cost: Puppeteer is a library that runs browsers you install or manage; the documentation cited here does not provide a hosting cost or usage price. Budget for the compute and browser infrastructure in your environment rather than assuming headless mode itself removes those costs.
Troubleshooting Puppeteer headless mode
The page looks different in shell
Shell does not completely match regular Chrome. Retry with headless: true to determine whether the difference is specific to shell, then decide whether the feature gap is acceptable for your automation.
The script changed behavior after an upgrade
Check whether the project relied on an implicit headless default. Puppeteer v22.0.0 switched the default to new headless mode. Set the headless value explicitly and confirm the version-specific browser pairing.
Puppeteer cannot find a browser executable
If you use puppeteer-core, remember that it does not download Chrome. Install or manage a browser and pass its path with executablePath, or use a supported channel as appropriate. For the full puppeteer package, consult the installation guide if browser download or cache configuration has been customized.
You need to inspect a failed interaction
Set headless: false, optionally add slowMo, and rerun the same navigation and actions so you can see the page state. If the browser is running in an environment without a display, a visible window may not be available there; reproduce locally or use the headless mode appropriate to the deployment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
There is no clear performance improvement
The vendor’s description is not a quantified guarantee. Compare shell and new headless on the same workload and environment, and include correctness checks in the comparison. Keep the regular mode if shell’s compatibility trade-off does not produce a meaningful benefit for your case.
Or skip the browser setup
If your goal is to get a website screenshot rather than control a browser workflow, ScreenshotNeo provides a screenshot API and MCP server. Its one-call request can return an image or PDF without you managing Puppeteer and a browser binary:
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 request options. It removes known cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.
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.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
