How to Install Puppeteer Extra

For a typical Node.js project, install Puppeteer and Puppeteer Extra together:

npm install puppeteer puppeteer-extra

Then import puppeteer-extra in place of puppeteer and call launch() as usual. Plugins are optional and installed separately. The standard puppeteer package downloads a compatible browser; choose puppeteer-core when you manage the browser yourself or connect to a remote one. See the Puppeteer Extra README and Puppeteer installation guide.

1. Choose your installation path

What you need	Install	Browser handling
Typical local development	`puppeteer` + `puppeteer-extra`	Puppeteer downloads a compatible Chrome for Testing and headless shell.
Browser managed separately	`puppeteer-core` + `puppeteer-extra`	Provide an executable path, standard browser channel, or remote connection details.
Extra behavior such as stealth or ad blocking	Add the relevant plugin package	Register it with `.use()`.

The wrapper’s default export attempts to load either puppeteer or puppeteer-core. If your project uses a compatible custom implementation or needs separate configured instances, use its addExtra() export. The packages and plugins should be kept compatible; the project documentation does not establish a version matrix for every combination.

2. Install Puppeteer Extra with npm or Yarn

Typical setup with npm

npm install puppeteer puppeteer-extra

Typical setup with Yarn

yarn add puppeteer puppeteer-extra

Use a separately managed browser

npm install puppeteer-core puppeteer-extra

For Yarn, run yarn add puppeteer-core puppeteer-extra. Since puppeteer-core does not download Chrome, you must configure the browser or connection when launching. Do not install both browser packages unless you have a specific reason to do so: the wrapper can resolve an installed implementation, and having multiple candidates can make the setup less clear.

3. Run a minimal Puppeteer Extra script

Create index.cjs in your project:

const puppeteer = require('puppeteer-extra');

async function main() {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
    console.log(await page.title());
  } finally {
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run it with node index.cjs. Using try/finally closes the browser even if navigation fails. If your project uses ES modules, set "type": "module" in package.json or use an .mjs file, then write:

import puppeteer from 'puppeteer-extra';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  await browser.close();
}

4. Add an optional plugin

Install the plugin package separately. For example, to use the stealth plugin:

npm install puppeteer-extra-plugin-stealth

const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');

puppeteer.use(StealthPlugin());

async function main() {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');
  } finally {
    await browser.close();
  }
}

main().catch(console.error);

Another documented example is the adblocker plugin:

npm install puppeteer-extra-plugin-adblocker

const puppeteer = require('puppeteer-extra');
const AdblockerPlugin = require('puppeteer-extra-plugin-adblocker');

puppeteer.use(AdblockerPlugin({ blockTrackers: true }));

Omit the plugin’s install, import, and .use() call if you only need the wrapper. Register plugins before calling launch(). Review each plugin’s own documentation for its options and behavior.

5. Use Puppeteer Extra with puppeteer-core

Install the core library and wrapper:

npm install puppeteer-core puppeteer-extra

For an installed Chrome at a known path, wrap puppeteer-core explicitly and pass the executable path:

const puppeteerCore = require('puppeteer-core');
const { addExtra } = require('puppeteer-extra');

const puppeteer = addExtra(puppeteerCore);

async function main() {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/chrome',
    headless: true,
  });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');
    console.log(await page.title());
  } finally {
    await browser.close();
  }
}

main().catch(console.error);

Replace the example path with the browser executable available in your environment. Puppeteer also supports a standard installed browser channel. If connecting to a remote browser, use the connection details supplied by that browser service rather than assuming a local Chrome exists. The browser and Puppeteer must be compatible.

6. Fix “Could not find Chrome” after installation

The most common cause is a package manager blocking Puppeteer’s install script, so the npm package is present but its browser download did not run. Install the browser manually:

npx puppeteer browsers install

