Recommended Free Tools
By default, installing puppeteer downloads a compatible Chrome for Testing browser and chrome-headless-shell into Puppeteer’s browser cache. You can change the cache location or browser, run the download manually if package scripts are blocked, or skip Puppeteer’s download and supply a browser you manage. The simplest and most compatibility-assured option is the default install; using a separately managed browser gives you more control but makes you responsible for compatibility.
What Puppeteer downloads by default
Installing the puppeteer package normally downloads Chrome for Testing and chrome-headless-shell. The installation guide identifies the latter as available starting with Puppeteer v21.6.0. Puppeteer stores these browser files in ~/.cache/puppeteer by default; globally cached browser files have been the documented behavior since v19.0.0. See the Puppeteer installation guide.
The current installation guide lists approximate downloads of 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows. These are guide estimates, not guaranteed sizes for every platform or installation. Check the guide for the version you are installing before budgeting disk space or CI cache size.
Choose how Puppeteer gets its browser
| Option | Who installs and updates the browser? | Compatibility | Best fit |
|---|---|---|---|
Install puppeteer normally |
Puppeteer’s install process downloads its browser. | Strongest documented assurance: Puppeteer says its bundled browser is guaranteed to work with Puppeteer. | Most projects that can download browser binaries during installation. |
| Install browser manually with the CLI | You run Puppeteer’s browser installer after installing the package. | Still uses a Puppeteer-managed browser build. | Package managers or policies that block install scripts. |
Use puppeteer-core with a separate browser |
You or your infrastructure provider install and maintain the browser. | You must validate and maintain compatibility; the bundled-browser guarantee does not apply. | Remote browsers or environments where browser lifecycle is managed separately. |
Use the default bundled browser
For a new project, install puppeteer and allow its install process to run:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#1 Best Overall
npm install puppeteerThen launch Puppeteer without specifying a browser path:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}This is the least complicated route when downloading the browser is acceptable and package scripts are permitted. Puppeteer’s release-to-browser mapping changes over time, so use the browser paired with your installed Puppeteer version rather than assuming a system Chrome version is interchangeable.
Install the browser manually when scripts are blocked
Some package-manager defaults or project policies block dependency install scripts. In that situation Puppeteer may be installed while its browser binary is missing. A common symptom is Could not find Chrome (ver. ...).
- Install the package without relying on its postinstall download, according to your package manager’s policy.
- Run the Puppeteer browser installer from the project directory:
npx puppeteer browsers install - Retry your launch script. If it still cannot find the browser, verify the cache directory and the configured browser selection.
The installation guide also documents equivalent invocations for Yarn, pnpm, and Bun. Use the syntax shown there for your package manager and current version. Alternatively, configure your package manager to allow Puppeteer’s install script if that is permitted by your project’s security policy.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Install a particular browser build
The @puppeteer/browsers tooling can install a named build such as chrome@stable, a milestone, or an exact version. Its installation options include the browser, build ID, cache directory, and platform. Consult the browser management documentation for the current command and API options.
You can supply an expected SHA-256 hash to the installer; when supplied, installation fails if the downloaded archive does not match. Do not assume checksum verification happens automatically when you omit that option. Puppeteer also documents custom browser providers, but describes them as unsupported: compatibility testing and ongoing maintenance are your responsibility.
Control the download, cache, and executable
Puppeteer recommends configuration files for settings that affect browser installation. Environment variables are also available. The configuration guide documents these principal controls:
| Purpose | Configuration key | Environment variable |
|---|---|---|
| Set browser cache directory | cacheDirectory |
PUPPETEER_CACHE_DIR |
| Skip browser downloads generally | skipDownload |
PUPPETEER_SKIP_DOWNLOAD |
| Choose the default browser | defaultBrowser |
PUPPETEER_BROWSER |
| Set the executable used for launch | executablePath |
PUPPETEER_EXECUTABLE_PATH |
Chrome- and Firefox-specific skip settings are also documented, along with browser-specific versions and download base URLs. Check the configuration API for the exact supported keys and behavior in your installed version.
Free tools Windows power users keep installed
One-click scans. No signup required.
For example, a project configuration file can move the cache to a directory managed by your build system:
import { Configuration } from 'puppeteer';
export default {
cacheDirectory: './.cache/puppeteer',
};After changing settings that affect which browser is downloaded or where it is stored, rerun Puppeteer’s postinstall process or the browser-install command so the selected browser is present in the new location. Configuration files and these environment-variable overrides are ignored by puppeteer-core.
Skip Puppeteer’s download and manage Chrome yourself
Use puppeteer-core when a browser is supplied by a remote service, container image, operating-system package, or another deployment process. Unlike puppeteer, puppeteer-core does not download Chrome.
npm install puppeteer-coreWhen launching, provide an explicit executable path or a channel for a standard system Chrome installation:
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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
executablePath: '/path/to/chrome',
// Or use a supported installed Chrome channel instead of executablePath.
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
} finally {
await browser.close();
}Replace /path/to/chrome with the actual executable path in your environment. An explicit path points directly to an executable; a channel asks Puppeteer to look for a standard system Chrome installation. Puppeteer’s launch options explain that it is “only guaranteed to work with the bundled browser.” For an independently managed browser, pin compatible browser and Puppeteer versions and test the launch and automation flows you depend on. See the LaunchOptions API.
Choose Firefox or check browser-version compatibility
Puppeteer documents Chrome for Testing as its default supported Chrome path and also supports Firefox. Do not copy a browser version from an old setup guide: use Puppeteer’s supported-browser table for the release installed in your project.
As a dated example, the supported-browser table for documentation version 25.12.0 lists Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Those pairings are not permanent recommendations; consult the supported browsers table for your Puppeteer release.
Rank #4
Common download and launch problems
- “Could not find Chrome (ver. …).” The browser download may have been skipped because install scripts were blocked, or Puppeteer may be looking in a different cache. Run
npx puppeteer browsers installand confirm the configured cache directory. - Install completed but no browser is present. Check whether your package manager allowed Puppeteer’s install script. Run the browser installer manually or explicitly permit the script under your project policy.
- Changing the cache path did not move the existing browser. A configuration change controls where Puppeteer expects or downloads browser files; rerun the install process after changing it, then ensure your runtime uses the same configuration.
puppeteer-coreignores configuration settings. This is expected: it does not use Puppeteer configuration files or environment-variable overrides. Supply the browser path or channel in launch options and manage the browser separately.- A system Chrome launches but automation behaves differently. A separately managed browser is outside Puppeteer’s bundled-browser compatibility assurance. Pin versions and test the relevant workflows, or return to the browser bundled for your Puppeteer release.
Or skip the browser setup
For a screenshot rather than a browser-automation workflow, ScreenshotNeo is a website screenshot API and MCP server: one request returns a PNG, JPEG, WebP, or PDF. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents use screenshot tools, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.
Example cURL request, using the documented endpoint and parameters:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and options. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does Puppeteer download a browser if I install puppeteer-core?
No. puppeteer-core does not download Chrome; provide a browser through an executable path, channel, or remote-browser setup.
Can I use a Chrome version other than the one Puppeteer downloads?
Yes, but the bundled-browser compatibility assurance does not cover a separately managed browser. Pin versions and validate your own automation workflows.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →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.
