Puppeteer System Requirements: Node.js and Browser Versions

Puppeteer’s current system requirements page specifies Node.js 22.12 or later. Pair your installed Puppeteer release with the browser version in Puppeteer’s supported-browsers table: the current documentation lists Puppeteer v25.12.0 with Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. These version requirements change, so check the official pages when choosing a version or upgrading.

This guide uses Puppeteer documentation checked on October 3, 2026. Requirements below describe the current documentation, not every historical Puppeteer release.

1. Node.js and TypeScript requirements

The current Puppeteer system requirements page specifies Node.js 22.12+. It says Puppeteer follows the latest maintenance LTS version of Node, so treat the stated floor as version-sensitive and recheck it when updating Puppeteer.

Component	Current documented requirement	Practical action
Node.js	22.12 or later	Use a runtime meeting the current floor in development, CI and production.
TypeScript	5.0.1 or later, if using TypeScript	Upgrade TypeScript if your project compiles Puppeteer types.
TypeScript target	ES2022 or later when type-checking node_modules	Set an appropriate target if your TypeScript configuration checks dependencies.

These are the current page’s requirements. An older Puppeteer version may have had a different runtime floor; consult the documentation for the exact version you install.

2. Match Puppeteer to its browser

Puppeteer’s supported-browsers table maps library releases to browser versions. In the current table, Puppeteer v25.12.0 maps to Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. The table says that when an exact Puppeteer version is not listed, use the browser version for the immediately prior listed Puppeteer version.

Find the Puppeteer version in your lockfile or package manifest.
Look up that release in the official supported browsers table.
Use the listed browser pairing, or the prior listed version’s browser when your exact Puppeteer release is absent.
Recheck the mapping when upgrading either Puppeteer or a separately managed browser.

Do not assume an arbitrary Chromium build is interchangeable with the matching Chrome for Testing release. Puppeteer’s browser pairing exists for compatibility. Puppeteer uses Chrome DevTools Protocol (CDP) by default for Chrome and WebDriver BiDi by default for Firefox. Its FAQ describes production-ready WebDriver BiDi support for both Chrome and Firefox from Puppeteer v23.0.0; API behavior can still vary by browser and protocol.

3. Operating system and architecture support

The current requirements page lists these Chrome for Testing platforms:

Operating system	Architectures listed	Notes
Windows	x64	Chrome archive extraction needs tar.exe or PowerShell.
macOS	x64, arm64	Chrome extraction needs unzip; Firefox DMG handling additionally lists hdiutil.
Debian/Ubuntu Linux	x64, arm64	Use the linked distribution-specific package list for required system packages.
openSUSE/Fedora Linux	x64, arm64	Use the linked distribution-specific package list for required system packages.

Do not copy a Linux package recipe from a different distribution without checking it. The system requirements page points to Chromium package lists for the supported Linux families; package prerequisites can differ by distribution and image.

4. Browser downloads and installation choices

Let Puppeteer manage its browser

A regular Puppeteer installation downloads a recent Chrome for Testing and a chrome-headless-shell binary. The installation guide says reported download sizes are approximate and platform-dependent, and they can change with package versions. This is the simplest path when the environment can download and store the expected browser binaries.

Starting with Puppeteer 20, the package downloads and works with Chrome for Testing. The old headless mode is a separate chrome-headless-shell program, selected with headless: 'shell'. From Puppeteer v23, it also downloads and works with stable Firefox.

Manage or connect to a browser yourself

Use puppeteer-core when connecting to a remote browser or managing browser installation independently. Its launch API requires an executablePath or channel. Make sure that the chosen browser is compatible with your Puppeteer release and exists in the runtime environment.

Minimal containers and custom CI images

Check archive utilities as well as browser libraries. Chrome for Testing archive extraction requires tar.exe or PowerShell on Windows and unzip on macOS/Linux, unless optional yauzl is installed. Firefox on Linux needs xz or bzip2 for its archives. Firefox DMG handling on macOS lists hdiutil. A minimal image may omit these tools even when Node.js is correctly installed.

5. Runnable setup examples

Default Puppeteer installation

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

