ScreenshotNeo
Sign in Get a free key

BlogGuides

Puppeteer Browsers CLI Constructor: Options and Setup

Learn when to use the Puppeteer browsers CLI, what its public CLI constructor accepts, and how to configure browser installs, caches, and versions.

By the ScreenshotNeo team4 October 20268 min read

The quickest way to use the Puppeteer browsers CLI is to run npx @puppeteer/browsers --help, then use its install, launch, list, or clear commands. Instantiate the exported CLI class directly only when embedding the CLI or customizing its behavior in your own Node.js program. Its constructor accepts either a cache-path string or an options object, plus an optional readline.Interface.

1. Choose the right setup

There are two related ways to use these tools:

  • Standalone CLI: Run npx @puppeteer/browsers for browser installation and management without writing a Node.js wrapper.
  • Puppeteer wrapper: If Puppeteer is part of your project, its puppeteer browsers command can manage the browsers associated with that installation.
  • Direct constructor: Import CLI from @puppeteer/browsers when a program needs to configure or embed the CLI.

Use the command-line route unless you need to customize the CLI itself. The CLI class is public. Do not instantiate InstalledBrowser: Puppeteer’s API documentation marks its constructor internal and says third-party code should not call it directly. See the InstalledBrowser API documentation.

2. Run the CLI from a shell

Start with general help, then request help for the command you plan to use:

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

If the package is installed in the current project, npx uses that copy. Otherwise, it fetches and runs the package. To use a specific CLI release, pin it in the invocation:

npx @puppeteer/browsers@2.4.1 --help

That version is an example of version pinning, not a recommendation to use that release. Check the current package and command help before choosing a version.

Install, list, and clear browsers

# Install Chrome from the stable channel
npx @puppeteer/browsers install chrome@stable

# Install a Chrome build or version (availability can change)
npx @puppeteer/browsers install chrome@117

# Install a ChromeDriver channel build
npx @puppeteer/browsers install chromedriver@canary

# See browsers in the configured cache
npx @puppeteer/browsers list

# Clear browser downloads from the cache
npx @puppeteer/browsers clear

Browser names and build identifiers are browser-specific. An identifier may refer to a release channel, version, milestone, or build ID depending on the browser. Check current help and availability rather than assuming a documented example will remain downloadable. See the Puppeteer browsers API and CLI documentation.

Install system dependencies on Ubuntu or Debian

Puppeteer documents this command for installing Chrome and its required system dependencies on Ubuntu or Debian:

npx puppeteer browsers install chrome --install-deps

This option is scoped to Chrome on Ubuntu or Debian and requires root privileges. It is not a general installation command for other operating systems or browsers. See Puppeteer’s configuration guide for its documented setup context.

3. Instantiate the public CLI constructor

The constructor accepts a cache path string as shorthand, or an options object as its first argument. An optional readline.Interface can be provided as the second argument. The examples below show the documented API shape; use the exported types from the exact package release installed in your project because the source on the default branch can evolve.

Install the package

npm install @puppeteer/browsers

Use the cache-path shorthand

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

const cli = new CLI('/tmp/browser-cache');

// Use the package's public API to run the CLI in your application.

Pass options explicitly

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

const cli = new CLI({
  cachePath: '/tmp/browser-cache',
  scriptName: 'my-browser-tool',
  allowCachePathOverride: false,
});

// Use the package's public API to run the CLI in your application.

These snippets illustrate construction, not a complete command runner: command dispatch and interaction depend on the package release’s exported API. Consult the API documentation and the installed package’s TypeScript declarations for the methods available in your version.

Constructor options

Argument or option Meaning Default or notes
First argument: string Cache directory shorthand. Equivalent to setting cachePath.
cachePath Directory used for browser downloads. Defaults to process.cwd() when omitted for the standalone CLI constructor.
scriptName Name displayed for the command. Defaults to @puppeteer/browsers.
version Version displayed by the CLI. Defaults to the package’s compiled version value.
prefixCommand Custom command prefix and its description. Object with cmd and description fields.
allowCachePathOverride Controls whether a CLI cache-path option may override the configured path. Defaults to true.
pinnedBrowsers Per-browser build IDs and skip-download flags for the pinned-browser workflow. A partial mapping from browser identifiers to {buildId, skipDownload}.
Second argument: rl Optional Node.js readline.Interface. Omit it when the CLI should create or manage interaction itself.

For the authoritative signature, consult the CLI implementation and match it to the version in your lockfile. Options such as pinnedBrowsers customize CLI behavior; they do not make a browser build available if its artifact has been removed upstream.

4. Configure browser downloads and cache location

