How to List Installed Browsers with Puppeteer

To list browser builds installed in Puppeteer’s managed cache, run npx @puppeteer/browsers list. In a Node.js program, use getInstalledBrowsers({cacheDir}) from @puppeteer/browsers. These methods inspect the selected Puppeteer browser cache; they do not scan the whole computer for every browser executable.

List browsers from the command line

Run this from a project directory or any directory where npx can fetch the package:

npx @puppeteer/browsers list

The command lists browser builds found in the browsers package’s managed cache. It is the quickest choice for a one-time check. If you need reproducible automation, install the package as a project dependency and use its API as shown below.

Check the cache location

Puppeteer’s standard cache is ~/.cache/puppeteer on Linux and macOS starting with Puppeteer v19.0.0. The actual location can differ because of Puppeteer configuration or the PUPPETEER_CACHE_DIR environment variable. Also check which operating-system user installed the browser: a browser installed under one account may not appear in another account’s cache. See the official installation guide and configuration interface.

List cached browsers in Node.js

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

npm install @puppeteer/browsers

Save this as list-browsers.mjs. Set PUPPETEER_CACHE_DIR if your browser cache is in a non-default location; otherwise the script uses the documented default path for Puppeteer v19 and later.

import {getInstalledBrowsers} from '@puppeteer/browsers';
import os from 'node:os';
import path from 'node:path';

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

const browsers = await getInstalledBrowsers({cacheDir});
console.log(`Cache: ${cacheDir}`);
console.dir(browsers, {depth: null});

Run it with node list-browsers.mjs. The API returns metadata for browser installations in the supplied directory. Treat the returned objects as package metadata rather than assuming fields not documented by the version you installed; consult that package’s current types or API reference if your script needs a specific field.

Choose the right cache directory

Use the directory where the browser download actually went. Puppeteer’s cache configuration and environment override may change it, and getInstalledBrowsers accepts an explicit cacheDir. For example, to inspect a project-specific cache:

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

On Windows, use the cache directory configured for that installation rather than assuming the Linux or macOS default. A relative path is resolved according to the process’s working directory, so prefer an absolute path in scripts and deployment configuration.

Understand what “installed” means

The CLI and API answer: “Which browser builds are present in this Puppeteer-managed cache?” They do not promise to discover applications in operating-system folders, package-manager databases, directories on PATH, containers, or remote browser services. There is no universal Puppeteer cache-list command for a complete host inventory.

Puppeteer’s regular puppeteer installation downloads Chrome for Testing by default. puppeteer-core does not download a browser and is intended for setups where you manage the browser separately. Therefore, an empty cache listing can be expected with puppeteer-core. See the installation documentation.

Find and launch a system Chrome

Listing a cache and choosing a system browser are separate tasks. To launch a regular Chrome installation in a known release channel, use channel. To launch a particular binary, provide executablePath. These options select a browser; they do not make the cache listing search the operating system. The LaunchOptions reference documents both options.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  channel: 'chrome',
  headless: true,
});

console.log(await browser.version());
await browser.close();

For an explicit executable, replace channel with the path appropriate to the host:

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

Use an actual executable path for your operating system and runtime image. System-browser launching through the browsers tooling is documented for Chrome/Chromium; do not assume an arbitrary installed browser can be selected this way. Puppeteer supports Chrome and Firefox, but the browser type and launch path must match your installed Puppeteer version and setup. See Puppeteer’s supported browsers.

Check the browser version and compatibility

After launching, browser.version() reports the version of that running browser. It is useful for confirming what your launch configuration selected. The compatible browser build changes with Puppeteer releases, so check the supported-browser table for the exact Puppeteer version in your project rather than relying on a version remembered from another release.

For version context, the Puppeteer v25.12.0 supported-browser table maps to Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Those are version-specific mappings, not universal requirements. Check the current supported-browser table when debugging a mismatch.

Common problems and fixes

Symptom	Likely cause	Fix
The list is empty	The command is checking a different cache, user account, or environment than the one used for installation; or the project uses `puppeteer-core`.	Check `PUPPETEER_CACHE_DIR`, Puppeteer configuration, the active user’s home directory, and the package installation workflow. Pass the actual cache path to `getInstalledBrowsers`.
`getInstalledBrowsers` is not found	`@puppeteer/browsers` is missing, or the installed package version/API differs from the example.	Install the package in the project and check its installed version and current API types. Use the documented CLI for a quick inventory.
The script reports no browser but Puppeteer launches successfully	Puppeteer may be launching system Chrome through `channel` or `executablePath`, outside its managed cache.	Check the launch options and inspect the system executable separately. Cache inventory does not enumerate that binary.
Launch fails after selecting a system executable	The path may be wrong in the current operating system or container, or the selected browser may not be supported by that setup.	Verify that the executable exists and is runnable in the same environment as Node.js. Use the matching Chrome channel or a valid `executablePath`; consult the supported-browser and launch-option references.
The browser version differs from expectations	The installed Puppeteer release maps to a different browser build, or launch selected system Chrome instead of the managed download.	Print `browser.version()`, inspect the launch configuration, and compare the installed Puppeteer release with its supported-browser table.
The command works locally but not in a container or CI	The runtime may use a different home directory, environment variable, filesystem, or installation stage.	Set the cache path explicitly and ensure the browser installation and listing step run with the same user and filesystem. For system Chrome, verify its path inside the runtime image.

Performance, reliability, and cost

Listing metadata from a local cache is a small diagnostic operation and does not launch each browser. It should not be treated as a health check: a directory entry does not prove that a browser can start in the current container or that its dependencies are available. If launchability matters, launch the specific browser and check its version as a separate step.

For reliable scripts, make the cache directory explicit, run installation and inspection as the same user, and avoid depending on undocumented metadata fields. The Puppeteer approach uses the compute and storage of the environment where you install and run it; browser download size, execution capacity, and hosting cost depend on your own infrastructure.

Or skip the browser setup

If your goal is to capture a website rather than inspect Puppeteer’s local browser cache, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, and cache hits are not billed; responses identify the page verdict and billing status in headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card.

FAQ

Does the list command show the version of every browser on my computer?

No. It lists builds in the Puppeteer-managed cache it checks. Use operating-system-specific discovery for a complete host inventory.

Can I use the API without Puppeteer itself?

Yes. getInstalledBrowsers is provided by @puppeteer/browsers; install that package in the project using the API.

How do I know what browser a script actually launched?

Call await browser.version() on the launched browser and check whether your launch options specify a channel or executable path.

Does an empty cache mean Puppeteer is broken?

No. It can mean there are no managed downloads in the selected cache, especially when using puppeteer-core or a separately installed system browser.