Workflow:Puppeteer Puppeteer Browser Installation And Management
| Knowledge Sources | |
|---|---|
| Domains | Browser_Management, DevOps, CI_CD |
| Last Updated | 2026-02-11 23:30 GMT |
Overview
End-to-end process for downloading, installing, caching, and launching browser binaries using the @puppeteer/browsers package.
Description
This workflow covers the standard procedure for managing browser binaries outside of Puppeteer's default auto-download behavior. The @puppeteer/browsers package provides both a CLI and programmatic API for downloading specific browser versions (Chrome, Chrome Headless Shell, Chromium, Firefox, ChromeDriver), managing a local cache of installed browsers, resolving version identifiers to concrete build numbers, and launching browser processes with configurable arguments. This workflow is essential for CI/CD environments, Docker containers, and scenarios requiring precise control over which browser version is used.
Usage
Execute this workflow when you need explicit control over browser binary management. Common scenarios include: setting up browsers in CI/CD pipelines, building Docker images with pre-installed browsers, managing multiple browser versions for testing across versions, downloading browsers for offline environments, cleaning up unused browser installations, or using browsers independently of the Puppeteer automation library.
Execution Steps
Step 1: Detect Platform
Identify the current operating system and architecture to determine the correct browser binary to download. The package automatically detects the platform (linux, darwin, win32/win64) and architecture (x64, arm64) but this can be overridden for cross-platform downloads.
Key considerations:
- Supported platforms: linux64, mac, mac_arm, win32, win64
- Apple Silicon (arm64) is detected and uses native arm builds where available
- Platform detection can be overridden in the install options
Step 2: Resolve Browser Version
Translate a version identifier (channel name, milestone, or specific version) into a concrete build identifier that can be downloaded. For Chrome, this uses the Chrome for Testing version API to resolve channel names (stable, beta, canary, dev) or milestones (e.g., "120") to specific version strings.
Key considerations:
- Chrome channels: stable, beta, dev, canary resolve to the latest version in that channel
- Chrome milestones (e.g., "120") resolve to the latest version in that milestone
- Firefox versions use direct version strings
- Chromium uses revision numbers from the build infrastructure
Step 3: Download Browser Binary
Download the browser archive from the appropriate source (Chrome for Testing endpoints, Mozilla archives, Chromium build storage). The download includes progress tracking and can use custom download functions or proxy configurations. Archives are stored in a local cache directory organized by browser, platform, and version.
Key considerations:
- Default cache directory is platform-specific (e.g., ~/.cache/puppeteer on Linux)
- Custom cache directories can be specified for isolated environments
- Download progress is reported via an optional callback
- Base download URL can be overridden for enterprise mirror servers
- Custom BrowserProvider implementations can supply alternative download sources
Step 4: Extract And Cache
Extract the downloaded archive (ZIP, DMG, or tar.bz2 depending on platform) into the cache directory. The cache uses a structured directory layout: {cacheDir}/{browser}/{platform}-{buildId}/. Metadata about the installation is recorded for later listing and management.
Key considerations:
- Archives are automatically extracted after download
- The executable path within the extracted archive is browser and platform-specific
- Cache directory structure allows multiple versions of the same browser to coexist
- Metadata tracking enables listing all installed browsers and their sizes
Step 5: Launch Browser Process
Start the installed browser as a child process with configurable command-line arguments. The launcher resolves the executable path from the cache, constructs the appropriate command line, and manages the process lifecycle including stdout/stderr piping and graceful shutdown.
Key considerations:
- The launch function returns a Process object with stdin/stdout/stderr access
- Browser-specific arguments are supported (Chrome flags, Firefox preferences)
- A WebSocket debugging endpoint is often required for protocol connections
- The process can be detached from the parent for long-running scenarios
Step 6: Manage Cache
List, inspect, and clean up installed browser binaries. The cache management API provides methods to enumerate all installed browsers, get installation metadata (size, path, build ID), and uninstall specific versions to reclaim disk space.
Key considerations:
- The CLI provides list, clear, and uninstall commands
- Programmatic API offers getInstalledBrowsers() and uninstall() methods
- Cache cleanup is important in CI environments to manage disk space
- Uninstall removes the extracted files and updates metadata