To stop Puppeteer from downloading its bundled browser, install Chromium separately and use puppeteer-core, or keep puppeteer and set its browser download to skip. Either way, supply the installed browser’s actual executable path when launching. Skipping the download does not install Chromium, and Puppeteer does not guarantee compatibility with arbitrary system Chromium versions.
Choose how Puppeteer should handle the browser
The default puppeteer package downloads Chrome for Testing during installation. Its installation guide also describes downloading a chrome-headless-shell binary. If you want to manage the browser yourself, there are two routes:
As an Amazon Associate I earn from qualifying purchases.
| Choice | What it does | Use it when |
|---|---|---|
puppeteer-core |
Does not download Chrome; browser management is left to your project. | You want to control browser installation and version explicitly. |
puppeteer with downloads skipped |
Keeps the regular package but prevents its automatic browser download. | You want the full package while supplying your own browser executable. |
Both options require a browser installed separately and selected at launch. Puppeteer’s installation guide explains the package distinction.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Install Chromium outside Puppeteer
Install Chromium through the operating system’s package manager or include it in your deployment image. The package name and executable path depend on the operating system, distribution, and installation method; do not assume a single path works everywhere. Confirm the executable on the machine or container where Puppeteer will run.
#1 Best Overall
For Linux, the Puppeteer troubleshooting guide uses /usr/bin/chromium-browser as an example of an existing Chromium path, not as a universal default. Linux launches can also fail when shared-library dependencies are missing. The guide cautions that Chrome does not support Alpine out of the box. See Puppeteer troubleshooting for platform-specific dependency guidance.
Option 1: use puppeteer-core
Install the core package rather than the default package:
npm install puppeteer-coreThen provide the real Chromium path. This runnable example expects PUPPETEER_EXECUTABLE_PATH to be set to that path in the runtime environment.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteimport puppeteer from 'puppeteer-core';
const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
if (!executablePath) {
throw new Error('Set PUPPETEER_EXECUTABLE_PATH to the installed Chromium executable');
}
const browser = await puppeteer.launch({
executablePath,
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}Alternatively, the launch API accepts a supported Chrome channel; for a separately installed Chromium binary, an explicit executablePath is usually the clearest choice. puppeteer-core is driven through its programmatic interface: do not rely on the full package’s configuration files or environment defaults to select the browser. See the launch API.
Option 2: keep puppeteer and skip its download
Set an environment variable
Set PUPPETEER_SKIP_DOWNLOAD=true during installation. For example, in a POSIX shell:
PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteerIn CI or a deployment system, configure the same variable in the environment used for the package installation. It prevents the automatic browser download; it does not install Chromium for you.
Set Puppeteer configuration
Alternatively, add a project configuration file such as .puppeteerrc.js:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →export default {
chrome: { skipDownload: true },
};Puppeteer’s configuration interface defines skipDownload and notes that environment variables can override configuration. If you change download configuration, run your project’s install workflow so the setting applies. The configuration API also documents browser-specific skip settings and executablePath: configuration interface.
At launch, select the separately installed browser rather than relying on Puppeteer to find it:
Rank #4
import puppeteer from 'puppeteer';
const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
if (!executablePath) {
throw new Error('Set PUPPETEER_EXECUTABLE_PATH to the installed Chromium executable');
}
const browser = await puppeteer.launch({
executablePath,
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}Check compatibility and platform requirements
Puppeteer says it works best with the Chrome for Testing version it downloads by default and does not guarantee it will work with another browser version. System Chromium can be a valid choice, but test the exact Puppeteer and Chromium versions together, including the page behavior your application depends on. The compatibility warning is in the launch documentation.
Requirements are version-sensitive. Puppeteer’s current system requirements page, which identifies documentation version 25.12.0, lists Node 22.12+ and Chrome for Testing support for Windows x64, macOS x64/arm64, Debian/Ubuntu Linux x64/arm64, and openSUSE/Fedora Linux x64/arm64. These describe the documented Chrome for Testing support matrix, not a promise that every system Chromium build is supported. Check the system requirements for the Puppeteer version you install.
Free tools Windows power users keep installed
One-click scans. No signup required.
Understand the download and deployment trade-off
Skipping Puppeteer’s browser download avoids that installation-time transfer, but makes browser provisioning your responsibility. You must ensure the executable exists in each runtime environment, its OS dependencies are present, and upgrades remain compatible with your Puppeteer version. Conversely, the bundled Chrome for Testing is the browser version against which Puppeteer’s compatibility guarantee is made.
Puppeteer’s installation guide gives approximate default browser download sizes of about 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows. They are guide estimates, not fixed sizes for every release or network transfer. See the installation guide. If you want to manage browser binaries with Puppeteer’s browser tooling, review its browser management API and provider caveats.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common failures
- Puppeteer still downloads a browser: confirm
PUPPETEER_SKIP_DOWNLOAD=trueis set in the environment during installation, or that the configuration file is in the project and the install workflow was rerun. Check for an environment override. - Launch reports a missing executable: verify the path exists in the actual runtime (including inside the container), is executable, and points to the browser binary rather than a directory or unrelated wrapper. Set
executablePathto that confirmed path. - Chromium exists but will not start on Linux: inspect launch output and install the distribution’s missing shared-library dependencies. The required libraries vary by OS and image; consult the troubleshooting guide. Alpine needs particular care because Chrome is not supported there out of the box.
- Browser starts but automation behaves incorrectly: check the Chromium and Puppeteer versions together and test the features your app uses. Puppeteer’s compatibility guarantee is for its bundled browser, not arbitrary system Chromium.
- Configuration appears ignored: verify the package is
puppeteer, notpuppeteer-core, which does not apply Puppeteer configuration files in the same way. Confirm the configuration is being read during installation and that environment settings are not overriding it.
Or skip the browser setup
If your actual task is to capture a website screenshot or PDF rather than automate a local browser, ScreenshotNeo provides a screenshot API and MCP server. A single GET request can return an image or PDF without installing Chromium in your project. Its options include full-page captures, CSS-selector element capture, device and viewport settings, PDF controls, waits, custom headers and cookies, request blocking, caching, and bulk capture.
Example cURL request (replace the target URL and API key):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request parameters. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Does PUPPETEER_SKIP_DOWNLOAD install Chromium?
No. It only prevents Puppeteer’s automatic browser download; install Chromium separately and point Puppeteer to it.
Can I use Google Chrome instead of Chromium?
Puppeteer’s launch API can select a supported Chrome channel or an executable path. The compatibility guarantee applies to Puppeteer’s bundled browser, so test any independently installed browser version.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
