Puppeteer launch(): Options and Examples

puppeteer.launch() starts a browser and resolves to a Browser object. For most projects, install puppeteer and call await puppeteer.launch(); headless mode is the default. If you use puppeteer-core, provide a browser through executablePath or channel.

This guide covers the launch options developers most often need: headless mode, browser selection, executable paths, startup timeout, and command-line arguments.

How do I launch Puppeteer?

Install Puppeteer, launch the bundled browser, open a page, and close the browser when your work is complete. Puppeteer’s official example uses this pattern:

npm install puppeteer

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();
}

Save this as launch.mjs and run node launch.mjs. The finally block closes the browser even if navigation or another action throws, which helps avoid orphaned browser processes.

puppeteer.launch() without options is equivalent to launching with { headless: true }. It returns a Browser; use browser.newPage() to create a page. See the Puppeteer launch API and LaunchOptions reference for the installed version’s complete option list.

How do I run Puppeteer headless?

Headless mode is the default, so this works without an option:

const browser = await puppeteer.launch();

You can make the choice explicit with headless: true. Puppeteer also supports headless: 'shell' for Chrome Headless Shell and headless: false for a visible browser.

Setting	What it does	Use it when
true	Launches new headless Chrome.	You need normal headless browser automation.
'shell'	Launches chrome-headless-shell.	Your automation does not need the complete feature set of regular Chrome. It may be more performant for those workloads, but there is no universal speed guarantee.
false	Launches a visible browser.	You need to observe the browser while debugging or interacting with a desktop session.

const browser = await puppeteer.launch({ headless: false });

Chrome Headless Shell does not fully match regular Chrome. Choose it based on the features your automation needs, and check behavior in your target environment rather than assuming the two modes are interchangeable.

Choose a browser: bundled Chrome, channel, or executable path

The puppeteer package downloads a compatible browser by default. Puppeteer says it works best with the Chrome for Testing version it downloads; compatibility with other Chrome versions is not guaranteed. Prefer the bundled browser when you can.

Use a browser channel

When using puppeteer-core, supply channel or executablePath. A channel selects an installed Chrome channel:

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  channel: 'chrome',
  headless: true,
});
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
} finally {
  await browser.close();
}

Channel names and available installations depend on the machine. If launch cannot find the selected browser, use a valid executable path or install the matching browser in the environment.

Set executablePath

Use executablePath when the browser binary is installed at a known location. It must point to an executable browser, not a directory or a profile folder.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  executablePath: '/path/to/chrome',
  headless: true,
});
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
} finally {
  await browser.close();
}

Replace /path/to/chrome with the browser binary path for your operating system and deployment environment. The path on a developer laptop may not exist inside a container or server. Puppeteer warns that it only guarantees compatibility with its bundled browser; when overriding the executable, specify the browser where the API supports it and use a compatible version.

Configure timeout and browser arguments

Startup timeout

The launch option timeout is measured in milliseconds and defaults to 30,000. Increase it if browser startup is observably slow in your environment. Set it to 0 to disable the timeout, though disabling it also means a stalled launch will not fail promptly.

const browser = await puppeteer.launch({
  timeout: 60_000,
});

A larger timeout is not a fix for a missing executable or an incompatible browser. Check the underlying launch error before increasing it.

Pass extra command-line arguments

Use args to append browser arguments needed for a specific environment or behavior:

const browser = await puppeteer.launch({
  args: ['--lang=en-US'],
});

Pass an array of strings. Add only flags tied to a concrete requirement, since flags can change browser behavior. Avoid copying a large collection of flags from unrelated examples without understanding their effects.

Be careful with ignoreDefaultArgs

Puppeteer supplies default arguments that help configure its browser process. The ignoreDefaultArgs option can be a boolean that disables all defaults or an array that filters particular defaults. The documentation cautions that callers probably want Puppeteer’s default arguments. If you need to filter an argument, do so narrowly and confirm the browser still starts and behaves as expected.

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--some-specific-default-argument'],
});

Do not use the placeholder argument above literally; select an actual default only when you have a specific reason to remove it.

Common launch configurations

Default headless launch

