Skip to main content
Version: Next

Configuration

By default, Puppeteer downloads and uses a specific version of Chrome 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. See status of cross-browser support for more information.

All defaults in Puppeteer can be customized in two ways:

  1. Configuration files (recommended)
  2. Environment variables
caution

Note that some options are only customizable through environment variables (such as HTTPS_PROXY).

caution

Puppeteer's configuration files and environment variables are ignored by puppeteer-core.

Configuration files​

Configuration files are the recommended choice for configuring Puppeteer. Puppeteer will look up the file tree for any of the following formats:

  • package.json
  • .config/puppeteer.config.cjs
  • .config/puppeteer.config.js
  • .config/puppeteerrc.cjs
  • .config/puppeteerrc.js
  • .config/puppeteerrc.json
  • .config/puppeteerrc (JSON)
  • .puppeteerrc.cjs
  • .puppeteerrc.js
  • .puppeteerrc.json
  • .puppeteerrc (JSON)
  • puppeteer.config.cjs
  • puppeteer.config.js

See the Configuration interface for possible options.

Changing download options​

When the changes to the configuration include changes to download option, you will need to re-run postinstall scripts for them to take effect.

This can most easily be done with running:

npx puppeteer browsers install

Examples​

Downloading multiple browsers​

Starting with v23.0.0, Puppeteer allows downloading multiple browser without the need to run multiple commands.

Update the Puppeteer configuration file:

project-directory/.puppeteerrc.js
/**
 * @type {import("puppeteer").Configuration}
 */
export default {
  // Download Chrome (default `skipDownload: false`).
  chrome: {
    skipDownload: false,
  },
  // Download Firefox (default `skipDownload: true`).
  firefox: {
    skipDownload: false,
  },
};

Run CLI to download the new configuration:

npx puppeteer browsers install

Changing the default cache directory​

Starting in v19.0.0, Puppeteer stores browsers in ~/.cache/puppeteer to globally cache browsers between installation. This can cause problems if puppeteer is packed during some build step and moved to a fresh location. The following configuration can solve this issue (reinstall puppeteer to take effect):

project-directory/.puppeteerrc.js
import {join} from 'path';

/**
 * @type {import("puppeteer").Configuration}
 */
export default {
  // Changes the cache location for Puppeteer.
  cacheDirectory: join(import.meta.dirname, '.cache', 'puppeteer'),
};

Environment variables​

Along with configuration files, Puppeteer looks for certain environment variables for customizing behavior. Environment variables will always override configuration file options when applicable.

The following options are environment-only options

  • HTTP_PROXY, HTTPS_PROXY, NO_PROXY - defines HTTP proxy settings that are used to download and run the browser.
note

To use a proxy for downloading browsers, you must have the proxy-agent package installed as an optional peer dependency.

All other options can be found in the documentation for the Configuration interface.

Custom certificates​

Browsers are downloaded using the Node.js HTTPS client, so the standard Node.js TLS environment variables apply. This is useful if downloads go through a corporate proxy or mirror that uses a custom certificate authority (CA):

  • NODE_EXTRA_CA_CERTS - path to a PEM file with additional CA certificates to trust, for example NODE_EXTRA_CA_CERTS=/path/to/ca.pem npm install puppeteer.
  • NODE_TLS_REJECT_UNAUTHORIZED=0 - disables certificate verification entirely. This is insecure and should only be used as a last resort.
note

By default, Node.js does not read SSL_CERT_FILE or SSL_CERT_DIR, so setting them has no effect on browser downloads.