If Puppeteer reports Could not find Chrome (ver. ...), first determine whether Chrome was never downloaded or whether Puppeteer is looking in a different cache or runtime. The usual fix is to install the browser explicitly with npx puppeteer browsers install, or allow Puppeteer’s installation script to run. If you use puppeteer-core or manage Chrome yourself, launch with an explicit executablePath or a standard-install channel. A browser that is found but will not start is a separate Linux dependency or sandbox problem.
What the error means
The standard puppeteer package normally downloads a compatible browser during installation. Your JavaScript package can therefore be present while the browser binary is missing. Package managers can block dependency install scripts, which prevents Puppeteer’s browser download and commonly produces Could not find Chrome (ver. ...). See the Puppeteer installation guide for the package-manager-specific behavior.
puppeteer-core is different: it is intended for a browser that you install or operate separately and does not download Chrome. Likewise, a CI job, container, or deployment process may run as a different user from the one that installed the browser. Treat those as configuration and environment issues rather than repeatedly reinstalling your application.
Fix the common case: install Puppeteer’s browser
1. Check which package you installed
npm list puppeteer puppeteer-core- If
puppeteeris listed, continue with the managed-browser steps. - If only
puppeteer-coreis listed, skip to the separately managed browser section. - If neither package is listed, install the one your project expects before troubleshooting the browser.
2. Run the documented browser installer
From the project directory, run the command for your package manager:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
npx puppeteer browsers installyarn dlx puppeteer browsers install
pnpm dlx puppeteer browsers install
bun x puppeteer browsers installThese commands download the browser revision required by the Puppeteer version that is being invoked. Re-run your script after the command completes. The command is documented at pptr.dev/next/guides/installation.
3. Allow the installation script when your package manager blocked it
Recent npm workflows, pnpm, Yarn Berry, Bun, and Deno configurations can restrict dependency install scripts. If the restriction skipped Puppeteer’s post-install download, configure your package manager to allow Puppeteer’s script, then reinstall the package or run the browser installer above. The Puppeteer guide shows an allowScripts example for npm; do not copy that setting as a universal configuration for every package manager or version. Check the policy syntax for the tool and release you actually use.
A reliable sequence is:
- Remove the failed dependency installation according to your package manager’s normal workflow.
- Change the install-script policy to permit Puppeteer.
- Install dependencies again.
- Run
npx puppeteer browsers installexplicitly and verify the browser is present before starting your application.
Check cache and user identity
Since Puppeteer v19.0.0, the default browser cache is ~/.cache/puppeteer, derived from the home directory of the user running the install. A browser installed as one user is invisible to a process running with another HOME, inside another container layer, or under a different CI account. The troubleshooting guide documents this cache behavior at pptr.dev/next/troubleshooting.
Compare the installation and runtime environments
- Print the effective user and home directory in both stages.
- Check whether the install runs in a build image while the script runs in a fresh runtime image.
- Check whether a CI cache restores the same directory that the runtime reads.
- Confirm that the process can read and execute files in the cache.
On Unix-like systems, these quick checks expose the most common mismatch:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
whoami
printf 'HOME=%sn' "$HOME"
printf 'PUPPETEER_CACHE_DIR=%sn' "$PUPPETEER_CACHE_DIR"
ls -la "${PUPPETEER_CACHE_DIR:-$HOME/.cache/puppeteer}"Set one cache directory deliberately
You can choose a shared location with PUPPETEER_CACHE_DIR:
export PUPPETEER_CACHE_DIR=/var/cache/puppeteer
npx puppeteer browsers installMake sure the account that launches Chrome can read and execute that directory. You can also set cacheDirectory in .puppeteerrc.js or puppeteer.config.js:
module.exports = {
cacheDirectory: '/var/cache/puppeteer',
};After changing a configuration-file cache directory, reinstall Puppeteer so the new setting is applied during browser installation. Do not configure one path during an image build and another at runtime.
Use an externally managed Chrome correctly
With puppeteer-core, a remote browser, or an organization-managed Chrome installation, Puppeteer expects you to provide the browser location. The official installation guide says to pass an explicit executablePath, or use channel when Chrome is installed in a standard location.
Rank #3
Explicit executable path
const puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
executablePath: '/opt/google/chrome/chrome',
headless: true,
});
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
console.log(await page.title());
await browser.close();
})();Replace the path with the executable that exists in the same environment as your Node process. A path from your laptop will not work inside a container or a hosted runner unless the binary is there too.
Standard installation channel
const puppeteer = require('puppeteer-core');
const browser = await puppeteer.launch({ channel: 'chrome' });Use channel only when the corresponding browser is installed where Puppeteer expects a standard-channel installation. If discovery still fails, switch to an absolute executablePath and verify it directly.
Distinguish “not found” from “found but will not launch”
Do not apply Linux dependency fixes to a browser that is absent. First establish that Puppeteer has a real executable path. If it has one but Chrome exits immediately, you are on the launch-failure branch.
Linux shared libraries
Puppeteer’s troubleshooting page recommends inspecting unresolved libraries with:
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
ldd /path/to/chrome | grep notInstall the missing libraries using the dependency names and versions appropriate for your Linux distribution. Debian- and CentOS-oriented package lists in documentation can age; use your distribution’s current packages rather than treating one static list as universal. Re-run the ldd check until no required library is reported missing.
Sandbox and security policy
Sandbox restrictions, AppArmor rules, and container security profiles can stop a correctly located browser. The Puppeteer troubleshooting guide discusses Linux sandbox cases and AppArmor behavior on Ubuntu 23.10 and later. Diagnose these only when the error mentions sandbox, permissions, or policy. Running Chrome with --no-sandbox is strongly discouraged because it removes a security boundary; prefer fixing the host, container, or policy configuration.
CI, containers, and deployment checks
- Build versus runtime image: install the browser in the image that actually runs the script, or copy the complete Puppeteer cache into the runtime image.
- Cache keys: include the Puppeteer version, operating-system image, architecture, and cache directory in CI cache identity.
- Environment variables: set
HOMEandPUPPETEER_CACHE_DIRconsistently in install and execution steps. - Permissions: run the browser as a user that can read, execute, and create temporary files in the configured locations.
- Architecture: an x64 browser binary cannot run on an incompatible architecture without an appropriate compatibility layer.
- Network restrictions: if the installer cannot reach the download host, perform the download in an allowed build stage and preserve the resulting cache.
Diagnostic commands and expected outcomes
- Run
npm list puppeteer puppeteer-core. This identifies who is supposed to manage Chrome. - Run
npx puppeteer browsers install. A successful completion should place a browser in the active cache. - Print
HOMEandPUPPETEER_CACHE_DIRin both install and runtime contexts. They should resolve to the same intended location. - For a managed browser, test the exact path with your operating system’s file and permission tools before launching.
- If the path exists but launch fails, run
ldd /path/to/chrome | grep noton Linux and follow the sandbox or policy branch indicated by the error.
Common errors and targeted fixes
| Symptom | Likely cause | Fix |
|---|---|---|
Could not find Chrome (ver. ...) immediately after install |
Install script was blocked or browser download was skipped | Run npx puppeteer browsers install or permit Puppeteer’s install script and reinstall. |
| Browser exists locally but not in CI | Different user, HOME, image layer, or cache directory |
Align environment variables and copy or restore the Puppeteer cache into the runtime environment. |
puppeteer-core cannot launch |
No browser is downloaded by that package | Install Chrome separately and pass executablePath or an appropriate channel. |
| Executable is found, then exits on Linux | Missing shared library, sandbox, or security-policy restriction | Use ldd ... | grep not, install distribution-appropriate libraries, and investigate policy logs; avoid --no-sandbox unless you accept the security consequences. |
Changing cacheDirectory appears to do nothing |
Existing browser was installed under the old configuration | Reinstall Puppeteer after changing the configuration-file cache directory. |
Or skip the browser setup
If your goal is simply to obtain reliable website screenshots rather than maintain a Puppeteer environment, ScreenshotNeo provides a website screenshot API and MCP server. A single request returns PNG, JPEG, WebP, or PDF; it handles browser setup for you.
Using the documented API examples (see ScreenshotNeo documentation):
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemscurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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 and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers identify the page verdict and whether the shot was billed.
- An MCP server exposes
take_screenshot,get_page_info, andcapture_pdfto 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 screenshots; every feature is on every plan.
Sign up for 1,000 free screenshots a month with no card.
Prevent the error next time
- Pin Puppeteer and record the browser-install command in your build instructions.
- Make install-script policy explicit in CI rather than relying on developer-machine defaults.
- Set one cache directory and preserve it between build and runtime stages.
- Log the effective user, home directory, Puppeteer version, and selected executable path at startup.
- Keep browser discovery tests separate from launch tests so a missing binary is not confused with a host dependency failure.
Frequently Asked Questions
Does installing Google Chrome on the host always fix Puppeteer?
No. The package may still be looking for its managed browser in the Puppeteer cache. Use the managed install command, or pass the installed browser’s exact executable path or channel.
Should I use –no-sandbox to make the error disappear?
Only a sandbox-specific launch failure points to that setting, and Puppeteer strongly discourages disabling the sandbox. Fix dependencies and security policy instead.
Why does the error appear only in production?
Production often uses a different user, HOME directory, container layer, architecture, or install-script policy. Compare those values with the environment where the browser was installed.
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.
