Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallUse the public getDownloadUrl(browser, platform, buildId, baseUrl?) helper from @puppeteer/browsers to construct the archive URL for a specific browser build. It returns a URL; it does not download, install, or launch the browser. For a download and install, use the package’s install API instead.
Get a browser archive URL with getDownloadUrl
The documented API reference labels this function version 25.10.0. Its signature is:
getDownloadUrl(
browser: Browser,
platform: BrowserPlatform,
buildId: string,
baseUrl?: string,
): URLImport the helper and enums from @puppeteer/browsers. Supply the exact browser, platform, and build ID you want; optionally supply a base URL if the archive is hosted elsewhere.
import { Browser, BrowserPlatform, getDownloadUrl } from '@puppeteer/browsers';
const url = getDownloadUrl(
Browser.CHROME,
BrowserPlatform.LINUX,
'1234567',
);
console.log(url.href);Replace 1234567 with the build ID you actually intend to use. The URL identifies an archive for that browser/platform/build combination. Do not guess a URL from a naming pattern: mismatched values can point to a different artifact or a URL that does not exist. See the official API reference for the current signature and supported values.
#1 Best Overall
Choose between constructing a URL, installing, and launching
| Goal | Use | What happens |
|---|---|---|
| Find an archive URL | getDownloadUrl(browser, platform, buildId, baseUrl?) |
Returns a URL; it does not fetch or unpack the archive. |
| Download and install a browser | install({ browser, buildId, cacheDir, baseUrl? }) |
Downloads and installs the selected browser build into the cache directory. |
| Start a browser | Puppeteer launch API, with the relevant executable path or channel when needed | Starts an installed or otherwise available browser; URL construction alone does not make one available. |
The browser-management documentation describes the install options and default hosts. For Chrome for Testing, the documented default is https://storage.googleapis.com/chrome-for-testing-public; for Firefox nightly, it is https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central. These are documented install defaults, not a universal URL rule for every browser or custom provider. See the install API.
Install a browser from code or the command line
Install with the browser-management API
Use install when you need the archive downloaded and unpacked rather than merely identifying its URL. Set browser and buildId to the matching values, and choose a cache directory if the default is unsuitable.
import { Browser, install } from '@puppeteer/browsers';
const installed = await install({
browser: Browser.CHROME,
buildId: '1234567',
cacheDir: './.browser-cache',
});
console.log(installed);This example requires a real build ID appropriate to the browser and environment. To use a different download host, pass baseUrl to install; the host must provide compatible artifacts. Consult the install options before wiring a mirror into automation.
Install Puppeteer’s supported browser manually
The current installation guide says installing the puppeteer package downloads a recent Chrome for Testing binary and chrome-headless-shell. If a package manager blocks installation scripts, run:
npx puppeteer browsers installUse the equivalent command for your package manager if appropriate. puppeteer-core does not download Chrome as part of package installation; it is intended for setups where you connect to a remote browser or manage the browser yourself. The guide documents approximate download sizes of 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows (Puppeteer, undated installation documentation accessed 2026). Actual transfer size and time can vary. See the installation guide.
Change the download host or cache location
Use a different host
For a supported install flow, provide baseUrl to the install API. Puppeteer’s configuration reference also documents browser-specific download-base URL settings, including Firefox’s downloadBaseUrl and its environment-variable override. Use the configuration that matches the browser and workflow rather than assuming a Chrome setting applies to Firefox. The exact available settings are in Puppeteer’s configuration reference.
Move the browser cache
Starting with Puppeteer v19.0.0, the default cache directory is $HOME/.cache/puppeteer. Change it through Puppeteer configuration or the PUPPETEER_CACHE_DIR environment variable. This matters in containers, CI jobs, and restricted home directories: make sure the install process and the process launching the browser use the same cache location. Refer to the installation guide and configuration reference.
Use a proxy when downloads require one
Proxy behavior depends on the environment. Puppeteer’s installation documentation says proxy-agent is needed to use a proxy for browser downloads. Configure the proxy for the installation environment and verify that the browser archive host is reachable from it; a correctly formed URL cannot bypass network restrictions.
Recommended Free Tools
When a custom browser provider makes sense
If your alternative source uses a different archive layout or needs custom URL logic, implement BrowserProvider.getDownloadUrl(options) and getExecutablePath(options). A provider can be tried alongside other providers, but Puppeteer warns that provider URLs are not validated in advance, so an unavailable URL may fail later when the download is attempted.
Puppeteer’s documentation is explicit: “Custom providers are NOT officially supported.” It also says, “Puppeteer only tests and guarantees Chrome for Testing binaries.” That means you own compatibility testing, artifact validation, and ongoing maintenance for a custom provider or mirror; forming a URL is not proof that the archive is compatible. Read the BrowserProvider interface documentation before relying on one.
Troubleshoot missing or unusable browser downloads
- The URL is wrong or the archive returns not found: check that browser, platform, and build ID describe the same artifact. Use a known matching build ID rather than inferring one from a version string.
- You expected
getDownloadUrlto download Chrome: it only returns a URL. Callinstallor run Puppeteer’s browser installation command to fetch and unpack a browser. puppeteer-coreinstalled but no browser is present: this package does not download Chrome during installation. Install a browser separately or connect to a remote one, then provide the executable path or channel required by your launch setup. See installation and configuration.- The install step appears to have been skipped: package managers can block install scripts. Run
npx puppeteer browsers installafter installation. - The download fails in CI or a container: check network access, proxy configuration, write permissions, and whether the install and launch processes share the same cache directory. The default cache is
$HOME/.cache/puppeteerfrom v19.0.0 onward unless configured otherwise. - A custom mirror URL exists but installation fails: the provider URL may be invalid, unavailable, or incompatible with Puppeteer’s expected archive and executable layout. Custom providers are not officially supported; validate the archive and executable path yourself.
- The browser installs but does not launch: URL resolution and installation do not guarantee launch readiness. Confirm the installed executable path or configured channel, platform compatibility, and that the launching process can access the same cache.
Or skip the browser setup
If your goal is a website screenshot rather than managing a local Puppeteer browser, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return an image or PDF; its options include full-page capture, selectors, device presets, custom CSS and JavaScript, and wait conditions.
Example cURL request (replace YOUR_API_KEY with your key):
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 documentation for API details. Cookie banners are accepted or removed before capture, along with known newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for the free plan.
Frequently Asked Questions
Which Puppeteer version is this API documented for?
The public getDownloadUrl reference displays version 25.10.0; adjacent documentation pages display 25.12.0. Check the API for the version installed in your project before relying on behavior across older releases.
Does Puppeteer validate a custom provider’s download URL before using it?
No. The BrowserProvider interface warns that URLs are not validated in advance, so a bad URL can fail later during the download.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →
