Puppeteer Installed Browser Metadata Explained

Puppeteer’s installed browser metadata is an inventory of browser builds managed in a specific cache directory. Use getInstalledBrowsers({ cacheDir }) from @puppeteer/browsers to retrieve it, or run npx @puppeteer/browsers list to see cached installations in a terminal. Each record identifies a browser and build, its platform, its installation root, and its executable path. This inventory does not scan every browser installed on the machine.

What is Puppeteer installed browser metadata?

It is a set of InstalledBrowser records describing browser builds in the managed cache directory you specify. The API returns a promise of an array. The package documents these fields: browser, buildId, platform, path, and executablePath. See the official getInstalledBrowsers reference and InstalledBrowser reference.

Field	What it tells you	How to use it
`browser`	Which browser product the record describes.	Use it to distinguish browser families.
`buildId`	The browser build identifier.	Use it when recording or matching an installed build; build IDs identify binaries and are used for caching.
`platform`	The platform associated with the build.	Use it as installation context, especially in cross-platform tooling.
`path`	The root of the browser installation folder.	Use it to inspect the installation directory, not as a substitute for the executable path.
`executablePath`	The browser executable location.	Use this path when you need the binary location.

The constructor is internal. Obtain records from the package APIs instead of constructing InstalledBrowser instances yourself. The class reference distinguishes the installation root from the executable binary location and points to computeExecutablePath() for resolving an executable path.

How do I list browsers installed by Puppeteer?

Programmatically with Node.js

Install the package if it is not already available in your project:

npm install @puppeteer/browsers

Save this as list-browsers.mjs and run node list-browsers.mjs. Pass the same cache root used for installation.

import { getInstalledBrowsers } from '@puppeteer/browsers';

const cacheDir = process.env.PUPPETEER_CACHE_DIR ?? `${process.env.HOME}/.cache/puppeteer`;
const browsers = await getInstalledBrowsers({ cacheDir });

if (browsers.length === 0) {
  console.log(`No managed browser builds found in ${cacheDir}`);
} else {
  for (const browser of browsers) {
    console.log({
      browser: browser.browser,
      buildId: browser.buildId,
      platform: browser.platform,
      installationRoot: browser.path,
      executablePath: browser.executablePath,
    });
  }
}

The default cache path shown follows Puppeteer configuration on Unix-like systems. On Windows, HOME may not be set; use an explicit path or derive the home directory with Node’s os.homedir(). A version-independent way to set the path is:

import os from 'node:os';
import path from 'node:path';

const cacheDir = process.env.PUPPETEER_CACHE_DIR
  ?? path.join(os.homedir(), '.cache', 'puppeteer');

Puppeteer configuration documents cacheDirectory and the PUPPETEER_CACHE_DIR override. The lower-level browsers API accepts its own cacheDir option. These values must point at the same cache root if you want the API to report Puppeteer’s installed builds. See Puppeteer configuration and GetInstalledBrowsersOptions.

From the terminal

Use the documented list command to inspect installed managed browsers without writing a script:

npx @puppeteer/browsers list

For command details and supported browser operations, refer to the @puppeteer/browsers documentation.

What does the cache directory control?

getInstalledBrowsers() inventories the cache root passed as cacheDir; it is not a host-wide browser discovery function. If your script reports an empty list, first check that you are enumerating the directory where the browser was installed.

Puppeteer’s documented configuration default is path.join(os.homedir(), '.cache', 'puppeteer').
PUPPETEER_CACHE_DIR can override that configured cache location.
The browsers package API has a cacheDir option of its own.
Installation options also include browser, build ID, cache directory, and platform. The build ID identifies the binary used for caching.

For example, if installation used /srv/puppeteer-cache, enumerate that same directory:

const browsers = await getInstalledBrowsers({ cacheDir: '/srv/puppeteer-cache' });

Check the official InstallOptions reference when you need to confirm which installation inputs were used.

Metadata inventory is different from launch selection

A cached record answers “what managed builds are in this cache?” It does not by itself decide which browser Puppeteer launches. The launch API has separate selection options:

Launch input	Selection behavior	Important limit
`channel`	Looks for a regular Chrome installation in known system locations.	This is system installation lookup, not enumeration of the managed cache.
`executablePath`	Uses the explicit binary path you provide.	Confirm that it points to a runnable executable compatible with your environment.
Default bundled browser	Uses Puppeteer’s expected bundled browser setup.	Puppeteer says it only guarantees compatibility with its bundled browser.

Consult the official LaunchOptions reference before changing launch selection. Do not assume that a browser listed in a cache will be the one selected by channel, or that any arbitrary system browser is guaranteed to work.

Common errors and fixes

Symptom	Likely cause	Fix
The result is an empty array.	The supplied `cacheDir` is not the directory used by installation, or no managed browser builds are present there.	Check Puppeteer’s `cacheDirectory` and `PUPPETEER_CACHE_DIR`; pass that cache root to `getInstalledBrowsers()`.
The script cannot find the expected cache path.	The process runs under a different user, home directory, container, or CI environment.	Resolve the path for the process actually running the script, or set an explicit shared cache path for installation and enumeration.
A launch fails even though metadata lists the browser.	Inventory confirms a cached record, but does not guarantee launch compatibility or that launch selection uses that record.	Check the executable path and launch options. Prefer Puppeteer’s bundled browser for the compatibility guarantee; use explicit `executablePath` or `channel` intentionally.
The installation folder is mistaken for the executable.	`path` is the installation root, not necessarily the binary filename.	Use the record’s `executablePath` or resolve it with `computeExecutablePath()`.
Code examples do not match the installed package.	Puppeteer APIs are versioned, and package versions may differ from the reviewed documentation.	Check the installed `@puppeteer/browsers` version and use the matching official API docs. The references cited here were reviewed against Puppeteer documentation version 25.12.0.

Performance, reliability, and cost

Listing metadata is a local cache inventory operation. Its practical reliability depends on asking about the correct cache root and having access to it. In CI or container setups, make the cache location explicit when installation and inspection run in different processes or users. The API documentation does not provide a performance benchmark for enumeration, so avoid assuming a particular runtime.

The metadata API itself does not capture pages or invoke a screenshot service. Its costs are the package and browser storage or compute resources in your environment. If your actual task is to capture a website image and you do not need control over a local browser cache, a screenshot API can remove browser installation and launch setup from that workflow.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A single GET request returns a PNG, JPEG, WebP, or PDF. Its API documentation covers 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}`);

Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets are removed. Each of these steps can be turned off.
Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses include X-Page-Verdict and X-Billed headers.
An MCP server gives AI agents tools for screenshots, page info, and PDF capture.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Does getInstalledBrowsers find Chrome installed by my operating system?

It lists browser records from the cache directory you pass. For regular system Chrome discovery at launch time, Puppeteer documents the separate channel option.

Can I create an InstalledBrowser object myself?

The constructor is internal. Retrieve metadata through package APIs.

Is path the same as executablePath?

No. path is the installation folder root; executablePath identifies the executable location.

Will every listed build launch successfully?

A record confirms the cache inventory, not universal compatibility. Puppeteer guarantees compatibility with its bundled browser; consult the launch options for explicit paths and channels.