Recommended Free Tools
Puppeteer is a Node.js library for automating Chrome and Firefox. For most projects, npm i puppeteer is the straightforward start: it downloads a compatible browser and provides defaults. Use puppeteer-core when you will manage or connect to the browser yourself. The answers below cover browser and protocol support, installation, navigation, input events, headless modes, and common 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 program launches or connects to a browser, opens pages, navigates to URLs, and interacts with page content through Puppeteer’s API. The getting-started guide demonstrates the basic workflow.
As an Amazon Associate I earn from qualifying purchases.
Which browsers and protocols does Puppeteer support?
From Puppeteer v23.0.0 onward, the official FAQ describes support for Chrome and Firefox. Chrome uses the Chrome DevTools Protocol (CDP) by default; WebDriver BiDi is the default for Firefox. Puppeteer also supports BiDi for both browsers, and CDP support for Chrome is continuing. The APIs available can vary by protocol, so consult the WebDriver BiDi guide before assuming a feature behaves identically.
Why does my Puppeteer version not work with my Chrome or Firefox version?
Puppeteer releases are paired with specific browser releases to maintain compatibility with the underlying protocols. Check the supported-browser table for the Puppeteer version you actually use; do not treat one browser mapping as universal. The documentation version 25.12.0 lists Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Those are the mappings for that documented version, not a guarantee for other releases.
#1 Best Overall
How do I install Puppeteer, and why can’t it find Chrome?
The puppeteer package normally downloads Chrome for Testing and chrome-headless-shell as part of installation. With npm:
npm i puppeteerThe installation guide also documents Yarn, pnpm, and Bun. Some package-manager configurations block dependency install scripts, which can leave Puppeteer installed without its browser and trigger an error such as Could not find Chrome (ver. ...).
- Install the package using your package manager.
- If the browser was not downloaded, run
npx puppeteer browsers install(or the corresponding command for your package manager). - Alternatively, configure the package manager to allow Puppeteer’s install script, then install again.
The installation guide estimates Chrome for Testing downloads at approximately 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. These are the guide’s estimates for the documentation version 25.12.0, not independent measurements; allow for the download and cache space required on the host.
Should I use puppeteer or puppeteer-core?
| Package | Use it when | What you manage |
|---|---|---|
puppeteer |
You want Puppeteer’s convenient defaults and browser download. | The package normally installs a compatible browser for you. |
puppeteer-core |
You manage the browser yourself or connect to a remote browser. | Provide the browser connection or, for a locally managed browser, an executablePath or known channel. |
puppeteer-core does not download Chrome. For the setup details and package-manager commands, see the installation guide.
What does Puppeteer require?
The system requirements page for Puppeteer 25.12.0 lists Node.js 22.12 or later and, if using TypeScript, TypeScript 5.0.1 or later. Platform support and required Linux system packages depend on the operating system and architecture. Check the system requirements for the actual machine or CI image; a successful laptop setup does not establish that a container has the same dependencies.
How do Puppeteer’s headless modes differ?
| Setting | What it launches | Choose it for |
|---|---|---|
Default (headless: true) |
Chrome in headless mode. | Automation needing Chrome’s broader feature behavior without a visible window. |
headless: 'shell' |
The separate chrome-headless-shell binary. |
Automation where its potentially faster performance is useful and the differences from regular Chrome are acceptable. |
headless: false |
Visible Chrome. | Watching or debugging browser interaction with a UI. |
The shell implementation does not match regular Chrome completely. For launch configuration and caveats, see headless modes.
Rank #3
What counts as a navigation?
Puppeteer treats any URL change as a navigation. This includes a full document load, an anchor navigation, and History API changes. That definition is useful for single-page applications, where the URL can change without loading a new document. The official FAQ explains this behavior.
What is the difference between trusted and untrusted input events?
Puppeteer-generated input methods produce trusted input events and the accompanying events expected from user interaction. 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 site’s security checks or automation policies. See the Puppeteer FAQ for the event distinction.
Does Puppeteer support media and audio playback?
The official FAQ includes media and audio playback as a common support question, but the material cited here does not establish a blanket guarantee for every browser, codec, operating system, or playback scenario. If playback matters to a test, verify it with the browser and host configuration you deploy and consult the current FAQ rather than assuming protocol support guarantees a particular media outcome.
Why won’t Chrome launch on Linux, Windows, or in Docker?
Launch failures are usually tied to the host setup, not a single universal Puppeteer fix. Check these items against the exact error and environment:
- Browser missing or cache unavailable: Confirm the browser installation completed and that the process can read Puppeteer’s browser cache. The troubleshooting guide documents
PUPPETEER_CACHE_DIRfor choosing a different cache location. - Linux dependencies: Confirm the required system packages are installed for the target distribution and architecture. Use the system requirements and troubleshooting guide for the host.
- Sandbox configuration: Make sure the environment supports Chrome’s sandbox. Puppeteer’s troubleshooting guidance strongly discourages
--no-sandbox; do not use it as a routine workaround. - Docker image: Check that the image includes the browser’s required shared libraries and other system dependencies, not just Node.js and the Puppeteer package.
- Windows policies or permissions: Verify that system or organization Chrome policies and file permissions are not blocking launch.
Compare the failing environment and error with the OS- and deployment-specific advice in the official troubleshooting guide.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Or skip the browser setup
If the task is simply to capture a website screenshot or PDF rather than automate a full browser workflow, ScreenshotNeo offers a screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. For example, save a screenshot as WebP with cURL:
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 options. Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups, and chat widgets; these cleanup steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers indicate the page verdict and whether the request was billed. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Where can I get help with Puppeteer?
For installation and runtime failures, first compare your setup with the official troubleshooting guide. The Puppeteer FAQ points users with questions to Stack Overflow and users reporting bugs to GitHub Issues; search existing discussions before posting. Use the channels and links listed in the current FAQ.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →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.
