puppeteer normally downloads a compatible Chrome for Testing build and chrome-headless-shell during installation, then keeps them in a local cache. If the browser is missing, check whether your package manager blocked install scripts or Puppeteer’s download settings disabled the download. For more control, install a specific build with @puppeteer/browsers; for an externally managed or remote browser, use puppeteer-core and configure the browser yourself.
What Puppeteer downloads—and which package does it
The puppeteer package’s installation process normally fetches a compatible Chrome for Testing build and chrome-headless-shell. The browser is separate from the Node.js package and is stored in Puppeteer’s cache. The documented default is $HOME/.cache/puppeteer. Puppeteer’s installation guide describes this default behavior and provides approximate download sizes of 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. Treat these as estimates from the current guide, not fixed size guarantees.
As an Amazon Associate I earn from qualifying purchases.
puppeteer-core behaves differently: it does not download a browser. Choose it when your application or infrastructure manages the browser separately, and provide a browser executable path or channel when launching.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Approach | Who obtains and manages the browser? | Good fit when |
|---|---|---|
puppeteer |
Puppeteer’s install workflow downloads its compatible browser into the local cache. | You want the standard local setup and can allow the install script to run. |
@puppeteer/browsers |
Your setup explicitly selects and installs a browser build and cache location. | You need to control the browser, build, platform, or installation step. |
| Custom provider or mirror | Your integration redirects or implements browser downloads. | You have an internal distribution need and can own compatibility testing and maintenance. |
puppeteer-core |
You or your infrastructure provide a local or remote browser. | You need an externally managed browser and can validate its compatibility. |
Where the browser is stored and how to configure downloads
The default cache path is $HOME/.cache/puppeteer. You can change the cache directory through Puppeteer configuration or the PUPPETEER_CACHE_DIR environment variable. Configuration can also select the default browser, set an executable path, or skip browser downloads. Environment-variable overrides include PUPPETEER_SKIP_DOWNLOAD. See the configuration guide for the supported settings and their precedence.
#1 Best Overall
When diagnosing a missing browser, inspect both general download settings and browser-specific settings. A skip-download option, including an environment override, can prevent acquisition even when the package itself installed successfully. Firefox is separately configured; the current reference lists its skipDownload default as true, so do not assume Firefox was fetched. Check the settings for your installed version in the configuration API reference.
Install the browser manually with Puppeteer’s supported tools
If post-install scripts are disabled in your environment, run Puppeteer’s browser installation command explicitly from your project directory:
Rank #2
- Install the
puppeteerpackage using your package manager’s normal workflow. - Run
npx puppeteer browsers installto download the browser required by Puppeteer. - Run your script again and confirm it launches. If it still reports a missing executable, check the cache path and download settings described above.
The install command and recovery options are documented in the installation guide. Alternatively, the @puppeteer/browsers package provides explicit browser/build installation into a chosen cache, with platform and download-base-URL options. It also supports optional SHA-256 archive verification. Consult the browsers API reference for the command’s precise options rather than assuming flags from another version.
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 glitchesThe install-dependencies option is limited to Chrome on Debian or Ubuntu and requires system-level privileges. Browser archives also need the platform’s required unpacking utilities. Check the current system requirements before building a minimal container or server image.
Choose a browser version and platform deliberately
Browser compatibility is version-specific. The stable documentation identifies Puppeteer v25.12.0 with Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. Those pairings describe that documented Puppeteer version; do not assume they apply to a different release. Check the supported browsers page for the version you install.
The current requirements specify Node.js 22.12 or later and list supported platforms and architectures. Chrome for Testing support includes Windows x64, macOS x64 and arm64, and specified Linux distributions and architectures; the exact Linux support matrix matters for containers and less common distributions. Verify your Node.js version, operating system, architecture, and unpacking tools against the system requirements before choosing a browser build.
When to use a custom provider, mirror, or remote browser
Custom providers and mirrors
A custom provider can redirect or implement browser downloads, but it is an integration you own—not a supported compatibility guarantee. Puppeteer’s browser-provider documentation says, “Puppeteer only tests and guarantees Chrome for Testing binaries.” If you use a custom provider or mirror, you are responsible for checking that the downloaded executable, version, platform, and Puppeteer release work together, and for maintaining that validation over time. The browser-provider documentation explains the supported integration surface and its limits.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Externally managed and remote browsers
Use puppeteer-core when the browser is managed outside Puppeteer’s package-install workflow. At launch, supply executablePath for a local executable or channel when selecting an installed browser channel, as described in the launch options reference. Puppeteer warns that a separately selected executable is used at the user’s risk; the bundled browser is its compatibility baseline. Validate your chosen browser against the Puppeteer version and deployment environment rather than treating any installed Chrome as interchangeable.
Best Value
- Used Book in Good Condition
Troubleshoot a missing or unusable browser
| Symptom | Likely cause | What to check or do |
|---|---|---|
| Launch fails because the Chrome executable is missing after package installation. | The package manager blocked dependency install scripts, or the browser download was skipped. | Run npx puppeteer browsers install, then inspect PUPPETEER_SKIP_DOWNLOAD and the configuration’s download settings. The installation guide documents both recovery paths. |
| The browser was downloaded but Puppeteer cannot find it. | The cache directory differs from the expected path, or the runtime uses a different environment from installation. | Check PUPPETEER_CACHE_DIR and the configured cache location. Ensure the install and launch stages use the same cache or explicitly configure the executable path. |
| A build or container cannot unpack or run the browser. | Required system packages or unpacking utilities may be absent, or the OS/architecture may not be supported. | Compare the environment with the current system requirements. On Debian or Ubuntu, the install-dependencies option can install Chrome dependencies but requires system-level privileges. |
| A proxy or internal network prevents a manual browser download. | The download process may not be using the expected proxy configuration. | @puppeteer/browsers respects HTTP_PROXY, HTTPS_PROXY, and NO_PROXY when the documented proxy-agent package is installed. Use its documented NODE_DEBUG channels to diagnose download and installation operations; see the browsers API reference. |
| Firefox is missing even though Puppeteer is installed. | Firefox download is separately configured, and the current reference lists its download-skip default as true. | Check the installed version’s Firefox configuration and explicitly install the browser you intend to use. See the configuration API reference. |
| A custom or system browser launches incorrectly. | Its version or build may not match Puppeteer’s tested compatibility baseline. | Check the browser pairing for your Puppeteer version and validate the exact executable in your deployment environment. Custom providers and separately selected executables make you responsible for that compatibility work. |
Or skip the browser setup
If the task is to capture a website rather than run a local Puppeteer workflow, ScreenshotNeo provides a screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. Its API handles browser setup for the capture:
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 request options. ScreenshotNeo removes known cookie-consent platforms, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents use screenshot tools. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can Puppeteer download a browser from a custom provider?
A custom provider can implement or redirect downloads, but Puppeteer does not officially support it; the implementer owns compatibility testing and maintenance.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does installing puppeteer-core download Chrome?
No. It expects you to provide or manage the browser separately.
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.
