Puppeteer Browser Tags: How to Identify Browser Builds

Direct answer: A Puppeteer browser tag names a moving release channel, such as stable or beta. A build ID identifies a particular browser build. To identify a concrete binary, record the browser family, resolved build ID, and platform; to inspect the browser that is actually running, call browser.version().

This distinction matters when reproducing automation behavior, caching browser downloads, or diagnosing a mismatch between Puppeteer and a custom browser executable. A tag is a selection rule; it is not a version number or a permanent identity.

1. Tag, build ID, platform, and runtime version

Value	What it tells you	When to use it
Browser tag	A release channel, for example `stable`, `beta`, or `canary`.	When you want a channel selection that can move as releases change.
Build ID	A concrete browser build identifier resolved for a browser.	When installing or locating a particular build, or recording a reproducible selection.
Platform	The operating system and architecture target for the browser binary.	When installing or computing a path to a build for a specific machine or deployment target.
`browser.version()`	A runtime browser name/version string reported by the launched browser.	When checking what executable actually started.

Puppeteer documents tags including stable, beta, canary, dev, devedition, esr, latest, and nightly. Use resolveBuildId() to resolve a tag when a concrete build ID is needed. Tag availability depends on the browser provider and its release channels; do not treat every tag as valid for every browser. See the Puppeteer BrowserTag API.

2. Resolve a browser tag to a build ID

The @puppeteer/browsers package provides browser management functions. This runnable Node.js example resolves Chrome’s stable tag, installs that build for the current platform, and prints the selected identifiers and executable path.

npm install @puppeteer/browsers

# Save as resolve-build.mjs and run with: node resolve-build.mjs
import { resolveBuildId, install, detectBrowserPlatform } from '@puppeteer/browsers';

const browser = 'chrome';
const platform = detectBrowserPlatform();
if (!platform) {
  throw new Error('Could not detect a supported browser platform for this machine');
}

const tag = 'stable';
const buildId = await resolveBuildId(browser, platform, tag);
const installed = await install({ browser, buildId, platform });

console.log({ browser, tag, buildId, platform, executablePath: installed.executablePath });

The exact API surface is documented by Puppeteer’s browser management API. The install options use browser, build ID, and platform; the build ID is used to identify binaries and for caching. Store all three values in deployment metadata or logs if you need to recreate the selection. See InstallOptions and Options.

Pin a build instead of following a channel

For repeatable environments, resolve the channel at a deliberate update point and save the returned build ID. In subsequent installs, provide that build ID directly rather than resolving the moving tag each time:

import { install, detectBrowserPlatform } from '@puppeteer/browsers';

const browser = 'chrome';
const platform = detectBrowserPlatform();
const buildId = process.env.CHROME_BUILD_ID;
if (!platform || !buildId) {
  throw new Error('Set a valid platform and CHROME_BUILD_ID');
}

const installed = await install({ browser, buildId, platform });
console.log(installed.executablePath);

Use a build ID appropriate to the selected browser and platform. A build ID alone is not a complete deployment record if the browser family or platform is omitted.

3. Check which browser Puppeteer actually launched

Resolving and installing a build tells you what the browser manager selected. The runtime check tells you what the launched browser reports. With the puppeteer package, the bundled browser is the usual managed setup:

npm install puppeteer

# Save as inspect-browser.mjs and run with: node inspect-browser.mjs
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
try {
  console.log('Runtime browser:', await browser.version());
  console.log('Process:', browser.process()?.spawnfile ?? 'not exposed');
} finally {
  await browser.close();
}

Browser.version() returns a browser name/version string. Puppeteer’s examples include strings such as HeadlessChrome/..., Chrome/..., and Firefox/..., but the precise format may change. Parse it only when necessary, and avoid relying on a permanent string grammar. See Browser.version().

4. Configure an explicit browser with puppeteer-core

puppeteer-core does not select a bundled browser for you. Its launch configuration requires either an explicit executablePath or a channel. If you use a path, point it at the executable returned by your installation process:

npm install puppeteer-core

# Save as launch-core.mjs and run with: node launch-core.mjs
import puppeteer from 'puppeteer-core';

const executablePath = process.env.CHROME_EXECUTABLE_PATH;
if (!executablePath) {
  throw new Error('Set CHROME_EXECUTABLE_PATH to the browser executable');
}

const browser = await puppeteer.launch({
  executablePath,
  headless: true,
});
try {
  console.log(await browser.version());
} finally {
  await browser.close();
}

A channel is another option when the intended channel is installed and discoverable in the environment:

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

Consult PuppeteerNode and LaunchOptions for the current options. Puppeteer’s bundled browser is its guaranteed configuration. Other executable paths are used at the user’s risk, so verify compatibility in the environment where the automation will run.

