npm install puppeteer fails while downloading the browser
ERROR: 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.
Fix it fast
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 chrome2Match what you see, then jump to its fix
- 1
HTTP_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
The 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
The download completes, then the install step fails while extractingunzip (Linux and macOS) or tar.exe (Windows) is missingFix - 4
The host is blocked, or the build runs offline, so the postinstall step always failsThe build machine cannot download Chrome at allFix
- 1
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-agent2Fix
Install proxy-agent in the project and retry the download.
npm install proxy-agent
npx puppeteer browsers install chrome3Verify
The download finishes and the debug output ends with the installed path.
NODE_DEBUG="puppeteer:browsers:install" npx puppeteer browsers install chromeConfirmed by pptr.dev
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 chrome3Verify
The download completes without a certificate error.
ls ~/.cache/puppeteer/chromeConfirmed by pptr.dev
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 unzip2Fix
Install unzip and run the install again.
sudo apt-get update && sudo apt-get install -y unzip
npx puppeteer browsers install chrome3Verify
The browser folder now exists in the cache.
ls ~/.cache/puppeteer/chromeConfirmed by pptr.dev
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-browser2Fix
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.jsConfirmed by pptr.dev
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix