Puppeteer Documentation: Getting Started and API Reference

Puppeteer is a JavaScript library for controlling Chrome or Firefox through browser automation protocols. To get started locally, install puppeteer: it normally downloads a compatible Chrome for Testing browser with the package. Choose puppeteer-core if you manage the browser yourself or connect to a remote browser. Then launch or connect, create a page, navigate, interact, and close the browser.

This guide covers the setup and starter workflow, how to choose the package, where to find the API reference, version compatibility, and common installation and runtime errors. The official documentation used here identifies itself as Puppeteer v25.12.0; browser and runtime versions can change, so check the live pages for the release you install.

1. Check your runtime and choose a package

For the retrieved v25.12.0 documentation, Puppeteer’s system requirements list Node.js 22.12 or newer and TypeScript 5.0.1 or newer when using TypeScript. Supported operating systems also need the system libraries and utilities required by the browser. See the current system requirements for your platform and installed release.

Package	Use it when	Browser setup
puppeteer	You want the conventional local setup.	Normally downloads a compatible Chrome for Testing browser and headless shell during installation.
puppeteer-core	You manage the browser installation or connect to a remote browser.	Does not download a browser. Supply a browser endpoint or executable path as appropriate.

The installation guide gives approximate browser download sizes of 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows. These are vendor-published estimates; actual disk and network use depends on the browser artifacts and platform. If your package manager blocks install scripts, the automatic download may not happen. The installation section below explains the manual browser install path.

Install one package from your project directory:

# Conventional setup: Puppeteer downloads its compatible browser
npm install puppeteer

# Alternative: manage or provide the browser yourself
npm install puppeteer-core

Yarn, pnpm, and Bun are also covered by the official installation guide. Check your package manager’s install-script policy if the browser download is skipped.

2. Run the basic Puppeteer workflow

Save this as capture.mjs in a project where puppeteer is installed. It launches the downloaded browser, creates a page, sets a viewport, visits a URL, interacts with a link using a locator, records the resulting page title, takes a screenshot, and closes the browser even if an operation fails.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();

try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 800 });
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

  const title = await page.title();
  console.log('Page title:', title);

  // Locators wait for the target to be available before interacting.
  const moreInformation = page.locator('a');
  await moreInformation.click();
  await page.waitForNavigation({ waitUntil: 'domcontentloaded' });

  await page.screenshot({ path: 'page.png', fullPage: true });
} finally {
  await browser.close();
}

Run it with node capture.mjs. This is a starting pattern, not a claim that every website uses the same navigation or interaction behavior. Replace the selector and wait condition with ones that match the page you automate.

What each step does

1. Launch: puppeteer.launch() starts a browser process using Puppeteer’s configured browser.
2. Create a page: browser.newPage() opens a tab for navigation and interaction.
3. Set the viewport: choose the layout dimensions your task needs before capturing.
4. Navigate: page.goto() loads the target URL. A wait condition determines what load milestone Puppeteer waits for.
5. Interact and inspect: use page methods and locators to act on the DOM and read results.
6. Capture and clean up: save a screenshot or other output, then close the browser to release its processes and resources.

For a remote browser or a browser you installed yourself, use puppeteer-core and connect to the browser endpoint or launch with an explicit executable path. Connection details depend on the remote provider; do not assume a local executable exists in a container just because Puppeteer is installed.

import puppeteer from 'puppeteer-core';

