Puppeteer Command-Line Options Explained

The Puppeteer browser-management CLI is @puppeteer/browsers. Start with npx @puppeteer/browsers --help; then use a command’s own --help output to see the full flags supported by the version you are running. The common command families are install, launch, list, and clear.

That CLI is separate from Puppeteer’s JavaScript LaunchOptions, and both are separate from Chrome’s native command-line switches. For code, Puppeteer’s args property passes additional arguments to the browser process; it does not make those switches Puppeteer CLI flags. The current official documentation consulted for this guide is labeled Puppeteer 25.12.0. Flag lists can vary by installed package version. Puppeteer’s CLI documentation directs users to built-in per-command help for the current complete list.

1. Find the flags supported by your installed CLI

Run the top-level help to discover commands, then ask each command for its own options:

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

npx uses the package installed in the current project when available; otherwise it can fetch the package to run it. To make the CLI package version explicit, use a package tag or version:

# Request the latest package version
npx @puppeteer/browsers@latest --help

# Request one specific package version
npx @puppeteer/browsers@2.4.1 --help

# Automatically confirm npx's package installation prompt
npx --yes @puppeteer/browsers@latest --help

The version after @ here selects the npm CLI package; it does not select a Chrome build. Use the install command’s browser identifier to select a browser channel, milestone, or build. The official guide says built-in help provides the CLI documentation; the examples below illustrate common tasks and are not an exhaustive inventory of flags.

2. Install, inspect, launch, and remove browser builds

Install Chrome

Install the current Stable Chrome for Testing build with:

npx @puppeteer/browsers install chrome@stable

The documented command accepts channel, milestone, and full-build forms. The specific old build numbers shown below are syntax examples from the documentation, not recommendations to use those builds today:

# A full browser build identifier
npx @puppeteer/browsers install chrome@116.0.5793.0

# A Chrome milestone
npx @puppeteer/browsers install chrome@117

Use the browser package’s install --help for the current browser names and exact options. Do not confuse browser build identifiers with the version of @puppeteer/browsers.

Install the browser selected by a Puppeteer project

If the goal is to install the browser expected by the project’s Puppeteer configuration, use Puppeteer’s wrapper command:

npx puppeteer browsers install

This is also the documented manual recovery step if a package manager skipped Puppeteer’s automatic browser-download script. For Yarn, pnpm, or Bun, use the corresponding runner documented for your environment, such as yarn dlx puppeteer browsers install, pnpm dlx puppeteer browsers install, or bun x puppeteer browsers install.

Install Ubuntu or Debian Chrome system dependencies

The documented --install-deps example applies only to Chrome on Ubuntu or Debian and requires root privileges:

npx puppeteer browsers install chrome --install-deps

This can attempt dependency setup even if the browser binary is already present. It is not a general-purpose option for every browser or operating system.

List installed browsers

npx @puppeteer/browsers list

Use the output to check which browser builds are present in the browser cache. If Puppeteer still cannot find the expected browser, check which cache directory the project is configured to use.

Launch a browser from the CLI

The CLI has a launch command, but its accepted arguments should be read from the version you have installed:

npx @puppeteer/browsers launch --help

This guide does not infer a launch syntax beyond the official reference. If you need browser automation from application code, use Puppeteer’s JavaScript API and its own launch options, described below.

Clear installed browsers

clear removes all installed browsers managed by this CLI. It may require you to download them again before automation can run, so check the target environment and cache before proceeding:

npx @puppeteer/browsers clear

3. Know which kind of option you need

Scope	Where it goes	What it controls
Browser-management CLI flag	After a CLI command, such as `install` or `launch`	Installing, launching, listing, or clearing browser builds. Check that command’s installed-version help.
Puppeteer configuration	Configuration file or supported environment variable	Project defaults such as browser choice, cache location, executable path, and download behavior.
Puppeteer launch property	Object passed to `puppeteer.launch()`	How Puppeteer starts and configures the browser process.
Browser-native argument	Usually an item in Puppeteer’s `args` array	A switch interpreted by Chrome or another browser, not automatically a Puppeteer CLI option.

For example, --help is a CLI option. headless is a JavaScript launch property. A Chrome switch passed through args is a browser argument. Puppeteer’s LaunchOptions reference documents the API properties.

4. Configure Puppeteer from JavaScript

This runnable Node.js example uses the browser downloaded by the puppeteer package, opens a page, and closes the browser reliably:

// Save as screenshot.mjs after: npm install puppeteer
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  timeout: 30_000,
  // args: ['<browser-native-switch>'], // Add only a switch you understand.
});

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

Run it with node screenshot.mjs. The example’s args line is commented out intentionally: browser-native switches are browser-specific, and there is no universal list of switches that should be added to every Puppeteer launch.

Launch property	Practical meaning
`args`	Additional command-line arguments passed to the browser process.
`browser`	Selects the browser type supported by the API.
`channel`	Selects a browser release channel where supported, such as an installed Chrome channel.
`executablePath`	Points Puppeteer at a specific executable. Using an external executable is at your risk; Puppeteer guarantees compatibility only with its bundled browser.
`headless`	Defaults to `true`. `true` uses Chrome’s new headless mode; `'shell'` uses the old headless shell. Setting `devtools: true` forces headless mode off.
`timeout`	Startup timeout in milliseconds; the documented default is 30 seconds. Set to `0` to disable this timeout.
`userDataDir`	Chooses the browser profile directory used for the launch.

