Puppeteer quick start

Installation

To use Puppeteer in your project, run:

npm i puppeteer
# or "yarn add puppeteer"

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.

Example: 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().

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

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