How to Check Whether Puppeteer Can Download a Browser

Puppeteer can download its compatible browser when the puppeteer package’s install script runs and downloads have not been disabled. To check whether it can download one, inspect the install-script and skip-download settings, confirm the cache path, and run Puppeteer’s browser installation command. Then test launching the browser separately: a downloaded file does not guarantee it can launch in your environment.

1. Check the package and install scripts

The standard puppeteer package downloads a compatible Chrome for Testing browser during installation. If your package manager blocks dependency install scripts, that automatic download can be skipped. The official installation guide documents npx puppeteer browsers install as the manual installation command. Puppeteer installation guide.

First, confirm which package your project uses:

npm ls puppeteer puppeteer-core

puppeteer-core does not download Chrome. It is intended for workflows where you manage a browser separately or connect to a remote browser. If your project uses it, a missing local browser is expected unless you install and configure one yourself.

If you use puppeteer, check your package manager’s install-script policy and installation output. If scripts were blocked, allow the Puppeteer install script according to your package manager’s documented configuration, then reinstall the package or run the manual browser install command below. Do not assume that a successful package installation means its browser download ran.

2. Check whether downloads are disabled

Look for settings that skip browser downloads. Puppeteer’s configuration supports the PUPPETEER_SKIP_DOWNLOAD environment variable and a skipDownload configuration option; browser-specific skip settings may also apply. Environment variables can override configuration values. See the Puppeteer configuration guide.

Check the environment in the same shell or process environment used for installation:

# macOS or Linux
printenv PUPPETEER_SKIP_DOWNLOAD

# PowerShell
$env:PUPPETEER_SKIP_DOWNLOAD

An unset value is different from a value explicitly set to skip downloads. Also inspect Puppeteer configuration files and CI or container settings for skipDownload or browser-specific equivalents. The exact active configuration matters: checking your interactive shell alone will not reveal an environment variable set only in the build job.

3. Locate Puppeteer’s browser cache

Since Puppeteer v19.0.0, the default cache directory is ~/.cache/puppeteer. PUPPETEER_CACHE_DIR or the cacheDirectory configuration option can change it. The environment that installs the browser and the environment that launches it must resolve to the same effective cache location. See the configuration guide.

Check the default directory on macOS or Linux:

ls -la ~/.cache/puppeteer

On Windows, inspect the directory under your home folder, typically %USERPROFILE%\.cache\puppeteer, unless configuration changes the cache path. To inspect the environment override:

# macOS or Linux
printenv PUPPETEER_CACHE_DIR

# PowerShell
$env:PUPPETEER_CACHE_DIR

A missing default folder does not prove that no browser was downloaded; Puppeteer may be configured to use another directory. Likewise, a populated cache does not prove the installed browser can start.

4. Install the browser manually

From the project directory, run Puppeteer’s documented browser installation command:

npx puppeteer browsers install

This is useful when a package manager blocked the automatic install script or when you need to populate the browser cache in a build environment. Run it with the same Puppeteer configuration and cache settings that the application will use.

The official installation guide lists approximate Chrome for Testing download sizes of 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. Treat these as rough expectations, not pass/fail thresholds; browser versions and packaging can change. Puppeteer’s guide also says it downloads a chrome-headless-shell binary starting with v21.6.0. Installation guide.

5. Run a separate launch check

Once installation completes, test launching the browser through Puppeteer. Save this as check-browser.cjs and run node check-browser.cjs from the project directory:

const puppeteer = require('puppeteer');

(async () => {
  let browser;
  try {
    browser = await puppeteer.launch({ headless: true });
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
    console.log('Browser launched and loaded the page.');
  } catch (error) {
    console.error('Browser launch check failed:', error);
    process.exitCode = 1;
  } finally {
    if (browser) await browser.close();
  }
})();

This checks more than whether files exist: Puppeteer must resolve a browser, start it, create a page, and navigate. A navigation failure can also come from network access or the target site, so read the reported error rather than treating every failure as a missing download.

If you use ES modules, the equivalent import is import puppeteer from 'puppeteer';; save the script with an .mjs extension or configure the project for modules. The launch check requires a compatible Puppeteer package and browser cache in the runtime environment.

6. Troubleshoot common failures

Symptom	Likely cause	What to do
`Could not find Chrome (ver. ...)`	The expected browser is absent from the cache Puppeteer is using. A blocked install script or skip-download setting may have prevented installation; the runtime may also be using a different cache path.	Check install-script policy and skip-download settings, verify `PUPPETEER_CACHE_DIR` or `cacheDirectory`, then run `npx puppeteer browsers install` in the environment that needs the browser. The wording is documented in the installation guide.
`Could not find expected browser locally`	Puppeteer cannot find the browser it expects in its configured local cache.	Confirm package choice, effective cache path, and download settings. Install the browser with `npx puppeteer browsers install`. See Puppeteer troubleshooting.
The install command succeeds but launch fails	Installation and launch are separate checks. The process may have a different cache path, or the environment may not be able to start the downloaded browser.	Run the launch check in the actual runtime or deployment environment. Confirm that installation and runtime use the same configuration. Investigate the specific launch error and environment requirements.
Using `puppeteer-core` with no browser configured	`puppeteer-core` does not download a browser.	Use `puppeteer` if you want its managed browser download, or install/manage a browser separately and configure Puppeteer to use it.
A separately installed browser is found but behaves incompatibly	Puppeteer guarantees compatibility with its bundled browser, not arbitrary separately managed executables.	Prefer the browser installed for your Puppeteer version. If you manage one yourself, configure its executable path and account for compatibility and update ownership. See Puppeteer configuration API.

7. Choose who manages the browser

Automatic download is usually simplest when you use puppeteer, permit its install script, and keep the install and runtime cache paths aligned. Managing a browser separately can fit remote-browser or controlled deployment workflows, but then you own installation, updates, executable configuration, and compatibility checks. Puppeteer supports executablePath for a separately managed browser; its compatibility guarantee applies to the bundled browser. See the launch options.

Automatic download: use puppeteer, allow its install script, avoid skip-download settings, and preserve the configured cache for runtime.
Separate browser management: install the browser through your chosen workflow, configure its executable or remote connection, and test it with the same runtime environment.
CI and containers: install the browser in the image or job that runs Puppeteer, and keep cache configuration consistent between build and execution.

Or skip the browser setup

If your goal is to capture a website screenshot rather than control a browser, ScreenshotNeo provides a screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

FAQ

Does installing Puppeteer always download Chrome?

The puppeteer package normally downloads its compatible browser during installation, provided its install script runs and downloads are not disabled. puppeteer-core does not download Chrome.

Where should I look for the downloaded browser?

By default, Puppeteer uses ~/.cache/puppeteer since v19.0.0. Check PUPPETEER_CACHE_DIR and cacheDirectory for overrides.

Is finding the browser in the cache enough?

No. Run a launch check in the environment where your application runs; the browser may be present but unable to start there.

Can I point Puppeteer at another Chrome installation?

Yes. Puppeteer supports executablePath, but its compatibility guarantee is for the browser it bundles.