5. Set browser download and cache configuration

The puppeteer package downloads Chrome for Testing and chrome-headless-shell during installation by default. Puppeteer’s installation guide publishes approximate archive sizes of 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows; these are documentation estimates and downloads consume additional disk space after extraction. The default browser cache is $HOME/.cache/puppeteer. See the official installation guide and configuration reference for current details.

Setting	Use
`PUPPETEER_BROWSER`	Overrides the default browser choice.
`PUPPETEER_CACHE_DIR`	Changes the browser cache directory.
`PUPPETEER_EXECUTABLE_PATH`	Sets a browser executable path.
`PUPPETEER_SKIP_DOWNLOAD`	Skips Puppeteer’s automatic browser download.

Configuration can also set a default browser, cache directory, executable path, log level, skipped downloads, and temporary directory. Environment variables can override configuration. puppeteer-core ignores Puppeteer configuration files and environment variables; it does not download Chrome, so provide an executable path or channel as needed.

6. Platform requirements, proxies, and logs

Node.js: the CLI requires a Node version compatible with the installed package. Check the package’s engine requirements when an older runtime fails.
Chrome archive extraction: Linux and macOS require unzip; Windows requires tar.exe.
Firefox archive extraction: Linux requires xz and bzip2; macOS requires hdiutil.
Proxy environments: @puppeteer/browsers respects HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Proxy operation requires the proxy-agent package.

For verbose browser-management logs, the official guide shows:

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

Available debug channels include cache operations, file utilities, installation, and launching. This is useful for distinguishing download failures from archive extraction or launch failures.

7. Common errors and fixes

Symptom	Likely cause	What to do
`Could not find Chrome (ver. ...)`	The install script was blocked, the browser was never downloaded, or runtime and install steps use different cache directories.	Run `npx puppeteer browsers install` using the project package manager’s runner. Check the configured cache path and download settings.
`npx` shows unexpected flags or behavior	A project-local or cached package version differs from the version expected.	Run `npx @puppeteer/browsers --help` in the project and inspect the version in use; pin a package version when repeatability matters.
Browser download or extraction fails	Network, proxy, archive tool, or platform requirement is missing.	Check proxy variables and install the platform’s required extraction utility. Use `NODE_DEBUG="puppeteer:browsers:*"` for detail.
Launch fails with an external executable	The executable path may point to an absent or incompatible browser.	Verify the path and browser build. Prefer Puppeteer’s downloaded browser where compatibility is important.
`--install-deps` fails or requests elevated access	The option installs system packages and its documented scope is Chrome on Ubuntu/Debian; it requires root.	Use it only on the supported distributions with appropriate privileges. On other platforms, install platform prerequisites using their normal system process.
Proxy settings appear ignored	The required `proxy-agent` package is not installed.	Install `proxy-agent` in the environment running the CLI and confirm `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`.
Browser binaries are missing after cleanup	`clear` removed the managed browser cache.	Reinstall the required browser build before running the automation job.

8. Performance, reliability, and cost considerations

Browser downloads are large, so repeated ephemeral builds can waste network time and storage. In CI or containers, choose a deliberate cache location, keep the browser package and browser build aligned, and avoid clearing the cache on every run. Pinning versions makes a setup reproducible; channel installs track a moving release and may change over time.

The install command needs network access unless the browser archive is already available through the configured environment. In restricted networks, configure the documented proxy variables and required proxy package. A CLI install succeeding does not by itself guarantee a launch: the host still needs compatible system libraries and a working executable. Browser compatibility is most predictable with Puppeteer’s downloaded browser; the documentation warns that external executables are used at the user’s risk.

There is no per-command Puppeteer CLI fee in the cited documentation. Practical costs are download bandwidth, cache storage, CI time, and any infrastructure needed to run a browser. The documented approximate archive sizes help with planning, but vary as browser builds change.

Or skip the browser setup

If your task is simply to capture a website, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns an image or PDF, so you do not need to install and manage a local browser for that capture. See the ScreenshotNeo API documentation for request parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Equivalent Python:

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)

Equivalent Node.js:

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 capture; each cleanup step can be turned off.
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 Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

Frequently asked questions

Are Puppeteer CLI flags the same as Chrome flags?

No. The CLI flags belong to browser-management commands. Chrome switches are interpreted by Chrome and can be passed through Puppeteer’s args launch property.

Can I install a particular Chrome version?

The browser CLI supports a channel, milestone, or full build identifier. Check the installed command’s help for the accepted current syntax.

Does installing `puppeteer-core` download Chrome?

No. It is intended for cases such as connecting to a remote browser or managing a browser yourself, and you supply the executable path or channel as applicable.

Where can I see which browser builds are installed?

Run npx @puppeteer/browsers list and confirm that Puppeteer is configured to use the same cache.