Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install puppeteer fails while downloading the browser

ErrorERROR: Failed to set up Chromium r782078! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.

Short answer

Installing puppeteer downloads Chrome for Testing in a postinstall step. When that download cannot finish, the install fails with a message that tells you to set PUPPETEER_SKIP_DOWNLOAD. The cause is almost always the network path: a proxy without proxy-agent, a company CA, a missing unzip, or a blocked host.

  • Applies to Puppeteer 24, Node.js 22, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the download alone with debug output on. It prints each step and the exact network or extract error.

    NODE_DEBUG="puppeteer:browsers:install" npx puppeteer browsers install chrome
  2. 2Match what you see, then jump to its fix

    1. 1HTTP_PROXY or HTTPS_PROXY is set in the shell, and the download times out or is refusedA proxy is set but proxy-agent is not installedFix
    2. 2The download fails with a TLS certificate error, and browsers on the same network work only after your company CA is installedA company proxy re-signs HTTPS with its own CAFix
    3. 3The download completes, then the install step fails while extractingunzip (Linux and macOS) or tar.exe (Windows) is missingFix
    4. 4The host is blocked, or the build runs offline, so the postinstall step always failsThe build machine cannot download Chrome at allFix

What does the error look like?

  • ERROR: Failed to set up Chromium r782078! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.
  • Could not find Chrome (ver. ...)

Cause 1 of 4

A proxy is set but proxy-agent is not installed

1Check

The browser download and install CLI respect HTTP_PROXY, HTTPS_PROXY and NO_PROXY, but only when the proxy-agent package is installed.

env | grep -i proxy
npm ls proxy-agent

2Fix

Install proxy-agent in the project and retry the download.

npm install proxy-agent
npx puppeteer browsers install chrome

3Verify

The download finishes and the debug output ends with the installed path.

NODE_DEBUG="puppeteer:browsers:install" npx puppeteer browsers install chrome

Confirmed by pptr.dev

Did this fix it?

Cause 2 of 4

A company proxy re-signs HTTPS with its own CA

1Check

Puppeteer's download honors NODE_EXTRA_CA_CERTS for extra trusted CAs. SSL_CERT_FILE and SSL_CERT_DIR have no effect on downloads.

echo "$NODE_EXTRA_CA_CERTS"

2Fix

Point NODE_EXTRA_CA_CERTS at your company root certificate file and install again. Do not set NODE_TLS_REJECT_UNAUTHORIZED=0, which turns checking off.

export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem
npx puppeteer browsers install chrome

3Verify

The download completes without a certificate error.

ls ~/.cache/puppeteer/chrome

Confirmed by pptr.dev

Did this fix it?

Cause 3 of 4

unzip (Linux and macOS) or tar.exe (Windows) is missing

1Check

Chrome on Linux or macOS needs unzip, and on Windows it needs tar.exe.

command -v unzip

2Fix

Install unzip and run the install again.

sudo apt-get update && sudo apt-get install -y unzip
npx puppeteer browsers install chrome

3Verify

The browser folder now exists in the cache.

ls ~/.cache/puppeteer/chrome

Confirmed by pptr.dev

Did this fix it?

Cause 4 of 4

The build machine cannot download Chrome at all

1Check

Puppeteer can skip its bundled download and use a Chrome you already installed. The puppeteer-core package never downloads a browser.

which google-chrome chromium chromium-browser

2Fix

Skip the download at install time, then launch with the path of the installed Chrome.

PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteer

// in code
const browser = await puppeteer.launch({
  executablePath: '/usr/bin/google-chrome',
});

3Verify

The script launches the browser and opens a page.

node scrape.js

Confirmed by pptr.dev

Did this fix it?

How do I stop it coming back?

  • Keep proxy-agent in the project's dependencies if builds run behind a proxy.
  • In CI, cache the folder named by PUPPETEER_CACHE_DIR or the default ~/.cache/puppeteer so the download runs once.
  • On package managers that block install scripts, run npx puppeteer browsers install as an explicit build step.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.