Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsThe fix depends on which Puppeteer package your Linux app uses. With puppeteer, install its managed browser from the project directory with npx puppeteer browsers install. With puppeteer-core, provide a browser yourself and point Puppeteer to its executable. Then check that the browser is installed in a cache the runtime user can access. The wording varies by version: older setups may say “Browser is not downloaded,” while current Puppeteer documentation describes a missing-browser error such as “Could not find Chrome (ver. …).”
First identify which browser setup you have
Puppeteer’s error usually means that the browser executable expected by the application is unavailable where it runs. That does not necessarily mean Linux has no browser installed: the browser may not have been downloaded, the package may be configured not to download one, or the runtime may not be able to see the browser installed during setup.
| Package or setup | Who supplies the browser? | First action |
|---|---|---|
puppeteer |
Puppeteer normally downloads a compatible Chrome for Testing browser. | Run npx puppeteer browsers install in the project context. |
puppeteer-core |
Your application or deployment supplies and manages the browser. | Set executablePath or, when appropriate, channel in launch options. |
| Browser installed during build, missing at runtime | The browser may exist in another user’s home directory or build stage. | Check the runtime user, cache directory, and executable path. |
Confirm the dependency actually loaded by your application rather than assuming it from a tutorial or package file. The official Puppeteer installation guide documents the package and managed-browser setup; the launch API documents browser selection.
Fix a missing managed browser for puppeteer
Run the browser install command from the project directory, with the same project dependencies and package-manager context used by the application:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
npx puppeteer browsers installThis is the documented manual remedy when a package manager blocks dependency install scripts. It installs the browser expected by the Puppeteer setup. Then rerun the application in the same environment and as the same user that will launch it.
Allow the install script when appropriate
Puppeteer normally installs its compatible browser through its package installation process. If your package manager suppresses dependency scripts, configure it to allow Puppeteer’s postinstall script or keep the explicit browser install command as a deployment step. The current installation guide gives npm’s allowScripts setting as an example; consult the guide for the package manager and version you use rather than copying an old, version-specific install script path.
Check the result in the actual runtime
A successful download on a developer workstation is not proof that a container, service account, CI job, or production process can access the same files. Run the install command in the environment that will launch the browser, or deliberately configure and share the browser cache as part of deployment.
Rank #2
Use puppeteer-core or a system browser deliberately
puppeteer-core does not download Chrome. It is intended for setups where your application controls the browser. Supply the actual Linux executable path using executablePath, or use channel when you have installed a browser in a standard location supported by Puppeteer.
Recommended Free Tools
const puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
executablePath: '/usr/bin/chromium',
headless: true
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}
})();Replace /usr/bin/chromium with the executable path that exists in your Linux environment. Installing distribution Chromium alone does not automatically tell Puppeteer to use it. For puppeteer-core, the launch API requires executablePath or channel. Puppeteer works best with its paired Chrome for Testing build; compatibility with every other Chrome version is not guaranteed. See the launch API documentation before relying on a separately updated system browser.
| Choice | Browser installation and updates | Runtime requirement | Compatibility consideration |
|---|---|---|---|
puppeteer with managed browser |
Puppeteer normally downloads its paired browser; your install or deployment process must permit that step. | The runtime must be able to access the managed-browser cache. | The paired Chrome for Testing build is the version Puppeteer works best with. |
puppeteer-core with external browser |
Your application or deployment installs and updates the browser. | Configure executablePath or channel and ensure the executable is accessible. |
Compatibility with arbitrary browser versions is not guaranteed. |
Check the browser cache, user, and deployment boundary
Puppeteer’s documented default managed-browser cache is $HOME/.cache/puppeteer. The value of $HOME depends on the user running the install process. If installation ran as a build user but the service launches as another account, the second account may have a different home directory and cache.
- Check which user runs the install command and which user runs the Node.js process.
- Check whether both steps run in the same container or build stage, and whether the browser files survive into the runtime image.
- Check whether the process has permission to read and execute the browser files.
- If the default location is unsuitable, configure a suitable
cacheDirectory, then runnpx puppeteer browsers installin that configured environment.
Puppeteer’s configuration guide warns that a globally cached browser can cause problems when a packaged application is moved to a fresh location. Treat the browser as a deployment dependency: place it where the deployed application can find it, rather than assuming a cache on the build machine will travel with the application.
When the browser download fails on Linux
A download failure is different from a browser that installed successfully but cannot be found. If installation cannot reach the download host, inspect the network and proxy configuration used by the install process. Puppeteer documents HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for downloading and running the browser. Browser downloads through a proxy require the optional proxy-agent package. See the configuration guide for details.
- Confirm the proxy variables are present in the environment where the browser install command runs.
- For proxied browser downloads, install the documented optional
proxy-agentdependency. - After correcting network access, rerun
npx puppeteer browsers installand check that the runtime can access the resulting cache.
Common errors and what to do
| Symptom | Likely cause | Fix |
|---|---|---|
Browser is not downloaded or Could not find Chrome (ver. ...) |
The managed browser is missing, or the process is looking in a different cache. | For puppeteer, run npx puppeteer browsers install in the app’s environment; check the runtime user and cache. |
| The error persists after installing Chromium through Linux packages | Puppeteer is not automatically selecting that system executable. | Set the real executable path with executablePath, or use an appropriate channel. |
| Works locally but not in a container or service | The browser was installed for another user, in another stage, or in a cache unavailable to the runtime. | Install in the runtime image or configure a shared cacheDirectory; verify access under the launching user. |
| Browser-management command cannot download the browser | Network restrictions or proxy settings block the download. | Set the documented proxy variables and install proxy-agent if downloads must pass through a proxy. |
puppeteer-core launches without a browser |
The package does not manage or download Chrome for you. | Provide a browser and specify executablePath or channel. |
Plan for install size and reliability
The Puppeteer installation guide lists an approximate Linux browser download size of about 282 MB for documentation version 25.12.0, observed September 30, 2026. Treat that as a planning estimate from the guide, not a permanent size guarantee. Make sure your build or deployment process allows the download and retains the browser where the application needs it.
For repeatable deployments, keep the Puppeteer dependency, browser installation step, cache location, and runtime user consistent. If you choose a system browser instead, manage its installation and updates yourself and validate it against the Puppeteer version you deploy; the documentation does not guarantee every external browser version will work identically.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your task is to produce website screenshots rather than run a custom Puppeteer workflow, ScreenshotNeo offers a screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF. It handles browser setup for the capture request; it is not a replacement for Puppeteer when you need arbitrary browser automation.
cURL example, with the endpoint options documented at ScreenshotNeo’s API documentation:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie/consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools 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.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently asked questions
Is this error specific to Linux?
No. The underlying issue is whether the expected browser is available to Puppeteer. This article focuses on Linux paths, users, caches, and deployment environments.
Can I use Firefox instead of Chrome?
The browser setup discussed here concerns Puppeteer’s managed Chrome for Testing browser and externally selected Chrome or Chromium. The cited setup guidance does not establish Firefox as a direct fix for this missing-Chrome error.
Does the old node_modules/puppeteer/install.js command remain the universal solution?
No. Use the current browser-management command documented by Puppeteer: npx puppeteer browsers install.
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.
