Windows 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 reinstallOutdated 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 matchIf Puppeteer appears stuck on “running the postinstall script,” first determine whether the browser download is actually running, was blocked by your package manager, or is failing for a specific environmental reason. The puppeteer package normally downloads a compatible Chrome for Testing browser during installation. If that lifecycle script is blocked or browser downloads are intentionally disabled, installing the package alone will not provide Chrome; run npx puppeteer browsers install or configure Puppeteer to use a browser you manage.
What Puppeteer’s postinstall script does
The puppeteer package installs a compatible browser as part of setup. The Puppeteer installation guide explains: “When you install Puppeteer, it automatically downloads a recent version of Chrome for Testing.” Puppeteer installation guide
That browser download is separate from installing the JavaScript package into node_modules. Some package managers or project policies block dependency lifecycle scripts. In that case, the package can install successfully while its browser download is skipped; the failure may surface later when an app tries to launch Chrome.
puppeteer-core behaves differently: it does not download Chrome. It is intended for setups where your team manages the browser and supplies a compatible executable path, browser channel, or remote connection. Puppeteer installation guide
#1 Best Overall
Why is Puppeteer stuck on running the postinstall script?
“Running” may mean the browser download is progressing slowly, the package manager is waiting on a hidden or blocked lifecycle script, or the script has stopped after an error. Do not assume the network is at fault until you have the complete output.
- Rerun the install with lifecycle-script output visible. For npm, use its foreground-script option, for example
npm install --foreground-scripts. - Copy the full output, including the lines immediately before the apparent stall or failure.
- Record the Node.js version, operating system, CPU architecture, package-manager version, and whether the command runs locally, in CI, Docker, WSL, or a serverless build.
- Check whether your package manager or repository policy blocks dependency install scripts.
- Check whether a Puppeteer setting deliberately disables browser downloads.
These details distinguish a blocked script from a download problem, a cache-permission issue, or a browser that installed correctly but cannot launch.
How to fix Puppeteer postinstall failed
1. Allow the install script or install the browser manually
Modern package-manager policies can block dependency scripts. Puppeteer’s installation guide identifies npm under its newer policy, pnpm, Yarn Berry, Bun, and Deno as environments where script approval or configuration may be needed. Check the documentation for the exact package-manager version and project policy you use. Puppeteer installation guide
The manual recovery command is:
npx puppeteer browsers install
Run it from the project directory after installing Puppeteer. It asks Puppeteer to install its managed browser without relying on the original package-install lifecycle run. If your environment blocks that command’s downloads too, resolve the relevant network, policy, or permission restriction rather than repeatedly rerunning installation.
For npm’s documented package-level approval form, add this to package.json:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
{
"allowScripts": {
"puppeteer": true
}
}
Then reinstall or run the browser installation command. Confirm the syntax and behavior against the npm version in use; package-manager script controls vary by release. Puppeteer installation guide
2. Remove an unintended download-suppression setting
Search shell profiles, CI variables, Docker build arguments, hosting settings, and Puppeteer configuration for:
Free tools Windows power users keep installed
One-click scans. No signup required.
PUPPETEER_SKIP_DOWNLOADPUPPETEER_CHROME_SKIP_DOWNLOADskipDownload: true
These controls intentionally prevent browser downloads; they are not general-purpose fixes for a hanging install. If Puppeteer is supposed to manage Chrome, remove the unintended setting and run npx puppeteer browsers install or reinstall the package. If suppression is deliberate, install or provide a compatible browser yourself and configure Puppeteer with its executable path or browser channel. Puppeteer configuration guide Puppeteer installation guide
3. Make the browser cache consistent between build and runtime
Since Puppeteer v19.0.0, the default browser cache is $HOME/.cache/puppeteer. A common deployment failure is that installation runs as one user or with one home directory, while the application runs as another user or with a different cache path. The runtime then cannot find or read the browser that installation downloaded.
Rank #3
For CI, containers, serverless builds, or multi-user environments, set a stable cache location using PUPPETEER_CACHE_DIR or the supported cacheDirectory option in a Puppeteer configuration file. Ensure that the install and runtime stages use the same path and that the runtime account can read and execute its contents. After changing the cache configuration, rerun the browser installation command or reinstall Puppeteer. Puppeteer configuration guide Puppeteer installation guide
4. Confirm that the deployment includes the browser
A build cache that reuses node_modules can also skip the install step that would have downloaded Chrome. If the deployment reuses a cached dependency tree, make sure the browser cache is included in the artifact and remains accessible to the runtime user.
Puppeteer’s guidance for Google App Engine and Cloud Functions places the browser cache under node_modules/.puppeteer_cache so the browser can travel with a cached dependency tree. Apply that approach only when your deployment actually packages and reuses that directory; the path alone does not ensure the runtime can execute the browser. Puppeteer troubleshooting guide
Why can’t Puppeteer find Chrome after npm install?
A successful npm install confirms that npm installed packages; it does not prove that Puppeteer’s browser download ran. The most common cause is a blocked lifecycle script. Other likely causes are an intentional skip-download setting, installation into a different cache or home directory, or a deployment artifact that omitted the browser cache.
- Check the install output and package-manager script policy.
- Run
npx puppeteer browsers installif Puppeteer should manage the browser. - Check for skip-download environment variables and
skipDownloadconfiguration. - Verify that the configured cache path is shared by installation and runtime and is readable by the runtime user.
- If you use
puppeteer-coreor intentionally manage Chrome yourself, set a valid browser executable path or channel instead of expecting a download.
The official browser management and configuration details are in Puppeteer’s installation guide and configuration guide.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Do WSL and Windows need a different fix?
WSL: check launch-time system libraries
Missing Linux libraries can prevent Chrome from launching under WSL even when the postinstall download completed. Puppeteer’s troubleshooting guide lists dependencies that may be needed, including libgtk-3-dev, libnotify-dev, libgconf-2-4, libnss3, libxss1, and libasound2. The exact requirements depend on the environment. Treat a missing-library launch error as a platform prerequisite problem, not evidence that the postinstall script never ran. Puppeteer troubleshooting guide
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Windows: distinguish cache permissions from download failure
Puppeteer documents a Windows launch issue in which Chrome sandbox files in the browser cache have insufficient permissions, along with an icacls remedy for the affected cache directory. Use the documented steps for the actual directory and error you see. Changing file permissions will not fix a lifecycle script that was blocked or a browser that was never downloaded. Puppeteer troubleshooting guide
Choose the fix for your environment
| Situation | Who supplies Chrome? | What to check | Likely action |
|---|---|---|---|
Local project using puppeteer |
Puppeteer | Lifecycle script output and policy | Allow the script or run npx puppeteer browsers install. |
Project using puppeteer-core |
Your project or host | Configured executable, channel, or remote browser | Provide a compatible browser; do not expect a Puppeteer download. |
| CI or Docker build | Puppeteer, unless download is suppressed | Build/runtime user, cache path, permissions, and artifact contents | Use one accessible cache path and make sure the browser is retained in the runtime image. |
| Serverless deployment with cached dependencies | Puppeteer, unless download is suppressed | Whether the browser cache travels with the reused dependency tree | Package and preserve the cache in a path the runtime can access. |
| WSL or Windows launch error | Usually Puppeteer if using the full package | System libraries on WSL; cache-file permissions on Windows | Apply the platform-specific troubleshooting fix only when the error matches. |
Common errors and what to do
- Install succeeds, then “Could not find Chrome.” A lifecycle script may have been blocked, downloads may be disabled, or runtime may be looking in another cache. Check policy and configuration, then install the browser manually or align cache paths.
- The install output says scripts are disabled or requires approval. Approve Puppeteer’s install script using the package manager’s supported mechanism, or run the manual browser install command if permitted.
- Browser install says it cannot download. Check the full error and the environment’s network and security policy. Do not unset a deliberate download-suppression control without first deciding whether Puppeteer or your deployment is meant to provide Chrome.
- Chrome downloads but fails at launch in WSL. Check the missing-library error and install the relevant platform dependencies documented by Puppeteer.
- Chrome downloads but Windows reports a permissions problem. Follow Puppeteer’s documented cache-directory permissions remedy for the matching sandbox-file error.
- It works in the build but not in production. Compare build and runtime users, home directories, cache paths, and packaged files. Ensure the deployed runtime can read and execute the browser.
Performance, reliability, and cost considerations
The browser download is an installation-time dependency, not a reason to repeatedly download Chrome for every run. In CI and deployment pipelines, a stable cache can avoid repeating setup, but a cache hit is useful only if the browser directory is preserved and accessible at runtime. Conversely, caching node_modules without the corresponding browser can create a misleadingly successful install followed by a missing-Chrome error.
If reproducible builds matter, treat the browser cache and package installation as part of the same deployment artifact. Record which package, Node version, operating system, and architecture produced the artifact, and verify a real browser launch in the same kind of runtime that will execute the app. A package install alone is not a browser launch test.
Browser downloads consume build time and storage, but the Puppeteer documentation cited here does not state a universal download duration, size, or cost. Those depend on the environment and should be measured in your own pipeline rather than assumed.
Or skip the browser setup
If you only need a website screenshot rather than a local Puppeteer browser, ScreenshotNeo offers a screenshot API and MCP server. Its one-request API returns an image or PDF; the response identifies page outcomes and billing status. Cookie banners, newsletter popups, and chat widgets are removed before capture, and bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.
Example cURL request, targeting Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo API documentation for authentication and options. ScreenshotNeo has a free plan with 1,000 screenshots per month and no card required; paid plans start at $5 for 3,000 screenshots. To try it, sign up for 1,000 free screenshots a month with no card.
Frequently asked questions
Should I use puppeteer or puppeteer-core?
Use puppeteer when you want Puppeteer to download and manage a compatible browser. Use puppeteer-core when your team supplies and configures the browser itself.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Does rerunning npm install always download Chrome?
No. A blocked lifecycle script, a skip-download setting, or a deployment that reuses cached packages can prevent that result. Check the script output and browser configuration, then use Puppeteer’s manual install command when appropriate.
Can I fix a postinstall failure by changing Chrome permissions?
Only if the browser was downloaded and the observed error is a permissions problem. Permissions changes do not make a blocked install script run or supply a missing browser.
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.
