The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →The documented constructor is new DefaultProvider(baseUrl): its single argument is a download-host URL, not a general options object. For routine browser installation, configure install({ ... }); use a custom provider only when you need a different download source or browser distribution. Puppeteer’s API pages consulted show different versions—25.5.0 for DefaultProvider and 25.12.0 for InstallOptions—so check the API reference matching your installed package before relying on version-sensitive behavior.
What does the DefaultProvider constructor accept?
Puppeteer documents DefaultProvider as its standard BrowserProvider implementation, with the constructor signature new DefaultProvider(baseUrl). The constructor reference names baseUrl; it does not document a general options object or additional constructor parameters. See the DefaultProvider API reference.
The provider API also lists getDownloadUrl(options), getExecutablePath(options), getName(), and supports(options). These methods belong to provider behavior; they are not extra constructor arguments.
When should you construct a provider yourself?
Use the default provider for ordinary installs
If Puppeteer’s normal browser download source works for your project, there is generally no need to instantiate DefaultProvider. Use the install API and specify the browser, build, and cache settings you need. Puppeteer’s InstallOptions reference says custom providers are optional and that a default provider is automatically added as a fallback.
#1 Best Overall
Use a custom provider for a mirror or private distribution
When downloads must come from a mirror or a different browser distribution, implement the BrowserProvider interface and pass the provider instance through install({ providers: [...] }). The provider must determine whether it supports the requested browser/build/platform, return a valid download URL, and identify the executable path after installation.
Puppeteer’s provider example is an interface pattern, not a plug-and-play mapping for every archive. Adapt the browser, platform, archive naming, and executable paths to the distribution you actually use. Custom providers are not officially supported; the implementer owns compatibility checks, testing, and maintenance. Puppeteer says it tests and guarantees compatibility with its default binaries.
Rank #2
Which settings belong in install options?
Install options control which browser binary Puppeteer downloads, where it comes from, and where it is cached. The documented settings include:
browser: browser to install.buildId: browser build identifier. Puppeteer says it should uniquely identify the binary and is used for caching.cacheDir: directory for downloaded browsers.baseUrl: optional download-host override. The documented defaults are Chrome for Testing storage for Chrome and Mozilla’s Firefox nightly archive for Firefox.platform: target browser platform; auto-detected when omitted.providers: optional providers attempted in order, followed by the default provider fallback.expectedHash: optional SHA-256 archive verification. If omitted, the download proceeds without integrity verification.installDeps: optional dependency installation, defaulting tofalse; supported only for Chrome on Debian or Ubuntu and requires system privileges forapt-get.unpack: whether to unpack the archive; defaults totrue.downloadProgressCallbackandlogger: controls for progress reporting and logging.
Check the InstallOptions API page for the precise types and signatures in the version you have installed.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How to set up a custom browser provider
The following shows the shape of an install call when you already have an object implementing the provider interface. Supply concrete values appropriate to your package version and target distribution; the example deliberately does not invent a universal archive or executable path.
import { install } from '@puppeteer/browsers';
import { myProvider } from './my-provider.js';
const installed = await install({
browser: 'chrome',
buildId: process.env.CHROME_BUILD_ID,
cacheDir: './.cache/puppeteer',
providers: [myProvider],
});
console.log(installed.executablePath);The custom provider itself should implement the provider methods for its distribution. For example, its getDownloadUrl(options) must construct a URL that actually serves the requested archive, and getExecutablePath(options) must match the archive’s installed layout. The exact provider API and accepted browser values are package-version-sensitive; use the official provider example and your installed package’s types as the implementation reference.
What is separate from provider setup?
Installation selects and caches a binary. Launch options configure the browser process after that binary is available. Puppeteer’s LaunchOptions reference includes options such as browser, channel, executablePath, args, headless, userDataDir, and timeout.
Use executablePath or channel when you intend to launch a different local installation or browser channel; those are not DefaultProvider constructor settings. Puppeteer warns that its compatibility guarantee applies to its bundled browser. Its configuration guide explains that it downloads a specific Chrome version by default, supports configuration files for defaults, and allows applicable environment variables to override configuration. Configuration files and environment variables are ignored by puppeteer-core. If browser download configuration changes, follow that guide’s instructions to rerun browser installation or the relevant postinstall step.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesBest Value
- Used Book in Good Condition
Default provider or custom provider?
| Approach | Download source | Compatibility responsibility | Setup | Fallback |
|---|---|---|---|---|
| Default provider | Puppeteer’s standard source | Puppeteer tests and guarantees compatibility with its default binaries | Use install options; no custom provider implementation | It is the documented fallback in the provider chain |
| Custom provider | Mirror, private host, or custom browser distribution | You validate binary/version compatibility, archive layout, executable paths, and integration | Implement provider methods and pass the instance in providers |
Can be placed in a chain that falls back to the default provider |
The comparison follows Puppeteer’s install options documentation and provider example.
Troubleshooting provider installation
- The constructor rejects an object or extra arguments. The documented constructor takes
baseUrl. Put browser, build, platform, cache, and provider-chain settings in the install options instead. - The mirror returns a 404 or downloads the wrong archive. Check that
getDownloadUrl(options)accounts for the requested browser, build ID, and platform, and that the host serves the resulting archive. - Installation succeeds but launch cannot find the browser. Verify
getExecutablePath(options)against the extracted archive layout and check that your launch configuration points to the installed executable where needed. - A provider does not handle a requested browser or platform. Ensure
supports(options)returns the correct result, or place another suitable provider later in the chain. The default provider is added as fallback according to the install options reference. - Download behavior does not reflect configuration changes. Confirm you are not using
puppeteer-coreif relying on Puppeteer configuration files or environment variables; those are ignored bypuppeteer-core. Then rerun the browser installation step described in the configuration guide. - Dependency installation fails on Linux. The documented
installDepssupport is limited to Chrome on Debian or Ubuntu and requires privileges forapt-get. - You need archive integrity checking. Set
expectedHashto the expected SHA-256 value; without it, the install does not perform that verification.
Or skip the browser setup
If your goal is to capture a website rather than manage a Puppeteer browser binary, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return an image or PDF; the example below saves the response body as a WebP file. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie/consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses include X-Page-Verdict and X-Billed headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Learn more at ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Does `DefaultProvider` accept a custom cache directory?
No. Configure `cacheDir` in the install options; the documented constructor argument is `baseUrl`.
Can a custom provider replace the default provider entirely?
The documented install flow automatically adds the default provider as a fallback, so a custom provider can be attempted first without removing that fallback.
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.
