How Puppeteer Resolves a Browser Build ID

Puppeteer resolves a browser build ID from three inputs: the browser, target platform, and tag or identifier. Its public resolveBuildId(browser, platform, tag) function returns a promise that resolves to a browser-specific build ID string. In Puppeteer’s package installation flow, the requested version comes from configuration, then Puppeteer’s pinned revision for that browser, then latest; the package resolves that selection before installing the binary.

1. What a browser build ID identifies

A build ID identifies a browser binary for downloading and caching. It is not simply a universal browser version: resolution is scoped to a browser and platform, and the mapping for a tag depends on browser data maintained by the package. The resulting ID is used to select the binary and its cache entry.

Keep the terms distinct:

Browser: the browser product requested, such as Chrome or another browser supported by the package.
Platform: the operating system and architecture target for the binary.
Tag or identifier: a moving channel such as stable, or a version-like selection.
Build ID: the resolved string identifying the binary to install.

The exact accepted tags and resolution behavior can vary by browser. Do not assume every browser accepts the same selectors.

2. The resolution and installation flow

Choose a browser and target platform.
Choose a channel tag or a specific version/identifier.
Call resolveBuildId to obtain the browser-specific build ID.
Pass that ID, browser, and cache directory to the installer.
Launch the installed browser, normally through Puppeteer’s supported browser selection.

The InstallOptions contract requires browser, buildId, and cacheDir; platform can be auto-detected when omitted. In Puppeteer’s package install flow, the unresolved choice is configuration.version, then PUPPETEER_REVISIONS[browser], then latest. The selected value is resolved before installation. If resolution changes the identifier, the installer can retain the original as buildIdAlias, which supports alias handling in launch selection.

3. Use a channel tag or an exact version

Selection	What it means	When to use it
`chrome@stable`	A channel selection that can move as releases change.	When you want the current stable channel for the selected browser/platform.
`chrome@116.0.5793.0`	An explicit version-style request.	When you need to request a particular version consistently.
`latest`	A latest selection interpreted for the chosen browser and platform.	When that moving selection is intentional.

The Puppeteer package overview demonstrates installing Chrome using npx @puppeteer/browsers install chrome@stable and an exact version such as chrome@116.0.5793.0. A channel is convenient but may resolve differently later. For repeatable automation, record the resolved build ID and use a deliberate versioning policy rather than assuming a channel remains fixed.

4. Resolve and install with the browsers package

Install the package, then resolve and install in code. This example uses the public API shape; use a browser, platform, and tag supported by the package version and target environment.

npm install @puppeteer/browsers

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

const browser = Browser.CHROME;
const platform = detectBrowserPlatform();
if (!platform) {
  throw new Error('Could not detect a supported browser platform');
}

const tag = 'stable';
const buildId = await resolveBuildId(browser, platform, tag);
console.log(`Resolved ${browser} on ${platform}: ${buildId}`);

const installed = await install({
  browser,
  buildId,
  cacheDir: './.browser-cache',
});
console.log(`Installed browser at ${installed.executablePath}`);

The APIs and enum exports should be checked against the installed @puppeteer/browsers version. If your environment requires a specific platform rather than auto-detection, supply that platform explicitly. The important sequence is resolution first, then installation using the returned build ID.

5. Install from the command line

For a direct package CLI installation, the documented examples are:

npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers install chrome@116.0.5793.0

The first requests the stable channel; the second requests an explicit version. The selection is interpreted for the browser and platform before the corresponding binary is installed. Consult the package documentation for the available command options for your installed release.

6. Compatibility and launch behavior

Resolving and downloading a build does not guarantee that every arbitrary build is fully compatible with your Puppeteer version. Puppeteer documents its compatibility guarantee for its bundled browser. Launching a different binary through executablePath is supported, but is at the user’s risk. If you need a reliable baseline, use the browser version bundled or pinned for your Puppeteer release; choose a custom build only when you can manage compatibility yourself.

Aliases matter when the requested channel or version string differs from the resolved build ID. Puppeteer’s package installation source preserves the unresolved value as buildIdAlias when they differ. Direct users of @puppeteer/browsers can instead resolve and install explicitly, and should retain whatever mapping their own launch workflow needs.

7. Platform, reproducibility, and operational notes

Resolve for the destination platform. A build selected for one operating system/architecture is not automatically the right artifact for another.
Record the resolved ID. Channel names express intent, while the resolved build ID records what was selected at that time.
Use a persistent cache directory where appropriate. Build IDs are used for cache identity, so repeated installs can reuse the corresponding cached browser when the environment preserves the cache.
Keep package and browser choices aligned. Puppeteer’s guaranteed compatibility applies to its bundled browser; custom versions add compatibility risk.
Plan for moving channels. A channel may resolve to a different build later, so builds that must be reproducible should pin or record the resolved identifier.

8. Troubleshooting

Symptom	Likely cause	Fix
Platform detection returns no value	The runtime platform/architecture is unsupported or not recognized.	Set the target platform explicitly if supported, and confirm the package supports that environment.
Resolution rejects a tag	The tag is not valid for that browser, platform, or package data version.	Check the browser-specific supported selectors; try a documented channel or explicit version.
Install cannot find the resolved build	The browser/platform/build combination is unavailable, or network access to the download source is blocked.	Verify the selection and platform, then check outbound network access and retry.
Launch fails after a successful install	The selected binary may not be compatible with the Puppeteer version, or its required runtime dependencies are missing.	Start with Puppeteer’s bundled browser; check environment dependencies and executable path before using a custom build.
A channel install changes between runs	Channel tags are moving selections.	Log the resolved build ID and pin a specific version/build for reproducible jobs.
Expected cache reuse does not occur	The cache directory differs across runs or the resolved build ID changed.	Use a stable cache directory and inspect the resolved ID and platform used by each run.

9. Screenshot capture without managing browser builds

For screenshots of public web pages, you can use ScreenshotNeo’s website screenshot API instead of installing and maintaining a local browser binary. ScreenshotNeo returns PNG, JPEG, WebP, or PDF from one GET request. 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}`);
await Bun.write('shot.webp', res);

ScreenshotNeo accepts common screenshot API parameter names to make switching easier. Cookie banners, newsletter popups, and chat widgets are removed before the capture; those cleanup steps can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. It also provides an MCP server with screenshot, page-info, and PDF tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for the free plan.

10. Frequently asked questions

What does `resolveBuildId` return?

A promise that resolves to a string build ID for the supplied browser, platform, and tag/identifier.

Does a build ID guarantee Puppeteer compatibility?

No. The documented compatibility guarantee is for Puppeteer’s bundled browser. A custom executable path is supported at the user’s risk.

Should I use `stable` or an exact version?

Use a channel when following its current release is intended. Use an explicit version or recorded resolved build when repeatability matters.

Why does platform matter?

The platform selects the operating system and architecture relevant to the binary, so resolution is not a global version lookup.