What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
If Puppeteer reports Could not find Chrome (ver. ...), its browser download may have been skipped because your package manager blocked the install script. From your project directory, run npx puppeteer browsers install. If you want the download to happen automatically during installation, approve Puppeteer’s install script in your package manager and reinstall. If you deliberately manage Chrome or Chromium yourself, keep downloads disabled and configure Puppeteer to use that browser instead.
Why Puppeteer’s postinstall step fails
The npm package puppeteer normally downloads a compatible Chrome for Testing browser during installation. A package manager configured to block dependency scripts can skip that download. Puppeteer may then install as a package but fail when your application tries to launch a browser, with an error such as Could not find Chrome (ver. ...).
That symptom does not prove the install script was blocked. The download could have been deliberately disabled, the browser could be in a different cache or user account, or the browser may exist but be unusable at runtime. Diagnose which case applies before changing package-manager security settings or deleting caches.
First identify which package you installed
puppeteer manages a browser download by default. puppeteer-core does not download a browser; it is intended for setups where you supply a browser path or connect to a separately managed browser. Check the project’s package.json and lockfile, rather than assuming that a global installation or another project’s browser is available.
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
Use the same project and user
Run the recovery command from the project directory, with the package manager and user that will run the application. A browser downloaded under a developer account may not be visible to a CI job, container, or production process running as another user. Likewise, a global npx or install performed elsewhere does not necessarily repair the browser configuration for this project.
Run the supported browser installer
From the project root, run:
npx puppeteer browsers installThis explicitly installs the browser Puppeteer needs and is the direct recovery when the automatic install-script download was skipped. Let it finish successfully, then run your application again under the same user and environment. If you use a package manager other than npm, use its project-local equivalent for invoking Puppeteer’s browser installer.
When to reinstall the package
If the explicit browser installer succeeds, you usually do not need to reinstall Puppeteer just because its postinstall download was skipped. Reinstall when you have changed the package-script approval policy and want installation to perform the download automatically, or when a changed download configuration requires a fresh install. Use the package manager and lockfile workflow the project already uses so dependency versions remain consistent.
Allow Puppeteer’s install script when policy blocked it
Package managers can restrict scripts run by dependencies. If your environment permits Puppeteer’s browser download and the blocked script is the cause, approve Puppeteer specifically rather than broadly enabling every dependency script. The documented npm allowScripts example is:
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 →Rank #2
{
"allowScripts": {
"puppeteer": true
}
}Apply the setting in the format and configuration location supported by the npm version and policy used by your project. Other package managers have their own script-approval mechanisms; do not assume an npm setting applies to them. After changing the policy, reinstall Puppeteer if you want the postinstall step to run under the new policy. You can also keep an explicit npx puppeteer browsers install build step when that is preferable to allowing a dependency script during installation.
Choose between approval and an explicit build step
| Situation | Next action | Trade-off |
|---|---|---|
| Policy blocked Puppeteer’s script and automatic downloads are acceptable | Allow Puppeteer’s script, then reinstall if needed | Changes script approval policy for this dependency |
| Policy should continue blocking dependency scripts | Run npx puppeteer browsers install as an explicit project or build step |
The browser-install step must be included in the relevant environment’s setup |
| The operating system or image owns Chrome | Keep the download disabled and configure the executable path | Your team owns browser compatibility, versioning, and updates |
Check whether downloads were intentionally disabled
Puppeteer can be configured not to download a browser. Check the environment and project configuration for PUPPETEER_SKIP_DOWNLOAD and the skipDownload setting. If either is intentionally enabled because your image supplies Chrome or Chromium, do not simply remove it: confirm that the external browser is present and configure Puppeteer to launch it.
Where applicable, Puppeteer environment variables override configuration. That means a setting in a developer shell, CI environment, container, or deployment platform can change behavior even if the checked-in configuration looks correct. Inspect the environment in which the install command actually runs.
Using an externally managed browser
If the operating system or container image installs the browser, provide its executable path through Puppeteer’s executablePath launch option or the PUPPETEER_EXECUTABLE_PATH environment variable. For example, in application code the shape is:
PC 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 & 11Outdated 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 matchconst browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH
});This example assumes the environment variable is set to a real browser executable in the runtime environment. It is not a universal filesystem path: the correct path depends on the operating system and image. Keep download skipping enabled only when you have verified the supplied browser is compatible with the Puppeteer version you run.
Align the browser cache, user, and runtime
Since Puppeteer v19.0.0, the default browser cache location is ~/.cache/puppeteer. A browser may have downloaded successfully yet appear missing if installation and runtime use different home directories, users, containers, or mounted filesystems. A cache path that exists during the build may not exist in the deployed runtime.
- Check which user runs the install step and which user runs the application.
- Check whether those steps see the same home directory and filesystem.
- Inspect
PUPPETEER_CACHE_DIRand any configured cache location. - Make sure the runtime user can read the cache and that the browser files are available after deployment.
- After changing the download configuration or cache location, rerun the browser installer in the environment that needs the browser.
For containers and CI, make the cache location and browser-install step part of a reproducible build rather than relying on a developer machine’s home directory. If a cache mount is used, verify that it is mounted at both the expected build and runtime stages.
Separate a successful download from a successful launch
Fixing the postinstall download does not guarantee Chrome will launch. Installation and runtime are separate stages: a browser can be present but fail because the runtime image lacks required Linux libraries, directories are not writable, file permissions differ, or the sandbox environment is incompatible.
Linux libraries and container images
If the browser executable exists but launch reports missing shared libraries, install the operating-system libraries required by the browser in the runtime image. The exact package names depend on the distribution and base image; a Puppeteer browser download does not install those system dependencies for you.
Read-only containers and writable directories
A read-only container may prevent Chrome from creating configuration, cache, or user-data files even when the browser itself is readable. Ensure the runtime has writable XDG configuration/cache locations and a writable browser user-data directory, or configure those paths to a writable location supported by your deployment.
Sandbox and permission errors
Treat sandbox and file-permission errors as environment-specific launch problems. Identify the exact launch error and the container or host security constraints before changing sandbox settings. Do not use --no-sandbox as a universal postinstall fix: it does not repair a missing download, mismatched cache, absent libraries, or unwritable profile directory.
Use puppeteer-core when you manage the browser
Choose puppeteer-core when the browser is supplied and managed separately, or when connecting to a remote browser. It avoids Puppeteer’s managed browser download, but it also means your application or deployment must provide the browser path or endpoint and keep the browser compatible with the library version. If you want Puppeteer to manage its browser download, use puppeteer instead.
Recommended Free Tools
Best Value
- Used Book in Good Condition
| Setup | Browser responsibility | What to configure |
|---|---|---|
puppeteer |
Puppeteer downloads a compatible browser unless download is skipped or blocked | Permit or explicitly run the browser installer; align cache and runtime user |
puppeteer-core |
Your environment supplies or hosts the browser | Provide an executable path or remote browser connection |
Or skip the browser setup
If your goal is to capture website screenshots rather than run browser automation in your own environment, ScreenshotNeo provides a screenshot API and MCP server. It does not repair Puppeteer or replace a Puppeteer automation workflow; it is an alternative when you need a screenshot or PDF without managing a local browser installation.
For example, make one GET request with a URL to receive a screenshot. See the ScreenshotNeo API documentation for the available parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe API can also be called from Python or Node.js:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie/consent banners are accepted before capture, and known consent platforms, newsletter popups, and chat widgets are removed; each step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Responses report the page verdict and billing status in headers.
- An MCP server offers
take_screenshot,get_page_info, andcapture_pdftools for Claude, Cursor, and other MCP clients. - The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Every feature is available on every plan.
Sign up for 1,000 free screenshots a month, with no card required.
Troubleshoot by symptom
| Symptom | Likely area to check | Next step |
|---|---|---|
Could not find Chrome (ver. ...) |
Blocked or skipped download; wrong user or cache | Run the browser installer, inspect skip settings, and align cache and runtime identity |
| Installer completes, but the application still cannot find Chrome | Build and runtime do not share browser files or cache path | Check PUPPETEER_CACHE_DIR, home directory, user, and deployment mounts |
| Browser exists, but launch fails on Linux | Missing system libraries, permissions, sandbox, or writable directories | Use the specific launch error to investigate the runtime image and security constraints |
| Chrome is managed by the image but Puppeteer tries to download | External-browser configuration is incomplete | Set the intentional skip configuration and provide a valid executable path |
Frequently Asked Questions
Does a successful npm install prove that Chrome was installed?
No. The package can install while a package-manager policy skips its browser-download script.
Does Puppeteer install chrome-headless-shell?
The Puppeteer installation guide notes that chrome-headless-shell is included beginning with Puppeteer v21.6.0.
Is there an established rate for how often this postinstall failure happens?
No authoritative failure-rate statistic is established in the cited official documentation.
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.
