How to Check Which Browsers Are Installed with Puppeteer
List browsers in Puppeteer’s cache with the CLI or JavaScript API, find the cache Puppeteer uses, and troubleshoot missing browser binaries.
To list browsers downloaded into a Puppeteer browser cache, run npx @puppeteer/browsers list. To inspect a specific cache from JavaScript, use getInstalledBrowsers({cacheDir}) from @puppeteer/browsers. These methods enumerate the chosen Puppeteer cache; they do not inventory every browser installed on the computer.
List browsers from the command line
From a terminal, run:
npx @puppeteer/browsers listThe command prints metadata for browser binaries found in the browser cache used by the tool. It is the quickest way to check manually. If your project uses a non-default cache directory, pass that same directory to the CLI:
npx @puppeteer/browsers list --path /path/to/puppeteer-cacheThe --path option selects the cache root to inspect. Run npx @puppeteer/browsers list --help if CLI flags differ in the installed package version. The official browser management guide documents the browsers CLI and its installed-browser listing command.
Find the cache directory Puppeteer uses
Puppeteer’s documented default browser cache is ~/.cache/puppeteer. The environment variable PUPPETEER_CACHE_DIR can point Puppeteer to a different cache. Check the project’s environment and configuration before interpreting an empty listing.
# macOS or Linux: show an explicit override if present
printf '%s\n' "${PUPPETEER_CACHE_DIR:-}"
# Windows PowerShell
$env:PUPPETEER_CACHE_DIR When the override is unset, inspect ~/.cache/puppeteer; when it is set, inspect the directory it names. If the browser was installed under a custom directory, listing another directory can return no entries even though the browser files exist elsewhere.
Inspect installed browsers from JavaScript
Install the browser management package if it is not already available in your project:
npm install @puppeteer/browsersThis runnable ES module reads the cache path from PUPPETEER_CACHE_DIR, falling back to Puppeteer’s documented default on macOS and Linux, then prints the browser metadata as JSON:
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(JSON.stringify(browsers, null, 2));Save this as list-browsers.mjs and run node list-browsers.mjs. The cacheDir option is the root directory to inspect. The function returns an array; an empty array means no recognized browser installations were found in that particular cache.
Read the returned metadata
Each installed-browser entry includes browser type, build ID, platform, executable path, and installation root path. The executable path points to the binary to launch; the path field identifies the browser’s installation root. Use the executable path when diagnosing a launch configuration, but confirm that the browser build is compatible with your Puppeteer release using the official supported browsers table.
Check for a system Chrome installation separately
The cache listing answers “which browser downloads are in this Puppeteer cache?” It does not answer “which browser applications exist anywhere on this machine?” For a system Chrome or Chromium executable, the browser-management API provides computeSystemExecutablePath. System-browser launching is available for Chrome/Chromium; it is a separate lookup from cache enumeration.
import {Browser, computeSystemExecutablePath} from '@puppeteer/browsers';
const executablePath = computeSystemExecutablePath({
browser: Browser.CHROME,
platform: process.platform,
});
console.log(executablePath);This computes the expected system executable location for the platform. It is not a universal browser discovery API and does not prove that the returned path exists. Check the path with the operating system if you need to confirm the file is present. See the API reference for system executable path computation.
Understand what an empty listing means
- Wrong cache directory: The browser may be in the directory configured by
PUPPETEER_CACHE_DIR, while you inspected the default or another path. - Browser download was skipped: Puppeteer normally downloads Chrome for Testing and, since v21.6.0,
chrome-headless-shell. Package managers or environment settings that block install scripts can prevent automatic downloads. - The project uses
puppeteer-core: This package does not download Chrome. You must provide a browser executable separately or install a browser through the browser management tooling. - Different installation mechanism: A browser installed by an OS package manager or another application may not be registered in Puppeteer’s cache.
Therefore, an empty cache result means only that the selected cache has no browser installation recognized by the tool. It does not mean the computer has no browser. Consult the official installation guide for package and download behavior.
Choose the right check
| What you need to know | Use | Scope |
|---|---|---|
| Quick manual list | npx @puppeteer/browsers list |
Browser cache selected by the CLI |
| List in a script or inspect a custom cache | getInstalledBrowsers({cacheDir}) |
The exact cache directory passed in |
| Compute expected system Chrome path | computeSystemExecutablePath |
System Chrome/Chromium path for the platform |
Troubleshooting
The list is empty, but Puppeteer launches a browser
You may be launching a system-installed browser or using a different cache. Check PUPPETEER_CACHE_DIR, the project’s Puppeteer configuration, and the executable path passed to launch. The CLI and API only report the cache they inspect.
The list is empty after installing Puppeteer
Check whether installation scripts were disabled by the package manager or deployment environment. Also confirm that the application installed puppeteer rather than puppeteer-core. Install a browser using the documented Puppeteer browser installation process, then list the same cache directory again.
The listing works locally but not in a container or CI job
Each environment has its own filesystem and environment variables. A browser downloaded on a developer workstation is not automatically present in a container or CI runner. Configure the cache path and install the browser in the environment where the script runs.
A listed browser still fails to launch
Use the entry’s executable path to see which binary your code should target, then compare its browser build with the compatibility table for your Puppeteer version. A binary’s presence does not guarantee compatibility. Also check that the runtime user can access the executable and its files.
The CLI command is not found
Use the package runner form npx @puppeteer/browsers list from a project with npm available. If package resolution fails, install @puppeteer/browsers in the project and consult its CLI help for the installed version.
Performance, reliability, and cost
Listing the cache reads installation metadata and is generally a small local operation; it does not launch a browser or download one. The main reliability concern is inspecting the wrong filesystem path or running the check in a different environment from the application. Browser downloads consume disk space and installation time, so in CI or containers, install only the browser builds your Puppeteer version needs and reuse a cache when the environment permits it. The CLI and API have no separate service charge; resource costs come from storing and downloading browser binaries and running them.
Or skip the browser setup
If your goal is to capture a website rather than manage a local browser binary, ScreenshotNeo provides a screenshot API and MCP server. Make one request for an image:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options and response details. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.
FAQ
Does Puppeteer list Firefox too?
The browser management tooling supports browser types documented by Puppeteer, including Chrome and Firefox. The installed list only includes browsers actually present in the selected cache.
Does finding a browser mean my Puppeteer version supports it?
No. Check the supported-browser compatibility table for the Puppeteer version installed in your project.
Can I use the listing to find every browser on my computer?
No. It enumerates a Puppeteer cache. System browser lookup is a separate, limited Chrome/Chromium path computation, not an operating-system-wide inventory.
