repository·main·Indexed Apr 15, 2026
https://github.com/puppeteer/puppeteerPuppeteer is a Node.js library providing a high-level API to control headless Chrome, Chromium, and Firefox browsers over the DevTools Protocol. It supports web scraping, end-to-end testing, and generating screenshots or PDFs. The library offers a bundled Chrome installation and a library-only mode via puppeteer-core, with browser binary management handled by the @puppeteer/browsers package. Features include programmatic browser installation and launching, CLI tools for managing browser binaries, CDPSession for raw DevTools Protocol access, and options to connect to existing browser instances. The repository includes Docker images for containerized execution and examples for common use cases.
Puppeteer is a JavaScript library that provides a high-level API to control Chrome or Firefox. It operates via the DevTools Protocol or WebDriver BiDi.
By default, Puppeteer runs in headless mode (no visible user interface), but it can be configured to run in headful mode (a visible browser window).
Puppeteer allows you to automate almost any manual browser interaction. Key capabilities include:
bidi/core is a low-level abstraction layer designed to sit above the WebDriver BiDi transport. It transforms the flat WebDriver BiDi API into a structured, object-oriented API.
Key features include:
You can provide an array of BrowserProvider implementations via the providers property in InstallOptions to use alternative download sources.
Important Considerations:
Many Puppeteer classes extend the EventEmitter class, which allows you to listen to specific events fired by those objects and execute code in response.
To interact with events, you will primarily use:
on(type, handler): Binds a listener to fire every time a specific event occurs.once(type, handler): Binds a listener that fires only the first time the event occurs, then automatically removes itself.off(type, handler): Unbinds a previously registered listener.removeAllListeners(type): Removes all listeners for a specific event type, or all listeners if no type is provided.listenerCount(type): Returns the number of active listeners for a specific event.Note: The EventEmitter constructor is internal. You should not call the constructor directly or attempt to create your own subclasses that extend EventEmitter in third-party code.
// Example pattern for using an EventEmitter-based class
page.on('request', request => {
console.log('Request sent to:', request.url());
});
page.once('close', () => {
console.log('Page closed');
});Puppeteer provides mechanisms to restrict browser access to specific sites to prevent unauthorized navigation:
24.42.0, this allows you to restrict access to unauthorized sites.24.43.0, providing a way to permit only specific URLs.The HandleOr<T> type is a union type used in Puppeteer to represent a value that can be one of three things: a HandleFor<T>, a JSHandle<T>, or the raw value T itself. This allows Puppeteer APIs to be flexible, accepting either a direct value or a reference (handle) to an object within the browser context.
export type HandleOr<T> = HandleFor<T> | JSHandle<T> | T;The Keyboard class provides an API for managing a virtual keyboard in Puppeteer. The primary high-level method is Keyboard.type(), which takes raw characters and automatically generates the necessary keydown, keypress/input, and keyup events for each character.
Important Limitations:
⌘ A (Select All) do not work on macOS.Keyboard constructor is internal. Do not attempt to call the constructor directly or create subclasses that extend the Keyboard class.// High-level usage
await page.keyboard.type('Hello World!');Cooperative Intercept Mode allows multiple handlers to 'vote' on how a request should be resolved. Instead of the first handler winning, the resolution with the highest priority wins.
priority argument to abort(), continue(), or respond(). If any handler omits the priority, the system reverts to Legacy Mode (immediate resolution by the first handler).abort > respond > continue.0 or DEFAULT_INTERCEPT_RESOLUTION_PRIORITY (from HTTPRequest) for standard behavior. This allows for graceful coexistence.| Mode | Requirement | Behavior |
|---|---|---|
| Legacy Mode | Any handler omits priority | First handler to call a resolution method wins immediately. |
| Cooperative Mode | All handlers provide priority | All handlers run; the highest priority resolution wins. |
// Cooperative Intercept Mode Example
page.setRequestInterception(true);
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
// Votes to abort at priority 0
request.abort('failed', 0);
});
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
// Votes to continue at priority 5. This wins because 5 > 0.
request.continue(request.continueRequestOverrides(), 5);
});Puppeteer provides two distinct packages depending on your use case:
Use this for standard browser automation. It is a high-level package that automatically downloads a compatible version of Chrome and provides reasonable defaults for automation workflows.
Use this if you want to manage browsers yourself or connect to a remote browser. It is a lightweight library that does not download Chrome.
When to use puppeteer-core:
puppeteer.connect.Note: If you use puppeteer-core, you must provide an executablePath or channel to puppeteer.launch, and you must change your import statement.
import puppeteer from 'puppeteer-core';18.2.0, Puppeteer was split into two packages: puppeteer (which includes a bundled version of Chromium) and puppeteer-core (which does not include a browser and requires you to provide one). Use puppeteer-core if you want to connect to an existing browser installation or manage your own browser binaries to reduce package size.If Chrome crashes with No usable sandbox!, it means the host environment is not configured for sandboxing.
Warning: Running with --no-sandbox is strongly discouraged for security reasons.
You can use the chrome_sandbox executable provided in the Puppeteer cache. You must set its ownership to root and permissions to 4755, then point to it using the CHROME_DEVEL_SANDBOX environment variable.
# Example setup for setuid sandbox
cd ~/.cache/puppeteer/chrome/linux-<version>/chrome-linux64/
sudo chown root:root chrome_sandbox
sudo chmod 4755 chrome_sandbox
# Export the variable
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox