Puppeteer Browser Platforms: Supported Operating Systems

Direct answer: Puppeteer’s current system requirements list Chrome for Testing on Windows x64; macOS x64 and arm64; Debian or Ubuntu Linux x64 and arm64; and openSUSE or Fedora Linux x64 and arm64. Puppeteer also supports Firefox, but its documentation points to Mozilla for Firefox’s operating-system requirements rather than publishing its own Firefox platform matrix. A listed OS still needs compatible system libraries, and the browser version must work with the Puppeteer release you use.

This guide explains the documented platforms, how to install and launch Puppeteer, and what to check when a browser fails to start. The version-specific details below reflect the Puppeteer documentation version 25.12.0. Check the current system requirements when choosing a new deployment target.

Supported operating systems and architectures

Browser	Operating system	Documented architecture
Chrome for Testing	Windows	x64
Chrome for Testing	macOS	x64, arm64
Chrome for Testing	Debian or Ubuntu Linux	x64, arm64
Chrome for Testing	openSUSE or Fedora Linux	x64, arm64
Firefox	See Mozilla’s system requirements	Puppeteer’s page does not specify an architecture matrix

The Linux entries name distributions rather than promising support for every Linux derivative. In particular, do not assume that a distribution not listed in the table will launch Chrome without additional work. Puppeteer says Chrome does not support Alpine out of the box.

For Firefox, consult Mozilla’s Firefox system requirements for the Firefox release and operating system you plan to use. Puppeteer’s documentation does not establish a minimum Firefox OS version in its own matrix.

What “supported” means in practice

The OS and CPU architecture are only part of a working setup. You also need a compatible browser binary, the libraries that browser expects, and a writable environment for its profile and cache. Puppeteer’s current requirements specify Node.js 22.12 or later. If you use TypeScript, they specify TypeScript 5.0.1 or later; use an ES2022-or-later target when type-checking Puppeteer’s dependencies.

Browser choice: The explicit OS and architecture list is for Chrome for Testing. Firefox has a separate Mozilla requirements reference.
Linux packages: Missing shared libraries can prevent Chrome from starting even on a listed distribution.
Archive tools: Chrome downloads need tar.exe or PowerShell on Windows and unzip on macOS or Linux, unless the optional yauzl dependency is installed. Firefox Linux archives need xz or bzip2.
Browser pairing: Puppeteer releases are paired with browser versions. A manually installed browser may not match the protocol Puppeteer expects.
Install behavior: The puppeteer package normally downloads Chrome for Testing and a headless shell. puppeteer-core does not download a browser.

See Puppeteer’s system requirements, FAQ, and troubleshooting guide for the current version-specific details.

Install and launch Puppeteer

Use a supported Node.js version and an OS/architecture combination from the matrix.
Install Puppeteer and allow its install step to download the paired browser.
Launch a page, navigate to a URL, and close the browser in a finally block so it is cleaned up even after an error.

npm install puppeteer

Save this runnable example as screenshot.mjs, then run node screenshot.mjs https://example.com. It writes a screenshot named page.png.

import puppeteer from 'puppeteer';

const url = process.argv[2] ?? 'https://example.com';
let browser;

try {
  browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 });
  await page.screenshot({ path: 'page.png', fullPage: true });
  console.log('Saved page.png');
} catch (error) {
  console.error('Screenshot failed:', error);
  process.exitCode = 1;
} finally {
  await browser?.close();
}

networkidle2 waits until the page has no more than two network connections for a short period. Sites with persistent connections may never become idle, so use a different readiness condition or a bounded wait where appropriate. Puppeteer documents headless mode as the default; headless: true makes the intent explicit.

Using a browser you manage yourself

Use puppeteer-core when the browser is remote or installed and managed separately. Provide its executable path explicitly. You are then responsible for obtaining a compatible browser build and its OS dependencies.

npm install puppeteer-core

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  executablePath: '/absolute/path/to/chrome',
  headless: true,
});

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

The path shown is a placeholder: replace it with the browser executable path on your machine. Puppeteer’s installation guide explains the package distinction and browser download behavior.

Installation and configuration details

Automatic browser download

Installing puppeteer normally downloads a compatible Chrome for Testing build and chrome-headless-shell. By default, the browser cache is under ~/.cache/puppeteer (using the home directory appropriate to the OS). Package managers may block dependency install scripts, which skips the download. If so, install the browser explicitly:

npx puppeteer browsers install

Use the equivalent command for your package manager if you use Yarn, pnpm, or Bun. When deployment builds reuse dependencies or run under another user, ensure the browser cache exists in the runtime environment and is readable by that user. The installation guide covers download configuration.

Architecture and browser selection

On Apple silicon, the documented Chrome for Testing architectures include arm64 as well as x64. Confirm that the Node.js process and browser binary you install are suitable for the machine.
On Linux arm64, Puppeteer’s current matrix names Debian or Ubuntu and openSUSE or Fedora. It does not list Windows arm64.
If you use Firefox, check Mozilla’s current OS requirements and install the Firefox build you intend to run. Puppeteer’s system requirements note that Linux Firefox archive extraction needs xz or bzip2.
When you choose a custom Chrome or Chromium executable, verify compatibility with your Puppeteer version instead of assuming any installed browser will work.