5. Match the browser to your Puppeteer version

Check the official supported-browser table for the Puppeteer version installed in your project. It maps Puppeteer releases to Chrome for Testing and Firefox versions. If an exact Puppeteer release is not listed, Puppeteer’s documentation says the supported browser version is the one for the immediately prior Puppeteer version. See Supported browsers.

Record the installed Puppeteer package version from your lockfile or package manager.
Find that release in the supported-browser table.
Use the mapped browser build where possible, especially in CI and production.
If choosing a different provider or browser version, run your own compatibility checks and keep the browser selection pinned.

Puppeteer tests and guarantees Chrome for Testing binaries. Custom providers are not officially supported; compatibility testing, feature validation, maintenance, and cross-platform version consistency are the user’s responsibility. See @puppeteer/browsers.

6. A practical build record

For bug reports and reproducible automation, log a compact record with these values:

{
  "puppeteerVersion": "value from your lockfile",
  "browser": "chrome",
  "tagUsedForResolution": "stable",
  "buildId": "resolved build ID",
  "platform": "detected platform",
  "runtimeVersion": "value from browser.version()",
  "executablePath": "installed executable path"
}

The tag explains how the selection was made. The build ID, browser, and platform identify the installed binary selection. The runtime version is useful evidence that the expected browser started, while the executable path helps distinguish a managed installation from a system browser. Avoid treating any one of these fields as a substitute for the others.

7. Troubleshooting

Symptom	Likely cause	Fix
`resolveBuildId` rejects the tag	The tag is unavailable for that browser/provider, or the value is misspelled.	Use a documented tag supported by that browser provider, and check the current BrowserTag API.
No platform is detected	The current operating system or architecture is not supported by the detection helper.	Check the supported platform values for the browser-management API and choose a supported deployment target explicitly where appropriate.
Install succeeds but launch fails	The selected executable may not run in the environment, required system dependencies may be missing, or the architecture may not match.	Verify the executable path and platform, install the runtime dependencies required by the environment, and test the selected build there.
`puppeteer-core` reports a missing executable	Neither a usable `executablePath` nor `channel` was configured.	Set `executablePath` to the installed binary or configure an installed browser channel.
Runtime version differs from the expected build	The launch path or channel selected a different browser than the one you installed.	Log `browser.version()` and the executable path; make the launch configuration point directly to the intended binary.
Behavior changes across machines	A moving tag resolved at different times, or machines use different platforms/providers.	Pin and record the build ID, browser, platform, and Puppeteer version; update them together deliberately.
A custom browser has missing or changed behavior	The browser provider or version is outside Puppeteer’s tested and guaranteed configuration.	Validate required features against the Puppeteer version, and maintain that compatibility check for every platform you support.

8. Performance, reliability, and cost considerations

Resolve channels during provisioning: resolving a moving channel at every application start can produce different selections over time. Resolve at an update boundary, record the ID, and install the pinned build for repeatable runs.
Reuse the browser cache: Puppeteer’s browser install options use the build ID to identify binaries for caching. Keep the cache available across builds when your CI system supports it, while ensuring the browser and platform selections match.
Plan for platform-specific binaries: a build record should include platform. Do not assume an executable installed for one operating system or architecture can be used on another.
Budget maintenance for custom providers: custom browser providers require your team to check compatibility, validate features, and keep versions consistent across platforms.
Control download and startup work: install browsers in image or environment provisioning rather than repeatedly downloading them for individual automation tasks.

These practices reduce avoidable downloads and make failures easier to reproduce. Actual startup time and resource use depend on the binary, host, and workload; Puppeteer’s cited documentation does not establish universal benchmark values.

9. Capture a page without managing a browser binary

For a website screenshot rather than browser automation or browser-build testing, ScreenshotNeo is an alternative to try first. ScreenshotNeo is a screenshot API and MCP server from ScreenshotNeo; its one-call API returns an image or PDF, so there is no Puppeteer binary to install or pin. See the ScreenshotNeo API documentation.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

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}`);
const bytes = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

ScreenshotNeo accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Plans include every feature.

10. FAQ

Is `stable` a Chrome version?

No. It is a release-channel tag. Resolve it to a build ID to select a concrete build.

Does a build ID identify a browser on every platform?

Use the build ID together with the browser and platform. Those are the inputs used to select and locate a browser binary.

Can I trust `browser.version()` as a permanent format?

It is useful runtime evidence, but Puppeteer warns that the returned string format may change. Avoid depending on a fixed parsing rule.

Which binary does Puppeteer guarantee?

Puppeteer tests and guarantees Chrome for Testing. Treat other providers and executable paths as compatibility choices that you must validate.