Heuristic:Puppeteer Puppeteer Mac Silicon Performance
| Knowledge Sources | |
|---|---|
| Domains | Performance, Cross_Platform |
| Last Updated | 2026-02-11 23:30 GMT |
Overview
Running x64 Node.js on Apple Silicon Macs causes Rosetta translation of the Chrome binary, resulting in severe performance degradation. Use arm64 Node.js instead.
Description
When Node.js is running under Rosetta 2 translation on Apple Silicon (M1/M2/M3/M4 Macs), Puppeteer detects this condition and emits a console warning. The issue occurs because even though Chrome for Testing provides native arm64 binaries, the entire process tree inherits the architecture of the parent Node.js process. This means an x64 Node.js process will force Chrome to also run through Rosetta, causing significant performance overhead.
Usage
Apply this heuristic when experiencing slow Chrome automation on Apple Silicon Macs. Symptoms include: slow page loads, high CPU usage, sluggish screenshot/PDF generation, and timeout errors that do not occur on x64 Linux or on native arm64 setups.
The Insight (Rule of Thumb)
- Action: Install and use arm64 Node.js on Apple Silicon Macs. Verify with `node -p "process.arch"` — it should output `arm64`, not `x64`.
- Value: Eliminates Rosetta translation overhead for both Node.js and Chrome processes.
- Trade-off: Some npm packages may not have arm64 native binaries; most do as of 2024+.
- Detection: Puppeteer automatically checks for this condition by examining `process.platform === 'darwin'`, `process.arch === 'x64'`, and `os.cpus()[0].model.includes('Apple')`.
Reasoning
Rosetta 2 translates x64 instructions to ARM instructions at runtime. While functionally transparent, this adds significant CPU overhead, particularly for compute-intensive operations like rendering web pages, processing JavaScript, and encoding screenshots/PDFs.
From `packages/puppeteer-core/src/node/ChromeLauncher.ts:38-56`:
override launch(options: LaunchOptions = {}): Promise<Browser> {
if (
this.puppeteer.configuration.logLevel === 'warn' &&
process.platform === 'darwin' &&
process.arch === 'x64'
) {
const cpus = os.cpus();
if (cpus[0]?.model.includes('Apple')) {
console.warn(
[
'\x1B[1m\x1B[43m\x1B[30m',
'Degraded performance warning:\x1B[0m\x1B[33m',
'Launching Chrome on Mac Silicon (arm64) from an x64 Node installation results in',
'Rosetta translating the Chrome binary, even if Chrome is already arm64. This would',
'result in huge performance issues. To resolve this, you must run Puppeteer with',
'a version of Node built for arm64.',
].join('\n '),
);
}
}
return super.launch(options);
}