// Use an executable path managed by your deployment, or connect to a
// browser endpoint supplied by your remote browser environment.
const browser = await puppeteer.launch({
  executablePath: process.env.CHROME_PATH,
  headless: true,
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  await browser.close();
}

Set CHROME_PATH to a real executable path before running this example. If using a remote browser, follow its endpoint and authentication instructions and use Puppeteer’s connect API. The API reference documents the current options.

3. Choose navigation and interaction behavior

Wait for the right page milestone

Navigation waits affect correctness and latency. The starter example uses domcontentloaded, which is often a useful point for pages whose initial document is enough. A page can continue loading images, scripts, or data after that point. Choose the milestone that matches what you need to inspect, and add a locator or application-specific readiness condition when the content is rendered asynchronously. Avoid waiting for more work than your task needs.

For interaction, prefer locators for finding and acting on elements. They make the intended target explicit and provide built-in waiting behavior. Selectors must match the actual page, and an element may still be hidden, covered by a dialog, or replaced during a rerender. For navigation caused by a click, arrange the navigation wait so the action and wait cannot race; consult the current page and locator method documentation for the exact API behavior in your release.

Set the browser mode deliberately

Puppeteer runs headless by default. Headless mode is suited to unattended automation. When diagnosing layout or interaction problems, launching a visible browser can make the page state easier to inspect. Browser launch options are version-sensitive; use the launch API reference rather than copying old flags without checking whether they still apply.

Use a browser lifecycle that fits the job

For a short script, launch once, do the work, and close in a finally block. For a service processing many tasks, consider reusing a browser process and creating isolated pages or contexts for work, with explicit limits and cleanup. Browsers consume memory and CPU, and a page that hangs can retain resources. Apply job timeouts at the application level and close pages or browsers when work ends or fails.

4. Find your way around the API reference

The Puppeteer API Reference is an index of classes, types, and methods. It is most useful after you understand the basic browser and page workflow: look up the specific method or option you need rather than treating the reference as a step-by-step tutorial.

• Browser startup and connection: begin with the Puppeteer class methods launch and connect.
• Tabs and pages: look up Browser, Page, and the relevant navigation, viewport, locator, and screenshot methods.
• Options and types: follow the method’s parameter types to check accepted values and defaults for your installed version.
• Browser downloads: consult the separate @puppeteer/browsers API for browser installation and cache management.
• Configuration: use the configuration interface reference for supported configuration fields.

The getting-started guide is the task-oriented path; the API reference answers what a particular class or method accepts. Keep both open when building a script so examples and option details stay aligned with your installed release.

5. Keep Puppeteer and the browser compatible

Puppeteer releases are paired with browser releases because the automation implementation must match browser protocols. The supported-browser table for the retrieved Puppeteer v25.12.0 documentation lists Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. These values describe that documented release and can change; consult the live supported browsers table for the Puppeteer version in your project.

The project documentation says Chrome automation uses the DevTools Protocol (CDP) by default and Firefox automation uses WebDriver BiDi by default. Puppeteer has supported both Chrome and Firefox since v23, and the FAQ describes production-ready WebDriver BiDi support for both browsers from v23 onward, while Chrome CDP support continues. Check the current FAQ and compatibility table before changing browser or protocol assumptions.

If your exact Puppeteer release is absent from the compatibility table, its guidance is to use the browser version paired with the immediately prior listed Puppeteer version. In practice, prefer the package-managed browser for a local default setup, or pin and manage the browser deliberately when your deployment owns it. Do not assume an arbitrary system Chrome build is compatible.

6. Troubleshoot common setup and runtime errors

Symptom	Likely cause	What to do
Launch reports that Chrome is missing or cannot find the expected executable.	The install script was blocked, the browser download did not complete, or the cache was moved or removed.	Check the installation output and Puppeteer cache/configuration. Allow the package install script or install the browser using the documented Puppeteer browsers command. If using puppeteer-core, provide a valid executable path or connect to a remote browser.
Browser download fails during package installation.	Network restrictions, a proxy, unavailable disk space, or package-manager script policy can prevent the download.	Check network access and free disk space, review install-script policy, and use the documented manual browser-install workflow if scripts are intentionally disabled. Browser downloads are substantial; the installation guide’s approximate sizes are about 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows.
Browser starts locally but fails in a container or Linux host.	Required system libraries or platform dependencies are missing.	Compare the host with the current system requirements, install the listed dependencies for that environment, and confirm the browser executable can run there.
Navigation times out even though the page appears partly loaded.	The chosen wait milestone may depend on resources or activity that never settles, or the site is slow or blocked.	Choose a wait condition that matches the task, wait for a specific element when appropriate, and set a deliberate timeout. Check whether the URL is reachable from the machine running the browser.
A click times out or the wrong element is activated.	The selector is too broad or stale, the target is hidden, an overlay covers it, or the page rerendered.	Inspect the page state, narrow the locator, wait for the intended target, and account for dialogs or rerenders before clicking.
Works on one machine but not another.	Different Puppeteer/browser versions, missing system dependencies, or a different executable path can alter behavior.	Record and pin the package version, use its paired browser version, and make runtime, dependencies, and browser configuration explicit across environments.
Automation works in Chrome but not Firefox.	The browser uses a different protocol path and may have different support or behavior for a particular feature.	Check the supported-browser table and current FAQ for your release, then verify the exact API feature and browser combination you need.
Memory grows or jobs leave browser processes behind.	Pages or browsers are not closed after errors, or concurrent work exceeds available resources.	Use try/finally cleanup, set concurrency limits, close pages and browsers on cancellation, and enforce job timeouts.

For version-specific failures, compare the installed Puppeteer version with its browser pairing before changing launch flags. Start with the official installation guide, system requirements, and FAQ.

7. Performance, reliability, and cost considerations

Performance

• Launch a browser only as often as the workload needs. A long-lived process can avoid repeated startup, but it needs lifecycle management and resource limits.
• Choose the lightest navigation milestone that still guarantees the content your task needs.
• Limit concurrent pages to fit available CPU and memory. A browser page is a real browser workload, not a lightweight HTTP request.
• Use an appropriate viewport and avoid capturing or processing content your task does not need.
• Account for the browser download at install time: the official guide gives platform-specific approximate download sizes, so CI images and deployment caches may need room for the browser artifacts.

Reliability

• Keep Puppeteer and its compatible browser version aligned; check the release-specific supported-browser table.
• Make install scripts and browser provisioning explicit in CI. A successful JavaScript package install does not guarantee the browser binary was downloaded.
• Use bounded navigation and job timeouts, targeted readiness checks, and cleanup paths for errors and cancellation.
• Log the Puppeteer version, browser version, target URL, and failure stage when diagnosing environment-dependent problems. Avoid logging secrets carried in page URLs or headers.

Cost

Puppeteer itself is a JavaScript library, but browser automation has infrastructure costs: browser downloads consume bandwidth and disk, and running browsers uses memory and CPU. Remote browser services may have their own charges and limits; those terms are not specified by the Puppeteer documentation. Estimate capacity from your own workload rather than assuming a universal pages-per-machine figure.

8. Or skip the browser setup

If your task is simply to get a website screenshot, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Its API accepts one GET request with a URL and returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for options and current usage details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Replace YOUR_API_KEY with your ScreenshotNeo access key. The examples use Stripe as the target URL; change it to the page you are allowed to capture. ScreenshotNeo accepts the parameter names used by other screenshot APIs, which can make switching easier. It can also capture full pages, selected elements, PDFs, or HTML/CSS to an image, with options for viewport, device, waits, custom CSS or JavaScript, headers, cookies, and more. See the docs for the complete option list.

Cookie and consent banners are accepted like a visitor would accept them, and ScreenshotNeo removes more than 60 known consent platforms as well as newsletter popups and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo and get 1,000 screenshots a month free, with no card required.

9. Frequently asked questions

Is Puppeteer only for Chrome?

No. The project documents support for Chrome and Firefox. The default protocol differs by browser, and supported browser versions are paired with Puppeteer releases.

Does installing Puppeteer install a browser?

The puppeteer package normally downloads a compatible browser during installation. puppeteer-core does not; it is intended for browser setups you manage or remote connections.

Where should a beginner start in the API reference?

Start with the Puppeteer class’s launch or connect method, then follow the browser and page types used by your workflow. Use the getting-started guide for the sequence of tasks.

Can I use my system Chrome?

You can configure a browser you manage, but compatibility is release-specific. Check the supported-browser table for the Puppeteer version in use and provide the executable path when needed.

Does a screenshot script need to close the browser?

Yes. Close browser processes when the job is finished, including on errors, so they do not keep consuming resources.

Official Puppeteer references

• Overview
• Installation
• Getting started
• Supported browsers
• System requirements
• API reference
• FAQ
• @puppeteer/browsers API
• Configuration interface