Install Puppeteer and fix browser executable/cache problems

Installing the JavaScript package and installing a compatible browser are distinct steps. A browser-cache error usually needs a specific install/path/user diagnosis—not disabling the sandbox or deleting every cache.

Choose the package and runtime

puppeteer manages downloaded browser defaults/configuration. puppeteer-core is appropriate when you deliberately manage a binary or remote browser; it does not perform the browser download and ignores Puppeteer’s configuration defaults. Give core a real executablePath/channel or supported connection.

Use a supported Node.js release and the browser installed by Puppeteer. A browser that starts successfully may still be incompatible with the APIs your script uses.

Install in your application project

Install the library directly in your own project:

npm install puppeteer

The package’s installation manages its browser download. Install and runtime must resolve the same configuration and account. If you choose a custom cache directory, configure it in your own application and carry the required browser into the runtime. See the beginner tutorial for a complete inline browser script.

Blocked install scripts

Some package-manager policies block dependency scripts. The package can be present in node_modules while its browser is missing. Check the installation output and your package manager’s script policy.

After installing the package, use its own local CLI from your application directory:

node node_modules/puppeteer/lib/puppeteer/node/cli.js browsers install chrome

Using the local CLI keeps browser installation aligned with the package and configuration in your project. Do not set skip-download unless a compatible browser is intentionally supplied.

Read-only executable diagnosis

Save/run this ESM snippet from the same project/account as your application:

import puppeteer from "puppeteer";
import { existsSync } from "node:fs";

const executable = await puppeteer.executablePath();

console.log({
    node: process.version,
    platform: process.platform,
    arch: process.arch,
    executable,
    exists: existsSync(executable),
});

Await executablePath() to get the default browser path. If you use launch({executablePath}), check that custom path separately. Paths can differ between a laptop, build image and runtime container.

Runtime user, cache and packaging

Installing as one user and running as another can point at different home and cache directories. Set a consistent cache location in your application when needed, and ensure the runtime user can read and execute the browser.

CI must carry the required browser artifact into the runtime, not just node_modules or an empty build folder. Key caches by the relevant package/browser/platform combination and verify the executable after restoration. Missing OS libraries are another layer: install them at image-build time for the supported distribution, then run the browser as non-root.

Check that the browser is available for your target OS and CPU architecture. If you use a system browser, configure its executable or channel explicitly and test the operations your application needs.

Troubleshooting

• Could not find Chrome: installation scripts, configured cache, runtime user and required build.
• Folder exists but executable missing: inspect/preserve only the exact confirmed incomplete build before reinstalling it.
• Configured executablePath missing: correct that path or install the intended compatible browser.
• Invalid Chrome version: validate numeric comparison input; channel tags are not accepted by that comparison grammar.
• WebSocket startup deadline: read browser startup output before changing timeout.

Never run broad recursive home/cache deletion. Preserve logs and use an explicit, validated build folder when a targeted repair is necessary. Do not remove lock files from an active browser profile.

Next steps

Run a small browser script in the environment where your application will run, not just on your laptop. For Docker setup and Chrome’s sandbox checks, see sandbox and Docker.