To stop Puppeteer downloading its own Chrome, install Chromium separately, then use either puppeteer-core or the regular puppeteer package with browser downloads disabled. In both cases, pass Chromium’s actual executable path to launch(). Disabling the download does not install Chromium for you.
Choose how Puppeteer should handle the browser
Puppeteer’s regular puppeteer package downloads Chrome for Testing and a chrome-headless-shell binary by default. To manage a system Chromium yourself, you can either use puppeteer-core, which does not download a browser, or keep puppeteer and turn off its download. The Puppeteer installation guide describes both workflows.
| Choice | Browser download | Configuration | Best fit |
|---|---|---|---|
puppeteer-core |
Does not download Chrome. | Supply the browser executable path or a supported Chrome channel when launching. It does not use Puppeteer configuration files or environment defaults in the same way as the full package. | You want to manage the browser installation and version yourself. |
puppeteer with download disabled |
Does not download the browser when the skip setting is applied. | Set PUPPETEER_SKIP_DOWNLOAD=true during installation or configure skipDownload: true. Supply the browser executable path when launching. |
You want the regular package but need to control when and where the browser is installed. |
Neither choice makes an arbitrary Chromium version compatible by guarantee. Puppeteer says it works best with its bundled Chrome for Testing and does not guarantee it will work with another version; test your selected browser and Puppeteer combination in the target environment. See the launch API.
Install Chromium separately
-
Install Chromium using the package manager or deployment image for the operating system where Puppeteer will run. The package name and executable location differ by distribution and installation method; confirm the path on that machine rather than assuming a universal location.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Make sure the account running Node.js can execute the browser binary. In a container or server, install the required operating-system libraries as well as Chromium. Puppeteer’s troubleshooting guide covers Linux shared-library dependencies.
-
Record the full path to the executable. Puppeteer’s troubleshooting page uses
/usr/bin/chromium-browseras an example, but it is not a universal path.
Option 1: Use puppeteer-core
Install the browser-management package in your project:
npm install puppeteer-coreSet PUPPETEER_EXECUTABLE_PATH to Chromium’s actual path in the environment where the script runs. Then launch it explicitly:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
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();
}This example uses ECMAScript modules. If you use CommonJS, load the package with require('puppeteer-core'). The environment variable must contain a valid executable path; an unset or incorrect value will prevent launch. You can also provide a supported Chrome channel instead of executablePath, as described in the launch API.
Option 2: Keep puppeteer and skip its browser download
Set the environment variable during installation
Set PUPPETEER_SKIP_DOWNLOAD=true before installing the package so Puppeteer does not download its managed browser:
PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteerEnvironment-variable syntax varies by shell and operating system. In CI, set the variable in the job environment before the install step. In deployment, ensure it is set wherever dependencies are installed, not merely when the script later runs.
Or configure the regular package
For a project configuration file named .puppeteerrc.js, use:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →export default {
chrome: { skipDownload: true },
};Puppeteer’s configuration interface documents skipDownload and environment-variable overrides. Configuration changes that affect browser downloads need to be in place when the project’s installation workflow runs.
Launch the installed Chromium
With the regular package, explicitly point Puppeteer at the browser you installed:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
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();
}Set PUPPETEER_EXECUTABLE_PATH to the real path before running the script. If you want Puppeteer to skip downloads for a particular browser, consult the configuration interface for the browser-specific setting relevant to your installed version.
Verify the setup on the target machine
-
Check that the configured path points to the Chromium executable and that the Node.js process has permission to run it.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Run a small script that launches a browser, opens a page and closes cleanly. A successful dependency installation alone does not prove the browser can start in a container or server environment.
-
Exercise the pages and browser features your application relies on. Puppeteer’s compatibility guarantee applies to its bundled browser; a separately managed Chromium release may behave differently.
Puppeteer’s system requirements are version-sensitive. The documentation for v25.12.0 lists Node 22.12+ and supported Chrome for Testing platforms including Windows x64, macOS x64/arm64, Debian/Ubuntu Linux x64/arm64, and openSUSE/Fedora Linux x64/arm64. Check the system requirements for the Puppeteer version you install; these Chrome for Testing platform listings do not establish support for every independently packaged Chromium build.
Rank #4
What you avoid—and what you take on
The installation guide gives approximate default browser download sizes of about 170 MB for macOS, 282 MB for Linux and 280 MB for Windows. These are guide estimates, not fixed sizes for every release or network transfer. Skipping the download avoids that Puppeteer installation step, but makes browser installation, updates, executable paths and system dependencies your responsibility.
Free tools Windows power users keep installed
One-click scans. No signup required.
For browser management beyond a system package, Puppeteer also documents its @puppeteer/browsers API. Browser availability and provider details depend on that tooling and the chosen platform.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
-
Puppeteer still downloads Chrome: Check that
PUPPETEER_SKIP_DOWNLOAD=trueis set before installation, or thatskipDownload: trueis in the project configuration used by the install workflow. Environment variables can override configuration values. -
Launch fails with an executable-path error: Confirm the environment variable is present in the running process, points to the installed binary, and is not a directory or a path copied from another OS or container image.
-
Browser fails because a shared library is missing: Install the OS-specific dependencies required by Chromium in the runtime image, not just on the host used to build the project. The troubleshooting guide lists Linux dependency guidance.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
It works locally but not in a container: Compare the container’s browser path, installed libraries, runtime user permissions and Puppeteer version with your local environment. Validate the launch from inside the final image.
-
Using Alpine Linux: Puppeteer’s troubleshooting documentation warns that Chrome does not support Alpine out of the box. Do not assume a standard Chrome or Chromium setup will work there without addressing the distribution-specific compatibility and dependency requirements.
-
Chromium launches, but a page behaves differently: Check the Chromium and Puppeteer versions together and test the features your application uses. Puppeteer does not guarantee operation with every browser version.
Or skip the browser setup
If your goal is to capture website screenshots rather than run a browser you manage, ScreenshotNeo provides a screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP or PDF. See the API documentation.
Crashes, 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 minuteWindows 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 reinstallcurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server includes take_screenshot, get_page_info and capture_pdf for AI agents and MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does disabling Puppeteer’s browser download install Chromium?
No. Install Chromium separately and configure Puppeteer to use its executable.
Can I use a system Chromium version with any Puppeteer release?
Puppeteer does not guarantee compatibility with arbitrary browser versions. Test the combination you deploy.
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.
