Puppeteer is a JavaScript library for controlling Chrome and Firefox: it can open pages, interact with controls, inspect content, and save screenshots or PDFs. Its default is headless operation, but you can configure a visible browser when you need to watch an automation run. This guide walks through installation, a complete first script, useful outputs, version matching, and common setup problems.
What Puppeteer does—and how it controls a browser
Puppeteer exposes browser automation in JavaScript. The official guide describes Chrome and Firefox automation through the Chrome DevTools Protocol (CDP) or WebDriver BiDi. Chrome uses CDP by default, with BiDi also available; Firefox uses BiDi by default. Puppeteer’s FAQ says Chrome CDP support will continue alongside BiDi support. Puppeteer documentation and its FAQ describe the current interfaces and protocol behavior.
As an Amazon Associate I earn from qualifying purchases.
Typical jobs include form submission, UI tests, keyboard input, performance traces, Chrome extension testing, and crawling single-page applications to generate pre-rendered content. Puppeteer is a browser-control library, not a test runner or a hosted browser service: your script defines the steps, and your environment supplies the browser runtime.
Choose the right package and install it
Use puppeteer for a local first run
The standard installation is npm i puppeteer. The package downloads a compatible Chrome for Testing build, which makes it the simplest choice when you want Puppeteer to manage a local browser. The installation guide explains browser setup and package-manager configuration.
#1 Best Overall
npm init -y
npm install puppeteerUse puppeteer-core when you manage the browser
npm i puppeteer-core does not download a browser. Choose it if your setup already provides a browser or connects to a remote browser, and explicitly select the browser executable or connection method in your code. It is not a drop-in way to get the same self-contained local setup: you are responsible for ensuring that the browser and Puppeteer version are compatible.
npm install puppeteer-coreIf Chrome is missing after installation
Package managers can block install scripts, preventing Puppeteer from downloading its browser. Allow the package’s install script in your package-manager settings, or install the managed browser manually:
npx puppeteer browsers installIf you deliberately use puppeteer-core, install scripts are not a substitute for providing a browser; configure the browser your environment actually supplies.
Free tools Windows power users keep installed
One-click scans. No signup required.
Run a first automation: navigate, interact, and read
This example uses Puppeteer’s locator API to search the Puppeteer site, open a result, and read the page title. Replace the example interaction with selectors and expected content from the application you need to automate.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
const puppeteer = require('puppeteer');
async function main() {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800 });
await page.goto('https://pptr.dev/', { waitUntil: 'domcontentloaded' });
const search = page.locator('::-p-aria(Search)');
await search.fill('locators');
await search.press('Enter');
await page.locator('::-p-text(Locators)').click();
const title = await page.title();
console.log(title);
} finally {
await browser.close();
}
}
main().catch(error => {
console.error(error);
process.exitCode = 1;
});The sequence is: launch a browser, create a page, set its viewport, navigate, locate and operate a control, read or assert a result, then close the browser. A finally block ensures the browser is closed even if navigation or an interaction throws. In a test, replace the console output with an assertion in your test framework.
Puppeteer’s locator API supports finding and interacting with elements; consult the Locator API reference for current methods and selector forms. Locators are useful when you need to wait for an element to be available before acting rather than immediately querying a possibly unfinished page.
Save a screenshot or PDF
Capture a screenshot
Add this before browser.close() to save a full-page PNG:
Recommended Free Tools
await page.screenshot({ path: 'page.png', fullPage: true });Use fullPage: true when the output should include content beyond the current viewport. Without it, the screenshot represents the visible page area. See the screenshot API for supported options.
Rank #3
Generate a PDF
For a PDF, add:
await page.pdf({ path: 'page.pdf', format: 'A4', printBackground: true });page.pdf() uses print CSS media by default, so the result may differ from the page’s screen appearance. If you need screen styling, emulate screen media before creating the PDF:
await page.emulateMediaType('screen');
await page.pdf({ path: 'page.pdf', format: 'A4', printBackground: true });Check the PDF API reference for current paper, margin, and other PDF options.
Headless or visible browser?
Puppeteer launches headless by default. For debugging an automation interactively, launch in headful mode:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
const browser = await puppeteer.launch({ headless: false });A visible browser can help diagnose which page opened or where an interaction failed, but it requires a graphical environment. Headless is generally the practical setting for unattended scripts and CI jobs; whether that environment can launch a browser also depends on its installed runtime and configuration.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Keep Puppeteer and its browser compatible
Puppeteer releases are paired with browser versions to maintain protocol compatibility. The supported-browser mapping changes over time, so check the supported browsers table for the Puppeteer version you install instead of relying on an old fixed version chart. The project says it has used Chrome for Testing beginning with Puppeteer v20.0.0 and stable Firefox beginning with v23.0.0. If a precise Puppeteer release is not listed, the support page advises using the browser version mapped to the immediately prior Puppeteer release.
A mismatch can surface as a launch or protocol error even when the script itself is valid. With puppeteer, let the package manage its compatible Chrome build unless you have a reason to override it. With puppeteer-core, take responsibility for selecting and maintaining the browser version.
Puppeteer and Selenium: choose by language and orchestration needs
Both projects contribute to WebDriver BiDi, so the useful distinction is not a blanket claim that one is always faster or more reliable. Puppeteer is a natural fit for JavaScript browser automation using its APIs and supported browser protocols. Selenium provides more language bindings and orchestration tooling such as Selenium Grid. If your team needs languages beyond JavaScript or Grid-style orchestration, those are concrete reasons to evaluate Selenium; if you need a JavaScript library and its browser-control workflow, Puppeteer may fit. The Puppeteer FAQ discusses BiDi, CDP, and the project’s scope.
Common setup and runtime problems
- “Could not find Chrome” or missing browser executable: an install script may have been blocked. Allow it or run
npx puppeteer browsers install. If usingpuppeteer-core, configure a browser executable or remote connection yourself. - Browser launches but protocol operations fail: check the Puppeteer-to-browser pairing in the supported-browser mapping; update or select a compatible browser rather than assuming any installed Chrome or Firefox will work.
- A locator times out or finds nothing: confirm the selector matches the live page, that navigation reached the expected state, and that the element is not inside a frame or hidden behind a flow your script has not completed. Inspect the page in headful mode or log the current URL and title to narrow down the failure.
- PDF looks unlike the page on screen: PDF generation uses print media by default. Call
page.emulateMediaType('screen')beforepage.pdf()if screen CSS is required. - Script exits with the browser still running: close the browser in a
finallyblock so exceptions do not leave a child process behind. - Headful launch fails on a server: the environment may not provide a display. Use the default headless mode for unattended runs, or provide the graphical environment required for visible mode.
Or skip the browser setup
If your goal is a website capture rather than browser interaction or UI testing, ScreenshotNeo offers a screenshot API and MCP server. One GET request returns a screenshot or PDF; its capture flow accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets, and you can turn each step off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with page verdict and billing details in response headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents.
Example cURL request (replace the target URL and API key):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://pptr.dev/ -o shot.webpSee the ScreenshotNeo API documentation for request options. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does Puppeteer support WebDriver BiDi?
Yes. Chrome automation uses CDP by default and can also use WebDriver BiDi; Firefox uses WebDriver BiDi by default. Consult the current Puppeteer FAQ for details.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesWill Puppeteer keep supporting CDP?
The project FAQ says Chrome CDP support will continue alongside Puppeteer’s support for WebDriver BiDi.
Is Puppeteer a replacement for Selenium?
Not categorically. The choice depends on language bindings, browser automation APIs, and whether you need orchestration tooling such as Selenium Grid.
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.
