puppeteer

library24.41.0jsnpmunverified

Puppeteer provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi, enabling browser automation for tasks like testing, scraping, and PDF generation. It runs headless by default but can be configured for full UI. The current stable version is 24.41.0. Releases are frequent, often several times a month, typically synchronizing with new Chrome and Firefox browser versions.

testing http-networking devops data

npm install puppeteer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PUPPETEER

puppeteer

testingjavascriptv24.41.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

puppeteer

✓ import puppeteer from 'puppeteer';

✗ const puppeteer = require('puppeteer');

ESM is preferred, but CommonJS is also supported.

This example launches a headless Chrome browser, navigates to a URL, interacts with elements using Puppeteer's custom selectors, extracts text content, and then closes the browser.

import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('https://developer.chrome.com/'); await page.setViewport({width: 1080, height: 1024}); await page.keyboard.press('/'); await page.locator('::-p-aria(Search)').fill('automate beyond recorder'); await page.locator('.devsite-result-item-link').click(); const textSelector = await page .locator('::-p-text(Customize and automate)') .waitHandle(); const fullTitle = await textSelector?.evaluate(el => el.textContent); console.log('The title of this blog post is "%s".', fullTitle); await browser.close(); })();

Debug

Known issues

gotchaThe default `puppeteer` package automatically downloads a compatible Chromium browser, which can significantly increase installation time and disk space. For smaller installations or to use an existing browser, consider `puppeteer-core`.

fix

Install `puppeteer-core` instead: `npm i puppeteer-core`. You will then need to provide the `executablePath` option to `puppeteer.launch()`.

affects: >=1.0.0

breakingPuppeteer requires Node.js version 18 or higher. Using an older Node.js version will result in installation or runtime errors.

fix

Upgrade your Node.js environment to version 18 or newer. Use a Node.js version manager like nvm (Node Version Manager) for easy switching.

affects: >=20.0.0

gotchaWhen running Puppeteer in environments like Docker containers or CI/CD pipelines, you may encounter errors related to sandboxing. Disabling the sandbox with `--no-sandbox` is often necessary but introduces security risks.

fix

Add `--no-sandbox` to the `args` array in `puppeteer.launch()`: `puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })`. For production, investigate a more secure sandboxing configuration for your environment.

affects: >=1.0.0

gotchaPuppeteer frequently updates to support the latest Chrome/Firefox versions. Mismatches between your installed Puppeteer version and the browser it controls can lead to unexpected behavior or broken features due to DevTools Protocol changes.

fix

Regularly update your Puppeteer package (`npm update puppeteer`) to ensure compatibility with the browser it launches. If using `puppeteer-core` with an external browser, ensure that browser is also up-to-date.

affects: >=1.0.0

gotchaPuppeteer's custom selectors like `::-p-aria()`, `::-p-text()`, and `::-p-xpath()` offer powerful ways to locate elements but are not standard CSS or XPath. Relying heavily on them may make your tests less portable outside Puppeteer.

fix

While powerful, consider supplementing custom selectors with standard CSS selectors (`page.locator('div.my-class')`) or `page.$eval()` for robust and widely understood element selection, especially for stable UI components.

affects: >=13.0.0

Errors

Common errors & fixes

Error: Failed to launch the browser process! No browser found at...

Puppeteer could not find a Chrome/Chromium executable at the expected path. This often happens if `puppeteer-core` is used without `executablePath`, or the `puppeteer` installation failed to download the browser.

fix

If using `puppeteer`, try reinstalling it to redownload the browser (`npm install puppeteer`). If using `puppeteer-core`, you must specify the `executablePath` in `puppeteer.launch()` to point to your browser binary.

Error: browserContext.newPage: Target closed.

You attempted to interact with a browser, page, or frame that has already been closed or navigated away from, invalidating the context.

fix

Ensure that `browser.close()` or `page.close()` is called only after all necessary operations on that context are complete. Check for asynchronous operations that might complete after a page or browser is closed.

Error: Navigation timeout of 30000 ms exceeded

A navigation action (`page.goto()`, `page.click()` followed by navigation, etc.) took longer than the default 30-second timeout.

fix

Increase the timeout for the specific navigation call (`await page.goto(url, { timeout: 60000 });`) or globally (`page.setDefaultNavigationTimeout(60000);`). Ensure the network and server are responsive.

Error: function: Cannot find context with specified id

This usually indicates that an `ElementHandle` or another browser-side object is being used after the page has reloaded, navigated, or the element itself no longer exists in the DOM.

fix

After any significant page navigation or DOM manipulation, re-select elements and obtain new `ElementHandle`s rather than reusing old ones. Ensure your element references are always fresh.

Error: The 'engines' field in 'package.json' specifies that this package is compatible only with Node.js >=18.

Your current Node.js version is older than the minimum required by Puppeteer.

fix

Upgrade your Node.js version to 18 or higher. You can use tools like `nvm install 18` and `nvm use 18`.

Upgrade

Version history

24.41.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/puppeteer/puppeteer.git#main ↗

packagehttps://www.npmjs.com/package/puppeteer ↗

homepagehttps://pptr.dev ↗