How to Resolve a Browser Build ID with Puppeteer

Use resolveBuildId(browser, platform, tag) from @puppeteer/browsers to turn a browser release tag, such as stable, into the concrete build ID for a particular browser platform. Install the browser with that ID, then calculate its executable path using the same browser, build ID, platform, and cache directory.

This is useful when you manage the browser yourself or need a repeatable build configuration. If you use Puppeteer’s default managed browser, check the official Puppeteer browser compatibility table before manually selecting a different binary. Puppeteer guarantees compatibility with its bundled browser; a custom executable is your compatibility choice.

Resolve a build ID with JavaScript

Install the browser management package, then pass the browser, target platform, and tag to resolveBuildId. The function is asynchronous and returns a string.

npm install @puppeteer/browsers

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

const browser = Browser.CHROME;
const platform = BrowserPlatform.LINUX;
const tag = 'stable';

const buildId = await resolveBuildId(browser, platform, tag);
console.log(buildId);

Run this in an environment configured for ES modules, or adapt the imports to your project’s module system. Choose the platform where the browser will actually run. A Linux build ID or archive is not a substitute for the appropriate macOS or Windows build.

Install the resolved browser and find its executable

The resolved ID identifies the browser build used for installation and caching. Keep the browser, platform, ID, and cache directory consistent when calculating the executable path.

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

const browser = Browser.CHROME;
const platform = BrowserPlatform.LINUX;
const cacheDir = '/path/to/puppeteer-cache';
const buildId = await resolveBuildId(browser, platform, 'stable');

const installed = await install({browser, buildId, platform, cacheDir});
const executablePath = computeExecutablePath({browser, buildId, platform, cacheDir});

console.log('Build ID:', installed.buildId);
console.log('Installed executable:', installed.executablePath);
console.log('Computed executable:', executablePath);

install() resolves to an InstalledBrowser, which includes the build ID and executable path. You can use that returned path directly, or compute it from the installation inputs. Replace the example cache directory with the cache location used by your application or deployment.

Choose a browser and platform

resolveBuildId accepts a browser, a platform, and a string or BrowserTag. The package exports browser and platform constants so you can avoid guessing their accepted values. Check the @puppeteer/browsers API reference for the current API details.

Input	What it controls	Practical choice
browser	The browser product whose build you want.	Use the matching Browser constant, such as Browser.CHROME.
platform	The target operating system and architecture combination.	Use the matching BrowserPlatform constant for the machine or container that will run the browser.
tag	A release selector, version, or supported browser tag.	Use a moving channel such as stable when you want the current channel build; record the resolved ID when repeatability matters.
cacheDir	Where the browser is installed and looked up.	Pass the same directory to installation and path computation.

Do not infer current platform constants or browser tags from an old snippet. Consult the package API documentation for the version installed in your project.

Use the CLI for a known selector or version

The package also provides a command-line workflow. Official examples include installing Chrome from the stable channel, a specific Chrome for Testing version, or a milestone selector:

npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers install chrome@<exact-version>
npx @puppeteer/browsers install chrome@latest

Replace <exact-version> with the version you intend to install. The CLI is convenient when you already know the selector. Use the programmatic resolver when your script needs to discover the concrete build ID and record it as part of a deployment or build process. For repeatable automation, save the resolved ID and platform in configuration rather than resolving a moving channel alias on every run.

Let Puppeteer manage the browser or manage it yourself?

Approach	Browser management	Trade-off
puppeteer	Normally downloads a recent Chrome for Testing browser during installation.	The bundled browser is the compatibility path Puppeteer supports most directly.
puppeteer-core	Does not download Chrome.	You supply a browser, for example with executablePath or a standard-location channel.
Manual @puppeteer/browsers installation	You resolve, install, cache, and select a browser build.	You gain control over platform and version selection and take responsibility for checking compatibility.

When launching Puppeteer with a custom binary, pass the path that matches the installed build and platform. A channel instead selects a regular Chrome installation at a known system location. See the Puppeteer installation guide and LaunchOptions reference for the current setup and launch options.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  executablePath: '/path/to/the/installed/chrome',
  headless: true,
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  await browser.close();
}

Use the actual path returned by the installation workflow, not the illustrative path above. Before pinning a browser manually, look up the Puppeteer version in the supported browsers table. That table changes with releases; do not rely on an undated version pairing copied from an old article.

Reproducibility, performance, reliability, and cost

• Reproducibility: a channel such as stable moves over time. Resolve it during a controlled build, then record the returned build ID and target platform for subsequent installs.
• Platform correctness: resolve for the deployment OS and architecture. Keep platform-specific artifacts and paths separate when building for multiple targets.
• Cache consistency: install and compute the path with the same cache directory. Puppeteer configuration can also set a cache directory; check cacheDirectory and PUPPETEER_CACHE_DIR if the browser appears missing.
• Performance: resolving a selector is a lookup step; browser download and installation are the work that can take time and storage. Reuse a managed cache in persistent build environments rather than downloading for every job.
• Reliability: prefer Puppeteer’s bundled browser when the supported pairing meets your needs. A custom binary or provider adds version, platform, and maintenance responsibilities.
• Cost: the workflow uses the package and browser binary; budget for download bandwidth, storage, and CI time in your own environment. No benchmark or fixed resource estimate is published in the documentation cited here.

Troubleshooting

Symptom	Likely cause	Fix
No browser was downloaded during package installation.	A package manager or install configuration blocked Puppeteer’s install script.	Run the browser installation command manually or allow the Puppeteer postinstall script, following the installation guide.
The computed path points to a missing executable.	The install and lookup used different cache directories, browser IDs, or platforms.	Use identical browser, buildId, platform, and cacheDir values for installation and path computation. Check cacheDirectory and PUPPETEER_CACHE_DIR.
Puppeteer launches another Chrome or cannot find the intended one.	An explicit executablePath, PUPPETEER_EXECUTABLE_PATH, or channel selects a different installation.	Inspect those settings and pass the intended installed executable path, or deliberately use a system channel.
A custom browser launches but behaves differently.	The binary may not match the Puppeteer release or target platform.	Check the live supported-browser table and test the exact browser/platform pairing. Puppeteer only guarantees its bundled browser.
A mirror or custom provider serves the binary.	Custom providers are not officially supported by Puppeteer.	Validate the provider’s binary, compatibility, and ongoing maintenance yourself; do not assume it behaves like the default provider.
The same channel produces a different build later.	Channel names are moving selectors.	Resolve the channel once in a controlled step and store the returned build ID alongside the platform and package version.

Or skip the browser setup

If your task is to capture a website screenshot rather than control a local Chrome binary, ScreenshotNeo is a website screenshot API and MCP server. Its one-call API returns an image or PDF, and the API documentation describes the available parameters.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

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);

• Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
• An MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs.
• 1,000 screenshots per month are free 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 resolving a build ID install the browser?

No. Resolution returns the ID. Call install() or use the CLI to obtain the browser binary.

Can I use the same build ID on every operating system?

Resolve for the target platform. The platform is part of the selection and must match the machine that runs the browser.

Should I pin a build ID or use stable?

Use a channel when you want to follow that release channel. Resolve and record its concrete ID when your build needs repeatable browser inputs.

Where can I check which Chrome works with my Puppeteer version?

Use Puppeteer’s live supported browsers table. The browser associated with each Puppeteer release can change as releases advance.

When is puppeteer-core appropriate?

Use it when browser installation is managed elsewhere and your application will provide a compatible executable or channel.