@puppeteer/browsers
Manage and launch browsers/drivers from a CLI or programmatically.
System requirements
- A compatible Node version (see
enginesinpackage.json). - For Firefox downloads:
- Linux builds:
xzandbzip2utilities are required to unpack.tar.gzand.tar.bz2archives. - MacOS builds:
hdiutilis required to unpack.dmgarchives.
- Linux builds:
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/browsers@2.4.1 --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 chrome@116.0.5793.0
# 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 chromedriver@116.0.5793.0
# 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
- Launching the system browsers is only possible for Chrome/Chromium.
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 |
|---|---|
| CLI | |
| InstalledBrowser | 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 |
| Process | |
| TimeoutError | 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 |
Enumerations
Enumeration | Description |
|---|---|
| Browser | Supported browsers. |
| BrowserPlatform | Platform names used to identify a OS platform x architecture combination in the way that is relevant for the browser download. |
| BrowserTag | 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. |
| ChromeReleaseChannel |
Functions
Function | Description |
|---|---|
| canDownload(options) | |
| computeExecutablePath(options) | |
| computeSystemExecutablePath(options) | 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. |
| createProfile(browser, opts) | |
| detectBrowserPlatform() | |
| getDownloadUrl(browser, platform, buildId, baseUrl) | Retrieves a URL for downloading the binary archive of a given browser. The archive is bound to the specific platform and build ID specified. |
| getInstalledBrowsers(options) | Returns metadata about browsers installed in the cache directory. |
| getVersionComparator(browser) | Returns a version comparator for the given browser that can be used to sort browser versions. |
| install(options) | Downloads and unpacks the browser archive according to the InstallOptions. |
| install(options) | Downloads the browser archive according to the InstallOptions without unpacking. |
| launch(opts) | Launches a browser process according to LaunchOptions. |
| makeProgressCallback(browser, buildId) | |
| resolveBuildId(browser, platform, tag) | |
| uninstall(options) |
Interfaces
Interface | Description |
|---|---|
| GetInstalledBrowsersOptions | |
| InstallOptions | |
| LaunchOptions | |
| Metadata_2 | |
| Options | |
| ProfileOptions | |
| SystemOptions | |
| UninstallOptions |
Variables
Variable | Description |
|---|---|
| CDP_WEBSOCKET_ENDPOINT_REGEX | |
| WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX |