For the simplest supported setup, install puppeteer and let it download its matching browser. If package-manager policy blocks install scripts, install that browser afterward with Puppeteer’s browser CLI. If you need to control the browser yourself or connect remotely, use puppeteer-core and provide a browser path or channel—but then you own version compatibility.
What Puppeteer downloads by default
Installing the puppeteer package normally downloads Chrome for Testing and chrome-headless-shell. The latter has been available since Puppeteer v21.6.0. Puppeteer keeps these browser files in $HOME/.cache/puppeteer by default in the documented setup; globally cached browser files have been the default behavior since v19.0.0. See the Puppeteer installation guide.
As an Amazon Associate I earn from qualifying purchases.
The current installation guide lists approximate download sizes of 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows. Treat these as guide estimates, not exact amounts for every operating system, package setup, or installation.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallThis default is usually the right choice when your project allows install scripts and can accommodate the browser download. Puppeteer says its bundled browser is the one it guarantees to work with.
#1 Best Overall
Choose the download approach that fits your project
| Approach | Who manages installation and upgrades? | Compatibility assurance | Best fit |
|---|---|---|---|
puppeteer default install |
Puppeteer’s install process | Strongest documented assurance: Puppeteer’s bundled browser | Projects that can run install scripts and accept the browser download |
| Install the browser with the CLI | Puppeteer, triggered manually by you | Uses a Puppeteer-managed browser | Package environments that block dependency install scripts |
puppeteer-core with a separate browser |
You or your remote-browser provider | You must validate compatibility; the bundled-browser guarantee does not apply | Remote browsers or environments where browser installation is managed separately |
Configuration files or environment variables let you alter download behavior without switching approaches. Browser version mappings and supported options can change between Puppeteer releases, so check the documentation for the version installed in your project.
Install the browser manually when install scripts are blocked
Some package-manager configurations block dependency install scripts. Puppeteer’s guide gives npm under a newer RFC, pnpm, Yarn Berry, Bun, and Deno as examples of environments where scripts may not run. Without the postinstall download, launching may fail with an error such as Could not find Chrome (ver. ...).
Rank #2
- Install Puppeteer as usual under your project’s package-manager policy.
- Run the browser installation command from the project directory:
npx puppeteer browsers install - Retry your launch. The CLI installs the browser expected by the Puppeteer setup. If the package manager supports allowing a specific dependency’s script, you can instead permit Puppeteer’s install script according to that manager’s policy.
Equivalent command forms include:
- Yarn:
yarn puppeteer browsers install - pnpm:
pnpm exec puppeteer browsers install - Bun:
bunx puppeteer browsers install
For more control, the @puppeteer/browsers documentation describes installing a named browser build such as chrome@stable, a milestone, or an exact version. Its API accepts a browser, build ID, cache directory, and platform, among other settings. You may supply an expected SHA-256 hash; if you do, installation fails when the archive does not match. Hash verification is not implied when you omit that option.
Control browser downloads and cache location
Puppeteer recommends configuration files for persistent settings; environment variables are also available. The configuration API documents settings such as these:
Rank #3
| Purpose | Configuration key | Environment variable |
|---|---|---|
| Choose the browser cache directory | cacheDirectory |
PUPPETEER_CACHE_DIR |
| Skip browser downloads generally | skipDownload |
PUPPETEER_SKIP_DOWNLOAD |
| Choose the default browser | defaultBrowser |
PUPPETEER_BROWSER |
| Supply an executable path | executablePath |
PUPPETEER_EXECUTABLE_PATH |
Chrome- and Firefox-specific skip-download settings are also documented. Browser-specific settings include versions and download base URLs. Consult the configuration API for exact key names and supported values for your release rather than copying a setting from another version.
When you change a setting that affects downloads, rerun the relevant installation step—for example, npx puppeteer browsers install—so the browser files match your configuration. Configuration files and environment variables are ignored by puppeteer-core.
Use a browser you manage yourself
Choose puppeteer-core when your application connects to a remote browser or your deployment process installs and maintains the browser separately. Unlike puppeteer, puppeteer-core does not download Chrome.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesWhen launching, supply either an explicit executable path or a channel. An explicit path points to a particular executable; a channel asks Puppeteer to look for a standard system Chrome installation. The LaunchOptions API describes the executablePath option and cautions: “Puppeteer is only guaranteed to work with the bundled browser.” For a separately managed or remote browser, pin a compatible version where practical and test both startup and the automation behavior your application relies on.
Best Value
Use this approach when operational control matters more than having Puppeteer manage the browser. It avoids Puppeteer’s browser download, but shifts installation, updates, and compatibility checks to you or your browser provider.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Check browser support for your Puppeteer version
Puppeteer documents Chrome for Testing as its default supported Chrome path and also documents Firefox support. The supported-browser table maps Puppeteer package releases to browser versions; use the row for the release actually installed in your project, not an old version copied from an example. See the supported browsers table.
As a dated illustration, the documentation labeled 25.12.0 lists Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. These are pairings for that documentation version, not permanent latest-version recommendations. Browser-management documentation also permits custom providers, but labels them unsupported; compatibility, testing, and maintenance are your responsibility.
Recommended Free Tools
Troubleshoot common download and launch failures
- Error:
Could not find Chrome (ver. ...). The install script may have been blocked, or the expected browser is absent from the configured cache. Runnpx puppeteer browsers installafter installation and confirm thatcacheDirectoryorPUPPETEER_CACHE_DIRpoints to the location you intend to use. - The browser downloaded to an unexpected directory. Check
cacheDirectoryandPUPPETEER_CACHE_DIR, including the environment of the user or build process running the install. Change the setting, then run the browser-install command again. - A browser-skip setting prevents installation. Check
skipDownload,PUPPETEER_SKIP_DOWNLOAD, and the browser-specific skip settings. Remove or adjust the setting if Puppeteer should download a browser, then rerun installation. puppeteer-coreignores your configuration. This is expected: it ignores Puppeteer configuration files and environment variables. Manage the browser separately and provide its executable path or a channel in launch options.- A system browser launches incorrectly or behaves differently. The bundled-browser compatibility guarantee does not cover your separately managed browser. Check the supported-browser mapping for your Puppeteer release, pin an appropriate browser version, and validate the operations your application needs.
- A browser archive fails a supplied hash check. The optional expected SHA-256 value did not match the downloaded archive. Verify the expected hash and selected build before retrying; do not assume a hash check occurred if you did not supply one.
Or skip the browser setup
If your goal is a website screenshot rather than browser automation, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. For the complete parameters and response behavior, see the ScreenshotNeo API documentation.
Quick Recap
curl -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 like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies page verdict and billing status in its headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
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.