For Yarn, the Puppeteer guide documents yarn dlx puppeteer browsers install; for pnpm, pnpm dlx puppeteer browsers install; and for Bun, bun x puppeteer browsers install. Alternatively, configure your package manager to allow Puppeteer’s install script. For npm, the current guide shows an allowScripts entry in package.json; syntax and defaults may depend on the package-manager version, so check its current documentation.

If you intentionally use puppeteer-core, the absence of an automatically downloaded browser is expected. Set executablePath or channel, or connect to your managed remote browser.

7. Browser downloads, configuration, and deployment

Download size and cache: the standard package downloads browser binaries, which can be large. Puppeteer documents its cache location and download configuration; those details can vary by version and platform. Account for the browser cache in containers and CI rather than assuming it lives in the project directory.
Skip downloads intentionally: Puppeteer provides configuration and environment options to skip browser downloads. Use these only when your runtime supplies a compatible browser.
Containers and Linux: downloading Chrome is separate from having all required operating-system libraries. If launch reports missing shared libraries, install the runtime dependencies required by the browser image or host.
Reproducible builds: use a lockfile, install dependencies with the project’s locked-install command, and make browser installation an explicit build step if install scripts are disabled.
Lifecycle: close browser instances in a finally block. Reuse a browser for multiple pages within a process where appropriate; launching a fresh browser for every small task adds startup and resource overhead.
Compatibility: keep the Puppeteer implementation and browser build aligned. Avoid assuming a plugin version supports every current Node.js, Puppeteer, or browser release; verify package metadata and project guidance for the versions you select.

Official browser installation and configuration details are in the installation guide and configuration guide.

8. Troubleshooting

Symptom	Likely cause	What to do
`Could not find Chrome (ver. ...)`	Install script was blocked, or the browser cache is unavailable in the runtime.	Run `npx puppeteer browsers install` during setup and ensure the runtime can access the configured cache. Alternatively allow the install script.
`puppeteer-core` launches with no browser	Core does not download Chrome and assumes explicit browser configuration.	Supply `executablePath` or `channel`, or connect to a remote browser.
`Cannot find module 'puppeteer-extra-plugin-…'`	The optional plugin package was not installed in this project, or the import name is wrong.	Install that plugin package and make the import match its documented package name.
Plugin appears to have no effect	It may not be registered, may be registered after launch, or may not apply to the operation.	Call `puppeteer.use(Plugin())` before `launch()`; check the plugin’s documentation and logs.
Browser exits immediately or navigation fails	Unhandled error, incompatible browser, missing system dependency, or a target page that never reaches the requested navigation condition.	Log the error, verify browser compatibility and host dependencies, and choose a suitable `waitUntil` condition or navigation timeout.
Works locally but fails in CI or a container	Browser binaries or system libraries are not present in the deployed image, or the cache is not persisted or accessible.	Install the browser during image/build setup, include required OS dependencies, and make the configured cache path available at runtime.
Import or syntax error	CommonJS and ES module syntax are mixed, or the file’s module mode is unexpected.	Use `require()` in CommonJS or `import` in an ES module with the appropriate file extension or package setting.

9. Or skip the browser setup

If your goal is to capture a page rather than automate a browser, ScreenshotNeo returns a screenshot or PDF from one API request. The API documentation covers its options.

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

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Start with 1,000 free screenshots a month.

10. Frequently asked questions

Do I need a plugin to install Puppeteer Extra?

No. The wrapper works without plugins; install and register a plugin only when you need its behavior.

Does Puppeteer Extra download Chrome?

The wrapper relies on an installed Puppeteer implementation. The usual puppeteer package downloads a compatible browser; puppeteer-core does not.

Can I use Puppeteer Extra with TypeScript?

The project README shows ES module imports, which TypeScript projects commonly use. Confirm the types and module settings for your selected package versions.

Should I use Puppeteer Extra or Puppeteer Core?

Use the standard Puppeteer package for the usual downloaded local browser setup. Use Core when you manage the browser or connect remotely; Puppeteer Extra can wrap either implementation.