puppeteer/puppeteer installation guide

Installing Puppeteer on macOS Tahoe (Apple silicon)

What this repository is

Puppeteer is a TypeScript/JavaScript library for controlling Chrome or Firefox through the DevTools Protocol or WebDriver BiDi. It launches in headless mode—without a visible browser window—by default. The normal installation is an npm dependency inside an existing Node project; you do **not** need to build the GitHub repository merely to use the published library.

Relationship to Claude Code: **unclassified**

The supplied first-party files do not document a Claude Code plugin, hook, skill, command, or Claude-specific setup. The main README does point to `chrome-devtools-mcp`, a separate Puppeteer-based MCP server, but it neither documents Claude Code nor places that MCP server in this repository. Therefore, the evidence does not support classifying this repository itself as a reliable Claude Code extension mechanism.

In practical terms, install Puppeteer because your JavaScript or TypeScript project needs browser automation—not because it will automatically add anything to Claude Code.

Before you begin

You need an existing Node project and a compatible version of Node.js with npm. The supplied files say that a compatible Node version is required but refer to the package’s `engines` field for the exact version; that field was not supplied. Consequently, this guide cannot responsibly state a minimum Node version or provide an undocumented Node installation command.

Open **Terminal** on your Mac and make sure it is already operating in the folder for the Node project where you want to use Puppeteer. If you do not yet have Node.js or a Node project, stop here and consult the current Node and project documentation first.

For macOS browser downloads, the repository lists `hdiutil` as necessary for unpacking Firefox `.dmg` files and `unzip` for Chrome downloads. It also explicitly recognizes an Apple-silicon browser platform named `MAC_ARM`. No Rosetta-specific setup is documented, so none should be added solely for Puppeteer based on these files.

Choose the correct package

There are two supported installation choices. Most beginners should use `puppeteer`:

• **`puppeteer`** provides the browser-control library and downloads a compatible Chrome during installation.
• **`puppeteer-core`** provides the library without downloading Chrome. This is the alternative for users who deliberately intend to manage the browser themselves.

Do not install both merely as a troubleshooting step. Choose the one matching your project.

Recommended installation: Puppeteer with Chrome

In Terminal, from your existing project folder, run:

npm i puppeteer

This is the repository’s documented normal installation command. Its install process is intended to download a compatible Chrome build as well as add Puppeteer to the project.

Be patient while npm installs the package and downloads the browser. This can take longer than installing a small JavaScript dependency because a browser binary is substantially larger.

If the browser was not downloaded

The README warns that modern package managers may block dependency install scripts by default. When that happens, the Puppeteer package can be present even though the required browser is missing, causing errors when your program tries to launch it.

Use the repository’s documented manual browser-download command:

npx puppeteer browsers install

This is the appropriate first repair when installation completed but runtime output says that Puppeteer cannot find the required browser. The first-party files also mention configuring a package manager to permit Puppeteer’s install script, but the only npm example involves editing `package.json`; because a complete copy-paste edit was not supplied, this guide does not invent one.

Alternative installation: library only

If you intentionally do not want installation to download Chrome, install the core package instead:

npm i puppeteer-core

This is not the easier beginner route. The README describes it as the library-only alternative, so browser availability and selection remain your responsibility. Use it only when your application already has a deliberate plan for the browser executable or connection.

Code using the full package imports `puppeteer`; code using the core alternative imports `puppeteer-core`. The repository’s example shows these as alternatives rather than packages that must be combined.

Check browser installation tools

The repository supplies a browser-management CLI. To display its overall help, run:

npx @puppeteer/browsers --help

The files state that `npx` installs and runs `@puppeteer/browsers` if necessary, or uses the locally installed version when one is available. You can inspect the installation command’s documented options with:

npx @puppeteer/browsers install --help

To list browsers managed by this tool, run:

npx @puppeteer/browsers list

A useful result here confirms what the browser manager can see. However, the supplied documentation does not define an exact expected line for every Puppeteer version, so do not treat the absence of a particular hard-coded version string from this guide as an error.

If you need the latest available stable Chrome for Testing independently of Puppeteer’s normal compatible-browser installation, the browser package documents:

npx @puppeteer/browsers install chrome@stable

For a routine Puppeteer setup, prefer `npm i puppeteer` and, if needed, `npx puppeteer browsers install`. Installing `chrome@stable` is an explicit browser-manager choice, not a required extra step in every setup.

Optional proxy support

The browser library and CLI recognize `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. The repository says those variables require the `proxy-agent` package to be installed:

npm install proxy-agent

Skip this unless your network is intentionally configured around an HTTP or HTTPS proxy. No proxy address, credentials, or environment-variable values are supplied by the repository, so this guide does not manufacture them.

Troubleshoot browser downloads

For verbose browser installation logging, the supplied documentation provides this command:

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

It reports browser-manager activity including cache, decompression, installation, and launcher details. Use it when the explicit stable-Chrome download is failing and ordinary output is insufficient.

To review all available browser-manager commands again, run:

npx @puppeteer/browsers --help

There is also a command that clears **all** browsers installed through this manager:

npx @puppeteer/browsers clear

This is destructive cleanup, not a normal installation step. Run it only when you genuinely intend to remove all browsers managed by the tool, after which a required browser must be downloaded again.

What not to do on this Mac

Do not use the documented Linux `--install-deps` example on macOS; the repository explicitly describes that option as Ubuntu/Debian-only. Likewise, the Docker commands build and run a Linux container and request `SYS_ADMIN`; they are not the standard native Apple-silicon installation path.

Do not run the repository’s `npm test`, workspace build, documentation deployment, Angular schematic, or example-development commands merely to install the published package. Those commands serve contributors, the documentation website, examples, internal tests, or Angular projects. They are separate from ordinary Puppeteer use.

Completion checklist

Your basic installation is complete when:

1. `npm i puppeteer` finishes successfully in your existing Node project.
2. A compatible browser downloads during installation, or the documented fallback command finishes:

npx puppeteer browsers install

1. The browser manager can be inspected with:

npx @puppeteer/browsers list

At that point Puppeteer is installed as a project dependency. It still has no evidenced automatic Claude Code registration. Any future MCP integration should be evaluated and installed from that separate MCP project’s own first-party instructions rather than inferred from this repository.