How to Run Browser Commands with the Puppeteer Browsers CLI

The @puppeteer/browsers package lets you install, list, and launch supported browsers and drivers from the command line. Start with its help, install a browser build, check the installed list, then launch it:

npx @puppeteer/browsers --help
npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers list
npx @puppeteer/browsers launch chrome@stable

Use the help shipped with the version you run: flags and available builds can change. The official Puppeteer browsers CLI documentation has examples and API details.

1. Check the CLI version and command help

When run through npx, the package version already installed in the current project is used when available. If it is not installed there, npx can fetch a package to run. You can select a specific version for a reproducible command, or choose @latest when you deliberately want the newest published version.

# General help
npx @puppeteer/browsers --help

# Help for the commands you plan to use
npx @puppeteer/browsers install --help
npx @puppeteer/browsers launch --help
npx @puppeteer/browsers list --help
npx @puppeteer/browsers clear --help

# Run a specific package version
npx @puppeteer/browsers@2.4.1 --help

# Deliberately run the newest published package
npx @puppeteer/browsers@latest --help

For scripts and CI, pin the package version and consult that version’s help. Examples in this guide illustrate documented command patterns; channels and available builds are mutable.

2. Install a browser or driver

The general form is install browser@build. A build can identify a moving channel such as stable or canary, a milestone, or a specific version/build. Installation output reports the resolved build ID and executable path; retain those when diagnosing which binary was installed.

# Chrome for Testing: current Stable channel
npx @puppeteer/browsers install chrome@stable

# Exact Chrome for Testing build
npx @puppeteer/browsers install chrome@116.0.5793.0

# Latest available build for a milestone
npx @puppeteer/browsers install chrome@117

# ChromeDriver and headless shell examples
npx @puppeteer/browsers install chromedriver@canary
npx @puppeteer/browsers install chrome-headless-shell@stable

# Firefox example
npx @puppeteer/browsers install firefox@stable

These identifiers represent different browser or driver artifacts. Choose the family your application needs, and pin an exact build when repeatability matters. A channel is convenient for following a release stream, but its resolved binary can change over time.

Choice	Use it when	Keep in mind
Stable or canary channel	You want a current build from a release channel.	The resolved build can change; record the build ID.
Milestone	You want a build associated with a browser milestone.	It selects the latest available build for that milestone, not necessarily a fixed binary.
Exact version/build	You need a repeatable local or CI setup.	Availability depends on the browser provider and platform.
ChromeDriver	You specifically need the driver binary.	It is distinct from installing Chrome itself.
Chrome headless shell	Your workflow targets the separate shell binary.	It is distinct from standard Chrome headless operation.

On Debian or Ubuntu, the Puppeteer CLI documents --install-deps for installing Chrome’s system dependencies. It is Linux-only, requires root privileges, and attempts dependency installation even if the browser is already present:

npx puppeteer browsers install chrome --install-deps

This example invokes the puppeteer CLI package. Check its own help and installation documentation before using it as part of a script.

3. Launch the installed browser

Launch using the browser identifier and build. The CLI supports options such as using a system-installed browser, detaching the child process, and forwarding browser output. Arguments after -- are passed to the browser executable.

# Launch a specific cached build
npx @puppeteer/browsers launch chrome@115.0.5790.170

# Launch a system-installed Chrome or Chromium
npx @puppeteer/browsers launch chrome@canary --system

# Detach the browser process
npx @puppeteer/browsers launch chrome@115.0.5790.170 --detached

# Forward browser stdout and stderr
npx @puppeteer/browsers launch chrome@115.0.5790.170 --dumpio

# Pass an argument through to the browser binary
npx @puppeteer/browsers launch chrome@115.0.5790.170 -- --version

The --system option selects a system browser rather than a package-managed cached build. The documentation notes that launching system browsers is supported only for Chrome/Chromium. Consult launch --help for exact options and syntax for your installed package.

4. List or clear browser installations

List cached installations to see what the CLI currently knows about. Clear removes installed browsers managed by the CLI cache, so check the command help and ensure you have no workflow relying on those binaries before running it.

npx @puppeteer/browsers list
npx @puppeteer/browsers clear

For automation, avoid depending on undocumented output formatting. Use a pinned CLI version and inspect its list --help or programmatic API if another process needs structured installation metadata.

