Puppeteer System Browser Options Explained

To use installed Chrome with Puppeteer, set channel when Chrome is installed in a standard location Puppeteer recognizes, or set executablePath when you need a specific executable at a known path. Puppeteer downloads Chrome for Testing by default; that bundled browser is its documented compatibility baseline. A system browser can be useful when your deployment requires it, but Puppeteer does not guarantee compatibility with every Chrome or Chromium version.

Choose the browser selection option

Option	How Puppeteer selects the browser	Use it when	Compatibility
Default bundled browser	Puppeteer downloads Chrome for Testing during installation.	You want the browser version Puppeteer is designed and documented to work with.	Officially guaranteed baseline.
channel	Finds a regular Chrome installation in a known system location for the requested release channel.	You intentionally need a recognized installed Chrome channel.	Not covered by the bundled-browser guarantee.
executablePath	Uses the browser executable at the exact path you provide.	The browser is installed in a custom location or managed explicitly by your deployment.	Use at your own risk; arbitrary versions are not guaranteed.

The documented system-browser support is scoped to Chrome and Chromium; channel is not a discovery mechanism for Firefox or arbitrary browser executables. Paths and channel availability vary by operating system and environment. See Puppeteer’s LaunchOptions reference and Browsers API.

Use a recognized Chrome channel

For a regular Chrome installation at a location Puppeteer recognizes, choose its release channel. For example, the stable Chrome channel is chrome:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  channel: 'chrome',
  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();
}

This example assumes Chrome is installed and discoverable in the same runtime environment as the Node.js process. Select a channel supported by the installed browser and Puppeteer version; do not assume a developer workstation’s installation is also present in a container or production host.

Use an explicit executable path

Use executablePath when the binary has a custom location or the deployment manages a particular executable. Replace the placeholder with the real path for the target machine or image:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  browser: 'chrome',
  executablePath: '/path/to/chrome',
  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();
}

/path/to/chrome is a placeholder, not a portable path. Configure the path for the operating system, package, and runtime image you actually deploy. Puppeteer’s launch reference recommends setting the browser property where appropriate alongside an explicit executable path.

Configure puppeteer-core

puppeteer-core does not download Chrome. Supply channel or executablePath when launching it, and ensure the selected browser is installed separately:

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', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  await browser.close();
}

If Chrome is at a custom path, replace channel with browser: 'chrome' and the actual executablePath. Puppeteer describes Chrome for Testing as the version it works best with and does not guarantee operation with any other version. See the PuppeteerNode API.

Check version and deployment requirements

1. Check the installed package version and consult documentation for that version. The official pages used for this guide identify Puppeteer 25.12.0; settings and platform requirements can change.
2. Decide whether you need the host browser. If not, the default Chrome for Testing download is the most predictable choice.
3. For standard-location Chrome, configure a recognized channel. For a custom installation, configure its exact executablePath.
4. For puppeteer-core, provide one of those browser selections and arrange installation yourself.
5. Check configuration and environment overrides, then confirm the binary exists and is executable for the user or container that runs Node.js.
6. Run launch and representative page automation in the deployment environment. A successful local launch does not establish compatibility with another OS, package, or browser version.

The current Puppeteer 25.12.0 system requirements documentation specifies Node 22.12+ and lists Chrome for Testing support for Windows x64, macOS x64 and arm64, Debian/Ubuntu Linux x64 and arm64, and openSUSE/Fedora Linux x64 and arm64. Treat these as version-specific documented requirements, not timeless requirements for all releases. See System Requirements.

Relevant launch and configuration options

Setting	What it affects	Practical note
browser	Browser type; the current generic launch reference documents chrome as the default.	Specify it with an explicit executable path where appropriate.
channel	Selection of a recognized Chrome release channel.	Use only when the installation is in a known location Puppeteer can find.
executablePath	Selection of a specific executable instead of the bundled browser.	Use a real path valid in the running environment.
headless	Whether the browser runs headlessly; documented default is true.	Set false when a visible browser is needed for local diagnosis and the environment has a display.
devtools	Opens DevTools; documented default is false.	devtools: true forces headless: false.
args	Additional browser command-line arguments.	Only add arguments needed by the deployment; they can affect browser behavior.
env	Environment passed to the browser process.	Check this if the child process needs specific environment values.
timeout	Launch timeout; documented default is 30,000 ms.	Increase only if startup is legitimately slow; a longer timeout does not fix a missing or incompatible binary.

