Puppeteer Default Browser Provider Constructor: Options and Setup

DefaultProvider has one documented constructor parameter: baseUrl, the download host. Create it with new DefaultProvider(baseUrl). For ordinary Puppeteer installs, you usually do not construct it yourself: pass browser selection, build ID, cache directory, platform, and optionally a provider chain to install({ ... }). Download setup controls which binary is fetched and cached; launch options control how an already available binary runs. See the official DefaultProvider API and InstallOptions reference.

What the DefaultProvider constructor accepts

The documented signature is new DefaultProvider(baseUrl). Puppeteer describes this as its standard BrowserProvider implementation. The API lists getDownloadUrl(options), getExecutablePath(options), getName(), and supports(options) as methods. The constructor reference names baseUrl; it does not document a general-purpose options object or additional constructor flags.

baseUrl is the host from which the provider constructs browser download URLs. A custom baseUrl makes sense when your organization maintains a compatible mirror or when downloads must come from a controlled host. The host alone does not make an arbitrary browser archive compatible: the expected build, platform layout, archive structure, and executable location must still match Puppeteer’s expectations.

Use Puppeteer’s default browser download

For the standard download source, use the install API directly. This example uses Chrome for Testing, resolves the installed package’s stable build ID for the current platform, installs it in an explicit cache directory, and prints the executable path.

npm install @puppeteer/browsers

// install-browser.mjs
import {
  Browser,
  detectBrowserPlatform,
  install,
  resolveBuildId,
} from '@puppeteer/browsers';

const platform = detectBrowserPlatform();
if (!platform) {
  throw new Error('Puppeteer could not detect a supported browser platform');
}

const browser = Browser.CHROME;
const buildId = await resolveBuildId(browser, platform, 'stable');
const cacheDir = `${process.cwd()}/.cache/puppeteer`;

const installed = await install({
  browser,
  buildId,
  platform,
  cacheDir,
  // expectedHash: '',
  // downloadProgressCallback: (downloaded, total) => {
  //   console.log(`${downloaded}/${total}`);
  // },
});

console.log(`Installed build ${buildId}`);
console.log(`Executable: ${installed.executablePath}`);

node install-browser.mjs

The required install properties are browser, buildId, and cacheDir. platform is auto-detected by Puppeteer when omitted, but detecting and passing it explicitly is useful in scripts that need predictable target selection. Build IDs identify the downloaded binaries and participate in caching. The exact build resolution behavior depends on the installed @puppeteer/browsers version.

Set a download host with DefaultProvider

To use Puppeteer’s standard provider with a different host, instantiate it and pass it through providers. The install API tries configured providers in order and automatically appends the default provider as the final fallback. The mirror must expose the expected archive for the requested browser, build, and platform.

// install-from-mirror.mjs
import {
  Browser,
  DefaultProvider,
  detectBrowserPlatform,
  install,
  resolveBuildId,
} from '@puppeteer/browsers';

const platform = detectBrowserPlatform();
if (!platform) throw new Error('Unsupported platform');

const browser = Browser.CHROME;
const buildId = await resolveBuildId(browser, platform, 'stable');
const mirror = new DefaultProvider('https://mirror.example.com');

const installed = await install({
  browser,
  buildId,
  platform,
  cacheDir: `${process.cwd()}/.cache/puppeteer`,
  providers: [mirror],
});

console.log(installed.executablePath);

Replace the example host with your actual mirror. This example only works if its URL structure and archive contents are accepted by the default provider for that browser and build. If your mirror uses a different layout, implement a custom provider instead.

Implement a custom BrowserProvider

A custom provider is useful for a private artifact repository, a distribution with a different archive layout, or a policy-controlled download source. Puppeteer’s official example implements supports, getDownloadUrl, and getExecutablePath. The following CommonJS pattern shows those responsibilities without assuming a particular vendor’s filenames or path layout; fill them in for your actual mirror.

// custom-provider.cjs
const {
  Browser,
  BrowserPlatform,
  install,
  resolveBuildId,
} = require('@puppeteer/browsers');

class MirrorProvider {
  constructor(baseUrl) {
    this.baseUrl = new URL(baseUrl);
  }

  supports(options) {
    return options.browser === Browser.CHROME;
  }

  getDownloadUrl(options) {
    if (!this.supports(options)) return null;
    const { buildId, platform } = options;
    const archive = archiveNameFor(platform);
    if (!archive) return null;
    return new URL(
      `chrome/${encodeURIComponent(buildId)}/${archive}`,
      this.baseUrl,
    );
  }

  getExecutablePath(options) {
    const path = executablePathFor(options.platform);
    if (!path) throw new Error(`Unsupported platform: ${options.platform}`);
    return path;
  }
}

