How to Install Puppeteer · ScreenshotNeo

For a standard Node.js project, run npm i puppeteer. Puppeteer normally downloads a compatible Chrome for Testing browser during installation. Then run a small script to launch the browser, open a page and close it.

mkdir puppeteer-demo
cd puppeteer-demo
npm init -y
npm i puppeteer

If your package manager blocked install scripts, install the package first and then download the browser explicitly:

npx puppeteer browsers install

Use puppeteer-core when your application manages Chrome separately or connects to a remote browser. It does not download Chrome for you.

1. Check prerequisites

The current Puppeteer system requirements document lists Node.js 22.12 or newer. TypeScript projects should use TypeScript 5.0.1 or newer; when type-checking dependencies, target ES2022 or later. Check the official system requirements before publishing because supported versions change.

node --version
npm --version

Chrome for Testing is documented for Windows x64, macOS x64 and arm64, Debian/Ubuntu Linux x64 and arm64, and openSUSE/Fedora Linux x64 and arm64. Linux also needs distribution-specific browser libraries. On Windows, Puppeteer may need tar.exe or PowerShell to unpack downloads; macOS and Linux may need unzip, unless the optional yauzl package is available.

2. Install with your package manager

npm

npm install puppeteer

Yarn

yarn add puppeteer

pnpm

pnpm add puppeteer

Bun

bun add puppeteer

The full puppeteer package is the default choice for new projects. Its installation process downloads a browser selected to work with the Puppeteer API. The browser cache normally lives at $HOME/.cache/puppeteer.

Package	Use it when	Browser handling
`puppeteer`	You want the standard setup	Downloads a compatible browser by default
`puppeteer-core`	You manage Chrome yourself or use a remote browser	No automatic browser download; provide connection details

3. Verify the installation

Create check-puppeteer.mjs:

import puppeteer from 'puppeteer';

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

Run it with:

node check-puppeteer.mjs

A successful run prints the page title and exits. Always close the browser in a finally block so failed navigation does not leave Chrome processes running.

CommonJS variant

const puppeteer = require('puppeteer');

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

4. Install and use puppeteer-core

Choose puppeteer-core when a container image, operating system package, managed browser service or remote endpoint supplies Chrome. Installing it alone does not install a browser.

npm install puppeteer-core

For a locally managed executable, pass its path:

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  headless: true,
  executablePath: '/absolute/path/to/chrome'
});
try {
  const page = await browser.newPage();
  await page.goto('https://example.com', {waitUntil: 'domcontentloaded'});
} finally {
  await browser.close();
}

When connecting to a remote browser, use the connection method and endpoint supplied by that browser service. Keep the Puppeteer and browser versions aligned by checking the supported browsers table. Version mappings are release-specific and should be rechecked before deployment.

5. Control browser downloads and configuration

Puppeteer recommends a configuration file for supported settings. Environment variables can also configure behavior, and some settings are environment-only. If a configuration change affects browser downloads, run the browser-install command again.

npx puppeteer browsers install

The default cache is ~/.cache/puppeteer. Set PUPPETEER_CACHE_DIR when your build or runtime needs another location:

PUPPETEER_CACHE_DIR=/opt/puppeteer-cache npx puppeteer browsers install

Make the same cache available in the runtime image. A common deployment failure is downloading the browser in one build stage and starting the application in another stage that does not contain that cache. Puppeteer configuration and environment variables do not apply to puppeteer-core, so configure custom-browser workflows explicitly.

6. When installation scripts are blocked

Some package-manager or CI policies disable dependency install scripts. The package can then appear in node_modules while its browser is missing.

Install the package using your normal package-manager command.
Run npx puppeteer browsers install in an environment where downloads are allowed.
Persist the Puppeteer cache in the deployment artifact or runtime image.
Run the smoke test again.

Package-manager settings differ, so use that manager’s documented mechanism to allow Puppeteer’s install script when you prefer automatic downloads. Do not copy an npm-specific setting into Yarn, pnpm or Bun configuration without checking its documentation.

7. Troubleshooting installation and launch errors

Symptom	Likely cause	Fix
“Could not find Chrome” or missing executable	Install script was blocked, or the cache is absent	Run `npx puppeteer browsers install`; verify the cache exists in the runtime environment.
Browser downloads but will not start on Linux	Required system libraries are missing	Install the packages listed for your distribution in the system requirements and troubleshooting guide.
Sandbox error	Linux sandbox permissions or setup are incorrect	Configure the supported sandbox setup. Running with `--no-sandbox` is strongly discouraged as a routine fix.
Custom Chrome launches unreliably	Browser and Puppeteer versions are mismatched	Compare versions with the supported-browser table and set the correct `executablePath`.
Works locally but fails in CI	Different architecture, missing libraries, blocked downloads or an empty cache	Confirm Node and OS architecture, install Linux dependencies, persist the browser cache and run the smoke test inside CI.
Chrome processes remain after an error	`browser.close()` was skipped	Put cleanup in `finally`; also avoid creating a new browser for every URL.

8. Performance, reliability and cost

Install time: the first full-package install includes a browser download. Cache the Puppeteer directory in CI to avoid downloading it on every build.
Runtime: launch one browser and reuse it across pages or jobs when isolation requirements permit. Close pages and the browser when work ends.
Reliability: pin dependency versions in your lockfile, check the supported browser mapping after upgrades and keep system libraries consistent across environments.
Storage: include the browser cache in container sizing and deployment artifacts. A fresh ephemeral runtime may need a network download before the first capture.
Cost: Puppeteer itself is installed as software; your practical costs come from CI minutes, bandwidth, storage and any browser infrastructure you operate.

9. Or skip the browser setup

If your goal is a screenshot rather than maintaining Chrome, ScreenshotNeo provides a website screenshot API and MCP server. The API is one GET request, and the documentation is at screenshotneo.com/docs.

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}`);

Cookie banners, newsletter popups and chat widgets are removed before the shot. Bot checks, blank pages and failed loads are never billed, and response headers identify the page verdict and whether it was billed. An MCP server lets AI agents such as Claude or Cursor take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

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

10. FAQ

Does installing Puppeteer install Google Chrome?

The default package downloads Chrome for Testing and the headless-shell binary selected for Puppeteer. It does not require a separate physical purchase.

Can I install Puppeteer without downloading a browser?

Yes. Install puppeteer-core and connect it to a browser that your application or infrastructure manages.

Why is the browser missing after `npm install`?

An install-script policy probably skipped the download. Run npx puppeteer browsers install and make the resulting cache available at runtime.

Should I use `--no-sandbox` in production?

No. Puppeteer strongly discourages disabling the sandbox as a routine fix. Configure the Linux sandbox and its permissions instead.

Where can I check version compatibility?

Use Puppeteer’s supported browsers page and recheck it when upgrading Puppeteer or the browser.