Save as capture.cjs and run node capture.cjs:

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' });
    await page.screenshot({ path: 'page.png', fullPage: true });
  } finally {
    await browser.close();
  }
})();

This uses Puppeteer’s managed browser installation. It requires the Node.js version and OS prerequisites appropriate to the installed Puppeteer release.

Externally managed browser with puppeteer-core

npm install puppeteer-core

Save as capture-core.cjs, set PUPPETEER_EXECUTABLE_PATH to the browser binary installed in your environment, then run node capture-core.cjs:

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

(async () => {
  const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
  if (!executablePath) {
    throw new Error('Set PUPPETEER_EXECUTABLE_PATH to a compatible browser binary');
  }

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

For a Puppeteer-supported browser channel, configure the documented channel option instead of executablePath. Check the launch API for the exact behavior for your installed version.

6. Troubleshooting requirements and launch failures

Symptom	Likely cause	What to check or fix
Install reports an unsupported Node.js engine	Runtime is below the requirement for the installed Puppeteer release	Use Node 22.12+ for the current documented requirements, or check the requirements for your pinned release.
Browser executable is missing	Browser download did not run, failed, or you are using puppeteer-core without a path	For regular Puppeteer, inspect installation/download logs. For puppeteer-core, supply a valid `executablePath` or supported `channel`.
Browser fails to launch in a minimal Linux image	Distribution-specific system packages or archive utilities are absent	Check the official package list for the exact distribution and architecture; confirm required extraction tools are available.
Browser download cannot unpack	Missing tar/PowerShell, unzip, xz or bzip2, depending on OS and browser	Install the utility listed for that platform and browser, then retry the browser installation.
New browser version behaves unexpectedly	Browser release does not match the Puppeteer compatibility mapping	Use the supported browser version for the installed Puppeteer release and verify protocol support for the API in question.
Type errors involving Puppeteer or dependencies	TypeScript version is too old or dependency checking uses an older target	Use TypeScript 5.0.1+ if applicable and ES2022+ when type-checking node_modules, as the current requirements page specifies.
Firefox archive installation fails on Linux	Required xz or bzip2 utility is unavailable	Install the required unpacker in the image and confirm it is available to the process performing installation.

7. Performance, reliability and cost considerations

Browser downloads: Managed installation uses disk space and can add time to a clean CI build. Cache dependencies and browser artifacts using the mechanism supported by your CI provider, and account for platform-specific downloads.
Reproducibility: Pin Puppeteer in the lockfile and keep its browser pairing aligned. A separately updated browser can introduce compatibility differences.
Containers: Validate the target OS and architecture, package prerequisites and archive tools in the actual deployment image. A successful install on a developer laptop does not establish that a minimal production image has the same dependencies.
Remote browser setup: puppeteer-core avoids Puppeteer-managed browser installation but transfers responsibility for browser lifecycle, version compatibility, executable availability and connectivity to your environment.
Cost: Puppeteer is software, but browser execution consumes your own compute, storage and CI time. The cited requirements documentation does not specify infrastructure pricing or a performance benchmark, so estimate those from your hosting and workload.

8. Or skip the browser setup

If your goal is a screenshot rather than browser automation, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A GET request returns a PNG, JPEG, WebP or PDF; see the ScreenshotNeo API documentation.

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 and consent banners are accepted like a visitor and removed along with 60+ known consent platforms, newsletter popups and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

9. Frequently asked questions

Does Puppeteer require Chrome to be installed separately?

A regular Puppeteer install downloads its expected browser binaries. With puppeteer-core, you manage the browser yourself or connect to a remote one.

Can I use Firefox with Puppeteer?

Yes. The supported browsers documentation describes stable Firefox support from Puppeteer v23, with version mapping in the browser table.

Should I upgrade Node.js or downgrade Puppeteer?

First compare your Node.js version with the requirements for the Puppeteer release you intend to use. Choose a compatible pair that your deployment platform supports, then pin it for repeatable installs.

Are Puppeteer’s requirements the same on every operating system?

No. Supported platforms, architectures, package prerequisites and archive tools vary. Consult the official requirements page for the target system.