Configuration

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:

• .puppeteerrc.cjs,
• .puppeteerrc.js,
• .puppeteerrc (YAML/JSON),
• .puppeteerrc.json,
• .puppeteerrc.yaml,
• puppeteer.config.js, and
• puppeteer.config.cjs

Puppeteer will also read a puppeteer key from your application's package.json.

See the Configuration interface for possible options.

caution

After adding a configuration file, you may need to remove and reinstall puppeteer for it to take effect if the changes affect installation.

Examples

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

const {join} = require('path');

/**
 * @type {import("puppeteer").Configuration}
 */
module.exports = {
  // Changes the cache location for Puppeteer.
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};

note

Notice this is only possible with CommonJS configuration files as information about the ambient environment is needed (in this case, __dirname).

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.

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