How Puppeteer Builds Browser Archive Filenames
Puppeteer’s standard archive filename, a provider’s download filename, and the installer’s cached archive path are related but distinct.
Puppeteer does not use one filename for every stage of installing a browser. Its documented buildArchiveFilename(browser, platform, buildId, extension) utility builds a standard archive filename, while the download provider supplies the URL and the actual archive name. During installation, Puppeteer takes the final path component of that URL and prefixes it with the build ID to form a temporary archive-cache path.
Keep these three things separate when debugging or writing tooling: the utility’s standard name, the provider’s source archive name, and the installer’s cached copy. The extracted installation directory and the browser executable inside it are separate again. Puppeteer documents the utility, but the available API index does not establish its exact filename template or default extension. Check the implementation for the exact Puppeteer version you use before relying on either.
This guide follows the official Puppeteer API and implementation material reviewed on 2026-10-03. The source checked was the mutable GitHub main branch, not a pinned release, so verify details against your installed version.
1. What does buildArchiveFilename do?
Puppeteer’s browser API describes buildArchiveFilename(browser, platform, buildId, extension) as a utility for building a “standard archive filename.” The API lists it separately from getDownloadUrl, which retrieves an archive URL for a browser, platform, and build ID, and install, which downloads and processes the archive. These operations are related, but they answer different questions:
buildArchiveFilename: what standard name should be constructed from the supplied browser, platform, build ID, and extension?getDownloadUrl: where does the configured provider say the archive is?install: how does Puppeteer fetch that URL and install the browser?
The API index does not give enough detail to safely state the utility’s exact output template or a default extension. Do not infer that its result must equal the final component of every provider URL.
2. The three filenames and paths
| Item | How it is determined | What it identifies |
|---|---|---|
| Standard archive filename | Constructed by buildArchiveFilename(browser, platform, buildId, extension). |
A standardized name; the exact template must be checked in the target version’s implementation. |
| Provider archive filename | The provider’s download URL; Puppeteer takes its final path component during installation. | The archive asset made available by that provider. |
| Temporary archive-cache path | path.join(browserRoot, `${options.buildId}-${fileName}`), where fileName comes from the provider URL. |
The downloaded archive copy used during installation, or returned/downloaded when unpacking is disabled. |
| Installation directory | Chosen by the installer separately from the archive path. | The destination for the unpacked browser files. |
| Executable path | Resolved within the installed browser layout. | The browser binary used to launch the browser, not the archive. |
In the installer implementation described by the official source, the browser root is the base for the temporary archive path. If unpack is disabled, Puppeteer downloads or returns that archive path. If unpacking is enabled, it processes the archive into a distinct installation directory and removes the downloaded archive after successful processing.
3. Trace the name for your installed Puppeteer version
- Record the version. Check the version resolved by your package manager, rather than assuming the current GitHub
mainimplementation matches it. - Inspect the utility implementation. Find
buildArchiveFilenamein that release’s source. Confirm how each argument is used and whether the extension is required or defaulted. - Inspect the provider. Follow
getDownloadUrlor the configured browser provider for the browser, platform, and build ID. The returned URL tells you which asset is actually being requested. - Inspect installation options. The install options include the browser, platform, build ID, cache directory, and
unpackchoice. The build ID identifies the binary and is also used for caching. - Derive the paths. Read the final URL path component for the provider filename, then apply the install implementation’s path construction. Do not substitute the standard utility result unless the target version’s code explicitly does so.
For version-specific answers, use the source tag or commit corresponding to your lockfile. A link to the moving main branch can explain current behavior, but it is not proof of behavior in an older installed release.
4. Why provider archive names differ
The provider controls the URL and therefore the archive filename Puppeteer sees at install time. The name can vary by browser, platform and architecture, build ID or release channel, and archive format.
Puppeteer’s API examples for a custom Chrome mirror show names such as chrome-linux64.zip, chrome-mac-x64.zip, chrome-mac-arm64.zip, chrome-win32.zip, and chrome-win64.zip. These illustrate platform-dependent names; they are not a promise that every provider or release uses those names.
Firefox’s official source demonstrates more variation. It constructs archive names from channel, platform, and build ID. Stable, Beta, ESR, and Developer Edition have patterns different from Nightly, and Linux, macOS, and Windows use different names. For the specified Nightly Linux archives, the source selects .tar.xz from major version 135 onward and .tar.bz2 for earlier versions. That is a version-specific source-code rule, not a general Puppeteer extension default.
5. Code: inspect the URL and model the cache path
The following runnable Node.js example illustrates the installer’s URL-derived naming rule. It accepts a provider URL, takes its final path component, and combines it with a build ID under a browser root. It does not call Puppeteer’s private internals or claim to reproduce buildArchiveFilename.
import path from 'node:path';
const providerUrl = process.argv[2];
const buildId = process.argv[3];
const browserRoot = process.argv[4] ?? './browser-cache';
if (!providerUrl || !buildId) {
console.error('Usage: node inspect-archive-path.mjs <provider-url> <build-id> [browser-root]');
process.exit(2);
}
const url = new URL(providerUrl);
const fileName = decodeURIComponent(url.pathname.split('/').filter(Boolean).at(-1) ?? '');
if (!fileName) {
throw new Error('Provider URL has no filename in its path');
}
const archivePath = path.join(browserRoot, `${buildId}-${fileName}`);
console.log({ fileName, archivePath });Save it as inspect-archive-path.mjs and run, for example:
node inspect-archive-path.mjs 'https://downloads.example.test/chrome-linux64.zip' '123456' './cache'The example prints a provider filename and a corresponding cache path. The example hostname is illustrative and is not a real browser download endpoint. URL encoding, query parameters, and platform-specific path rules can affect custom code; when matching Puppeteer exactly, inspect the version’s own implementation.
Using Puppeteer’s API
In the Puppeteer version you have installed, consult its browser API for the documented helper and the provider methods. The documented function signature is buildArchiveFilename(browser, platform, buildId, extension). Supply arguments valid for that version’s API; do not guess an extension or assume an undocumented default. The available API index also identifies getDownloadUrl and install as separate operations.
Install option values that matter when tracing paths are the browser, platform, build ID, cache directory, and unpack. The optional expected SHA-256 checksum controls an integrity check: the documentation says that if it is omitted, download proceeds without that verification. Use the matching version’s API documentation and types for exact import paths and argument shapes.
cURL: inspect a provider response
cURL can show response headers and redirect behavior, but it does not determine Puppeteer’s cache path. Use the actual provider URL obtained for your target version; do not treat the illustrative URL below as a working endpoint.
curl -fIL 'https://downloads.example.test/path/to/archive.zip'Check redirects and the final response’s headers when diagnosing a provider URL. The URL path component is the relevant source for the filename rule described above; a Content-Disposition header should not be assumed to override Puppeteer’s URL-derived name.
Python: derive the same illustrative path
from pathlib import Path
from urllib.parse import urlparse, unquote
import sys
if len(sys.argv) < 3:
raise SystemExit('Usage: python inspect_archive_path.py <provider-url> <build-id> [browser-root]')
provider_url, build_id = sys.argv[1], sys.argv[2]
browser_root = Path(sys.argv[3] if len(sys.argv) > 3 else './browser-cache')
file_name = unquote(urlparse(provider_url).path.rstrip('/').rsplit('/', 1)[-1])
if not file_name:
raise SystemExit('Provider URL has no filename in its path')
print('fileName:', file_name)
print('archivePath:', browser_root / f'{build_id}-{file_name}')Save as inspect_archive_path.py and run it with a provider URL and build ID. This models the documented source behavior; it is not a replacement for checking Puppeteer’s target-version code.
6. Troubleshooting
| Symptom | Likely cause | What to check or fix |
|---|---|---|
| Expected filename does not match the downloaded archive. | The standard utility name was mistaken for the provider’s asset name. | Inspect the actual URL returned by the configured provider and use its final path component. |
| Archive path has an unexpected prefix. | The build ID is prepended to the provider filename in the temporary cache path. | Compare the full path, including the build ID, rather than only the basename. |
| Code expects a ZIP but receives a tar archive. | The browser, platform, release channel, or build version uses another format. | Inspect provider source and the release-specific asset URL; Firefox Nightly Linux is an example where the format changes by major version. |
| Archive is missing after a successful install. | With unpacking enabled, Puppeteer removes the downloaded archive after successful processing. | Look for the installed browser directory. Set unpack appropriately if your workflow specifically needs the archive path. |
| Installer returns or leaves an archive instead of an installed browser. | Unpacking is disabled, or installation did not reach successful extraction. | Check the unpack option and the install result; distinguish the archive path from the installation directory. |
| Checksum is not being verified. | No expected SHA-256 checksum was supplied. | Provide the expected checksum using the version’s documented install option when you require this integrity check. |
| Source behavior differs from the documentation or a blog example. | The package version differs from the mutable source branch being consulted. | Inspect the release tag or commit matching the installed package and its provider implementation. |
7. Reliability, performance, and cost considerations
Filename construction itself is not the main source of installation cost or delay. The relevant operational factors are the provider URL, network transfer, archive format and size, unpacking, cache location, and whether an existing installation can be reused. The available sources establish that the build ID is used for caching, but provide no benchmark for install speed or storage savings.
For reliability, verify that the provider URL maps to the expected browser, platform, and build ID. When integrity matters, provide the optional expected SHA-256 checksum; omitting it means Puppeteer downloads without that verification. Keep temporary archives, unpacked installations, and executable paths distinct in cleanup logic, and avoid depending on an undocumented utility template across package upgrades.
This task concerns installing browser binaries; ScreenshotNeo is a hosted screenshot API rather than a replacement for Puppeteer’s browser installer. For pages where the goal is simply to obtain a screenshot, [ScreenshotNeo](https://screenshotneo.com) offers a one-request API and an MCP server for AI agents. Its billing rules and plans are listed in the callout below.
8. Or skip the browser setup
If you need a page screenshot rather than a locally installed browser archive, ScreenshotNeo accepts one GET request and returns an image or PDF. See the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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}`);- Cookie 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 are not billed. Response headers say which page verdict applied and whether the request was billed.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdffor 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. Every feature is on every plan.
Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.
9. Frequently asked questions
Does Puppeteer’s standard filename have to match the downloaded archive?
No. The provider URL supplies the archive filename used by the installer. The standard filename utility is a separate API, and the available API index does not establish that every provider uses its output.
Does Puppeteer keep the archive after installing the browser?
With unpacking enabled, the installer removes the downloaded archive after successful processing. With unpacking disabled, it returns or downloads the archive path instead of performing the normal unpack step.
Where should I look for the executable?
In the installed browser directory. The archive path, extraction destination, and executable inside that destination are separate; use the target version’s installation API to resolve the executable path.
Can I assume the extension from the browser name?
No. Providers and releases can use different archive formats. Inspect the actual provider URL and the relevant version’s source.
Sources
- Puppeteer Browser API: standard filename utility, URL lookup, install API, and custom-provider filename examples.
- Puppeteer Browsers API: browser installation options and cache behavior.
- Puppeteer source repository: installer path construction and browser-provider implementations. Consult the tag or commit for the package version in use.