5. Check prerequisites and choose the right installation path

The package requires a compatible Node.js version; the supported range belongs to the package version’s metadata and may change. Browser archives also require platform utilities to unpack:

Download	Required utility noted in the docs
Chrome on Linux or macOS	`unzip`
Chrome on Windows	`tar.exe`
Firefox on Linux	`xz` and `bzip2`
Firefox on macOS	`hdiutil`

There are two related but different package workflows:

puppeteer normally downloads a compatible Chrome for Testing build during installation; the documented behavior also includes downloading chrome-headless-shell from Puppeteer v21.6.0.
puppeteer-core does not download Chrome. Use it when you manage the browser yourself or connect to a remote browser, and provide an executable path or channel as appropriate.

Some package managers block install scripts by default, which can prevent Puppeteer’s automatic browser download. The documented remedy is to install the browser manually with the appropriate Puppeteer CLI command or configure the package manager to allow Puppeteer’s install script. See the official Puppeteer installation guide.

Chrome for Testing supports both headless and headful modes through the same browser code path. chrome-headless-shell is a separate binary associated with the older headless implementation; Puppeteer selects that mode with headless: 'shell'. Match the binary to your Puppeteer version and intended headless behavior. See Puppeteer’s supported browsers notes.

6. Troubleshoot common CLI failures

Symptom	Likely cause	What to do
The command or option is unrecognized	You may be using a different package version than the one whose syntax you expected.	Run `npx @puppeteer/browsers --help` and the specific command’s `--help`. Pin a package version for scripts.
Browser download fails during extraction	A platform archive utility may be missing.	Install the utility listed for that browser and OS, then retry.
Chrome installs but fails to start on Debian/Ubuntu	Required system libraries may be absent.	Review the documented Linux dependency installation option; it requires root privileges and applies to Chrome on Debian/Ubuntu.
`Could not find Chrome` after installing Puppeteer	A package manager may have blocked the postinstall download script, or no browser was installed.	Manually install the browser using the documented CLI, or allow the Puppeteer install script under the package manager’s policy.
`puppeteer-core` launches without a browser	`puppeteer-core` does not download Chrome or assume a default browser path.	Install/manage a browser separately and pass its executable path or a supported channel.
`--system` does not find the requested browser	The system-browser option is limited to Chrome/Chromium and depends on a compatible system installation.	Use Chrome/Chromium installed on that host, or install a managed browser and launch its build identifier.
Browser output is missing while debugging	Browser stdout/stderr are not forwarded by default.	Use `--dumpio` and inspect the command-specific help.
A pinned example build is unavailable	Build availability changes and may vary by platform.	Choose a currently available build from the package help/documentation and record the resolved build ID.

For verbose package diagnostics, the official CLI guide documents Node’s NODE_DEBUG channels. For example:

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

7. Keep browser installs reliable and costs predictable

For repeatable development and CI, pin both the CLI package and the browser build. A moving channel is useful when you want updates, while an exact build makes the chosen binary explicit. Capture the reported build ID and executable path in job logs so a later failure can be tied to the binary in use.

Browser downloads consume network bandwidth and local or CI cache storage; clearing the cache means those binaries must be downloaded again when needed. Make sure the runtime image includes the required archive utilities and browser system dependencies. The dossier provides no benchmark or fixed download cost: actual time and storage depend on the selected build, platform, network, and cache.

If you are choosing between Chrome for Testing and chrome-headless-shell, account for the distinction in behavior and use the binary that matches the Puppeteer workflow. Avoid assuming that a browser installed independently will be compatible with every Puppeteer version; Puppeteer documents its bundled browser as the supported default.

Or skip the browser setup

If your goal is to get a website screenshot rather than manage a local browser binary, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; 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.
The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.

Frequently asked questions

Does `@puppeteer/browsers` automate a page?

It installs and launches browser binaries. Use Puppeteer or another browser automation library to control pages and interact with them.

Can I run the commands without installing the package in my project?

npx can fetch and run the package when it is not already installed in the current directory. Specify a package version when you need a predictable CLI release.

Should I use Stable or pin an exact version?

Use Stable when tracking the current release channel is the intent. Pin a specific build when you need repeatable browser behavior across machines or CI runs.