@puppeteer/browsers

Manage and launch browsers/drivers from a CLI or programmatically.

System requirements

• A compatible Node version (see engines in package.json).
• For Firefox downloads:
  • Linux builds: xz and bzip2 utilities are required to unpack .tar.gz and .tar.bz2 archives.
  • MacOS builds: hdiutil is required to unpack .dmg archives.

CLI

Use npx to run the CLI:

# This will install and run the @puppeteer/browsers package.
# If it is already installed in the current directory, the installed
# version will be used.
npx @puppeteer/browsers --help

Built-in per-command help will provide all documentation you need to use the CLI.

npx @puppeteer/browsers --help # help for all commands
npx @puppeteer/browsers install --help # help for the install command
npx @puppeteer/browsers launch --help # help for the launch command
npx @puppeteer/browsers clear --help # help for the clear command
npx @puppeteer/browsers list --help # help for the list command

You can specify the version of the @puppeteer/browsers when using npx:

# Always install and use the latest version from the registry.
npx @puppeteer/browsers@latest --help
# Always use a specifc version.
npx @puppeteer/[email protected] --help
# Always install the latest version and automatically confirm the installation.
npx --yes @puppeteer/browsers@latest --help

To clear all installed browsers, use the clear command:

npx @puppeteer/browsers clear

To list all installed browsers, use the list command:

npx @puppeteer/browsers list

Some example to give an idea of what the CLI looks like (use the --help command for more examples):

# Download the latest available Chrome for Testing binary corresponding to the Stable channel.
npx @puppeteer/browsers install chrome@stable

# Download a specific Chrome for Testing version.
npx @puppeteer/browsers install [email protected]

# Download the latest Chrome for Testing version for the given milestone.
npx @puppeteer/browsers install chrome@117

# Download the latest available ChromeDriver version corresponding to the Canary channel.
npx @puppeteer/browsers install chromedriver@canary

# Download a specific ChromeDriver version.
npx @puppeteer/browsers install [email protected]

# On Ubuntu/Debian and only for Chrome, install the browser and required system dependencies.
# If the browser version has already been installed, the command
# will still attempt to install system dependencies.
# Requires root privileges.
npx puppeteer browsers install chrome --install-deps

Known limitations

1. Launching the system browsers is only possible for Chrome/Chromium.

Custom Providers

You can implement custom browser providers to download from alternative sources like corporate mirrors, private repositories, or specialized browser builds.

import {
  BrowserProvider,
  DownloadOptions,
  Browser,
  BrowserPlatform,
} from '@puppeteer/browsers';

class SimpleMirrorProvider implements BrowserProvider {
  constructor(private mirrorUrl: string) {}

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

  getDownloadUrl(options: DownloadOptions): URL | null {
    const {buildId, platform} = options;
    const filenameMap = {
      [BrowserPlatform.LINUX]: 'chrome-linux64.zip',
      [BrowserPlatform.MAC]: 'chrome-mac-x64.zip',
      [BrowserPlatform.MAC_ARM]: 'chrome-mac-arm64.zip',
      [BrowserPlatform.WIN32]: 'chrome-win32.zip',
      [BrowserPlatform.WIN64]: 'chrome-win64.zip',
    };
    const filename = filenameMap[platform];
    if (!filename) return null;
    return new URL(`${this.mirrorUrl}/chrome/${buildId}/${filename}`);
  }

  getExecutablePath(options: DownloadOptions): string {
    const {platform} = options;
    if (
      platform === BrowserPlatform.MAC ||
      platform === BrowserPlatform.MAC_ARM
    ) {
      return 'chrome-mac/Chromium.app/Contents/MacOS/Chromium';
    } else if (platform === BrowserPlatform.LINUX) {
      return 'chrome-linux64/chrome';
    } else if (platform.includes('win')) {
      return 'chrome-win64/chrome.exe';
    }
    throw new Error(`Unsupported platform: ${platform}`);
  }
}

Use with the install API:

import {install} from '@puppeteer/browsers';

const customProvider = new SimpleMirrorProvider('https://internal.company.com');

await install({
  browser: Browser.CHROME,
  buildId: '120.0.6099.109',
  platform: BrowserPlatform.LINUX,
  cacheDir: '/tmp/puppeteer-cache',
  providers: [customProvider],
});

Multiple providers can be chained - they're tried in order until one succeeds, with a default provider such as Chrome for Testing, as an automatic fallback.