function archiveNameFor(platform) {
  // Replace these examples with the real archive names hosted by your mirror.
  const names = {
    [BrowserPlatform.LINUX]: 'chrome-linux64.zip',
    [BrowserPlatform.LINUX_ARM]: 'chrome-linux-arm64.zip',
    [BrowserPlatform.MAC]: 'chrome-mac-x64.zip',
    [BrowserPlatform.MAC_ARM]: 'chrome-mac-arm64.zip',
    [BrowserPlatform.WIN32]: 'chrome-win32.zip',
    [BrowserPlatform.WIN64]: 'chrome-win64.zip',
  };
  return names[platform] ?? null;
}

function executablePathFor(platform) {
  // These paths are examples and must match the contents of your archives.
  if (platform === BrowserPlatform.LINUX) return 'chrome-linux64/chrome';
  if (platform === BrowserPlatform.LINUX_ARM) return 'chrome-linux-arm64/chrome';
  if (platform === BrowserPlatform.MAC) return 'chrome-mac/Chromium.app/Contents/MacOS/Chromium';
  if (platform === BrowserPlatform.MAC_ARM) return 'chrome-mac/Chromium.app/Contents/MacOS/Chromium';
  if (platform === BrowserPlatform.WIN32 || platform === BrowserPlatform.WIN64) {
    return 'chrome-win64/chrome.exe';
  }
  return null;
}

(async () => {
  const platform = BrowserPlatform.LINUX;
  const browser = Browser.CHROME;
  const buildId = await resolveBuildId(browser, platform, 'stable');
  const installed = await install({
    browser,
    buildId,
    platform,
    cacheDir: `${process.cwd()}/.cache/puppeteer`,
    providers: [new MirrorProvider('https://mirror.example.com/')],
    // Supply a trusted archive SHA-256 if your release process publishes one.
    // expectedHash: '',
  });
  console.log(installed.executablePath);
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

The mappings above illustrate the interface; they are not a guarantee that those names match your distribution. Adapt browser, platform, archive filename, and executable path together. Return null from getDownloadUrl when the provider does not support the requested combination, and make supports accurately describe that coverage.

InstallOptions that affect provider setup

Option	Purpose	Practical guidance
`browser`	Selects the browser to install.	Keep the provider’s advertised support consistent with this value.
`buildId`	Selects the browser build and identifies the cached binary.	Pin or resolve a compatible build; avoid mixing unrelated versions across platforms.
`cacheDir`	Sets the browser cache location.	Use a persistent writable location when the environment reuses installed binaries.
`baseUrl`	Overrides the download host in install configuration.	Use for the standard provider when its URL layout matches your source.
`platform`	Selects target platform; auto-detected if omitted.	Set explicitly for cross-platform packaging and reproducible deployments.
`providers`	Ordered custom provider chain.	Providers are tried in order; Puppeteer’s default provider is appended as fallback.
`expectedHash`	Optional lowercase SHA-256 for archive integrity checking.	Obtain the expected digest through a trusted release channel; a mismatch fails installation.
`installDeps`	Attempts installation of system dependencies.	Defaults to false; only supports Chrome on Debian or Ubuntu and requires system privileges for `apt-get`.
`unpack`	Controls whether the downloaded archive is unpacked.	Defaults to true. With false, `install` returns the archive path rather than an installed browser object.
`downloadProgressCallback`	Reports downloaded and total bytes.	Use a callback for build logs or set it to `'default'` for Puppeteer’s progress bar.
`logger`	Controls install logging.	Provide a logger if you need to route diagnostics into your application’s logging system.

The current API reference lists these fields, but generated documentation can change between releases. Check the API page for the exact package version in your lockfile before relying on version-sensitive settings.

Provider settings versus browser launch options

Installation and launch solve separate problems. Install settings determine which browser artifact is fetched, from where, and where it is cached. Launch settings select and configure a browser process after installation. The LaunchOptions API includes such settings as browser, channel, executablePath, args, headless, userDataDir, and timeout.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  // Use a known local executable instead of Puppeteer's bundled binary:
  executablePath: '/opt/chrome/chrome',
  headless: true,
  timeout: 30_000,
  args: ['--no-sandbox'], // Add only when required by the deployment environment.
});

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

executablePath selects a local executable and channel can select a regular Chrome installation at a known location. Puppeteer warns that compatibility is guaranteed with its bundled browser, so alternate executables need validation. Avoid copying a download host into launch configuration: baseUrl affects acquisition, not runtime executable selection.

Configuration files and environment variables

For standard puppeteer defaults, Puppeteer recommends configuration files; applicable environment variables override configuration values. If download configuration changes, rerun browser installation so the changed settings take effect. Configuration files and Puppeteer environment variables are ignored by puppeteer-core. See the official configuration guide.

// .puppeteerrc.cjs
module.exports = {
  cacheDirectory: './.cache/puppeteer',
  // Set browser-specific download settings in the format supported by
  // the version of Puppeteer installed in this project.
};

npx puppeteer browsers install

