Puppeteer’s Chrome settings are mainly JavaScript options passed to puppeteer.launch(), plus Chrome command-line switches passed through args. Start with Puppeteer’s defaults; change a setting only when you have a specific need, such as showing a browser window, choosing an installed Chrome, or adjusting a timeout. The details below follow the Puppeteer v25.12.0 documentation and can change in later releases.
Start with a basic launch
For ordinary automation, Puppeteer launches headless Chrome by default. This minimal Node.js example opens a page and closes the browser:
As an Amazon Associate I earn from qualifying purchases.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}
})();Most projects do not need a long list of launch flags. If you do need to customize behavior, choose the option that controls the relevant layer: browser visibility, browser binary, process arguments, page viewport, or a specific timeout.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Choose a headless mode
The headless option controls whether Chrome runs invisibly and which headless implementation Puppeteer uses.
#1 Best Overall
- SLIM. LIGHTWEIGHT. READY TO GO: The all-new slim design is perfect for busy lives on the go.
- SKILLFULLY DESIGNED. MILITARY TOUGH: Built with premium craftsmanship to withstand the occasional drop or ding.
- ALL-DAY, ALL-IN-ONE CHARGING: Power through your school day – and beyond – with a long-lasting 12-hour battery.¹
- 3X FASTER THAN THE PREVIOUS GENERATION OF WIFI: Crush your schoolwork in record time with Wi-Fi that’s three times faster than the previous generation of Wi-Fi.
- YOUR PHONE AND CHROMEBOOK WORK BETTER TOGETHER: Easily transfer files between devices, and control your phone right from your Chromebook.
| Setting | What it does | When to choose it |
|---|---|---|
true (default) |
Runs modern headless Chrome. | Use for normal automation unless you have a reason to select another mode. |
'shell' |
Runs the separate chrome-headless-shell program. |
Consider it when its narrower behavior is sufficient and automation performance is a priority. Puppeteer’s guide says it does not completely match regular Chrome behavior. |
false |
Runs a visible browser window. | Use when you need to see the browser during debugging or interaction. |
For example, to launch a visible browser, pass the option explicitly:
const browser = await puppeteer.launch({ headless: false });Puppeteer’s headless guide describes chrome-headless-shell as potentially more performant for automation that does not need Chrome’s complete feature set. Treat that as guidance about the mode, not as a performance guarantee for your workload.
Select the Chrome binary carefully
Puppeteer works best with the Chrome for Testing version it downloads by default; its launch documentation does not guarantee compatibility with arbitrary Chrome versions. Use a different browser only when your project needs one, and validate it in that project’s environment.
Use the bundled browser
The simplest option is to omit channel and executablePath. Puppeteer then uses its configured browser installation, providing the documented compatibility baseline. The supported-browser guide maps Puppeteer releases to browser builds; its v25.12.0 entry reports Chrome for Testing 154.0.8037.57. That is a version-specific snapshot, not a lasting requirement.
Use an installed Chrome channel or executable
channelasks Puppeteer to find a regular Chrome installation at a known system location. It is intended for Chrome.executablePathsupplies a specific browser executable instead of the bundled binary. The LaunchOptions documentation cautions that Puppeteer is only guaranteed to work with its bundled browser.
If you use puppeteer-core, Puppeteer’s launch documentation says you must provide an executablePath or channel.
const browser = await puppeteer.launch({
channel: 'chrome',
headless: false
});Use a channel or path only if you need that installed browser, and check that it works with the Puppeteer release and environment you deploy.
Rank #2
- FOR HOME, WORK, & SCHOOL – With an Intel processor, 14-inch display, custom-tuned stereo speakers, and long battery life, this Chromebook laptop lets you knock out any assignment or binge-watch your favorite shows..Voltage:5.0 volts
- HD DISPLAY, PORTABLE DESIGN – See every bit of detail on this micro-edge, anti-glare, 14-inch HD (1366 x 768) display (1); easily take this thin and lightweight laptop PC from room to room, on trips, or in a backpack.
- ALL-DAY PERFORMANCE – Reliably tackle all your assignments at once with the quad-core, Intel Celeron N4120—the perfect processor for performance, power consumption, and value (2).
- 4K READY – Smoothly stream 4K content and play your favorite next-gen games with Intel UHD Graphics 600 (3) (4).
- MEMORY AND STORAGE – Enjoy a boost to your system’s performance with 4 GB of RAM while saving more of your favorite memories with 64 GB of reliable flash-based eMMC storage (5).
Pass Chrome command-line arguments without removing defaults
Use args to add Chrome command-line switches. These flags affect the browser process, rather than a single page:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →const browser = await puppeteer.launch({
args: ['--some-chrome-flag']
});The example flag is illustrative; use only switches that are valid for your browser and deployment. Puppeteer supplies its own default arguments. ignoreDefaultArgs changes those defaults: set it to true to suppress all of them, or pass an array to filter out selected defaults. The API warns that defaults are likely needed. For example, its launch documentation shows filtering out --mute-audio:
const browser = await puppeteer.launch({
ignoreDefaultArgs: ['--mute-audio']
});Prefer adding a needed flag through args. Change or remove a default only when you understand what it does and have a reason to do so.
Understand profiles, viewport, and timeouts
Several settings that can seem related control different things. A profile directory is not a viewport, and browser startup time is not the same as a Chrome DevTools Protocol call timeout.
| Option | Controls | Documented default or behavior |
|---|---|---|
userDataDir |
The user-data directory path for the browser. | The API identifies its purpose but does not establish broader profile-sharing or lifecycle guarantees. |
defaultViewport |
Page dimensions set for each page. | 800 × 600; null is also accepted. |
timeout |
How long Puppeteer waits for the browser to start. | 30,000 ms; 0 disables the timeout. |
protocolTimeout |
How long to wait for an individual Chrome DevTools Protocol call. | 180,000 ms. |
slowMo |
A delay added to Puppeteer operations. | Useful for slowing operations while debugging. |
defaultViewport, protocolTimeout, and slowMo are documented as connection options; LaunchOptions extends the connection options interface. For example, to change the initial page dimensions and give browser startup more time:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →const browser = await puppeteer.launch({
defaultViewport: { width: 1280, height: 800 },
timeout: 60_000
});Increasing timeout affects startup only. If a protocol operation is the part that times out, review protocolTimeout instead.
Rank #3
- Storage: 16GB Flash Memory
- OS: Chrome OS
- Screen Size: 11.6"
Other useful launch options
browserselects the supported browser; Chrome is the default in the generic API.devtools: trueopens DevTools for each tab and forces headful mode.dumpio: truepipes browser stdout and stderr to the Node.js process streams, which can help diagnose browser output.handleSIGHUP,handleSIGINT, andhandleSIGTERMcontrol Puppeteer’s browser-process handling when Node receives those signals. Each istrueby default.pipe: trueuses pipe transport instead of WebSocket; the API documents it as Chrome-only.waitForInitialPagecontrols whether Puppeteer waits for the initial page. Disabling it can be useful when Chrome is explicitly started without a startup window.envsets environment variables visible to the browser. By default, the browser inheritsprocess.env.
Separate launch settings from global configuration
Launch options configure a particular browser session. Puppeteer’s configuration API covers installation and runtime behavior, including the default browser, executable path, browser cache directory, temporary directory, log level, and whether browser downloads are skipped. Several configuration settings also have environment-variable overrides.
If Puppeteer installs or locates a different browser than expected, check both the project’s configuration and its environment variables before changing per-launch options. A launch-time setting and an installation setting solve different problems.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common configuration problems
Puppeteer launches a different Chrome than expected
Check whether channel or executablePath selects an installed browser. Then review global configuration and environment-variable overrides, which can affect browser choice, executable path, cache location, or downloads. To return to Puppeteer’s bundled-browser baseline, remove the custom selection where appropriate.
Launch fails with a custom executable
Confirm the executable path is correct and points to a browser Puppeteer can run in the target environment. Because compatibility with arbitrary browser versions is not guaranteed, compare against the bundled browser before treating a custom executable as equivalent.
Startup or page operations time out
Identify which operation is timing out. Adjust timeout for browser startup; adjust protocolTimeout for an individual protocol call. A larger startup timeout will not change the per-call timeout.
A custom argument breaks expected behavior
Review the switches in args and any use of ignoreDefaultArgs. Remove custom flags one at a time to isolate the cause. Avoid suppressing all defaults unless you have a specific requirement and understand the consequences.
Rank #4
- Intel Celeron N4120: 4 Cores & Threads, 1.1GHz Base Clock, Up to 2.6GHz Boost Clock, 4MB Cache, Intel UHD Graphics 600. The perfect combination of performance, power consumption, and value helps your device handle multitasking smoothly and reliably with four processing cores to divide up the work.
You cannot see the browser window
Headless mode is the default. Set headless: false to show a browser, or enable devtools: true, which also forces headful mode.
Or skip the browser setup
If your goal is to capture a website rather than configure a local Puppeteer browser, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. Its clean-shot flow accepts consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers.
cURL example, documented at ScreenshotNeo API docs:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. 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 with no card.
Frequently Asked Questions
Does Puppeteer use headless Chrome by default?
Yes. The documented default is headless: true, which uses modern headless Chrome.
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 errorsShould I set ignoreDefaultArgs to true?
Usually not. Puppeteer warns that its default arguments are likely needed; add a required flag with args unless you have a specific reason to suppress defaults.
What viewport does Puppeteer use by default?
The documented defaultViewport is 800 by 600 pixels.
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.
