Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallTo make Puppeteer download Chrome from a mirror, set chrome.downloadBaseUrl in a Puppeteer configuration file or set PUPPETEER_CHROME_DOWNLOAD_BASE_URL before installation. Include the URL scheme, omit the trailing slash, then run npx puppeteer browsers install so the new download setting takes effect. This is a browser-install setting for the puppeteer package—not an option passed to puppeteer.launch().
Configure a project-wide Chrome download base URL
A configuration file is the clearest option when a project should consistently use the same browser mirror on developer machines and in CI. Puppeteer searches upward through the project tree for supported configuration filenames, including the following:
.config/puppeteer.config.cjs,.config/puppeteer.config.js,.config/puppeteerrc.cjs,.config/puppeteerrc.js,.config/puppeteerrc.json, and.config/puppeteerrcpuppeteer.config.cjsandpuppeteer.config.jspackage.json
For an ESM configuration file, use this shape:
/** @type {import('puppeteer').Configuration} */
export default {
chrome: {
downloadBaseUrl: 'https://mirror.example.com/chrome-for-testing-public',
},
};Save it under one of Puppeteer’s supported names, such as puppeteer.config.js. The example assumes the project is configured to load JavaScript configuration as ESM. If your project uses CommonJS, use a .cjs file instead:
/** @type {import('puppeteer').Configuration} */
module.exports = {
chrome: {
downloadBaseUrl: 'https://mirror.example.com/chrome-for-testing-public',
},
};You can also use a JSON configuration file when you do not need JavaScript comments or logic:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
{
"chrome": {
"downloadBaseUrl": "https://mirror.example.com/chrome-for-testing-public"
}
}Use the mirror’s base host or directory as the value. Do not add a final slash: Puppeteer builds the archive URL by adding the browser, platform, and build-specific path. The mirror therefore needs to provide the archive paths and build IDs Puppeteer expects; a server that merely hosts a Chrome archive under an unrelated filename will not necessarily work.
Apply the setting after changing it
Browser downloads happen as part of Puppeteer’s installation workflow, so adding or editing a config file alone does not change a browser that is already installed or cached. After setting the value, run:
npx puppeteer browsers installPuppeteer’s configuration guide says download-option changes require rerunning the postinstall scripts for the change to take effect. The browsers-install command is the direct way to request the browser installation after updating the setting. A new URL controls where the next required browser archive is fetched; it does not relocate an existing cached browser.
If you want the package installation itself to download from the mirror, make sure the setting is available before installing Puppeteer. For example, create the project config first, then install the package. If the package manager skips install scripts, run the browsers-install command manually or configure the package manager to permit Puppeteer’s install script.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Set the URL with an environment variable
For a one-off install, a CI job, or a build environment where config files should remain environment-neutral, set the Chrome-specific variable before installing or installing browsers:
PUPPETEER_CHROME_DOWNLOAD_BASE_URL=https://mirror.example.com/chrome-for-testing-public npm install puppeteer
npx puppeteer browsers installEnvironment variables override applicable configuration-file options. Current configuration uses the browser-specific name PUPPETEER_CHROME_DOWNLOAD_BASE_URL. Older Puppeteer API material used the more general PUPPETEER_DOWNLOAD_BASE_URL; use the variable documented for the Puppeteer major version actually installed in your project rather than assuming the older name applies to current configuration.
In CI, set the variable in the job or step environment before the install command, and keep the mirror endpoint consistent with the browser artifacts available to that job. Avoid putting credentials directly in a committed configuration file or in a URL that might appear in logs. For a private mirror, use the environment or secret-management mechanism your CI provider supplies for sensitive values; the exact authentication method depends on the mirror and is not defined by Puppeteer’s base-URL setting.
Choose the right method for your workflow
| Method | Scope | Best fit | Important detail |
|---|---|---|---|
| Configuration file | Project-wide | A repository whose local installs and CI should share a persistent setting | Keep it in a supported location and make sure the selected file format matches the project module system. |
PUPPETEER_CHROME_DOWNLOAD_BASE_URL |
Process or environment | CI jobs, temporary overrides, or builds with environment-specific mirrors | Set it before the browser installation step; it overrides an applicable config-file value. |
InstallOptions.baseUrl |
One direct Browsers API install call | Code that uses @puppeteer/browsers without relying on Puppeteer’s package configuration |
Pass the value to install(); it is not a puppeteer.launch() option. |
A checked-in config is reproducible because the setting travels with the project, while an environment variable allows the same project to target different mirrors in different environments. For credentials or other sensitive information, keep secrets out of source control and out of visible command output. Neither method changes the mirror’s contents: the host still needs the compatible browser artifacts Puppeteer requests.
Recommended Free Tools
Rank #3
Set a base URL with @puppeteer/browsers directly
If your code calls the Browsers API rather than relying on Puppeteer’s own installation behavior, pass the host as InstallOptions.baseUrl. This is a separate, explicit install call:
import { install, Browser } from '@puppeteer/browsers';
await install({
browser: Browser.CHROME,
buildId: 'YOUR_BUILD_ID',
cacheDir: './.cache/puppeteer',
baseUrl: 'https://mirror.example.com/chrome-for-testing-public',
});Replace YOUR_BUILD_ID with the build ID your application intends to install. The installer combines the selected browser, platform, and build ID with the base URL to construct the download location. The documented default hosts are Chrome for Testing’s Google Cloud Storage host and Mozilla’s Firefox nightly host; supplying baseUrl overrides the host for the install call. This API option does not configure puppeteer.launch() and does not make Puppeteer use a different executable automatically if you manage the browser separately.
Check whether the package is puppeteer or puppeteer-core
The config-file and environment-variable defaults described here apply to puppeteer. Puppeteer’s official configuration reference says those configuration files and variables are ignored by puppeteer-core. Also, puppeteer-core does not download Chrome when installed.
If your project uses puppeteer-core, obtain a compatible browser through your own deployment process or use the Browsers API directly, then tell Puppeteer where to find that browser at launch. The relevant launch options are executablePath for a specific executable path or a standard channel for a browser channel. Changing PUPPETEER_CHROME_DOWNLOAD_BASE_URL alone will not redirect a puppeteer-core install.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Troubleshoot a mirror that is not being used
Puppeteer still downloads from Google’s host
- Check that the variable is spelled
PUPPETEER_CHROME_DOWNLOAD_BASE_URLand is set in the same environment that runs installation. - Confirm the config file is in a supported name and location and is discoverable from the project.
- Check whether the project uses
puppeteer-core; it ignores these defaults. - Look for an environment variable overriding the config-file setting, since the environment takes precedence when applicable.
- After correcting the setting, run
npx puppeteer browsers installto apply it to a required browser download.
The download fails or returns a missing archive
Verify that the URL has an explicit protocol such as https://, has no trailing slash, and points to the expected mirror base. Then verify that the mirror preserves the browser archive paths and build IDs requested for the selected platform. Puppeteer constructs the final path; the base setting does not rename or search for arbitrary files.
No browser was downloaded during package installation
A package manager can block install scripts. Run npx puppeteer browsers install manually after installation, or adjust the package-manager policy so Puppeteer’s install script is allowed. Ensure the configuration or environment variable is set before running that command.
The setting changed but an existing browser is still present
A base URL selects the host for a future required archive download; it does not move a browser already in Puppeteer’s cache. To confirm the mirror is actually needed, use a browser installation that requires an archive not already available in the relevant cache. Do not infer that the mirror was ignored merely because an existing cached browser remains usable.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is to get a screenshot of a web page—not to run Puppeteer automation or configure a Chrome download mirror—a screenshot API can avoid setting up a browser in your project. ScreenshotNeo accepts a URL in one GET request and returns an image or PDF; it is a separate service, not a way to change Puppeteer’s download host. Its screenshot options include PNG, JPEG, or WebP output, and PDF output.
For example, using cURL:
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 API documentation for request options. ScreenshotNeo removes cookie and consent banners, 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 identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Frequently Asked Questions
Does changing the download base URL affect an already installed browser?
No. It determines the host for a future required archive download; it does not move an existing cached browser.
Can I set a custom download base URL in puppeteer.launch()?
No. Use Puppeteer configuration or its Chrome download environment variable, or pass baseUrl to the direct Browsers API installer.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsDoes the ScreenshotNeo call configure Puppeteer’s browser download?
No. It requests a screenshot from ScreenshotNeo; it is an alternative only when the task is capturing a page rather than running Puppeteer.
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.
