How to Use the Puppeteer Browsers CLI

The browser-management CLI is @puppeteer/browsers. Start with npx @puppeteer/browsers --help, then use its install, list, launch, and clear commands to manage browser binaries. If installing Puppeteer skipped its automatic Chrome download, the package-specific recovery command is npx puppeteer browsers install.

The CLI manages browser downloads and their cache; it is separate from Puppeteer’s JavaScript automation APIs. Puppeteer’s current documentation is for version 25.12.0. Browser channels, build IDs, package-manager behavior, and platform requirements can change, so check help from the version you actually run.

1. Check the CLI and command help

npx @puppeteer/browsers --help
npx @puppeteer/browsers install --help
npx @puppeteer/browsers list --help
npx @puppeteer/browsers launch --help
npx @puppeteer/browsers clear --help

The top-level help shows available commands. Each command’s own help describes its supported arguments and options. When the package is already installed in the current project, npx uses that version. If you intend to run a particular release, pin it explicitly using your package manager’s supported package-spec syntax; use @latest only when you want the newest published release.

2. Install a browser build

Pass a browser and a channel, milestone, or exact build ID to install:

npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers install chrome@117
npx @puppeteer/browsers install chrome@116.0.5793.0

chrome@stable follows the stable channel available to the tool. A milestone or exact build identifies a more specific version. The milestone and build ID shown above are historical documentation examples, not current recommendations; consult the installed CLI’s help for accepted identifiers and choose versions that suit your deployment and update policy.

For Chrome on Debian or Ubuntu, Puppeteer documents an option to attempt installation of browser dependencies:

npx puppeteer browsers install chrome --install-deps

This package-specific command is limited to Chrome on Debian/Ubuntu and uses privileged apt-get. It requires root privileges. It is not a general dependency installer for other Linux distributions, operating systems, or Firefox.

3. List or remove cached browser installs

Inspect browser binaries installed in the browser manager’s cache:

npx @puppeteer/browsers list

Remove all browser installs from that cache with:

npx @puppeteer/browsers clear

Clearing the cache removes the managed downloads; it does not uninstall the CLI package. Run list afterward to inspect what remains. Check the command help before using cleanup in an environment where other jobs may depend on the same cache.

4. Launch a browser from the CLI

The CLI includes a launch command. Use its help to see the options and required browser/build arguments for your installed release:

npx @puppeteer/browsers launch --help

Launching a system-installed browser is documented only for Chrome and Chromium. For automation inside a JavaScript program, use Puppeteer’s API rather than treating the CLI as the automation interface. With puppeteer-core and a browser you manage yourself, configure an explicit executablePath or a channel for a browser installed in a standard location.

5. Choose who manages the browser

Workflow	What it does	When it fits
`puppeteer`	Provides Puppeteer’s end-user defaults and normally downloads a compatible Chrome for Testing browser during installation.	Use when you want Puppeteer to provide the browser binary along with its library.
`puppeteer-core`	Does not download Chrome and is driven through its programmatic interface.	Use for remote-browser connections or a browser you manage separately; provide an executable path or suitable channel for a local browser.
`@puppeteer/browsers`	Provides the general browser-management CLI and library.	Use its commands to install, inspect, launch, and clear managed browser downloads.

Puppeteer’s installation guide explains that puppeteer-core has no assumed defaults and does not download Chrome. Keep the browser version and Puppeteer version aligned in deployments, and make the chosen browser available wherever the automation process runs.

6. Recover when package installation skipped Chrome

Some modern package managers can block install scripts. If Puppeteer’s install script does not run, its automatic browser download is skipped. A common runtime symptom is Could not find Chrome (ver. ...). After installing the package, run Puppeteer’s documented manual recovery command:

npx puppeteer browsers install

The official installation guide also documents equivalent invocations through Yarn, pnpm, and Bun. Use the syntax shown in that guide for your package manager and installed Puppeteer version. For npm, the guide describes allowing Puppeteer’s install script in package.json as an alternative, so the browser can be downloaded during installation.

Installing puppeteer normally downloads Chrome for Testing and, from Puppeteer v21.6.0 onward, a chrome-headless-shell binary. The documentation’s approximate Chrome download sizes are 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows; actual sizes can change. Account for these downloads in CI setup time, disk space, and cache strategy.

7. Configure cache, platform, and download integrity

The browser manager’s install options include the browser, build ID, cache directory, and optional platform selection. Choose a cache location that is writable by the process and persists for as long as you need the installed browser. Use the CLI help for the exact option spelling accepted by the version you run.

The installer also accepts an expected SHA-256 hash. When supplied, installation fails if the downloaded archive does not match it. If no expected hash is supplied, the documented installer behavior proceeds without that verification. For controlled builds, record the browser build and consider supplying the expected hash through the supported API or CLI options.

