Puppeteer is a Node.js library for automating Chrome and Firefox. The puppeteer package downloads a compatible browser for you; puppeteer-core is for a browser you manage yourself or access remotely. This FAQ explains the package and browser choices, version compatibility, navigation and input behavior, and common installation and launch failures.
What is Puppeteer, and who maintains it?
Puppeteer is a Node.js browser automation library and reference implementation maintained by the Chrome Browser Automation team. A script launches or connects to a browser, opens pages, navigates to URLs, and interacts with page content through Puppeteer’s API. The getting-started guide shows the basic workflow.
Which browsers and automation protocols does Puppeteer support?
Puppeteer supports Chrome and Firefox starting with version 23.0.0. It uses Chrome DevTools Protocol (CDP) by default for Chrome and WebDriver BiDi by default for Firefox; BiDi is also supported for both browsers. Puppeteer’s FAQ says Chrome automation through CDP will continue. Protocol support is not necessarily feature-for-feature identical, so check the WebDriver BiDi guide before assuming an API works the same way with both protocols.
Why does my Puppeteer version not work with my browser?
Puppeteer releases are paired with particular browser releases to keep the underlying protocols compatible. Use the official supported browser versions table to check the mapping for your installed Puppeteer version. For the documentation version 25.12.0, the table lists Chrome for Testing 154.0.8037.57 and Firefox 156.0.1; those are version-specific mappings, not permanent compatibility promises.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
Should I install puppeteer or puppeteer-core?
| Package | Best fit | What you manage |
|---|---|---|
puppeteer |
You want Puppeteer to download a compatible browser and provide convenient defaults. | Usually little browser setup; the install process downloads its supported browser. |
puppeteer-core |
You manage the browser yourself or connect to a remote browser. | You must provide the browser path or channel for a local browser, or configure the remote connection. |
puppeteer-core does not download Chrome. For a locally managed browser, set executablePath or a known channel when launching it. See the installation guide for package and configuration details.
How do I install Puppeteer, and what does it require?
For the managed package, run npm i puppeteer. The install normally downloads Chrome for Testing and chrome-headless-shell. The documentation for Puppeteer 25.12.0 lists Node.js 22.12 or later and, if you use TypeScript, TypeScript 5.0.1 or later. Requirements for browser platforms and Linux libraries vary by operating system and architecture; check the system requirements for the target machine, especially when moving from a developer computer to CI or a container.
The same versioned installation guide estimates the Chrome for Testing download at about 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. These are documentation estimates, not independent measurements; allow for the download and cache in build and disk-space planning.
Why can’t Puppeteer find Chrome after installation?
A package manager may block dependency install scripts, preventing the browser download. A common symptom is an error such as Could not find Chrome (ver. ...). Install the browser explicitly with npx puppeteer browsers install, or use the corresponding command for your package manager. Alternatively, configure that manager to allow Puppeteer’s install script, then rerun installation. The installation guide covers supported package-manager instructions.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWhich headless mode should I use?
| Setting | Browser behavior | Choose it when |
|---|---|---|
headless: true (the default) |
Runs Chrome without a visible window. | You want the regular Chrome headless mode and its broader Chrome behavior. |
headless: 'shell' |
Uses the separate chrome-headless-shell binary. |
You do not need the complete Chrome feature set and can accept behavioral differences; the guide says this mode can be more performant for automation. |
headless: false |
Opens visible Chrome. | You need to observe or interact with the browser window while debugging. |
The shell mode does not match regular Chrome completely. Compare results in the mode that reflects your actual test or production environment. See Puppeteer’s headless modes guide.
What counts as a navigation?
Puppeteer treats a URL change as navigation. That includes a normal document load, an anchor navigation, and a URL change made through the History API. This matters in single-page applications, where navigation can happen without a full document reload. See the official FAQ for the documented definition.
Are Puppeteer-generated input events trusted?
The Puppeteer FAQ describes input events generated through Puppeteer’s input APIs as trusted, with the appropriate accompanying events. By contrast, calling a DOM method such as element.click() inside page.evaluate creates an untrusted event. This distinction describes how the event was generated; it is not a way to bypass a website’s security checks or automation policies.
Why does Chrome fail to launch in Linux, Windows, or Docker?
Launch failures depend on the host and the exact error. Work through the environment rather than assuming every failure has the same cause:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →- Browser missing or cache unavailable: confirm that the browser install completed and that the process can access the browser cache. The troubleshooting guide documents
PUPPETEER_CACHE_DIRfor changing the cache location. - Linux dependencies missing: compare the target distribution and architecture with the system requirements; a browser that works on a workstation may lack shared libraries in a container.
- Sandbox configuration: configure a working sandbox for the host. Puppeteer’s troubleshooting guidance strongly discourages launching with
--no-sandbox. - Docker image incomplete: install the required system libraries and other dependencies for the chosen browser and base image, following the official troubleshooting guide.
- Windows policy or permissions: check whether Chrome policies or file permissions prevent the browser from starting or accessing its files.
Use the error-specific instructions in the official troubleshooting guide after confirming the browser version and cache location.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is to capture a page rather than automate a browser interactively, ScreenshotNeo is a website screenshot API and MCP server. A single request returns a PNG, JPEG, WebP, or PDF. For example, this cURL request captures a page as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters. Cookie banners, newsletter popups, and chat widgets are removed before the capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.
Where can I get help with Puppeteer?
For installation and runtime failures, start with the official troubleshooting guide and the system requirements for your host. The Puppeteer FAQ directs questions to Stack Overflow and bug reports to GitHub Issues; search the relevant channel for an existing answer or report before posting.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
