Puppeteer executablePath(): Find the Chrome Executable

executablePath is the filesystem path to the browser executable that Puppeteer launches. Most projects using the puppeteer package do not need to set it: Puppeteer downloads a compatible Chrome for Testing build by default. Set it when you manage Chrome yourself, use puppeteer-core, or need to select a specific installation.

The path is specific to the machine or container running Node.js. There is no single path that works across operating systems and installations. Puppeteer guarantees compatibility with its bundled browser; an external Chrome version may behave differently. See the official LaunchOptions API and installation guide.

1. Start with the default: Puppeteer-managed Chrome

The puppeteer package normally downloads Chrome for Testing and a chrome-headless-shell binary during installation. Puppeteer computes the executable path for that managed browser automatically. Start with this approach unless you have a reason to use a separately installed browser.

npm install puppeteer

Runnable example, saved as capture.js:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
    console.log(await page.title());
  } finally {
    await browser.close();
  }
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

Run it with node capture.js. If the browser download was skipped or failed, install it explicitly with npx puppeteer browsers install, then run the script again.

2. Find and set the Chrome executable path

Use an explicit path when your deployment supplies Chrome or when you use puppeteer-core. Replace the placeholder below with the real executable path on the runtime machine.

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/Chrome',
    // When using a non-bundled executable, identify its browser type too.
    browser: '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();
  }
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

The official API advises setting the browser property when using executablePath. The API also cautions that only Puppeteer’s bundled browser is guaranteed to work. Confirm that the file exists, is executable by the Node.js user, and is the browser you intend to launch.

To discover a path, check the installation configuration and the machine where the code runs. On a development machine, locate Chrome using that operating system’s application or package tools. In a container, inspect the image and its installed packages. Avoid copying a path from another OS, container image, or user account: those locations can differ.

3. Choose between a bundled browser, a channel, and an explicit path

Approach	Use it when	What to configure
Puppeteer-managed browser	You want Puppeteer to install the browser version it expects.	Install puppeteer and let it compute the path. Run the browser install command if the download was skipped.
Installed Chrome channel	Chrome is installed in a standard system location and you want a known release channel.	Use Puppeteer’s channel launch option, such as chrome or chrome-beta, when supported by your installed version and platform.
Explicit executable path	Your environment manages the browser or stores it at a nonstandard location.	Set executablePath to that machine’s actual executable path; for a non-bundled executable, set browser: 'chrome' as advised by the API.

puppeteer-core does not download Chrome. It is intended for setups where the application or environment manages the browser, so provide an executable path or a supported channel. The configuration guide also documents computeSystemExecutablePath, which checks known system locations for a release channel and throws if the expected Chrome installation is not found.

4. Configure the path and browser cache

For current Puppeteer versions, the browser cache defaults to $HOME/.cache/puppeteer (often written as ~/.cache/puppeteer). The cache directory and the executable path are separate settings: changing the cache location changes where Puppeteer-managed browsers are stored; it does not point Puppeteer at an arbitrary system Chrome.

Setting	Purpose	Example
executablePath	Per-launch path to the browser binary.	puppeteer.launch({ executablePath: '/path/to/Chrome' })
PUPPETEER_EXECUTABLE_PATH	Environment override for Puppeteer’s computed executable path.	Set it in the process environment to the path for that deployment.
PUPPETEER_CACHE_DIR	Changes where Puppeteer stores its downloaded browsers.	Set it to a writable cache directory before installing or running Puppeteer.

Configuration options can evolve across Puppeteer releases. Check the configuration documentation for the version in your lockfile, and make sure the install step and runtime use the same cache setting. A browser installed into one cache directory will not be found if the service later looks in another.

5. Install the browser in managed environments

1. Check whether your project uses puppeteer or puppeteer-core, and identify the installed Puppeteer version.
2. For puppeteer, check that its browser installation script ran and that its cache directory is available to the runtime user.
3. If the browser is missing, run npx puppeteer browsers install during image or environment setup.
4. For a system-managed browser or puppeteer-core, install Chrome in the runtime environment and configure a channel or its actual executable path.
5. Run the application as the same user and with the same environment variables used during deployment.

The Puppeteer browsers guide covers installing Chrome for Testing by channel or version and listing cached installations. Package managers or deployment environments that block dependency install scripts can prevent the automatic browser download. In that case, explicitly run the browser installation step as part of setup.

6. Troubleshoot launch failures

Symptom	Likely cause	What to do
Could not find Chrome (ver. ...)	The expected managed browser is not installed in the cache Puppeteer is using.	Run npx puppeteer browsers install. Check PUPPETEER_CACHE_DIR, the home directory of the runtime user, and whether install scripts were blocked.
Failed to launch or executable not found	The explicit path is wrong, points to a directory, or is not present in the deployed environment.	Verify the path on the runtime machine, not only on your workstation. Check file permissions and use a path to the browser executable.
Chrome starts locally but not in a container	The image may not contain the browser or its required runtime files, or the runtime user may lack access.	Install the browser and required environment dependencies in the image. Verify access as the service user and inspect the full browser launch output.
chrome_crashpad_handler: --database is required or immediate process exit	Chrome can fail while preparing profile, configuration, or cache data, including in read-only environments.	Provide writable locations for Chrome’s profile and required configuration/cache data. Check container filesystem permissions and startup logs.
Browser launches but behaves differently after an upgrade	An external Chrome version may not match the version Puppeteer expects.	Use the bundled browser for the documented compatibility guarantee, or pin and manage the external browser and Puppeteer versions together.
Works during installation but fails in the service	Install-time and runtime users, home directories, environment variables, or cache paths differ.	Align the user and cache configuration, or install Chrome at a stable location accessible to the runtime process.

When diagnosing an error, record the Puppeteer package and version, the browser source (bundled, channel, or explicit path), the effective cache directory, the runtime user, and the full launch error. This distinguishes a missing download from a bad path, version mismatch, or permissions issue.

7. Performance, reliability, and cost considerations

• Setup and updates: a Puppeteer-managed browser adds a download and cache to installation, while a system browser makes browser installation and updates your deployment’s responsibility.
• Compatibility: the bundled browser is the supported baseline. An external executable can be useful, but Puppeteer does not guarantee it will work with every Chrome version.
• Startup reliability: install the browser as part of a repeatable build or deployment step, and ensure the runtime has access to its executable and writable profile/configuration/cache locations.
• Runtime performance: executablePath selects a binary; it does not itself make page navigation or capture faster. Page load, network conditions, and your wait strategy still affect runtime.
• Cost: account for browser download and storage in your deployment process. The research sources provide no universal price or performance figures; these depend on the hosting environment and browser management approach.

Or skip the browser setup

If your goal is to capture a website rather than manage Chrome, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie/consent banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. An MCP server gives AI agents tools for screenshots and PDFs.

Example cURL request (replace the placeholder with your API key):

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

Python equivalent:

import requests

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

Node.js equivalent:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned HTTP ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

See the ScreenshotNeo API documentation for parameters and response details. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo free.

FAQ

Does puppeteer.launch() need an executablePath?

Usually not with the puppeteer package after its managed browser has installed. With puppeteer-core, provide a browser through a path or supported channel.

Is executablePath a URL?

No. It is a local filesystem path to the browser executable on the machine running Puppeteer.

Can I use any Chrome version?

You can select an external Chrome executable, but Puppeteer guarantees compatibility only with its bundled browser. Keep external browser and Puppeteer versions aligned and verify them in your deployment.

Does changing PUPPETEER_CACHE_DIR set the executable path?

No. It changes where managed browser downloads are stored. Use executablePath or a supported channel to select a browser executable.