Puppeteer quick start

To use Puppeteer in your project, you must first install it.

Installation

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. This version of Puppeteer 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 versus puppeteer-core.

Usage

Puppeteer follows the latest maintenance LTS version of Node.

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

Save a screenshot

For example, to navigate to https://example.com and save a screenshot as example.png, save the following code to 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().

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.

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 Evaluate JavaScript 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.

For more information:

Creates a fresh user profile

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

Next steps