The downloader also respects HTTP_PROXY, HTTPS_PROXY, and NO_PROXY; Puppeteer’s guide notes that browser-download proxy support requires the optional proxy-agent peer dependency. Do not assume a puppeteer-core install will read Puppeteer’s configuration file or environment settings.

When to use each setup

Approach	Use it when	Compatibility work
Default install provider	You want Puppeteer’s normal browser source and cache behavior.	Lowest setup burden; Puppeteer tests and guarantees its default binaries.
`DefaultProvider(baseUrl)`	Your mirror preserves the URL and archive conventions expected by the standard provider.	Verify the host has the requested build and platform artifacts.
Custom `BrowserProvider`	Your source has a different URL layout, archive naming, or executable path.	You own binary compatibility, layout mapping, feature integration, tests, and upkeep.
Alternate `executablePath` or `channel`	A browser is already installed and you want to launch it.	Validate behavior against the Puppeteer version; this does not configure downloads.

Reliability, performance, and cost considerations

Pin reproducible inputs. Resolve or pin the intended browser build, platform, provider, and cache location so separate environments do not silently fetch different artifacts.
Validate mirror completeness. Check that every supported platform/build combination has a reachable archive and the executable path expected after unpacking. A provider fallback helps only when the default source can serve the same request.
Use hashes when available. expectedHash makes installation fail if the archive digest differs. If omitted, the install proceeds without that archive integrity check.
Reuse a persistent cache. Reusing a writable cache avoids repeated downloads in environments that retain files. In ephemeral build or serverless environments, include browser download time and disk space in cold-start planning.
Keep download and runtime network needs distinct. A successful install does not guarantee that the browser can reach target sites through your runtime network or proxy.
Account for operating-system libraries. installDeps is limited to Chrome on Debian/Ubuntu and requires privileges; plan image dependencies explicitly where that option is unavailable.

Puppeteer publishes no universal setup benchmark in the cited API references. Download time and storage depend on the artifact, network, platform, and cache reuse, so measure them in your deployment environment rather than relying on a generic figure.

Troubleshooting provider installation

Symptom	Likely cause	What to check or change
No supported platform detected	The runtime platform is unsupported or detection returned no result.	Check the host architecture and supported platform list; pass a valid `platform` explicitly when cross-targeting.
404 from mirror	Wrong base URL, build ID, platform path, or archive filename.	Log the requested build/platform and verify the exact URL and artifact exist in the mirror.
Archive downloads but executable is missing	`getExecutablePath` does not match the archive’s internal directory layout.	Inspect the extracted archive and update the provider mapping; test each supported platform.
Provider does not support requested browser	`supports` rejects the browser or `getDownloadUrl` returns `null`.	Confirm the requested browser/build/platform tuple and add a truthful mapping or use another provider.
SHA-256 mismatch	The expected hash belongs to another artifact or the downloaded file differs.	Verify the digest from a trusted source and ensure the build, platform, and downloaded archive match.
Permission denied writing cache	The process cannot create or modify `cacheDir`.	Choose a writable cache directory and ensure its parent exists with appropriate ownership.
Install works locally but not in deployment	Missing OS libraries, proxy settings, architecture mismatch, or an ephemeral/moved cache.	Check deployment architecture, runtime dependencies, proxy-agent setup, cache path, and installed executable path.
Browser installs but fails at launch	Install succeeded, but the binary is incompatible or launch configuration/environment is wrong.	Separate install logs from launch logs; validate the executable, required libraries, sandbox policy, and launch options.
Configuration change seems ignored	The configuration is ignored by `puppeteer-core` or the browser was not reinstalled after download settings changed.	Use configuration supported by the installed package and rerun `npx puppeteer browsers install` when appropriate.

Or skip the browser setup

If your goal is a website screenshot rather than managing a local browser binary, ScreenshotNeo provides a screenshot API and MCP server for developers. One GET request returns a screenshot as PNG, JPEG, or WebP, or a PDF. See the ScreenshotNeo API documentation.

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

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report 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 a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

FAQ

Does DefaultProvider accept an options object?

The documented constructor takes baseUrl. The install options are a separate object passed to install().

Does setting `baseUrl` select a system Chrome executable?

No. It changes the download host. Use launch-time executablePath or channel to choose a local browser.

Can I provide several custom providers?

Yes. The install API tries providers in order and appends Puppeteer’s default provider as a fallback.

Are custom providers supported by Puppeteer?

They are not officially supported. The implementer is responsible for compatibility, testing, and maintenance.

Do Puppeteer configuration files apply to puppeteer-core?

No. The official configuration guide says configuration files and Puppeteer environment variables are ignored by puppeteer-core.

Version note

The API details here follow the Puppeteer documentation surfaced for version 25.12.0. Constructor and install behavior can be version-sensitive; compare these references with the generated documentation for the exact package version installed in your project.