Free tools Windows power users keep installed
One-click scans. No signup required.
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If Puppeteer appears stuck on “running the postinstall script,” first check whether your package manager allowed Puppeteer’s install script to run. The puppeteer package normally downloads a compatible Chrome for Testing browser during installation. If a package-manager policy blocks that script—or a setting intentionally skips the download—the package can still appear in node_modules even though no browser was installed. The official recovery command is npx puppeteer browsers install; use it after checking script policy, download settings, cache paths, and the account that will run Puppeteer.
What Puppeteer’s postinstall script does
When you install the full puppeteer package, its installation process downloads a compatible Chrome for Testing browser. That browser is what Puppeteer uses by default when your code launches a browser. The Puppeteer project’s official installation guide describes the behavior this way: “When you install Puppeteer, it automatically downloads a recent version of Chrome for Testing.”
The install script is separate from adding the JavaScript package to node_modules. A package manager can install the package while blocking dependency lifecycle scripts, so a successful-looking install does not prove that Chrome was downloaded. Later, Puppeteer may fail when it tries to find or launch a browser.
Recommended Free Tools
puppeteer-core is different: it does not download Chrome. It is intended for projects that supply and manage the browser themselves. If you use it, configure a browser explicitly—for example with executablePath or a supported channel—or connect to a remote browser. Running the postinstall recovery command does not change the fact that puppeteer-core leaves browser management to you.
#1 Best Overall
Why is Puppeteer stuck on running the postinstall script?
“Stuck” can describe different failures: the script may be waiting on a browser download, it may have been blocked before it ran, or it may have completed without putting the browser somewhere the runtime can find it. Start by collecting the actual installer output rather than assuming that a long pause means a network problem.
1. Show the full lifecycle-script output
For npm, rerun the install with foreground script output enabled:
npm install --foreground-scripts
If you are installing from a lockfile, use the equivalent install command for your project with that option, such as npm ci --foreground-scripts. Preserve the complete output, including the lines immediately before and after the Puppeteer script message. Also record your Node.js version, operating system, CPU architecture, package-manager version, and whether the command runs locally, in CI, Docker, WSL, or a serverless build. These details help distinguish a policy block from a download, permissions, or platform issue.
2. Check whether dependency scripts are allowed
Current Puppeteer installation guidance identifies npm under its newer policy, pnpm, Yarn Berry, Bun, and Deno as environments where dependency install scripts may be blocked. The exact setting and prompt can vary by package-manager version and project configuration. If the package was installed but its browser is missing, check the package manager’s script-approval policy before repeatedly reinstalling.
Rank #2
For npm, the documented package.json opt-in form is:
{
"allowScripts": {
"puppeteer": true
}
}After allowing the script, rerun the install or install the browser explicitly:
npx puppeteer browsers installIf you prefer not to permit dependency scripts, the manual browser-install command lets you install Puppeteer’s browser after the package itself is present. In a team or CI environment, make the choice in the project’s package-manager configuration so developers and builds do not behave differently by accident.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →3. Check whether you deliberately disabled browser downloads
Search your shell environment, CI variables, Dockerfile, deployment settings, and Puppeteer configuration for these controls:
PUPPETEER_SKIP_DOWNLOADPUPPETEER_CHROME_SKIP_DOWNLOADskipDownload: truein Puppeteer configuration
These settings suppress browser downloads; they are not general-purpose ways to fix a slow postinstall. Remove the setting if you expect Puppeteer to manage Chrome, then run npx puppeteer browsers install or reinstall with the intended script policy. If skipping the download is intentional, make sure your environment supplies a compatible browser and configure its location with executablePath or a supported channel.
How to fix “Puppeteer postinstall failed”
Use the symptom and deployment setup to choose a remedy. Installing a browser manually and permitting lifecycle scripts are alternatives when scripts were blocked; changing cache configuration is appropriate when a browser was downloaded but is unavailable to the runtime.
| Situation | Who supplies Chrome? | What to check or do |
|---|---|---|
| Local project; scripts are blocked | Puppeteer, installed manually | Approve Puppeteer’s lifecycle script or run npx puppeteer browsers install after installing the package. |
| CI or container where scripts are permitted | Puppeteer | Confirm the browser-install step ran, and that the cache is retained and readable by the runtime user. |
| Managed browser or host-provided Chrome | Your image, host, or team | Keep download suppression only if intentional; configure the browser with executablePath or channel. |
puppeteer-core |
Your project or remote-browser provider | Supply a browser and configure an executable path, channel, or remote connection; this package does not download Chrome. |
The reliable fix is the one that makes the browser available to the same runtime that launches Puppeteer. A successful package install alone is not enough if the browser is missing, in a different cache, or inaccessible to the runtime account.
Why can’t Puppeteer find Chrome after npm install?
If npm reports that the package installed but Puppeteer later reports that it cannot find Chrome, check for a blocked install script first. The next checks are intentional download suppression, the configured cache location, and whether installation and runtime use the same account and home directory.
Rank #4
Install the browser after installing Puppeteer
From the project directory, run:
npx puppeteer browsers installThen rerun the application in the same environment and as the same user that will use the browser. If this command cannot download a browser, its output should provide more specific information than the original package-install symptom; keep that output when investigating connectivity or permissions.
Align cache location and runtime identity
Since Puppeteer v19.0.0, the default browser cache is $HOME/.cache/puppeteer. If installation runs as one user and the application runs as another, their $HOME values can point to different caches. A browser can therefore be present on disk and still be missing from Puppeteer’s runtime perspective.
For CI, containers, serverless builds, or multi-user systems, choose an explicit cache location using PUPPETEER_CACHE_DIR or the cacheDirectory setting in a supported .puppeteerrc or puppeteer.config file. Ensure the install and runtime stages resolve the same location and that the runtime identity has permission to read and execute the browser. After changing download or cache configuration, run npx puppeteer browsers install again or reinstall so the browser is placed according to the new setting.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Check whether the deployment preserved the browser
Some build systems cache node_modules and skip installation on a cache hit. In that case, a browser download that happened only during an earlier install may not be present in the current build or runtime. Google App Engine and Cloud Functions guidance places Puppeteer’s cache under node_modules/.puppeteer_cache so the browser can travel with a cached dependency tree. Apply that approach only when your deployment actually reuses that directory and the runtime user can read it. Otherwise, add an explicit browser-install step to the build and ensure the browser cache is included in the deployed artifact.
Distinguish postinstall failures from browser launch failures
A postinstall script that never ran is not the same problem as a browser that downloaded successfully but cannot launch. The distinction matters: repeatedly changing package-manager script policy will not repair missing operating-system libraries or filesystem permissions.
WSL and missing system libraries
Puppeteer’s troubleshooting guidance notes that WSL may need system libraries such as libgtk-3-dev, libnotify-dev, libgconf-2-4, libnss3, libxss1, and libasound2. If Chrome exists but fails when launched in WSL, check the launch error and install the required libraries for your distribution. This is a runtime prerequisite issue, not evidence that the postinstall download was skipped.
Windows cache permissions
The Puppeteer troubleshooting guide documents an icacls remedy for affected Windows Chrome sandbox files in the browser cache. Use the documented remedy for the specific affected cache directory and permissions problem; do not apply a broad permission change simply because installation took a long time. If the download itself failed, diagnose the installer output and download configuration instead.
A reliable install sequence for CI and containers
Make the browser installation an explicit, reproducible part of the build. This prevents a cache hit or a change in the build user from silently leaving the runtime without Chrome.
- Install dependencies under a known script policy. Confirm the package manager is configured to allow Puppeteer’s script, or plan to install the browser manually.
- Choose the browser owner. Use the full
puppeteerpackage if Puppeteer should download Chrome; usepuppeteer-coreonly when your project supplies or connects to a browser. - Set the cache deliberately when needed. In multi-stage builds or multi-user deployments, configure
PUPPETEER_CACHE_DIRorcacheDirectoryso the install and runtime stages agree. - Install the browser in the build. Run
npx puppeteer browsers installafter package installation if lifecycle scripts are not running. - Preserve and grant access to the browser. Make sure the selected cache or packaged browser survives deployment and is readable and executable by the runtime user.
- Test from the actual runtime environment. Run the application in the same container, CI job stage, or deployment identity that will launch Puppeteer; a local developer test does not prove that a separately built runtime has the cache.
Or skip the browser setup
If your goal is to capture a website screenshot rather than run browser automation in your own environment, ScreenshotNeo offers a screenshot API that returns an image or PDF from one GET request. The call below saves a WebP screenshot of the example URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Quick Recap
See the ScreenshotNeo API documentation for request details. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →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.
