How to Check Whether Puppeteer Supports a Browser
Check Puppeteer’s official browser mapping, verify the binary your code launches, and test that pairing in your runtime.
To check whether Puppeteer supports a browser, look up your exact Puppeteer release in the official supported browsers table. Use the Chrome for Testing or Firefox version listed on that row. If your Puppeteer release has no row, Puppeteer says to use the browser version shown for the immediately prior Puppeteer release.
The table currently lists Puppeteer 25.12.0 with Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Browser mappings change, so check the table when you publish or upgrade rather than treating those versions as permanent.
1. Find the Puppeteer version your project uses
Compatibility depends on the Puppeteer release actually installed by your project. Check the dependency declaration, lockfile, or installed package instead of relying on a globally installed version.
# Show the installed version in a project
npm ls puppeteer
# Or read the installed package version with Node.js
node -p "require('puppeteer/package.json').version"If you use puppeteer-core, inspect that package instead. It does not download a browser for you, so you must also know which browser executable your application supplies.
node -p "require('puppeteer-core/package.json').version"For a reproducible deployment, commit the lockfile and install from it in CI and production. A broad dependency range can resolve to a different Puppeteer version later, which can change the browser mapping.
2. Look up the supported browser version
- Open the Puppeteer supported browsers table.
- Find the exact Puppeteer version identified in your project.
- Record the listed Chrome for Testing or Firefox version for that release.
- If the release is absent, follow the table’s fallback rule and use the browser version associated with the immediately prior Puppeteer release.
- Repeat the lookup after upgrading Puppeteer; do not assume a browser pairing remains unchanged.
Puppeteer tightly pairs releases with browser releases because its automation depends on browser protocols. The Puppeteer FAQ explains that changes in Chrome or Firefox can otherwise break compatibility with the implementation of the Chrome DevTools Protocol (CDP) or WebDriver BiDi.
3. Check which browser binary Puppeteer actually launches
By default, the puppeteer package downloads and uses a specific Chrome for Testing build. That bundled browser is the best-supported choice. If you set executablePath, or use puppeteer-core, Puppeteer launches the binary you name; that setting does not make an arbitrary browser version supported.
Get the version of the binary your deployment will run:
# Linux example; replace the path with the binary used by your app
/path/to/chrome --versionCompare that output to the table. A matching version is a useful compatibility check, but it does not guarantee that the process can start in every operating system or container. Test the launch in the target environment.
4. Run a minimal launch check
This JavaScript example reports the Puppeteer package version, launches its configured browser, prints the browser version, and closes cleanly. Save it as check-browser.js and run node check-browser.js after installing puppeteer.
const puppeteer = require('puppeteer');
(async () => {
let browser;
try {
console.log('Puppeteer:', require('puppeteer/package.json').version);
browser = await puppeteer.launch({ headless: true });
console.log('Launched browser:', await browser.version());
} catch (error) {
console.error('Browser launch failed:', error.message);
process.exitCode = 1;
} finally {
if (browser) await browser.close();
}
})();For a custom Chrome or Chromium executable, configure the path explicitly, then run the same launch check:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: true,
executablePath: '/path/to/chrome',
});
try {
console.log('Puppeteer:', require('puppeteer/package.json').version);
console.log('Launched browser:', await browser.version());
} finally {
await browser.close();
}
})();Use the executable path supported by your installed Puppeteer configuration. Avoid committing a machine-specific path that differs between local development, CI, and production.
5. Check Firefox support and protocol behavior
Puppeteer supports both Chrome and Firefox from v23.0.0 onward. The supported-browser table includes a version mapping for each. Puppeteer uses CDP by default for Chrome and WebDriver BiDi for Firefox, according to its FAQ. Check the Firefox version against the same Puppeteer row, then perform a launch check in the target runtime.
Do not infer Firefox compatibility from a successful Chrome launch: the browser family and protocol path differ.
6. Know what “supported” means in practice
| Check | What it tells you | What it does not tell you |
|---|---|---|
| Exact Puppeteer row in the support table | The browser release Puppeteer pairs with that library release. | Whether a custom installation has all runtime dependencies. |
| Custom executable version matches the mapping | The binary version is the intended pairing. | A guarantee that any Chrome or Chromium build will work; Puppeteer provides no such general guarantee. |
| Launch test succeeds in your environment | The browser can start there with the current configuration and dependencies. | That every page, feature, or deployment environment will behave identically. |
The strongest practical check combines all three: identify the installed Puppeteer version, compare the actual binary to its documented mapping, and launch-test in the environment that will run the automation.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The browser version does not match the table. | A system-installed or custom browser is being launched instead of Puppeteer’s downloaded Chrome for Testing. | Check executablePath and the launch configuration. Use the mapped browser build, or explicitly accept that an alternate version is not guaranteed and validate it in your target runtime. |
| “Could not find Chrome” or browser executable missing. | The browser download did not run, was blocked, or the deployment did not include the downloaded browser. | Install the browser explicitly with npx puppeteer browsers install, then ensure the deployment can access that installation. |
| Browser process exits immediately in Linux or a container. | Required shared libraries or other operating-system dependencies are missing. | Inspect the launch error and check the browser’s shared-library dependencies in the target image; install the missing system packages and retry the launch check. |
| Chrome works but Firefox fails. | Firefox has its own supported version mapping and uses WebDriver BiDi by default. | Check the Firefox column for your Puppeteer release and test Firefox separately. Do not use the Chrome mapping as a substitute. |
| Local launch works but CI or production fails. | The runtime may have a different browser binary, OS libraries, filesystem permissions, or installation step. | Log the Puppeteer and browser versions in each environment, install the browser during the deployment build, and run the launch check in the same image or host. |
| The Puppeteer version is missing from the table. | The table may not contain a row for that release. | Use the browser version for the immediately prior listed Puppeteer release, following the table’s instruction, and verify by launching. |
8. Reliability, performance, and cost considerations
Reliability: Pin Puppeteer with a lockfile and keep the browser version aligned with its documented mapping. When you intentionally use a system browser, record its version and repeat the launch check whenever the browser, Puppeteer, base image, or operating system changes.
Performance: Version checking itself is inexpensive. Browser startup and page rendering are usually the heavier parts of an automation job; reuse a browser process for multiple controlled tasks when appropriate, and close pages and browsers so processes do not accumulate. Test resource use under your own workload rather than assuming a version match predicts speed.
Cost: Puppeteer is an open-source browser automation library, but operating a browser incurs your infrastructure and maintenance costs. Account for browser downloads, container image size, runtime dependencies, and engineering time spent keeping the browser and library compatible.
9. Or skip the browser setup
If the task is to capture a webpage rather than automate browser behavior, ScreenshotNeo provides a website screenshot API and MCP server. It accepts one GET request and returns a PNG, JPEG, WebP, or PDF. Its 63 options include full-page capture with lazy images loaded, CSS selector capture, device and viewport settings, custom CSS and JavaScript, waits, request blocking, headers and cookies, caching, signed links, asynchronous jobs, and bulk capture.
Example in cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent Python:
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()
open("shot.webp", "wb").write(r.content)Equivalent Node.js:
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 require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));See the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.
Sign up for 1,000 free screenshots a month, with no card.
10. FAQ
Does specifying executablePath make my Chrome version supported?
No. It selects the executable Puppeteer launches. Compatibility still depends on the browser mapping and successful validation in your runtime.
Should I use Chrome or Chrome for Testing?
Puppeteer’s downloaded Chrome for Testing build is its best-supported option. Use the version paired with your Puppeteer release in the support table.
Does a successful launch prove my automation is correct?
It proves the browser starts with that configuration. It does not verify the behavior of every page or automation flow, so exercise the actions your application depends on.
Where can I find the current pairing?
Use the official supported browsers table; it is the authoritative lookup and may change over time.
