Environment:Puppeteer Puppeteer Cross Platform Browser Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Browser_Automation, Cross_Platform |
| Last Updated | 2026-02-11 23:30 GMT |
Overview
Cross-platform environment supporting Linux (x64/arm64), macOS (x64/arm64), and Windows (x64/arm64 on Win11) for Chrome and Firefox browser automation.
Description
Puppeteer supports six platform targets for browser binary downloads: Linux x64, Linux arm64, macOS x64, macOS arm64, Windows 32-bit, and Windows 64-bit. Platform detection is automatic via `detectBrowserPlatform()`. Chrome for Testing and Firefox binaries are downloaded per-platform from Google and Mozilla CDNs respectively. On Linux, additional system dependencies (fonts, D-Bus) are required for Chrome to render correctly.
Usage
This environment defines the platform-level requirements for running Puppeteer with a downloaded browser. It is the mandatory prerequisite for the Browser_Installation_And_Management workflow, the PuppeteerNode_Launch implementation, and all browser-interaction workflows.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS (Linux) | Debian/Ubuntu or RHEL/Fedora x64/arm64 | System deps via `--install-deps` flag |
| OS (macOS) | macOS x64 or arm64 (Apple Silicon) | arm64 Node.js recommended on M-series |
| OS (Windows) | Windows x64, or arm64 on Windows 11+ | Win11 ARM supports x64 emulation |
| Browser | Chrome 145.0.7632.46 (pinned) | Auto-downloaded by Puppeteer |
| Browser | Firefox stable 147.0.3 (pinned) | Opt-in, skipped by default |
| Disk | ~500MB per browser | Chrome for Testing download + extraction |
Linux System Dependencies
On Debian/Ubuntu, Chrome requires system fonts and libraries:
- `fonts-ipafont-gothic` — Japanese fonts
- `fonts-wqy-zenhei` — Chinese fonts
- `fonts-thai-tlwg` — Thai fonts
- `fonts-khmeros` — Khmer fonts
- `fonts-kacst` — Arabic fonts
- `fonts-freefont-ttf` — General fonts
- `dbus`, `dbus-x11` — D-Bus session for Chrome IPC
- X server or `xvfb-run` for headful mode
Dependencies
Browser Binaries
- Chrome for Testing `145.0.7632.46` — Primary automation target
- Chrome Headless Shell `145.0.7632.46` — Lightweight headless variant
- Firefox `stable_147.0.3` — Cross-browser testing target
Archive Utilities
- `extract-zip` >= 2.0.1 — Extracts Chrome .zip archives
- `tar-fs` >= 3.1.1 — Extracts Firefox .tar.bz2/.tar.xz archives
- Linux: `xz` or `bzip2` required to unpack Firefox
Credentials
No credentials required for browser download from default CDN sources.
Quick Install
# Install Puppeteer (auto-downloads Chrome)
npm install puppeteer
# Install system dependencies on Debian/Ubuntu (requires root)
npx puppeteer browsers install chrome --install-deps
# Install Firefox browser
npx puppeteer browsers install firefox
# Docker setup
docker pull ghcr.io/puppeteer/puppeteer
Code Evidence
Platform detection from `packages/browsers/src/detectPlatform.ts:14-32`:
export function detectBrowserPlatform(): BrowserPlatform | undefined {
const platform = os.platform();
const arch = os.arch();
switch (platform) {
case 'darwin':
return arch === 'arm64' ? BrowserPlatform.MAC_ARM : BrowserPlatform.MAC;
case 'linux':
return arch === 'arm64'
? BrowserPlatform.LINUX_ARM
: BrowserPlatform.LINUX;
case 'win32':
return arch === 'x64' ||
(arch === 'arm64' && isWindows11(os.release()))
? BrowserPlatform.WIN64
: BrowserPlatform.WIN32;
default:
return undefined;
}
}
Windows 11 ARM64 detection from `packages/browsers/src/detectPlatform.ts:39-52`:
function isWindows11(version: string): boolean {
const parts = version.split('.');
if (parts.length > 2) {
const major = parseInt(parts[0] as string, 10);
const minor = parseInt(parts[1] as string, 10);
const patch = parseInt(parts[2] as string, 10);
return (
major > 10 ||
(major === 10 && minor > 0) ||
(major === 10 && minor === 0 && patch >= 22000)
);
}
return false;
}
Missing X server detection from `packages/puppeteer-core/src/node/BrowserLauncher.ts:240-243`:
if (logs.includes('Missing X server') && options.headless === false) {
throw new Error(
'Missing X server to start the headful browser. Either set headless to true or use xvfb-run.'
);
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Missing X server to start the headful browser` | No display server on Linux | Set `headless: true` or use `xvfb-run` |
| `The browser is already running for {userDataDir}` | Browser lockfile exists | Use different `userDataDir` or stop existing browser |
| `Cannot find browser binary` | Browser not downloaded | Run `npx puppeteer browsers install chrome` |
| Platform detection returns `undefined` | Unsupported OS (e.g., FreeBSD) | Use `executablePath` to specify browser manually |
Compatibility Notes
- macOS ARM64: Running x64 Node.js on Apple Silicon causes Rosetta translation overhead for Chrome. Use arm64 Node.js for best performance.
- Windows ARM64: Supported only on Windows 11 (version 10.0.22000+) via x64 emulation.
- Linux ARM64: Supported for both Chrome and Firefox.
- Alpine Linux 3.20: Known Chromium timeout issues. Use Alpine 3.19 instead (see Puppeteer issues #11640, #12637).
- Docker: Official image based on `node:24-bookworm` with system dependencies pre-installed. Uses non-root user (UID 10042).
- Firefox Archive Format: Firefox 135+ uses `xz` compression; older versions use `bz2`.