Puppeteer System Requirements: Node.js, Browsers, and Linux Dependencies

Direct answer: Puppeteer 25.12.0 requires Node.js 22.12 or later. If you use TypeScript, the documented minimum is 5.0.1; target ES2022 or later when type-checking node_modules. Chrome for Testing targets Windows x64, macOS x64 and arm64, Debian/Ubuntu Linux x64 and arm64, and openSUSE/Fedora Linux x64 and arm64. Check the requirements for your installed Puppeteer release because browser and platform support can change. Official system requirements.

1. Runtime and platform checklist

Requirement	Puppeteer 25.12.0
Node.js	22.12 or later
TypeScript, if used	5.0.1 or later
TypeScript target when checking node_modules	ES2022 or later
Documented Chrome for Testing platforms	Windows x64; macOS x64 and arm64; Debian/Ubuntu Linux x64 and arm64; openSUSE/Fedora Linux x64 and arm64

Confirm both operating system and CPU architecture. The listed platforms are not a promise that every OS or Linux distribution is supported.
The requirements page does not give minimum CPU, RAM, or free disk figures. Check the needs of your workload and environment rather than assuming a universal hardware minimum.
For Linux, compare the base image and release with Chromium’s current package manifests; distribution libraries vary.

2. Install Puppeteer and its browser

The puppeteer package downloads Chrome for Testing and chrome-headless-shell by default. These approximate Chrome download sizes are about 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. They are download estimates, not a total installed disk-space requirement. The default browser cache location is $HOME/.cache/puppeteer (since Puppeteer v19.0.0).

# npm
npm install puppeteer

# Yarn
yarn add puppeteer

# pnpm
pnpm add puppeteer

# Bun
bun add puppeteer

Some package managers block dependency install scripts. If Puppeteer’s script is blocked, the package may install without downloading its browser. Allow Puppeteer’s install script in your package manager, or install the browser explicitly:

npx puppeteer browsers install

A minimal runnable JavaScript capture, saved as screenshot.mjs:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1365, height: 900 });
  await page.goto('https://example.com', { waitUntil: 'networkidle2' });
  await page.screenshot({ path: 'screenshot.png', fullPage: true });
} finally {
  await browser.close();
}

node screenshot.mjs

Use puppeteer when you want Puppeteer to download and drive its corresponding Chrome. Use puppeteer-core when you will manage a DevTools Protocol-compatible browser yourself; it does not download Chrome. With puppeteer-core, set executablePath or a supported channel as appropriate.

npm install puppeteer-core

For reproducible deployments, pin the Puppeteer version and use the browser version mapped to it in the supported browsers table. The 25.12.0 table maps to Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Check the table for the version you actually install.

3. Linux, containers, and deployment

Chrome can fail to start on Linux when shared libraries or other system packages are missing. Puppeteer’s troubleshooting guide names common GTK, NSS, GBM, X11, font, and xdg-utils dependencies, but the exact packages depend on your distribution and release. Use Chromium’s current Debian or RPM package manifests for the image you deploy.

# Inspect the Chrome binary for unresolved shared libraries
ldd /path/to/chrome | grep not

Use the output to identify missing libraries, then install the corresponding packages for your base image. Puppeteer also needs a writable user-data directory; its default temporary profile usually handles this, but a configured userDataDir must be writable by the process user.

Chrome does not support Alpine out of the box. If Alpine is required, arrange compatible dependencies and validate browser launch in the actual image. Puppeteer’s Docker guide also documents an image with Chrome for Testing, required dependencies, and a preinstalled Puppeteer version; follow the current guide for runtime instructions.

The @puppeteer/browsers documentation covers browser installation and extraction requirements. Its Debian/Ubuntu dependency-install option requires root privileges.

4. Troubleshooting common setup errors

Symptom	Likely cause	What to do
“Could not find Chrome” or no executable found	The install script was blocked, or the browser was not installed in the expected cache.	Allow Puppeteer’s package install script or run `npx puppeteer browsers install`. Check the configured cache and browser installation.
Chrome exits immediately on Linux	Missing shared libraries or other system dependencies.	Run `ldd` on the Chrome binary and inspect unresolved libraries; install the matching distribution packages using current Chromium manifests.
Browser cannot create or use a profile	The process cannot write to its temporary or configured user-data directory.	Provide a writable directory for the runtime user, especially when setting `userDataDir`.
Browser fails in Alpine	Chrome does not support Alpine out of the box.	Use a supported base image, or arrange compatible dependencies and test the exact Alpine image.
Works locally, fails in container or CI	The deployed OS/architecture, libraries, permissions, or browser install differs from local development.	Check the supported platform list, install the browser in the deployment environment, inspect dependencies, and ensure the runtime user can write its profile.
Type errors while checking dependencies	TypeScript version or compiler target is below the documented requirement.	Use TypeScript 5.0.1 or later and ES2022 or later when type-checking `node_modules`.
Browser/Puppeteer protocol incompatibility	The separately managed browser version does not match Puppeteer’s supported mapping.	Use the supported browser version for the installed Puppeteer release, or install the browser through Puppeteer.

Puppeteer’s FAQ describes this as a common test-environment problem: “I am having trouble installing / running Puppeteer in my test environment.” See the official FAQ and troubleshooting guide when the checks above do not resolve it.

5. Performance, reliability, and cost considerations

Installation and storage: budget for the browser download and extracted files in CI caches or deployment images. The published download sizes do not specify final disk consumption.
Cold starts: downloading a browser during every job adds setup work and makes jobs depend on network access. A persistent cache or a deployment image with the compatible browser already installed can avoid repeated downloads.
Repeatability: pin Puppeteer and align the browser version to its compatibility table. Recheck requirements when upgrading.
Host resources: the official requirements do not define a general RAM or CPU floor. Measure your own pages, concurrency, and capture settings in the intended environment.
Failure handling: close browsers in a finally block as in the example, and set navigation timeouts appropriate to your workload. Treat page navigation and browser startup as operations that can fail independently.
Cost: Puppeteer is a software package; the documented requirements do not name a paid Puppeteer license. Your operational cost comes from the machines, storage, bandwidth, and engineering time used to install and run browsers.

6. Or skip the browser setup

If your goal is to get a website screenshot rather than manage Chrome dependencies, ScreenshotNeo is a website screenshot API and MCP server for developers. Send one GET request with the target URL and receive an image or PDF. See the ScreenshotNeo API docs.

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

# Python
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)

// Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

7. FAQ

Does Puppeteer require Chrome to be installed separately?

Not when using the puppeteer package with its install script enabled; it downloads Chrome for Testing and chrome-headless-shell. puppeteer-core leaves browser management to you.

Can I use Firefox?

Puppeteer documents Firefox support. Consult the supported browsers table for the browser version corresponding to your Puppeteer release and the current setup instructions.

Does the download size tell me how much disk space to reserve?

No. The figures are approximate browser download sizes, not total extracted or runtime disk requirements.

Is every Linux distribution supported?

No. The requirements page names specific distribution families and architectures. Other configurations need their own dependency and launch validation.