Puppeteer quick start

Published on Updated on

Installation

To use Puppeteer in your project, run:

npm i puppeteer
# or "yarn add puppeteer"

When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, download into another path, or download a different browser, see Environment variables.

puppeteer-core

Since version 1.7.0 we publish the puppeteer-core package, a version of Puppeteer that doesn't download any browser by default.

npm i puppeteer-core
# or "yarn add puppeteer-core"

puppeteer-core is intended to be a lightweight version of Puppeteer for launching an existing browser installation or for connecting to a remote one. Be sure that the version of puppeteer-core you install is compatible with the browser you intend to connect to.

See puppeteer vs puppeteer-core.

Usage

Puppeteer follows the latest maintenance LTS version of Node.

Prior to v1.18.1, Puppeteer required at least Node v6.4.0. Versions from v1.18.1 to v2.1.0 rely on Node 8.9.0+. Starting from v3.0.0 Puppeteer starts to rely on Node 10.18.1+. All examples below use async/await which is only supported in Node v7.6.0 or greater.

Puppeteer will be familiar to people using other browser testing frameworks. You create an instance of Browser, open pages, and then manipulate them with Puppeteer's API.

Example: navigating to https://example.com and saving a screenshot as example.png:

Save file as example.js.

const puppeteer = require('puppeteer');

(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'example.png' });

await browser.close();
})();

Puppeteer sets an initial page size to 800×600px, which defines the screenshot size. The page size can be customized with Page.setViewport().

Example: create a PDF.

Save file as hn.js.

const puppeteer = require('puppeteer');

(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com', {
waitUntil: 'networkidle2',
});
await page.pdf({ path: 'hn.pdf', format: 'a4' });

await browser.close();
})();

Execute script on the command line:

node hn.js

See Page.pdf() for more information about creating pdfs.

Example: evaluate script in the context of the page

Save file as get-dimensions.js:

const puppeteer = require('puppeteer');

(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

// Get the "viewport" of the page, as reported by the page.
const dimensions = await page.evaluate(() => {
return {
width: document.documentElement.clientWidth,
height: document.documentElement.clientHeight,
deviceScaleFactor: window.devicePixelRatio,
};
});

console.log('Dimensions:', dimensions);

await browser.close();
})();

Execute script on the command line:

node get-dimensions.js

See Page.evaluate() for more information on evaluate and related methods such as evaluateOnNewDocument and exposeFunction.

Default runtime settings

Uses Headless mode

Puppeteer launches Chromium in headless mode. To launch a full version of Chromium, set the headless option when launching a browser:

const browser = await puppeteer.launch({ headless: false }); // default is true

Runs a bundled version of Chromium

By default, Puppeteer downloads and uses a specific version of Chromium so its API is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome or Chromium, pass in the executable's path when creating a Browser instance:

const browser = await puppeteer.launch({ executablePath: '/path/to/Chrome' });

You can also use Puppeteer with Firefox Nightly (experimental support). See Puppeteer.launch() for more information.

See this article for a description of the differences between Chromium and Chrome. This article describes some differences for Linux users.

Creates a fresh user profile

Puppeteer creates its own browser user profile which it cleans up on every run.

Next steps

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.