Implementation:Puppeteer Puppeteer GetConfiguration

Property	Value
sources	packages/puppeteer/src/getConfiguration.ts
domains	Configuration, Puppeteer Package
last_updated	2026-02-12 00:00 GMT

Overview

Description

The getConfiguration function is the central configuration resolver for the puppeteer npm package. It loads, merges, and validates configuration from multiple sources: a cosmiconfig-based configuration file (searched globally under the name puppeteer), environment variables, and sensible defaults.

The configuration resolution follows a layered precedence model where environment variables override file-based configuration, which in turn overrides defaults:

1. File-based configuration -- Loaded using cosmiconfigSync with a global search strategy. This supports .puppeteerrc.cjs, puppeteer.config.cjs, or a puppeteer key in package.json.
2. Environment variables -- Override specific properties:
   • PUPPETEER_BROWSER -- Sets the default browser ('chrome' or 'firefox').
   • PUPPETEER_EXECUTABLE_PATH -- Sets a custom browser executable path (also sets skipDownload: true).
   • PUPPETEER_SKIP_DOWNLOAD -- Skips all browser downloads.
   • PUPPETEER_CACHE_DIR -- Sets the cache directory (default: ~/.cache/puppeteer).
   • PUPPETEER_TMP_DIR -- Sets the temporary directory.
   • PUPPETEER_LOGLEVEL -- Sets log level ('silent', 'error', 'warn').
   • Browser-specific variables like PUPPETEER_CHROME_VERSION, PUPPETEER_CHROME_SKIP_DOWNLOAD, etc.
3. Defaults -- Default browser is 'chrome', default log level is 'warn', default cache directory is ~/.cache/puppeteer, Firefox download is skipped by default.

The module also contains helper functions: getBooleanEnvVar for parsing boolean environment variables, isSupportedBrowser for validation, getDefaultBrowser for browser resolution, getLogLevel for log level normalization, and getBrowserSetting for per-browser download configuration.

Usage

getConfiguration is called during Puppeteer initialization and during the browser installation postinstall script. It returns the fully resolved Configuration object used throughout Puppeteer.

Code Reference

Source Location

packages/puppeteer/src/getConfiguration.ts

Signature

export const getConfiguration = (): Configuration;

Import

import {getConfiguration} from '../getConfiguration.js';

I/O Contract

Input Source	Type	Description
Cosmiconfig file	Configuration	File-based configuration (e.g., .puppeteerrc.cjs)
PUPPETEER_BROWSER	string	Environment variable for default browser
PUPPETEER_EXECUTABLE_PATH	string	Environment variable for custom executable path
PUPPETEER_SKIP_DOWNLOAD	string	Boolean env var to skip all browser downloads
PUPPETEER_CACHE_DIR	string	Environment variable for cache directory
PUPPETEER_TMP_DIR	string	Environment variable for temporary directory
PUPPETEER_LOGLEVEL	string	Environment variable for log level

Output Property	Type	Default	Description
defaultBrowser	SupportedBrowser	'chrome'	The browser to launch by default
executablePath	undefined	--	Custom browser executable path
skipDownload	undefined	--	Whether to skip downloading browsers
cacheDirectory	string	~/.cache/puppeteer	Directory for caching browser binaries
temporaryDirectory	undefined	--	Directory for temporary files
logLevel	'error' | 'warn'	'warn'	Logging verbosity
chrome	ChromeSettings	--	Chrome-specific download settings
chrome-headless-shell	ChromeHeadlessShellSettings	--	Chrome headless shell settings
firefox	FirefoxSettings	{skipDownload: true}	Firefox-specific download settings
experiments	object	{}	Experimental feature flags

Usage Examples

import {getConfiguration} from '../getConfiguration.js';

const config = getConfiguration();

console.log(config.defaultBrowser);   // 'chrome'
console.log(config.cacheDirectory);   // '/home/user/.cache/puppeteer'
console.log(config.logLevel);         // 'warn'

// Configuration via environment variables
// PUPPETEER_BROWSER=firefox
// PUPPETEER_CACHE_DIR=/custom/cache
// PUPPETEER_SKIP_DOWNLOAD=true

const config = getConfiguration();
console.log(config.defaultBrowser);   // 'firefox'
console.log(config.cacheDirectory);   // '/custom/cache'
console.log(config.skipDownload);     // true

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime