Implementation:Puppeteer Puppeteer Package Install

Property	Value
sources	packages/puppeteer/src/node/install.ts
domains	Puppeteer Package, Browser Download, Installation
last_updated	2026-02-12 00:00 GMT

Overview

Description

The install module provides the downloadBrowsers function, which is Puppeteer's browser download orchestrator. It is invoked during the puppeteer npm package's postinstall script to automatically download the required browser binaries (Chrome, Chrome Headless Shell, and Firefox) to the local cache.

The module works as follows:

1. Proxy override -- The overrideProxy function checks for npm-configured proxy settings (npm_config_https_proxy, npm_config_http_proxy, npm_config_no_proxy) and applies them to the process environment variables (HTTPS_PROXY, HTTP_PROXY, NO_PROXY) so that the browser download respects npm proxy configuration.
2. Configuration loading -- Calls getConfiguration to load the merged configuration from files and environment variables.
3. Skip check -- If skipDownload is true globally, the entire download is skipped with an informational log.
4. Platform detection -- Uses @puppeteer/browsers detectBrowserPlatform to determine the current OS platform.
5. Per-browser download -- For each browser (Chrome, Chrome Headless Shell, Firefox), checks whether its download should be skipped based on per-browser configuration. For non-skipped browsers, calls the internal downloadBrowser function.
6. Build ID resolution -- downloadBrowser resolves the build ID from the configured version (or the default from PUPPETEER_REVISIONS) using @puppeteer/browsers resolveBuildId, then calls install to download the browser binary. A progress callback displays download progress. Build ID aliases are set when the resolved build ID differs from the configured version.
7. Logging -- The logPolitely function suppresses output when npm log level is 'silent', 'error', or 'warn'.

Usage

This module is executed as part of the puppeteer package's postinstall lifecycle script. Users do not typically call it directly, though it can be invoked programmatically.

Code Reference

Source Location

packages/puppeteer/src/node/install.ts

Signature

export async function downloadBrowsers(): Promise<void>;

Import

import {downloadBrowsers} from '../node/install.js';

I/O Contract

Input	Source	Description
Configuration	getConfiguration()	Merged Puppeteer configuration (file + env vars)
PUPPETEER_REVISIONS	puppeteer-core/internal/revisions	Default browser version mappings
npm_config_https_proxy	Environment	HTTPS proxy from npm config
npm_config_http_proxy	Environment	HTTP proxy from npm config
npm_config_no_proxy	Environment	No-proxy list from npm config
npm_config_loglevel	Environment	npm log level for output suppression

Output	Type	Description
Browser binaries	Files on disk	Downloaded browser executables in the cache directory
Console output	stdout	Progress and status messages (suppressed at warn/error/silent log levels)
Process exit	exit code 1	On fatal download errors

Usage Examples

// Programmatic invocation (normally called via postinstall)
import {downloadBrowsers} from 'puppeteer/node/install.js';

await downloadBrowsers();
// Downloads Chrome, Chrome Headless Shell, and Firefox (if not skipped)
// to ~/.cache/puppeteer (or configured cache directory)

// Controlling downloads via environment variables
// PUPPETEER_SKIP_DOWNLOAD=true        -- Skip all downloads
// PUPPETEER_CHROME_SKIP_DOWNLOAD=true -- Skip Chrome only
// PUPPETEER_CHROME_VERSION=120.0.6099.109 -- Download specific Chrome version
// PUPPETEER_CACHE_DIR=/custom/path    -- Use custom cache directory

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime