Next-Gen App & Browser Testing Cloud

Trusted by 2 Mn+ QAs & Devs to accelerate their release cycles

How to install or set up Puppeteer?

Q: What Node.js version does Puppeteer need?

Current Puppeteer (the v24.x line) requires Node.js 22.12 or newer. The safest choice is to install an active Node.js LTS release and confirm it with node -v before running npm install puppeteer.

To install Puppeteer, make sure Node.js (an active LTS release) and npm are installed, then run npm install puppeteer inside your project folder. That single command pulls in the Puppeteer library and automatically downloads a matching Chrome for Testing build, so you can import Puppeteer in a script and start automating Chrome right away. The rest of this guide walks through the prerequisites, the difference between puppeteer and puppeteer-core, a complete first script, environment configuration, and how to fix the most common install errors.

Prerequisites: Node.js and npm

Puppeteer is a Node.js library, so a working Node.js installation is the only hard requirement. npm ships with Node.js, so installing one gives you both.

Use an active LTS release: the current Puppeteer (v24.x line) requires Node.js 22.12 or newer. Installing the latest Node.js LTS keeps you comfortably above that floor and gives you long-term security updates.
npm comes bundled: you do not install npm separately. When you install Node.js, npm is included as its default package manager.
Where to download: grab the LTS installer from the official Node.js website, or use a version manager such as nvm if you juggle multiple Node.js versions.

Confirm both are available by checking their versions in a terminal. If the commands print version numbers, you are ready to install Puppeteer.

node -v
npm -v

Install Puppeteer with npm (puppeteer vs puppeteer-core)

There are two packages on npm, and choosing the right one saves you a lot of confusion later.

puppeteer (batteries included): installing this package downloads a compatible Chrome for Testing build (and chrome-headless-shell) automatically, into the Puppeteer cache directory. Pick this when you just want things to work locally with no extra configuration.
puppeteer-core (library only): this installs the same API but downloads no browser. You must point it at a browser with an executablePath or channel, or connect to a remote endpoint. Pick this when Chrome is already present, in size-sensitive CI images, or when you connect to a cloud browser grid.

For most people, the standard package is the right call.

npm install puppeteer

If you want the library without the bundled browser, install the core variant instead.

npm install puppeteer-core

Set Up a Puppeteer Project

Before installing the package, create a project folder and initialize it so npm has a package.json to write to. Follow these pointers in order.

Create and enter a folder: keep each automation project isolated so its dependencies and cache do not collide with other projects.
Initialize the project: running npm init with the -y flag accepts the defaults and generates a package.json instantly.
Install Puppeteer: run npm install puppeteer inside the folder so it is recorded as a dependency.
Decide on a module system: add "type": "module" to package.json if you want to use modern ESM import syntax. Leave it out to stay on CommonJS require.

The first three steps look like this on the command line.

mkdir puppeteer-project
cd puppeteer-project
npm init -y
npm install puppeteer

Write Your First Puppeteer Script

A first script is the fastest way to confirm the install worked. The example below launches a browser, opens a page, navigates to a URL, captures a screenshot, and closes the browser. Save it as index.js in your project folder.

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch(); // new headless mode by default
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png' });
  await browser.close();
})();

Run it with the Node.js runtime, then check your folder for the generated image.

node index.js

Headless by default: modern Puppeteer launches the new headless Chrome (chrome-headless-shell) automatically, so the script runs without opening a visible window.
Watch it run: pass headless: false to puppeteer.launch() when you want to see the browser perform each step on screen.
Always close: calling browser.close() releases the Chrome process. Forgetting it leaves zombie processes that pile up over repeated runs.

ESM import vs CommonJS require

Puppeteer supports both module systems, and the only difference is how you load it. The script above uses ESM, which requires "type": "module" in package.json (or a .mjs file extension).

import puppeteer from 'puppeteer';

If your project stays on CommonJS (the default when "type" is absent), use require instead. Everything after the import line is identical.

const puppeteer = require('puppeteer');

Use ESM when: you want top-level await, modern import syntax, or are sharing code with a frontend that already uses modules. Add "type": "module" or name the file with a .mjs extension.
Use CommonJS when: you are working inside an existing require-based codebase or older tooling. No package.json change is needed.

Configuration and Environment Variables

