Registry / http-networking / puppeteer-core

puppeteer-core

library24.41.0jsnpmunverified

puppeteer-core is a high-level API for controlling Chrome or Firefox over the DevTools Protocol or WebDriver BiDi. Unlike its sibling `puppeteer`, `puppeteer-core` does *not* download a browser binary during installation, making it suitable for environments where you manage the browser executable yourself (e.g., AWS Lambda, CI/CD, or existing browser installations). The current stable version is 24.41.0, released in April 2026. The project maintains a rapid release cadence, often synchronizing with Chrome and Firefox releases, typically with multiple updates per month to incorporate new browser features, bug fixes, and security patches. It is designed for scenarios requiring fine-grained control over the browser executable or minimal install size, offering the same powerful API for web scraping, test automation, and PDF generation.

http-networking testing web-framework

npm install puppeteer-core

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PUPPETEER-CORE

puppeteer-core

http-networkingjavascriptv24.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-core';

✗ const puppeteer = require('puppeteer-core');

While CommonJS `require` works, modern applications and the library itself primarily use ES Modules. TypeScript projects should use `import`.

Browser, Page

✓ import { Browser, Page } from 'puppeteer-core';

✗ import type { Browser, Page } from 'puppeteer-core'; // Wrong if you need the runtime values

These are interfaces/classes from the Puppeteer API. Use named imports for specific types or classes. `type` keyword is only for type-only imports in TypeScript.

launch

✓ const browser = await puppeteer.launch({...});

✗ import { launch } from 'puppeteer-core'; // Not directly exported from the top-level

`launch` is a method of the default `puppeteer` export, not a direct named export from the package root.

This quickstart demonstrates how to launch a browser using `puppeteer-core`, explicitly specifying the browser executable path, navigating to a page, interacting with elements, and logging content. It highlights `executablePath` which is crucial for `puppeteer-core`.

import puppeteer from 'puppeteer-core'; import { Browser, Page } from 'puppeteer-core'; async function runAutomation() { // IMPORTANT: For puppeteer-core, you MUST specify the executablePath. // This path needs to point to your installed Chrome/Chromium/Firefox executable. // Example for Linux: '/usr/bin/google-chrome' // Example for macOS: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' // Example for Windows: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe' const browser: Browser = await puppeteer.launch({ executablePath: process.env.CHROME_EXECUTABLE_PATH || '/usr/bin/google-chrome', // Provide actual path or use an env variable headless: true, // Use 'true' for new headless mode (default since Puppeteer v21) args: ['--no-sandbox', '--disable-setuid-sandbox'] // Recommended for CI/Linux environments }); const page: Page = await browser.newPage(); await page.goto('https://developer.chrome.com/docs/puppeteer/get-started/'); await page.setViewport({ width: 1080, height: 1024 }); await page.keyboard.press('/'); // Type into search box using accessible input name. await page.waitForSelector('::-p-aria(Search)'); await page.locator('::-p-aria(Search)').fill('headless testing'); // Wait and click on the first search result. await page.waitForSelector('.devsite-result-item-link'); await page.locator('.devsite-result-item-link').click(); // Wait for navigation and then locate the full title on the new page. await page.waitForNavigation(); const textSelector = await page .locator('::-p-text(Headless Chrome)') .waitHandle(); const fullTitle = await textSelector?.evaluate(el => el.textContent); console.log('Found title after search: "%s".', fullTitle?.trim()); await browser.close(); } runAutomation().catch(console.error);

Debug

Known issues

breakingThe `headless` option for `puppeteer.launch()` changed behavior in Puppeteer v21. Setting `headless: true` now uses the 'new' headless mode by default, which may behave differently than the 'old' headless mode.

fix

To explicitly use the 'new' headless mode, use `headless: true`. To revert to the 'old' headless mode, use `headless: 'shell'` or `headless: 'old'` (though 'old' is discouraged and may be removed). Review your scripts for compatibility with the new headless environment.

affects: >=21.0.0

gotchaWhen running Puppeteer-core in certain Linux environments (especially Docker or CI/CD), Chromium might fail to launch due to sandboxing issues. This is a common security feature on Linux that prevents a browser from doing harm.

fix

Launch Chromium with the `--no-sandbox` argument: `puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })`. Be aware of the security implications of disabling sandboxing in production.

affects: >=1.0.0

breakingThe default test runner `jest-circus` was removed as a direct dependency in v19. This primarily impacts users relying on Puppeteer's pre-configured Jest setup.

fix

If you use Jest with Puppeteer, ensure `jest-circus` (or your preferred test runner) is installed as a direct dependency in your project: `npm install --save-dev jest-circus`. Configure your Jest setup as needed.

affects: >=19.0.0

gotchaStarting with Puppeteer v15, the default browser downloaded (for `puppeteer` package) or expected (for `puppeteer-core`) shifted from a custom Chromium build to the stable Chrome browser, which changes its release cycle and potentially some DevTools Protocol behavior.

fix

Ensure your `executablePath` for `puppeteer-core` points to a recent, stable Chrome installation that is compatible with the `puppeteer-core` version you are using. Keep `puppeteer-core` updated to match the Chrome release cycle.

affects: >=15.0.0

deprecatedLegacy Page event handlers (e.g., `page.on('load', ...)`) and certain methods have been superseded by more robust alternatives like `page.waitForNavigation()` or specific locator APIs.

fix

Prefer using `page.waitForNavigation()`, `page.waitForSelector()`, or the new Locator API (`page.locator('selector').click()`) for improved reliability and clarity in your automation scripts. Consult the official API documentation for recommended patterns.

affects: >=19.0.0

Errors

Common errors & fixes

Error: Failed to launch the browser: No browser found at specified executablePath

The `executablePath` provided to `puppeteer.launch()` does not point to a valid browser executable, or the path is incorrect.

fix

Double-check the `executablePath` to ensure it's correct for your operating system and points directly to the browser executable (e.g., `chrome.exe`, `Google Chrome`, `chromium`). Ensure the browser is actually installed at that location.

TimeoutError: waiting for selector `selector` failed: timeout 30000ms exceeded

Puppeteer could not find the specified DOM element within the default (or specified) timeout period. This can happen if the element is not rendered, the selector is wrong, or the page takes too long to load/render.

fix

Verify the selector is correct and unique. Increase the timeout for `page.waitForSelector({ timeout: 60000 })` or `page.locator().waitHandle({ timeout: 60000 })`. Add `await page.waitForNavigation()` or `await page.waitForLoadState('networkidle')` before trying to find the element if it appears after a navigation or network request.

Protocol error (Page.navigate): Target closed.

The browser tab or page closed unexpectedly during navigation, possibly due to a JavaScript error on the page, network issues, or the page itself closing.

fix

Check the website for client-side errors during navigation. Add error handling around `page.goto()` and other navigation actions. Ensure the browser instance is stable and has sufficient resources. Sometimes, launching with `headless: false` can help debug on-screen errors.

Upgrade

Version history

24.41.0latest on npm

Audit

Dependencies

Chrome/Chromium or Firefoxrequiredpuppeteer-core requires a compatible browser executable (e.g., Chrome, Chromium, or Firefox) to be present on the system for its operations, as it does not bundle one itself. The user must provide the path to this executable.

Agent activity

5 hits · last 30 days

node

Resources

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

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

homepagehttps://pptr.dev ↗