Installation and launch are separate concerns. Puppeteer configuration includes executablePath, defaultBrowser, skipDownload, and cacheDirectory. Environment variables can override configuration, including PUPPETEER_EXECUTABLE_PATH, PUPPETEER_BROWSER, and PUPPETEER_SKIP_DOWNLOAD, along with browser-specific skip-download variables. The default browser cache is ~/.cache/puppeteer; PUPPETEER_CACHE_DIR changes it. Review the Configuration reference.

Compatibility and operational trade-offs

The Puppeteer documentation says its bundled browser is the only one it guarantees to work with. Its PuppeteerNode API says it works best with the Chrome for Testing version downloaded by default and gives no guarantee for other versions. Host Chrome can be appropriate when policy or deployment requires it, but updates to Chrome can change behavior independently of your Puppeteer package. Pin and manage the browser version when repeatable automation matters, and exercise important flows after browser or Puppeteer upgrades.

The installation guide gives approximate Chrome for Testing download sizes of 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. These are approximate download sizes, not a promise about total installed disk usage. Using a host browser may avoid downloading Puppeteer’s managed browser, but shifts installation, patching, and compatibility management to your environment. For downloaded archives, the install options reference documents an optional expectedHash check against an expected SHA-256 value; without it, the download proceeds without that integrity verification. See the installation guide and InstallOptions reference.

Troubleshooting

Symptom	Likely cause	What to check or change
Could not find Chrome / browser not found	A channel install is absent or not in a recognized location; the explicit path is wrong; or puppeteer-core has no browser selection.	Check the same runtime account/container, verify the file exists and is executable, use a valid channel or absolute executablePath, and provide a selection for puppeteer-core.
Launch uses an unexpected browser	An environment variable or configuration setting overrides the project choice.	Inspect PUPPETEER_EXECUTABLE_PATH, PUPPETEER_BROWSER, and related runtime environment values, plus the Puppeteer configuration file.
Bundled Chrome is missing after installation	A package manager blocked the install script or download was skipped.	Follow the official installation guide to permit the install script or run Puppeteer’s documented browser-install command manually.
Executable exists but launch fails	It may not be executable by the process user, may need system libraries, or may be incompatible with the Puppeteer version.	Check file permissions and runtime dependencies in the target image, then compare against a Puppeteer-managed Chrome for Testing browser.
Launch times out	Slow startup, resource pressure, a blocked process, or browser incompatibility.	Check container resources and browser startup logs; raise timeout only when startup needs more time.
Works locally but not in deployment	The deployed account or container has a different path, installation, permissions, libraries, architecture, or environment overrides.	Validate the browser selection and dependencies inside the actual deployment runtime, not only on the development machine.
Automation breaks after Chrome updates	The host browser changed while the Puppeteer package stayed the same.	Pin/manage the browser or test the relevant flows after updates; use the bundled browser when its predictable pairing is preferable.

Performance, reliability, and cost

Browser startup and page rendering consume time and memory, and a local browser introduces installation and update work. Puppeteer documentation does not provide a universal performance comparison between bundled and host Chrome, so measure in the target workload and environment. Reuse a browser process for multiple pages when your application design permits it, and close pages and browsers cleanly. Treat timeouts and browser crashes as operational failures to observe and handle, not as proof that the selected browser is compatible.

Cost depends on where the browser runs and who manages its binary. The bundled download uses cache space and build or install time; host Chrome shifts those responsibilities into the base image or machine. Puppeteer’s approximate download figures above are useful for planning, but they do not include every runtime dependency or total disk footprint.

Or skip the browser setup

If your goal is a screenshot rather than browser automation, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. The API documentation has the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

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 capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Create a free account at ScreenshotNeo sign-up.

FAQ

Can I point Puppeteer at a system Chromium build?

Use executablePath for its explicit binary if the build is compatible with your setup. Puppeteer’s documented compatibility guarantee applies to its bundled browser, not arbitrary system builds.

Does channel work with puppeteer-core?

Yes. puppeteer-core requires you to choose a browser, and the API accepts a channel or an executable path.

Should I set both channel and executablePath?

Choose the selection method that matches your deployment: a recognized release channel or one explicit executable. Check the version-specific LaunchOptions documentation for accepted combinations and behavior.

Where does Puppeteer keep its downloaded browser?

The documented default cache directory is ~/.cache/puppeteer, and PUPPETEER_CACHE_DIR can override it.