Puppeteer reads a handful of environment variables that control how and where it downloads the browser. These are the ones you will reach for most often.

PUPPETEER_SKIP_DOWNLOAD: set to true to skip the browser download during install, handy in CI images that already ship Chrome, or alongside puppeteer-core.
PUPPETEER_CACHE_DIR: relocate the browser cache directory, useful when you want the download cached in a path that survives between CI builds.
PUPPETEER_EXECUTABLE_PATH: point Puppeteer at an existing Chrome or Chromium binary instead of the bundled one.
HTTP_PROXY / HTTPS_PROXY / NO_PROXY: route the download and runtime traffic through a corporate proxy.

# Skip downloading Chrome on install
export PUPPETEER_SKIP_DOWNLOAD=true

# Relocate the browser cache
export PUPPETEER_CACHE_DIR="$HOME/.cache/puppeteer"

For settings you want committed with the project rather than exported in a shell, add a .puppeteerrc.cjs file at the project root. Puppeteer walks up the directory tree to find it, and you should re-install after changing it.

const { join } = require('path');

module.exports = {
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};

One thing you do not need to configure is TypeScript support, Puppeteer ships its own type definitions, so a TypeScript project gets full type checking without any extra @types package.

Troubleshooting Common Puppeteer Install Issues

"Failed to launch the browser process" on Linux: a minimal Linux image is usually missing shared libraries that Chrome needs. Install the dependencies and try again.

sudo apt-get update
sudo apt-get install -y libnss3 libatk-bridge2.0-0 libcups2 \
  libxkbcommon0 libgtk-3-0 libasound2

Crashes inside Docker or low-memory hosts: the default shared memory size is too small for Chrome. Launch with the --disable-dev-shm-usage argument (and usually --no-sandbox) to avoid intermittent crashes.
Install hangs behind a corporate proxy: set HTTP_PROXY and HTTPS_PROXY before installing so the browser download can reach the network, or skip the download entirely with PUPPETEER_SKIP_DOWNLOAD and use a preinstalled browser.
Version mismatch errors: if launch fails after upgrading, your cached browser may be stale. Re-run the install so Puppeteer fetches the Chrome for Testing build that matches the installed library version.

Running Puppeteer Tests at Scale

A local install is perfect for writing and debugging scripts, but it only covers the single Chrome build on your machine. When you need to confirm that your automation behaves the same across many browser and OS combinations, the next step is to point Puppeteer at a cloud grid. With TestMu AI Puppeteer you connect the same scripts to thousands of real browser and OS configurations using a remote endpoint, no local browser binaries required. It is the natural follow-on once your first script runs locally and you want broader coverage.

Frequently Asked Questions

What Node.js version does Puppeteer need?

The current Puppeteer (v24.x line) requires Node.js 22.12 or newer. The safest choice is to install an active Node.js LTS release and confirm it with node -v before running npm install puppeteer.

What is the difference between puppeteer and puppeteer-core?

The puppeteer package automatically downloads a compatible Chrome for Testing build during install, so it works out of the box. The puppeteer-core package installs the library only, with no browser download, and expects you to provide an executablePath or channel, or to connect to a remote browser endpoint such as a cloud grid.

Does npm install puppeteer install Chrome?

Yes. Running npm install puppeteer downloads a matching Chrome for Testing build (and chrome-headless-shell) into the Puppeteer cache directory, which defaults to the .cache/puppeteer folder in your home directory. This is why the first install is larger than a typical npm package.

How do I install Puppeteer without downloading Chromium?

Set the environment variable PUPPETEER_SKIP_DOWNLOAD=true before installing, or install puppeteer-core instead. Both approaches skip the browser download, which is useful in CI images that already ship Chrome or when you intend to connect to a remote browser.

Why do I get "Failed to launch the browser process" on Linux?

On a minimal Linux or Docker image the downloaded Chrome is usually missing shared system libraries. Installing packages such as libnss3, libatk-bridge2.0-0, libcups2, libxkbcommon0, libgtk-3-0 and libasound2 resolves the error. In containers you typically also add the --disable-dev-shm-usage and --no-sandbox launch arguments.

Does Puppeteer support TypeScript, and is it free?

Puppeteer is free and open source, and it ships its own TypeScript type definitions, so you do not need a separate @types/puppeteer package on current versions. You can import it directly into a TypeScript project and get full type checking.