Puppeteer Installed Browser Objects Explained

InstalledBrowser is an installation record returned by @puppeteer/browsers after it downloads and unpacks a browser. It identifies the browser and build and provides the installation root and executable path. It is not the live Puppeteer Browser connection. To launch the installed browser, pass its executablePath to Puppeteer’s launch options.

What an InstalledBrowser represents

The InstalledBrowser class describes files installed on disk. It does not represent an open browser process, a page, or a connection to Chrome DevTools Protocol. The class constructor is marked internal in the API reference, so application code should get an instance from the package’s installation API rather than instantiate it directly.

Member	Meaning	Typical use
browser	Browser family identifier.	Identify which browser was installed.
buildId	Identifier for the installed build.	Record or report the selected build.
platform	Package platform identifier for operating system and architecture.	Understand which platform-specific browser was installed.
path	Root directory of the installation.	Inspect or manage the installation directory.
executablePath	Path to the browser executable.	Pass it to Puppeteer’s launch().
readMetadata() / writeMetadata(metadata)	Methods for reading and writing installation metadata.	Use metadata operations where your installation workflow needs them.

The distinction between path and executablePath matters: the former is the install root; the latter points to the binary Puppeteer must start.

How install() returns a browser installation

With the default unpacking behavior, install() downloads and unpacks the browser archive and resolves to an InstalledBrowser. If you set unpack: false, the archive is downloaded without being unpacked and the result is a string containing the archive path. That second return value is not an InstalledBrowser, and it is not an executable path you can launch directly.

The package’s installer accepts installation options such as the browser, build ID, and cache directory. Use the options for the browser and build you intend to manage, and keep the cache directory consistent between installation and later lookup or cleanup. The documented return type depends on unpack, so check that setting before treating the result as an installation record.

Runnable example: install, then launch

This JavaScript example installs Chrome through @puppeteer/browsers, then starts it through puppeteer-core. Install the packages first:

npm install @puppeteer/browsers puppeteer-core

Save as install-and-launch.mjs and run with Node.js:

import {install, Browser, detectBrowserPlatform} from '@puppeteer/browsers';
import puppeteer from 'puppeteer-core';

const platform = detectBrowserPlatform();
if (!platform) {
  throw new Error('Could not determine a supported browser platform');
}

const installed = await install({
  browser: Browser.CHROME,
  buildId: 'stable',
  cacheDir: './.cache/puppeteer-browsers',
  platform,
});

console.log({
  browser: installed.browser,
  buildId: installed.buildId,
  platform: installed.platform,
  installRoot: installed.path,
  executable: installed.executablePath,
});

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

The package API and supported browser/build choices can vary by package version. Check the installed version’s @puppeteer/browsers API reference before pinning a build identifier in deployment code.

InstalledBrowser versus Browser

Question	InstalledBrowser	Puppeteer Browser
What is it?	A description of an installed browser and its paths.	A runtime object for a running browser process or connected browser.
When do you get it?	From the browser installation workflow.	From puppeteer.launch() or puppeteer.connect().
What does it let you do?	Find the executable and installation metadata.	Create pages, interact with targets, and close or disconnect from the browser.

Use the installation record to locate the binary. Use the runtime Browser object to automate it after launch or connection.

Choosing puppeteer or puppeteer-core

The full puppeteer package downloads Chrome and drives it through puppeteer-core. puppeteer-core does not download Chrome during installation; it is intended for setups where you manage the browser yourself or connect to a remote browser. When launching with puppeteer-core, provide executablePath or channel.

Use the full package when its managed browser download and defaults fit your project. Use puppeteer-core with @puppeteer/browsers when you want to control browser installation and the executable path explicitly. Puppeteer only guarantees compatibility with its bundled browser; a separately installed executable may have compatibility differences. See the official installation guide and LaunchOptions reference.

Common errors and fixes

Symptom	Likely cause	Fix
Chrome could not be found	The browser download did not run, or the expected cache does not contain the browser.	Install the browser explicitly with npx puppeteer browsers install, or use @puppeteer/browsers and pass the returned executablePath.
Launch fails with a missing executable	The code passed the installation root (path) instead of the binary path, or the installation was not unpacked.	Pass installed.executablePath. With unpack: false, install/unpack the archive before launching.
install() appears to return a string	unpack: false requests an archive path rather than an installation record.	Enable unpacking and handle the resolved value as InstalledBrowser; otherwise treat the string as an archive path.
Automatic browser download is skipped during package installation	A package manager may be configured to block dependency install scripts.	Run npx puppeteer browsers install manually, as described in the official configuration guide.
The installed executable launches but behaves unexpectedly	The executable may not be the browser build Puppeteer expects.	Use Puppeteer’s bundled browser for the compatibility guarantee, or align and pin the separately managed browser build with the Puppeteer version you deploy.

Operational notes: paths, deployment, and reliability

• Persist or recreate installs deliberately. A path under a temporary directory may disappear between runs. In deployments that reuse a cache, use the same cache directory when installing and locating the executable.
• Keep platform in mind. A browser installation is platform-specific. Install it for the operating system and architecture where the process will launch it; do not assume a path copied from another platform is valid.
• Check the actual executable path. Log browser, buildId, platform, and executablePath when diagnosing environment-specific startup failures. Avoid logging secrets from unrelated launch configuration.
• Close runtime browsers. Close the Puppeteer Browser in a finally block so failures during page work do not leave browser processes behind.
• Budget for the browser archive and extraction. Installation downloads and unpacks files, so first-time setup needs network access, disk space, and time. Reusing a managed cache can avoid repeating that installation work.

Or skip the browser setup

If your goal is a screenshot rather than managing a local browser installation, ScreenshotNeo provides a website screenshot API and MCP server. Its one-call API returns an image or PDF; see the API documentation.

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

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. AI agents can capture through its MCP server. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Create a free account and get 1,000 screenshots a month with no card.

FAQ

Can I construct an InstalledBrowser myself?

The constructor is marked internal. Obtain the instance from the installation API.

Does InstalledBrowser mean Chrome is already running?

No. It describes an installation on disk. Launch it to receive a runtime Browser object.

Should I pass path or executablePath to launch?

Pass executablePath, which points to the browser binary.

Does puppeteer-core install Chrome?

No. It requires a browser you manage and an explicit executablePath or channel when launching.

Which browser build is guaranteed to work?

Puppeteer’s compatibility guarantee applies to its bundled browser. A separately managed executable can work, but compatibility is not guaranteed by that statement.