If your application uses Puppeteer, prefer its configuration file for persistent download defaults. Puppeteer’s configuration guide documents supported config locations and formats, and says environment variables override applicable file options. Proxy settings such as HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are environment-only; proxy downloads require the optional proxy-agent peer dependency. Configuration files and environment variables are ignored by puppeteer-core.

Since Puppeteer v19.0.0, its downloaded browsers are stored under ~/.cache/puppeteer by default. The configuration guide explains how to change that location. If you change download configuration, rerun the browser install step:

npx puppeteer browsers install

These Puppeteer settings are distinct from passing cachePath to a standalone CLI instance. Decide which tool owns the download configuration, then make sure installation and later browser lookup use the same cache.

5. Pick a browser version deliberately

Choice Useful when Trade-off
Stable or another release channel You want a current channel build without selecting a fixed build identifier. The installed browser can change over time as the channel advances.
Explicit version or build ID You need repeatable setup across local development or CI. The chosen artifact must remain available, and you must update it intentionally.
Default cache You want the standard location for the tool you use. Different tools or environments may not share the same cache.
Custom cache path You need a known location for a container, build worker, or embedded CLI. Installation and launch processes must agree on the path and permissions.

Keep the browser paired with a supported Puppeteer version. Puppeteer’s support page says v20 and later use Chrome for Testing, and v23 and later download and work with stable Firefox. Check its current supported browser version mapping for the release you use; if an exact Puppeteer version is not listed, the page says the supported browser version is the immediately prior listed version.

6. Troubleshoot common setup errors

Symptom Likely cause Fix
npx cannot find or run the command. The package name or invocation is wrong, or installation/network access failed. Run npx @puppeteer/browsers --help and check the package spelling and npm access. If the project pins a version, confirm that release is installed or available.
Requested browser build is unavailable. The identifier is invalid for that browser, or the build is no longer published. Check command help and select a currently available channel or build ID for that browser.
The application cannot find a browser that the CLI installed. Installation and lookup use different cache directories or configuration. Inspect the CLI’s cachePath and Puppeteer configuration, then install and launch against the same cache.
Proxy download fails. Proxy environment variables are missing or the optional proxy agent is unavailable. Set the applicable HTTP_PROXY, HTTPS_PROXY, or NO_PROXY environment variable and install the documented proxy-agent peer dependency when required.
Browser launches but does not work with Puppeteer. The browser and Puppeteer versions are outside the supported pairing. Consult the supported browser mapping and install the matching browser release.
--install-deps fails with permissions or is unrecognized. It is being used outside its documented Chrome on Ubuntu/Debian scope or without root privileges. Use it only in that environment with the needed privileges; otherwise follow the platform’s documented dependency setup.
Changing config has no effect on the installed browser. The browser was already downloaded before the new download settings took effect. Rerun npx puppeteer browsers install after changing browser download configuration.

7. Performance, reliability, and cost considerations

  • Cache reuse: Reusing a cache avoids repeated browser downloads when the environment preserves it. In ephemeral CI workers, a cache may disappear between runs; configure and persist the intended directory according to your CI environment.
  • Reproducibility: Pin a Puppeteer release and a compatible browser version or build for repeatable automation. Channel-based installs are convenient but advance as the channel changes.
  • Network and disk: Browser downloads require network access and local disk space. A custom cache path can help place downloads on storage managed for the job, provided the process can read and write there.
  • System dependencies: Browser installation alone may not satisfy operating-system library requirements. Use platform-specific Puppeteer guidance; the documented --install-deps command has the narrow Ubuntu/Debian Chrome scope described above.
  • Cost: The package is software you run; account for your own compute, storage, and network use. The research sources provide no managed-service pricing or performance benchmarks, so none are claimed here.

8. Or skip the browser setup

If your task is to capture a website image rather than run browser automation, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF; see the 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 consent platforms, newsletter popups, and chat widgets; each step can be turned off.
  • Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
  • An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.
  • 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Every feature is on every plan.

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

9. FAQ

Should I use the standalone CLI or Puppeteer’s wrapper?

Use the standalone command for direct browser management. Use Puppeteer’s wrapper when you want its browser setup to follow Puppeteer configuration for the project.

Does a custom constructor cache path change Puppeteer’s config?

No. The constructor configures that CLI instance; Puppeteer’s own configuration applies to Puppeteer-managed browser downloads.

Can I instantiate InstalledBrowser instead?

No. Its constructor is documented as internal. Use the public CLI or browser APIs instead.

Will a pinned build remain downloadable forever?

No availability guarantee is stated in the documentation. Check current help and the upstream browser artifacts when setting up a pinned build.

Keep reading

7 min read

LinkedIn Open to Work Image

Learn what LinkedIn’s Open to Work photo frame means, who can see it, how to add or remove it, and how to choose the right privacy setting.