The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Use npx @puppeteer/browsers to install, list, launch, and clear browser builds managed by the Puppeteer Browsers CLI. Start with npx @puppeteer/browsers --help, then use command-specific help for the package version you intend to run; available browser builds and options can change.
Check which CLI version you are running
The @puppeteer/browsers package can “Manage and launch browsers/drivers from a CLI or programmatically,” according to the Puppeteer Browsers API and CLI guide. Run its help command first:
As an Amazon Associate I earn from qualifying purchases.
npx @puppeteer/browsers --helpnpx uses the package already installed in the current directory when available. To run a specific package version, include it in the command:
npx @puppeteer/[email protected] --helpUse @latest only if you deliberately want the newest published package rather than a version selected for a project. For repeatable scripts or environments, pin the package version and browser build, and check the help output for that installed version: CLI options and published browser builds are mutable.
#1 Best Overall
Install a browser build
The general pattern is install browser@version-or-channel. Examples from the Puppeteer documentation include:
npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers install [email protected]
npx @puppeteer/browsers install chrome@117
npx @puppeteer/browsers install chromedriver@canary
npx @puppeteer/browsers install chrome-headless-shell@stable
npx @puppeteer/browsers install firefox@stableThese identifiers illustrate the syntax; they do not guarantee that a particular channel or build remains available. A successful installation reports the actual build ID and the absolute path to its executable. The CLI implementation also supports installing Chromium by revision and Firefox variants such as beta, developer edition, ESR, and nightly. Check the install command’s help for the exact options in your version:
npx @puppeteer/browsers install --helpChoose a target and version policy
- Browser family: choose the documented target you need, such as Chrome for Testing, Chromium, ChromeDriver, Firefox, or
chrome-headless-shell. A driver is not the same thing as the browser it controls. - Channel or pinned build: a channel such as
stableis convenient when you want a current release, while a specific version, milestone, or revision is more suitable when a workflow depends on a repeatable browser build. Channels and available builds change. - Headless mode: standard Chrome and
chrome-headless-shellare distinct binaries. Select the one that matches the project’s intended headless behavior.
Install Linux system dependencies when needed
On Linux, the documentation describes --install-deps for installing Chrome system dependencies. This option is Linux-only and requires root privileges. It attempts to install dependencies even when the browser is already installed, so use it with that behavior in mind. Confirm the current syntax with install --help.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteLaunch a browser
Pass the browser identifier to launch. For example:
npx @puppeteer/browsers launch [email protected]
npx @puppeteer/browsers launch [email protected]
npx @puppeteer/browsers launch chrome@canary --system
npx @puppeteer/browsers launch [email protected] --detached
npx @puppeteer/browsers launch [email protected] -- --versionThe first examples select a browser build; --system asks the CLI to locate a browser installed on the system instead of using one from its managed cache. --detached detaches the child process. Use --dumpio to forward browser stdout and stderr to the CLI’s output. Arguments after -- are passed to the browser executable, as in the final example, which requests the binary’s version.
Check the installed command’s launch syntax before using options in automation:
npx @puppeteer/browsers launch --helpList or remove managed browser installations
List browser installations known to the CLI with:
npx @puppeteer/browsers listRemove installed browsers with:
npx @puppeteer/browsers clearBoth commands have their own help output:
npx @puppeteer/browsers list --help
npx @puppeteer/browsers clear --helpIf a script depends on the list output or clear behavior, inspect the help for the exact package version before building automation around it.
Meet Node.js and platform prerequisites
The package requires a compatible Node.js version. The supported range can change, so consult the current package metadata rather than assuming a fixed minimum. Downloads also depend on platform-specific archive tools:
- Chrome on Linux or macOS: extraction uses
unzip. - Chrome on Windows: extraction uses
tar.exe. - Firefox on Linux: extraction requires
xzandbzip2. - Firefox on macOS: extraction requires
hdiutil.
On Linux, the optional Chrome dependency-installation path additionally requires root privileges.
Understand how Puppeteer installs differ from the CLI
Installing the puppeteer package normally downloads a compatible Chrome for Testing build. Starting with Puppeteer v21.6.0, its installation also downloads a chrome-headless-shell binary. By contrast, puppeteer-core does not download Chrome; it is intended for cases where you manage the browser yourself or connect to a remote browser. See the Puppeteer installation guide.
Some package managers block install scripts by default. If that prevents Puppeteer’s automatic browser download, the installation guide documents manual installation with npx puppeteer browsers install or opting in to the package install script according to that package manager’s configuration.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Chrome for Testing and chrome-headless-shell serve different contexts. Puppeteer’s API uses headless: 'shell' to select shell mode. Choose the binary that matches both your Puppeteer version and the headless behavior you need; consult the headless modes guide.
Troubleshoot common setup problems
The command uses unexpected options or package behavior
Cause: npx may be running a package installed in the current directory, or the command may be using a different published version than expected.
Fix: check npx @puppeteer/browsers --help and the relevant command’s help. If you need a particular release, specify it explicitly, for example npx @puppeteer/[email protected] --help.
Browser download or extraction fails
Cause: a required archive utility may be unavailable on the machine.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Fix: verify the utility for your browser and operating system: Chrome uses unzip on Linux/macOS and tar.exe on Windows; Firefox uses xz and bzip2 on Linux or hdiutil on macOS.
Chrome starts but reports missing system dependencies on Linux
Cause: the system may lack Chrome’s required Linux dependencies.
Fix: consult npx @puppeteer/browsers install --help for the Linux-only --install-deps option. It requires root privileges and attempts dependency installation even if a browser is already present.
Puppeteer installed without its browser
Cause: a package manager may have blocked Puppeteer’s install script, or the project may use puppeteer-core, which does not download Chrome.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsFix: follow the package manager’s documented method for enabling the install script, or install a browser manually with npx puppeteer browsers install. For puppeteer-core, manage or provide the browser separately.
A headless run behaves differently than expected
Cause: Chrome for Testing and chrome-headless-shell are separate binaries, and Puppeteer’s headless modes select different execution paths.
Fix: match the browser binary and Puppeteer version to the desired mode, including headless: 'shell' when shell mode is intended.
A channel or example build is unavailable
Cause: browser channels and published builds change; a version shown in an example may no longer be downloadable.
Fix: check current command help and select an available build. For repeatable automation, pin a build rather than relying on a moving channel.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is to obtain a website screenshot rather than manage a browser binary, ScreenshotNeo offers a screenshot API and MCP server. One GET request returns an image 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.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers reporting the page verdict and billing status. Its 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 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Can I launch a browser already installed on my computer?
Yes. Use the CLI’s --system launch option to look for a system-installed browser instead of a cached build.
Does the Puppeteer Browsers CLI install Chrome automatically when I install Puppeteer?
The CLI is a separate browser-management route. Installing puppeteer normally downloads a compatible Chrome for Testing build, while puppeteer-core does not download Chrome.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
