Environment:Puppeteer Puppeteer Configuration Environment Variables

Knowledge Sources	Puppeteer Puppeteer Configuration
Domains	Infrastructure, Configuration
Last Updated	2026-02-11 23:30 GMT

Overview

Environment variables and cosmiconfig-based configuration system controlling Puppeteer browser downloads, executable paths, cache directories, and logging.

Description

Puppeteer resolves configuration through a layered system: environment variables take highest priority, followed by cosmiconfig-based configuration files (`.puppeteerrc.cjs`, `puppeteer.config.cjs`, etc.), followed by built-in defaults. The configuration controls which browsers are downloaded, where they are cached, custom download URLs, and runtime behavior. Boolean environment variables accept ``, `'0'`, `'false'`, `'off'` as falsy; all other values are truthy.

Usage

Configure this environment when you need to customize Puppeteer behavior, such as pointing to a custom browser binary, skipping browser downloads in CI, using a proxy for downloads, or changing the cache directory.

System Requirements

Category	Requirement	Notes
Runtime	Node.js >= 18	Required for `process.env` access
Config	cosmiconfig >= 9.0.0	Searches for `.puppeteerrc.*` files globally

Dependencies

Configuration Loading

`cosmiconfig` >= 9.0.0 — Searches for configuration files using `searchStrategy: 'global'`

Credentials

The following environment variables control Puppeteer behavior. None contain secrets by default, but custom download URLs may require authentication:

General Configuration

`PUPPETEER_BROWSER` — Default browser to use (`chrome` or `firefox`). Default: `chrome`
`PUPPETEER_EXECUTABLE_PATH` — Override browser executable path. Setting this automatically sets `skipDownload: true`
`PUPPETEER_CACHE_DIR` — Cache directory for downloaded browsers. Default: `~/.cache/puppeteer`
`PUPPETEER_TMP_DIR` — Temporary directory for operations
`PUPPETEER_LOGLEVEL` — Log level: `silent`, `error`, or `warn` (default)
`PUPPETEER_SKIP_DOWNLOAD` — Skip all browser downloads (boolean)

Per-Browser Configuration

`PUPPETEER_CHROME_VERSION` — Chrome version to download
`PUPPETEER_CHROME_DOWNLOAD_BASE_URL` — Custom Chrome download URL
`PUPPETEER_CHROME_SKIP_DOWNLOAD` — Skip Chrome download (boolean)
`PUPPETEER_SKIP_CHROME_DOWNLOAD` — Alternative skip Chrome download (boolean)
`PUPPETEER_CHROME_HEADLESS_SHELL_VERSION` — Chrome Headless Shell version
`PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL` — Custom Headless Shell URL
`PUPPETEER_CHROME_HEADLESS_SHELL_SKIP_DOWNLOAD` — Skip Headless Shell download
`PUPPETEER_FIREFOX_VERSION` — Firefox version to download
`PUPPETEER_FIREFOX_DOWNLOAD_BASE_URL` — Custom Firefox download URL
`PUPPETEER_FIREFOX_SKIP_DOWNLOAD` — Skip Firefox download (boolean)

Testing/Internal Variables

`PUPPETEER_TEST_EXPERIMENTAL_CHROME_FEATURES` — Enable experimental Chrome features (testing only)
`PUPPETEER_WEBDRIVER_BIDI_ONLY` — Force WebDriver BiDi protocol only

System Location Variables (used internally)

`LOCALAPPDATA` — Windows local app data directory
`PROGRAMFILES`, `ProgramW6432`, `ProgramFiles(x86)` — Windows program directories
`CHROME_CONFIG_HOME` — Linux custom Chrome config directory
`XDG_CONFIG_HOME` — Linux XDG config directory

Quick Install

# Skip browser download (e.g., in CI where browser is pre-installed)
PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteer

# Use custom browser path
PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome node script.js

# Custom cache directory
PUPPETEER_CACHE_DIR=/opt/browsers npm install puppeteer

# Use Firefox instead of Chrome
PUPPETEER_BROWSER=firefox npm install puppeteer

Code Evidence

Configuration resolution from `packages/puppeteer/src/getConfiguration.ts:118-166`:

export const getConfiguration = (): Configuration => {
  const result = cosmiconfigSync('puppeteer', {
    searchStrategy: 'global',
  }).search();
  const configuration: Configuration = result ? {...result.config} : {};

  configuration.logLevel = getLogLevel(
    process.env['PUPPETEER_LOGLEVEL'] ?? configuration.logLevel,
  );
  configuration.defaultBrowser = getDefaultBrowser(
    process.env['PUPPETEER_BROWSER'] ?? configuration.defaultBrowser,
  );
  configuration.executablePath =
    process.env['PUPPETEER_EXECUTABLE_PATH'] ?? configuration.executablePath;

  // Default to skipDownload if executablePath is set
  if (configuration.executablePath) {
    configuration.skipDownload = true;
  }
  configuration.cacheDirectory =
    process.env['PUPPETEER_CACHE_DIR'] ??
    configuration.cacheDirectory ??
    join(homedir(), '.cache', 'puppeteer');
};

Boolean env var parsing from `packages/puppeteer/src/getConfiguration.ts:19-33`:

function getBooleanEnvVar(name: string): boolean | undefined {
  const env = process.env[name];
  if (env === undefined) {
    return;
  }
  switch (env.toLowerCase()) {
    case '':
    case '0':
    case 'false':
    case 'off':
      return false;
    default:
      return true;
  }
}

Per-browser setting resolution from `packages/puppeteer/src/getConfiguration.ts:78-113`:

function getBrowserSetting(browser, configuration, defaultConfig = {}) {
  const browserEnvName = browser.replaceAll('-', '_').toUpperCase();
  browserSetting.version =
    process.env[`PUPPETEER_${browserEnvName}_VERSION`] ??
    configuration[browser]?.version ??
    defaultConfig.version;
  browserSetting.downloadBaseUrl =
    process.env[`PUPPETEER_${browserEnvName}_DOWNLOAD_BASE_URL`] ??
    configuration[browser]?.downloadBaseUrl ??
    defaultConfig.downloadBaseUrl;
  browserSetting.skipDownload =
    getBooleanEnvVar(`PUPPETEER_${browserEnvName}_SKIP_DOWNLOAD`) ??
    getBooleanEnvVar(`PUPPETEER_SKIP_${browserEnvName}_DOWNLOAD`) ??
    configuration[browser]?.skipDownload ??
    defaultConfig.skipDownload;
}

Common Errors

Error Message	Cause	Solution
`Unsupported browser {name}`	Invalid `PUPPETEER_BROWSER` value	Use `chrome` or `firefox`
`An executablePath must be specified for puppeteer-core`	Using puppeteer-core without specifying path	Set `PUPPETEER_EXECUTABLE_PATH` or pass `executablePath` in launch options
Browser download fails silently	`PUPPETEER_SKIP_DOWNLOAD` set unexpectedly	Check env vars; `PUPPETEER_EXECUTABLE_PATH` auto-sets skip

Compatibility Notes

Config File Priority: cosmiconfig searches globally for `.puppeteerrc.cjs`, `.puppeteerrc.js`, `.puppeteerrc.json`, `puppeteer.config.cjs`, etc. Environment variables always override config file values.
Boolean Parsing: Empty string, `'0'`, `'false'`, `'off'` are all treated as false. Any other value is truthy.
Firefox Default: Firefox download is skipped by default (`skipDownload: true`). Set `PUPPETEER_FIREFOX_SKIP_DOWNLOAD=false` to enable.
Cache Directory: Default `~/.cache/puppeteer`. In Docker, set to a writable directory for the container user.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment