Puppeteer quick start
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
- Learn more about Headless Chrome.
- Look over the examples.