How Puppeteer Compares Browser Versions
Find the Chrome or Firefox build paired with your Puppeteer release, pin it for repeatable captures, and troubleshoot browser mismatches.
Direct answer: Use Puppeteer’s supported browsers table to find the Chrome for Testing and Firefox builds paired with your installed Puppeteer release. If your exact Puppeteer version is absent, the table’s rule is to use the browser version for the immediately prior listed Puppeteer version. Check the live table before upgrading: its values change over time.
For repeatable automation, keep Puppeteer, its browser binary, Node.js, and the deployment platform aligned. Puppeteer releases are tied to browser releases because browser changes can affect the Chrome DevTools Protocol (CDP) and WebDriver BiDi.
1. Find the browser version for your Puppeteer release
- Check the installed Puppeteer version in your project:
npm ls puppeteer. If using a different package such aspuppeteer-core, identify that package and version too. - Open the official supported browsers table.
- Find your Puppeteer release and note its Chrome for Testing and Firefox versions.
- If the exact release is not listed, use the browser version for the immediately prior listed Puppeteer version, per the table’s guidance.
- Choose the browser family and protocol deliberately. Puppeteer uses CDP by default with Chrome and WebDriver BiDi by default with Firefox.
The current documentation snapshot identifies Puppeteer v25.12.0 with Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. These are a point-in-time mapping, not permanent compatibility guarantees; consult the live table when you read this or change versions.
2. Why the versions are paired
Puppeteer explains that each release is tightly bundled with a browser release to preserve compatibility with the underlying protocols, CDP and WebDriver BiDi. A browser can change protocol behavior or implementation details independently of your automation code, so an arbitrary browser upgrade can cause failures even if the browser still launches.
Browser support has evolved. Puppeteer v20.0.0 marked the move to downloading Chrome for Testing instead of Chromium. Support for Chrome and Firefox arrived in v23.0.0, and stable Firefox releases became supported then; earlier supported Firefox builds were Nightly. These transitions matter when diagnosing an older project or migrating an existing CI image.
3. Reproduce the supported setup
Recommended project setup
Install Puppeteer in the project and let it obtain its associated browser. This keeps the package and browser selection connected.
npm install puppeteer
npm ls puppeteer
Minimal runnable capture script, saved as capture.cjs:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'example.png', fullPage: true });
} finally {
await browser.close();
}
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});
Run it with node capture.cjs. Puppeteer’s launch documentation says it works best with the Chrome for Testing version downloaded by default. This is the simplest baseline when diagnosing version problems.
Pin Chrome for Testing explicitly
When a build must use a known browser version, use the @puppeteer/browsers CLI to install the exact Chrome for Testing version from the supported browsers mapping. Its documentation also supports selecting the latest version for a milestone or channel, but an exact version is more reproducible.
npx @puppeteer/browsers install chrome@154.0.8037.57
Use the version appropriate to your Puppeteer release, not the example version blindly. Puppeteer documents that it tests and guarantees Chrome for Testing binaries; that guarantee does not extend to arbitrary system-installed Chrome builds.
Check Node.js and platform separately
Browser mapping is only one compatibility axis. The current Puppeteer system requirements page lists Node.js 22.12 or newer and specifies supported operating systems and architectures. Check the system requirements for your installed Puppeteer release and target platform. A matching browser version does not compensate for an unsupported runtime or missing platform libraries.
4. Compare the compatibility choices
| Choice | What to verify | When it fits |
|---|---|---|
| Puppeteer-downloaded Chrome for Testing | Release mapping and successful browser installation | Default choice for a straightforward, supported Chrome setup |
| Explicit Chrome for Testing pin | Exact version exists and matches the release mapping | Reproducible CI, release builds, and controlled upgrades |
| System-installed Chrome | Version against the mapping, plus behavior in your target environment | Environments where the system browser is a requirement |
| Firefox | Supported Firefox version and WebDriver BiDi behavior | Firefox coverage or browser-specific automation |
Compare four things together: Puppeteer release to browser build, Chrome versus Firefox, CDP versus WebDriver BiDi, and the runtime/platform used in deployment. Compatibility is not established by matching only the major browser number.
5. Installation and configuration details
- Install scripts: Puppeteer’s installer downloads Chrome for Testing and, since v21.6.0, a
chrome-headless-shellbinary. Modern package managers can block install scripts by default, which may leave the browser binary absent. Review the install output and Puppeteer’s installation guide if no browser was downloaded. - Browser download control: Puppeteer documents configuration for controlling downloads. Set it deliberately in environments with managed caches or restricted network access, and confirm that the configured executable is available at launch.
- System browser path: If you select an executable yourself, keep that choice explicit in configuration and record its version in build logs. Recheck it whenever the host image changes.
- Protocol: Chrome defaults to CDP and Firefox defaults to WebDriver BiDi. Do not assume protocol-specific behavior is identical across the two browser families.
6. Troubleshooting browser-version problems
| Symptom | Likely cause | Fix |
|---|---|---|
| “Could not find Chrome” or browser executable missing | Install script was skipped or downloads were disabled/misdirected | Check package-manager install-script policy and Puppeteer download configuration; install the mapped browser and confirm its path. |
| Browser launches but automation methods fail | System browser differs from the build paired with this Puppeteer release, or protocol behavior changed | Check the supported browsers table and try the mapped Chrome for Testing build. For Firefox, verify the supported Firefox version and BiDi path. |
| Works locally but fails in CI | Different Node version, OS/architecture, libraries, browser cache, or executable path | Compare runtime and platform with system requirements; pin the browser, log versions, and use the same installation procedure in both environments. |
| Exact Puppeteer version is missing from the table | The documentation table does not list every patch or prerelease | Use the immediately prior listed Puppeteer version’s browser mapping as the table instructs, then validate your target workflows. |
| Upgrade introduces intermittent failures | Browser behavior or protocol implementation changed alongside the release | Pin the previous known-good Puppeteer/browser pair while investigating; upgrade the pair together and exercise critical flows before rollout. |
| Downloaded binary is present but will not start | Runtime platform or OS dependencies do not meet the requirements | Verify supported OS and architecture and install the required platform dependencies for the target environment. |
7. Performance, reliability, and cost
Version matching is a reliability measure: it reduces failures caused by browser/protocol drift. Pinning an exact browser build also makes local and CI behavior easier to compare. The tradeoff is maintenance: a pin does not update itself, so schedule deliberate Puppeteer and browser upgrades and validate them before deployment.
Browser downloads consume build time and storage. A managed cache can avoid repeating downloads, provided its key includes the relevant Puppeteer/browser version and platform. Avoid sharing a browser cache across incompatible architectures or silently reusing a binary after changing the mapping.
Puppeteer is software; its version table does not set a usage price. Operational costs come from the machines, CI time, storage, and network access used to install and run browsers. The documentation reviewed provides no universal performance figures, so measure capture time and resource use in your own deployment rather than relying on a generic benchmark.
8. When you need screenshots without managing browser builds
If your task is producing website screenshots rather than controlling browser automation, ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns an image or PDF. Its API avoids maintaining a Puppeteer/browser pairing in your application.
Or skip the browser setup
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. Cookie banners are accepted like a visitor and removed along with 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card.
9. Frequently asked questions
Does a newer Chrome always work with an older Puppeteer?
Not necessarily. Use the supported pairing as the baseline because protocol and browser changes can break automation.
Does Puppeteer support both Chrome and Firefox?
Yes, from Puppeteer v23.0.0 onward. Chrome uses CDP by default; Firefox uses WebDriver BiDi by default.
Should I pin Node.js too?
For reproducible builds, keep the Node.js version controlled and within the requirements for your Puppeteer release. The current requirements page lists Node 22.12+.
Can I use the browser version from the prior table row?
For an unlisted Puppeteer version, the official table says its supported browser version is the one for the immediately prior listed Puppeteer version. Recheck the live documentation before relying on that mapping.