Linux dependencies and containers

Linux Chrome relies on system libraries and fonts. Puppeteer’s troubleshooting guide lists common Debian dependencies and links to Chrome’s maintained package lists for Debian-based and RPM-based distributions. In a container, install the needed packages in the image and make sure Chrome can write its profile and cache. A read-only filesystem can cause startup failures unless the relevant directories are writable.

Alpine requires special care: Chrome does not support it out of the box. Compatible dependencies and a tested browser build are necessary; Puppeteer’s documentation also reports Chromium timeout issues for a particular Alpine release. Treat Alpine as a custom compatibility task rather than a platform guaranteed by the standard matrix.

Common errors and fixes

Error or symptom	Likely cause	What to do
`Could not find Chrome (ver. ...)`	The package manager blocked Puppeteer’s install script, or the runtime cannot see the browser cache.	Run `npx puppeteer browsers install`. Check the cache location and permissions, especially when build and runtime users differ.
Chrome exits immediately or reports a missing shared library	A Linux system dependency is absent.	Use `ldd` on the Chrome executable to identify missing libraries, then install the packages required by the distribution. Check Puppeteer’s current troubleshooting page and Chrome’s package lists.
`No usable sandbox!`	The host’s Linux sandbox setup or security profile blocks Chrome.	Configure a working Chrome sandbox for the host. Puppeteer documents `--no-sandbox` as an option only for content you absolutely trust and strongly discourages running without the sandbox.
`chrome_crashpad_handler: --database is required` or startup failure in a read-only container	Chrome cannot write its profile, configuration, or cache.	Provide writable temporary or mounted directories for Chrome’s runtime data and user profile; ensure the browser process owns them.
Navigation times out on Alpine	Alpine is not supported by Chrome out of the box, and browser/package compatibility may be the issue.	Prefer a distribution in Puppeteer’s documented matrix, or validate compatible dependencies and browser versions in the exact Alpine image.
Browser launches but protocol operations fail	The browser version may not be paired with the installed Puppeteer release.	Use the browser downloaded for that Puppeteer release or select a documented compatible version. Avoid upgrading one independently without checking compatibility.
Browser archive extraction fails	The required extraction utility is unavailable.	Install `tar.exe` or PowerShell on Windows, `unzip` on macOS/Linux, or the required `xz` or `bzip2` utility for Firefox archives on Linux.

For current error-specific guidance, consult the official Puppeteer troubleshooting page. Avoid adding --no-sandbox as a routine fix: it removes a security boundary around pages Chrome opens.

Choosing a deployment platform

Before committing to a host, check these points:

Identify the browser: Chrome for Testing or Firefox. The OS matrix differs in how Puppeteer documents them.
Check OS and architecture together: for Chrome, match both fields in the table above.
Confirm Linux packages: verify shared libraries and fonts in the actual base image, not just the distribution name.
Check writable paths: the browser must be able to create runtime profile and cache files.
Pin a compatible setup: keep the Puppeteer release and browser version aligned, and repeat a launch check when updating either.
Account for install scripts: make browser installation explicit in CI or deployment environments that suppress package scripts.

Reliability, performance, and cost notes

OS support is a compatibility statement, not a speed or uptime guarantee. Startup time and capture reliability depend on the browser binary, system libraries, available CPU and memory, fonts, page behavior, and network conditions. For repeatable builds, use a known OS image, install the browser and dependencies during the build, keep cache permissions consistent, and verify a real launch after changing Node, Puppeteer, the browser, or the base image.

The automatic Chrome download adds a substantial artifact to installation: Puppeteer’s installation page currently describes downloads of roughly 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows, plus a headless-shell binary. Consider build time, image size, and cache behavior when choosing between automatic browser management and puppeteer-core with a separately managed browser. These are download sizes from the documentation, not runtime-memory or speed benchmarks.

Or skip the browser setup

If your goal is a website screenshot rather than maintaining a browser installation, ScreenshotNeo is a website screenshot API: one GET request returns an image or PDF. Its API is documented at ScreenshotNeo’s 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Cookie banners are accepted like a visitor and removed along with supported newsletter popups and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed; cache hits cost nothing, and response headers identify page verdict and billing status. ScreenshotNeo also offers an MCP server for AI agents, with tools including 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 shots.

FAQ

Does Puppeteer support Windows?

Yes. Its current Chrome for Testing system requirements list Windows x64. The page does not list Windows arm64 for Chrome for Testing.

Does Puppeteer support Apple silicon?

Yes. The Chrome for Testing matrix lists macOS arm64, as well as macOS x64.

Can I use Puppeteer on a Linux distribution not in the table?

Possibly, but the named support matrix does not guarantee that distribution. You must resolve browser and library compatibility for that environment; Alpine has an explicit out-of-the-box caveat.

Does Puppeteer itself specify Firefox’s minimum OS version?

No. It refers readers to Mozilla’s system requirements. Check Mozilla’s page for the Firefox release you will run.

Do I need to install Chrome separately?

Usually not with the puppeteer package, which normally downloads its paired Chrome. You do need to arrange a browser yourself with puppeteer-core.