:::caution Custom providers are NOT officially supported by Puppeteer. You accept full responsibility for binary compatibility, testing, and maintenance. :::

API

The programmatic API allows installing and launching browsers from your code. See the test folder for examples on how to use the install, canInstall, launch, computeExecutablePath, computeSystemExecutablePath and other methods.

Classes

Class

Description

<span id="cli">CLI</span>

<span id="defaultprovider">DefaultProvider</span>

Default provider implementation that uses default sources. This is the standard provider used by Puppeteer.

<span id="installedbrowser">InstalledBrowser</span>

Remarks:

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the InstalledBrowser class.

<span id="process">Process</span>

<span id="timeouterror">TimeoutError</span>

Remarks:

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the TimeoutError class.

Enumerations

Enumeration

Description

<span id="browser">Browser</span>

Supported browsers.

<span id="browserplatform">BrowserPlatform</span>

Platform names used to identify a OS platform x architecture combination in the way that is relevant for the browser download.

<span id="browsertag">BrowserTag</span>

Enum describing a release channel for a browser.

You can use this in combination with resolveBuildId() to resolve a build ID based on a release channel.

<span id="chromereleasechannel">ChromeReleaseChannel</span>

Functions

Function

Description

<span id="buildarchivefilename">buildArchiveFilename(browser, platform, buildId, extension)</span>

Utility function to build a standard archive filename.

<span id="candownload">canDownload(options)</span>

<span id="computeexecutablepath">computeExecutablePath(options)</span>

<span id="computesystemexecutablepath">computeSystemExecutablePath(options)</span>

Returns a path to a system-wide Chrome installation given a release channel name by checking known installation locations (using https://pptr.dev/browsers-api/browsers.computesystemexecutablepath). If Chrome instance is not found at the expected path, an error is thrown.

<span id="createprofile">createProfile(browser, opts)</span>

<span id="detectbrowserplatform">detectBrowserPlatform()</span>

<span id="getdownloadurl">getDownloadUrl(browser, platform, buildId, baseUrl)</span>

Retrieves a URL for downloading the binary archive of a given browser.

The archive is bound to the specific platform and build ID specified.

<span id="getinstalledbrowsers">getInstalledBrowsers(options)</span>

Returns metadata about browsers installed in the cache directory.

<span id="getversioncomparator">getVersionComparator(browser)</span>

Returns a version comparator for the given browser that can be used to sort browser versions.

<span id="install">install(options)</span>

Downloads and unpacks the browser archive according to the InstallOptions.

<span id="install">install(options)</span>

Downloads the browser archive according to the InstallOptions without unpacking.

<span id="launch">launch(opts)</span>

Launches a browser process according to LaunchOptions.

<span id="makeprogresscallback">makeProgressCallback(browser, buildId)</span>

<span id="resolvebuildid">resolveBuildId(browser, platform, tag)</span>

<span id="resolvedefaultuserdatadir">resolveDefaultUserDataDir(browser, platform, channel)</span>

Returns the expected default user data dir for the given channel. It does not check if the dir actually exists.

<span id="uninstall">uninstall(options)</span>

Interfaces

Interface

Description

<span id="browserprovider">BrowserProvider</span>

Interface for custom browser provider implementations. Allows users to implement alternative download sources for browsers.

⚠️ IMPORTANT: Custom providers are NOT officially supported by Puppeteer.

By implementing this interface, you accept full responsibility for:

• Ensuring downloaded binaries are compatible with Puppeteer's expectations - Testing that browser launch and other features work with your binaries - Maintaining compatibility when Puppeteer or your download source changes - Version consistency across platforms if mixing sources

Puppeteer only tests and guarantees Chrome for Testing binaries.

<span id="downloadoptions">DownloadOptions</span>

Options passed to a provider.

<span id="getinstalledbrowsersoptions">GetInstalledBrowsersOptions</span>

<span id="installoptions">InstallOptions</span>

<span id="launchoptions">LaunchOptions</span>

<span id="metadata">Metadata</span>

<span id="options">Options</span>

<span id="profileoptions">ProfileOptions</span>

<span id="systemoptions">SystemOptions</span>

<span id="uninstalloptions">UninstallOptions</span>

Variables

Variable

Description

<span id="cdp_websocket_endpoint_regex">CDP_WEBSOCKET_ENDPOINT_REGEX</span>

<span id="webdriver_bidi_websocket_endpoint_regex">WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX</span>