puppeteer.launch() starts a browser and returns a Browser object. With the regular puppeteer package, the default call launches Puppeteer’s downloaded browser in headless mode; with puppeteer-core, provide a browser executablePath or channel.
How do I launch Puppeteer?
Install the full puppeteer package for the default setup, then launch, open a page, navigate, and close the browser when finished:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://www.google.com');
// Perform page actions here.
} finally {
await browser.close();
}This follows the pattern in Puppeteer’s PuppeteerNode class documentation. The default call is equivalent to puppeteer.launch({ headless: true }).
How do I run Puppeteer headless?
Headless mode runs the browser without displaying a regular browser window. It is the default; choose explicitly when you want to make the mode clear in your code.
#1 Best Overall
| Setting | What it launches | When to use it |
|---|---|---|
headless: true |
New headless Chrome | Standard headless automation. This is the default. |
headless: 'shell' |
chrome-headless-shell |
Consider for automation that does not require the full feature set. It does not fully match regular Chrome; the guide describes it as potentially more performant, but does not establish a universal speed advantage. |
headless: false |
A visible browser window | Useful when you need to watch the browser or inspect behavior interactively. |
Examples:
const headlessBrowser = await puppeteer.launch({ headless: true });
const shellBrowser = await puppeteer.launch({ headless: 'shell' });
const visibleBrowser = await puppeteer.launch({ headless: false });These modes are documented in Puppeteer’s headless modes guide. Do not assume shell mode behaves exactly like regular Chrome; choose it only if its feature differences suit the task.
How do I set executablePath?
executablePath points Puppeteer to a browser binary. Use it when the browser you intend to launch is not the browser downloaded and selected by the regular package. Puppeteer recommends its downloaded Chrome for Testing build; compatibility with other Chrome versions is not guaranteed. The API also recommends specifying browser when overriding the executable.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
browser: 'chrome',
executablePath: '/absolute/path/to/chrome',
headless: true,
});Replace the example path with the actual browser binary path for your operating system and environment. Check that the file exists and is executable by the account running your script.
Why does puppeteer-core need a browser path?
puppeteer-core is the library without Puppeteer’s normal browser-download setup. Its launch call therefore needs either executablePath or a channel identifying an installed browser channel. For example:
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
executablePath: '/absolute/path/to/chrome',
});Or select a channel where one is installed and appropriate for the environment:
const browser = await puppeteer.launch({ channel: 'chrome' });The launch options and browser selection requirements are described in the LaunchOptions reference and PuppeteerNode.launch() documentation. Puppeteer states that it works best with the Chrome for Testing version downloaded by default; using another Chrome may work, but is not guaranteed compatible.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
How do I set launch arguments and timeout?
Add only the browser flags you need
Pass additional Chromium command-line flags as strings in the args array. Use flags for a specific requirement rather than copying a large collection blindly:
const browser = await puppeteer.launch({
args: ['--some-flag'],
});Replace --some-flag with a valid flag needed for your environment. Puppeteer’s LaunchOptions reference documents args.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Adjust startup timeout only when necessary
The LaunchOptions reference for Puppeteer 25.12.0 lists timeout as 30,000 milliseconds by default. Increase it if browser startup is demonstrably slower in your environment; set it to 0 to disable the timeout. Disabling it means a launch that never completes will not fail through this timeout, so retain an operational way to detect stalled jobs.
const browser = await puppeteer.launch({ timeout: 60_000 });Use ignoreDefaultArgs cautiously
ignoreDefaultArgs can be a boolean that disables all Puppeteer defaults or an array that filters selected defaults. The documentation cautions that callers probably want Puppeteer’s default arguments. Prefer adding a necessary flag through args; change defaults only when you understand the specific browser behavior affected.
Choose a browser setup for the environment
- Use the default bundled browser when compatibility certainty matters and the downloaded Chrome for Testing build fits your deployment.
- Use
executablePathorchannelwhen the runtime requires a particular installed browser, while accounting for the fact that other versions are not guaranteed compatible. - Choose visible mode when interactive inspection is important; choose either headless mode for unattended automation, with shell mode’s limitations in mind.
- Keep the startup timeout finite when failing promptly matters. Increase it only in response to observed slow startup.
Troubleshoot Puppeteer launch errors
- “Could not find Chrome” or no browser executable: With
puppeteer-core, setexecutablePathto an installed browser or configurechannel. With the regular package, confirm its expected browser download is present. - Executable path is invalid: Verify the full path inside the same machine or container where the script runs, and check file permissions. A path from a developer workstation may not exist in a deployment container.
- Launch times out: Check whether the binary starts successfully in the runtime and whether the machine is under resource pressure. If startup is simply slow, raise
timeout; use0only when an unbounded wait is acceptable. - Behavior differs with a system Chrome version: Puppeteer guarantees compatibility only with its bundled browser. Try the downloaded Chrome for Testing build or verify the chosen browser version against the installed Puppeteer version.
- Browser fails after changing arguments: Remove recently added flags and restore Puppeteer’s defaults, then add only flags that address a known need. Avoid setting
ignoreDefaultArgs: trueunless you intend to replace all defaults.
Or skip the browser setup
If your goal is to save a website screenshot rather than automate a browser session, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return an image or PDF; this cURL example saves a WebP screenshot of Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and options. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never 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.
PC 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 & 11Crashes, 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 minuteFrequently Asked Questions
Does puppeteer.launch() return a Page?
No. It resolves to a Browser object; create a page with browser.newPage().
Can I use Puppeteer with Chrome installed on my computer?
Yes, by selecting an installed browser with executablePath or channel, but compatibility with arbitrary Chrome versions is not guaranteed.
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.