const browser = await puppeteer.launch();

Visible browser for debugging

const browser = await puppeteer.launch({ headless: false });

Headless Shell

const browser = await puppeteer.launch({ headless: 'shell' });

Custom path and startup timeout

const browser = await puppeteer.launch({
  executablePath: '/path/to/chrome',
  timeout: 45_000,
});

Use these settings with puppeteer-core when you manage the browser installation yourself. With the full puppeteer package, the downloaded browser is usually the simplest compatibility choice.

Troubleshooting Puppeteer launch errors

Symptom	Likely cause	What to do
Launch reports that a browser executable cannot be found.	puppeteer-core was used without executablePath or channel, or the configured location is wrong.	Set one of those options to a browser installed in the current environment. Confirm the path inside the runtime or container, not only on your local machine.
The browser process starts and exits, or Puppeteer reports a protocol or compatibility error.	The selected browser version may not be compatible with the installed Puppeteer version.	Use Puppeteer’s bundled Chrome for Testing browser where possible. If selecting another executable, verify that the browser and Puppeteer versions work together; compatibility is not guaranteed for arbitrary Chrome versions.
Launch fails with a timeout.	Startup took longer than the configured timeout, or the browser is stuck due to an environment or installation problem.	Inspect the launch error and environment first. If startup is legitimately slow, raise timeout; use 0 only when an unlimited wait is appropriate.
The visible browser does not appear.	headless may still be true, or the runtime may lack a usable desktop display.	Set headless: false for a visible launch and run it in an environment that provides a display. For ordinary server automation, keep it headless.
Browser behavior changes after adding flags.	A command-line argument or filtered default changed browser startup or behavior.	Remove the new flags, then add back only the one required. Avoid disabling all default arguments unless you have a specific need.
A local launch works but deployment fails.	The deployed machine may not contain the same browser binary, path, or runtime setup.	Install or provide a compatible browser in the deployment environment and configure its actual path or channel. Do not assume a workstation path carries over.

Performance, reliability, and cost considerations

• Startup time: Puppeteer’s launch timeout defaults to 30 seconds. Measure startup in the environment that will run the automation before changing it; fail promptly when launch is genuinely broken.
• Mode choice: Use regular headless Chrome for the broader feature set. Consider Headless Shell only when its feature set is enough; behavior and performance depend on the workload.
• Browser compatibility: The bundled Chrome for Testing version is Puppeteer’s recommended compatibility path. A system browser or a separately managed executable adds version and installation work.
• Cleanup: Close the browser when work is finished, including error paths, to avoid leaving browser processes behind.
• Cost: Puppeteer itself is a browser automation library; the launch API has no per-screenshot price in the cited launch documentation. Running a browser still consumes the compute and infrastructure you provide. Budget depends on your hosting environment and workload.

Or skip the browser setup

If your goal is a website screenshot rather than browser automation, ScreenshotNeo provides a screenshot API and MCP server. It returns a PNG, JPEG, WebP, or PDF from one GET request. The API documentation covers its request options.

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with page verdict and billing information in response headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up for 1,000 free screenshots a month, no card required.

FAQ

How do I launch Puppeteer?

Install puppeteer, then call await puppeteer.launch(). It launches the bundled browser headless by default and returns a Browser object.

Why does puppeteer-core need a browser path?

puppeteer-core does not download and manage the browser for you. Tell it which installed browser to use with executablePath or channel.

How do I set executablePath?

Pass the path to the browser binary in the launch options: await puppeteer.launch({ executablePath: '/path/to/chrome' }). Ensure that path exists in the environment where Node.js runs.

Is headless mode enabled by default?

Yes. Calling puppeteer.launch() uses headless mode. Set headless: false for a visible browser or headless: 'shell' for Chrome Headless Shell.

Can I use my system Chrome?

You can select a system browser with a channel or executable path, but Puppeteer only guarantees compatibility with its bundled browser. Check compatibility when using another version.

What is the default Puppeteer launch timeout?

The LaunchOptions reference specifies 30,000 milliseconds. Use timeout: 0 to disable the timeout, or choose a longer finite value if observed startup latency requires it.