Moving channels such as stable are convenient when you want current browser builds; a pinned milestone or exact build can make environments more repeatable. Pinning also means you must plan when to update and validate browser changes.

8. Meet the runtime and platform requirements

The Puppeteer 25.12.0 system requirements specify Node.js 22.12 or newer.
Documented Chrome for Testing platforms include Windows x64, macOS x64 and arm64, Debian/Ubuntu Linux x64 and arm64, and openSUSE/Fedora Linux x64 and arm64.
Chrome archive extraction needs tar.exe or PowerShell on Windows and unzip on macOS/Linux, unless the optional yauzl dependency is installed.
The CLI reference lists unzip on Linux/macOS and tar.exe on Windows for Chrome downloads. Firefox archive handling requires xz and bzip2 on Linux or hdiutil on macOS.

These requirements are version-specific. Check the system requirements and CLI reference for the Puppeteer release and operating system used in production.

9. Configure proxies and diagnostic logging

The CLI and library respect HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Puppeteer documents that proxy-agent must be installed for this proxy behavior. Confirm that the proxy allows access to the browser download host and that exclusions in NO_PROXY are intentional.

For detailed browser-manager logs, set the Node debug namespace:

NODE_DEBUG="puppeteer:browsers:*" npx @puppeteer/browsers install chrome@stable

The documented channels cover cache, file utilities, installation, and launch operations. Use the output to distinguish a download or extraction issue from a cache-path or launch issue.

10. Use a custom browser provider carefully

Custom providers can target mirrors or private repositories. Puppeteer does not officially support custom providers, and compatibility is guaranteed only for the default binaries. If you use a mirror, you own the binary compatibility checks, testing, and ongoing maintenance. Validate the browser against the Puppeteer release and deployment platform before relying on it.

11. Troubleshooting

Symptom	Likely cause	What to do
`Could not find Chrome (ver. ...)`	The install script was blocked or the browser was never downloaded.	Run `npx puppeteer browsers install`. If using a package manager that blocks scripts, follow Puppeteer’s package-manager guidance or allow the install script as documented for npm.
Install command rejects a channel or build	The identifier is unavailable, outdated, or not accepted by this CLI version.	Run `npx @puppeteer/browsers install --help` and use a currently supported channel, milestone, or build ID.
Download or extraction fails	A proxy, network restriction, missing archive utility, or unwritable cache can prevent installation.	Check proxy variables and proxy-agent availability, install the required extraction tool for the browser and platform, and choose a writable cache directory. Enable `NODE_DEBUG="puppeteer:browsers:*"` for details.
Browser starts locally but not in CI	The CI environment may use another platform, omit system dependencies, or lack the cached browser binary.	Install the browser in the target environment, confirm its platform and extraction requirements, and persist or recreate the selected cache there.
`--install-deps` fails or is unavailable	The option is for Chrome on Debian/Ubuntu and calls privileged `apt-get`.	Use it only on that supported combination with root privileges. For other systems, install the required dependencies using their platform’s supported method.
System browser cannot be launched	System-browser launching is documented only for Chrome/Chromium, or the executable is not at the selected location.	Use Chrome/Chromium and verify its executable path. For programmatic Puppeteer, set `executablePath` or a supported standard-location `channel`.

12. Reliability, performance, and cost

Browser installation is a large one-time or cache-miss download, so CI jobs can save setup time by retaining a compatible browser cache. Make the cache key account for the browser build, platform, and Puppeteer version; otherwise a stale or incompatible binary can make runs fail. When exact reproducibility matters, pin the build and validate it during upgrades. When following stable, expect the browser to advance over time and schedule compatibility checks.

Budget disk space as well as network transfer: Puppeteer may install both Chrome for Testing and chrome-headless-shell. Parallel jobs that share a cache should use a cache location and lifecycle appropriate to the runner so cleanup does not remove a browser another job still needs. Browser binaries are free software downloads in this workflow; the practical costs are bandwidth, storage, CI time, and maintenance of pinned versions.

13. Frequently asked questions

Is `npx puppeteer browsers install` the same package as `npx @puppeteer/browsers install`?

No. The former is Puppeteer’s package-specific manual recovery command; the latter invokes the general @puppeteer/browsers browser manager.

Does `puppeteer-core` install Chrome?

No. It is intended for programmatic control without Puppeteer’s end-user defaults, and does not download Chrome.

Can I use the CLI to manage Firefox?

The browser manager includes browser-specific archive requirements, including Firefox extraction dependencies. Check the installed CLI help for the supported Firefox commands and options.

Where should I look when a command’s options differ from an example?

Run that command with --help using the same package version you intend to use. Examples and browser identifiers can age as releases change.

Or skip the browser setup

If your goal is to capture a webpage rather than automate a browser, ScreenshotNeo provides a website screenshot API and MCP server. Its API accepts one GET request and returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for the available parameters.

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

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.