Skip to main content
Version: Next


All defaults in Puppeteer can be customized in two ways:

  1. Configuration files (recommended)
  2. Environment variables

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


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.


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


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):

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

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

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.