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 minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallPuppeteer 25.12.0 launches Chrome in headless mode by default. Set headless: false to show a browser window, use headless: 'shell' for the older headless shell, and point executablePath at a different browser binary when needed. Puppeteer guarantees compatibility only with its bundled browser; its documentation recommends setting browser when using a custom executable path. Examples below target Puppeteer 25.12.0, as shown in the official API reference on October 3, 2026.
Choose the launch configuration you need
| Need | Setting | What it does |
|---|---|---|
| Run without a visible browser window | headless: true or omit headless |
Uses the new headless mode; this is the default in Puppeteer 25.12.0. |
| Use the older headless implementation | headless: 'shell' |
Uses the old headless shell. |
| See and interact with a browser window | headless: false |
Runs in headed mode. Setting devtools: true also forces headed mode. |
| Use a Chrome installation Puppeteer detects on the system | channel: 'chrome' (or another supported Chrome channel) |
Selects a regular Chrome installation at a known system location. |
| Use a specific browser binary | browser and executablePath |
Selects the browser type and path instead of relying on Puppeteer’s bundled browser. Compatibility is not guaranteed for arbitrary binaries. |
These defaults and option meanings are documented for Puppeteer 25.12.0 in the LaunchOptions API. Launch option names and defaults can change between versions, so check the reference that matches the package version installed in your project.
Launch Chrome with the default browser
Install Puppeteer in a Node.js project and launch it without extra browser settings:
import puppeteer from 'puppeteer';
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();
}In Puppeteer 25.12.0 this uses Chrome in the new headless mode unless another setting changes that behavior. The finally block closes Chrome even if navigation or the title check fails.
Free tools Windows power users keep installed
One-click scans. No signup required.
Set headless mode explicitly
New headless mode
const browser = await puppeteer.launch({ headless: true });This makes the default explicit. It is useful when launch settings are assembled from configuration and you want the intended mode visible in code.
Older headless shell
const browser = await puppeteer.launch({ headless: 'shell' });Use this only when you specifically need the old headless implementation. It is distinct from true, which selects the new headless mode.
Visible browser window
const browser = await puppeteer.launch({ headless: false });Headed mode is useful when diagnosing navigation, page rendering, or interactions visually. If you set devtools: true, Puppeteer forces headless: false; do not expect DevTools to open while remaining headless.
Select a browser binary
Prefer Puppeteer’s bundled browser
Puppeteer guarantees compatibility with the browser it bundles. Prefer that browser unless a project requirement calls for a different installation. A system browser or custom binary can differ in version or packaging, and Puppeteer’s compatibility guarantee does not extend to arbitrary executables.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteSelect a known Chrome channel
const browser = await puppeteer.launch({ channel: 'chrome' });The channel option selects a regular Chrome installation at a known system location. Use it when the intended target is an installed Chrome channel rather than Puppeteer’s bundled browser. Availability depends on the machine where the program runs.
Point to a custom executable
const browser = await puppeteer.launch({
browser: 'chrome',
executablePath: '/absolute/path/to/chrome',
headless: true,
});Replace the path with the actual browser binary path on the target system. The official PuppeteerNode.launch() documentation recommends also setting browser when specifying executablePath. A custom path is an override, not a promise that every Chrome or Chromium build will work. With puppeteer-core, provide either executablePath or channel; it does not select a browser binary for you.
Pass browser arguments without breaking defaults
Add arguments
const browser = await puppeteer.launch({
args: ['--start-maximized'],
});args adds command-line arguments to the browser process. Puppeteer supplies its own defaults as well. Keep those defaults unless you have a specific reason to change them; removing them can affect browser startup or behavior.
Filter a specific default argument
const browser = await puppeteer.launch({
ignoreDefaultArgs: ['--mute-audio'],
});ignoreDefaultArgs accepts a list of default arguments to omit. The API also permits ignoreDefaultArgs: true, which removes all Puppeteer defaults; use that only when you intend to take responsibility for supplying the required browser arguments. Puppeteer’s launch documentation includes filtering --mute-audio as an example, and its defaultArgs() reference describes the default argument set.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Control startup, output, and shutdown
| Option | Default or behavior | When to use it |
|---|---|---|
timeout |
30,000 ms; 0 disables the startup timeout. |
Adjust when browser startup legitimately takes longer, or disable the limit only if your program has another way to detect and handle a stalled launch. |
dumpio |
Forwards browser stdout and stderr to the Node.js process. | Enable to inspect browser-process output while debugging. |
signal |
An abort signal; aborting it closes the browser. | Connect browser lifetime to an operation or cancellation controller. |
handleSIGHUP, handleSIGINT, handleSIGTERM |
Each defaults to true. |
Change only if the application needs to manage these process signals itself. |
For example, increase the startup timeout and forward browser output while investigating a slow or failing launch:
const browser = await puppeteer.launch({
timeout: 60_000,
dumpio: true,
});The timeout governs browser startup, not page navigation. Configure navigation waits separately with the relevant page methods.
Set a profile and browser environment
Use a user data directory
const browser = await puppeteer.launch({
userDataDir: '/path/to/puppeteer-profile',
});userDataDir sets the browser’s user data directory. Use a deliberate profile location when browser data needs a known home; avoid having concurrent browser processes write to the same profile directory.
Control environment variables
const browser = await puppeteer.launch({
env: {
...process.env,
LANG: 'en_US.UTF-8',
},
});env controls the environment variables visible to the browser process and defaults to the current process environment. When providing a custom object, spreading process.env preserves existing variables unless you intentionally want a reduced environment.
Recommended Free Tools
Understand inherited viewport settings
LaunchOptions extends ConnectOptions, so not every launch setting is a Chrome command-line option. In particular, defaultViewport is an inherited page/browser connection default: it is 800 by 600 unless changed, and null disables Puppeteer’s default viewport. The ConnectOptions API documents this behavior.
const browser = await puppeteer.launch({
defaultViewport: { width: 1440, height: 900 },
});Use defaultViewport: null when you want to disable that default and let the browser’s window determine the page size.
Check configuration and environment overrides
If Puppeteer selects an unexpected browser or executable, inspect both project configuration and environment variables. The configuration interface allows defaultBrowser and executablePath; PUPPETEER_BROWSER and PUPPETEER_EXECUTABLE_PATH override the corresponding configuration values. The configured executable path is auto-computed by default. See the versioned Configuration API.
- Check the installed Puppeteer version and its matching configuration file.
- Check whether
PUPPETEER_BROWSERorPUPPETEER_EXECUTABLE_PATHis set in the shell, container, CI runner, or service environment. - Make the launch call explicit if it should override an inherited project default.
- For
puppeteer-core, provide achannelorexecutablePath.
Troubleshoot common launch failures
The browser executable is not found
Check that the custom executablePath is the actual binary path on the runtime machine, not a path from your local development computer. If using puppeteer-core, supply executablePath or channel. Also check whether PUPPETEER_EXECUTABLE_PATH or project configuration is pointing somewhere unexpected.
The selected browser does not behave as expected
Verify the effective browser selection, channel, custom path, configuration, and environment overrides. When using a custom executable, set browser too and remember that Puppeteer guarantees compatibility only with its bundled browser.
Launch times out
The default startup timeout is 30 seconds. Inspect browser output with dumpio: true, confirm the binary can start in the current environment, and increase timeout if startup is simply slower. Setting timeout: 0 disables the startup timeout, so use it only when another safeguard prevents indefinite waits.
A supposedly headless launch opens a window
Check whether devtools: true is set; it forces headless: false. Also check whether configuration or launch-object composition changes headless.
Changing arguments causes a launch regression
Remove ignoreDefaultArgs: true first and retry with Puppeteer’s defaults. If only one default argument is problematic, filter that specific item rather than removing the full default set.
Best Value
Or skip the browser setup
If you need a website screenshot rather than browser automation, ScreenshotNeo returns a screenshot or PDF from one GET request. Its clean-shot flow accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf for AI agents using Claude, Cursor, or another MCP client.
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. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo free.
Frequently Asked Questions
Which version do these Puppeteer launch examples target?
Puppeteer 25.12.0, using the official API reference as displayed on October 3, 2026.
Can I use these settings with puppeteer-core?
Yes, but provide a browser through executablePath or channel; puppeteer-core does not select a binary for you.
Does a longer launch timeout also increase page navigation timeouts?
No. The launch timeout applies to browser startup; navigation waits are configured separately.
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.
