Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Set PUPPETEER_SKIP_DOWNLOAD before installing puppeteer. The variable tells Puppeteer to skip its installation-time browser download. Use the command that matches your shell:
- POSIX shells (Linux, macOS, and most CI runners):
PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteer - Windows Command Prompt:
set PUPPETEER_SKIP_DOWNLOAD=truefollowed bynpm install puppeteer - PowerShell:
$env:PUPPETEER_SKIP_DOWNLOAD = "true"followed bynpm install puppeteer
This setting affects installation, not whether a browser exists when your program runs. If you skip the download, provide a browser yourself or install one later.
What PUPPETEER_SKIP_DOWNLOAD does
The puppeteer package normally downloads a compatible Chrome for Testing release and a chrome-headless-shell binary during installation. Setting PUPPETEER_SKIP_DOWNLOAD=true changes that installation behavior: Puppeteer installs its Node.js package without fetching those browser binaries.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesPuppeteer maps the environment variable to its skipDownload installation option. The setting is read while the package installation script runs, so it must be present before npm install puppeteer, npm ci, or another install command that executes Puppeteer’s installer.
#1 Best Overall
Set it for one installation
Linux, macOS, and POSIX-compatible shells
PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteerThis is a one-command environment assignment. It applies only to that command and does not permanently alter your shell or project.
Windows Command Prompt
set PUPPETEER_SKIP_DOWNLOAD=true
npm install puppeteerset stores the variable in the current Command Prompt session. Close the window or clear the variable when you no longer want it:
set PUPPETEER_SKIP_DOWNLOAD=Windows PowerShell
$env:PUPPETEER_SKIP_DOWNLOAD = "true"
npm install puppeteerPowerShell keeps the value for the current session. Remove it with:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Remove-Item Env:PUPPETEER_SKIP_DOWNLOADnpm configuration and scripts
If you need the variable during a repeatable project command, define it in the environment that launches npm. For cross-platform projects, use your CI provider’s environment-variable settings or a platform-neutral environment-variable utility rather than relying on shell syntax from one operating system.
Persist the setting in project configuration
A configuration file is better than a shell command when every developer and build runner should use the same policy. Puppeteer searches supported files including .puppeteerrc.cjs, .puppeteerrc.js, .puppeteerrc.json, puppeteer.config.cjs, puppeteer.config.js, and a Puppeteer configuration in package.json.
For an ECMAScript-module configuration file, use:
/** @type {import('puppeteer').Configuration} */
export default {
skipDownload: true,
};Use the equivalent CommonJS form when your project is CommonJS:
/** @type {import('puppeteer').Configuration} */
module.exports = {
skipDownload: true,
};Environment variables take precedence over configuration-file options when both apply. After changing a download option, rerun the installation step. To install the browser later through Puppeteer’s supported installer, run:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
npx puppeteer browsers installEnvironment variable versus configuration file
| Approach | Scope | When it applies | Precedence | Best use |
|---|---|---|---|---|
PUPPETEER_SKIP_DOWNLOAD=true |
One shell session or command | Installation | Overrides configuration when applicable | Temporary builds, CI jobs, or a one-off install |
skipDownload: true |
Project-wide | Installation | Used unless an applicable environment variable overrides it | Consistent developer and CI setup |
| No skip setting | Default Puppeteer behavior | Installation | Not applicable | Let Puppeteer download its managed browser |
puppeteer versus puppeteer-core
puppeteer
The full puppeteer package includes installation logic for Puppeteer-managed browsers. By default it downloads a compatible Chrome for Testing release and a headless-shell binary. PUPPETEER_SKIP_DOWNLOAD and skipDownload: true control that download.
puppeteer-core
puppeteer-core does not download Chrome. It also ignores Puppeteer’s configuration files and environment variables. Choose it when your deployment owns the browser, and pass an executable path or a standard browser channel explicitly:
const puppeteer = require('puppeteer-core');
const browser = await puppeteer.launch({
executablePath: process.env.CHROME_PATH,
});Skipping the download for puppeteer therefore makes its browser-ownership model resemble puppeteer-core, but the packages are not interchangeable: puppeteer still contains its own browser-management behavior and configuration support.
Provide a browser at runtime
Skipping installation does not make puppeteer.launch() magically locate Chrome. Install Chrome or Chromium through your operating system, container image, or build process, then point Puppeteer to it:
const puppeteer = require('puppeteer');
const browser = await puppeteer.launch({
executablePath: process.env.CHROME_PATH,
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'networkidle2'});
console.log(await page.title());
} finally {
await browser.close();
}Set CHROME_PATH to the actual executable location in your operating system or container. If the path is wrong, Puppeteer can install successfully while every launch fails.
Rank #3
Re-enable or restore the browser download
Install after previously skipping
Remove the environment variable, change skipDownload to false or remove it, then run:
npx puppeteer browsers installThis is also the supported recovery when the package is present but its postinstall script did not run.
Package-manager scripts were blocked
Some package managers or security policies disable dependency install scripts. In that case, Puppeteer may be in node_modules without its browser. Allow the Puppeteer installation script according to your package manager’s policy, or run npx puppeteer browsers install explicitly in a trusted build step.
Recommended Free Tools
Be careful with false
Do not assume every Puppeteer version parses PUPPETEER_SKIP_DOWNLOAD=false identically. A reported issue in Puppeteer 21.3.6 showed a falsy environment value still causing the download to be skipped. Verify behavior against the exact version in your lockfile. Removing the variable entirely and using the supported browser-install command is less ambiguous.
Why Puppeteer still downloads Chrome in CI
- The variable was set after installation: Put it in the job environment before
npm ciornpm install. - The variable name is misspelled: Use the exact uppercase spelling
PUPPETEER_SKIP_DOWNLOAD. - The job uses a different shell:
set ..., PowerShell’s$env:syntax, and POSIX inline assignments are not interchangeable. - A cached dependency was restored: Inspect the installation logs and cache key; a fresh install may be needed to confirm behavior.
- A configuration file was not discovered: Keep the supported filename in the project location Puppeteer searches.
- You installed
puppeteer-core: Its browser behavior is independent of this variable.
Troubleshooting checklist
“Puppeteer installed, but no browser is found”
That is the expected result when the download was skipped. Install a browser yourself and set executablePath, or run npx puppeteer browsers install.
“The browser download failed”
Confirm that the variable was present in the same process that ran npm. In CI, print whether the variable is set without exposing unrelated secrets, then rerun the install. If you actually need Puppeteer-managed Chrome, remove the skip setting and run the browser installer.
“My config works locally but not in CI”
Check the filename, module format, working directory, and Puppeteer version in the lockfile. An environment variable supplied by CI can override the file, so inspect the job environment for PUPPETEER_SKIP_DOWNLOAD.
“Changing the setting had no effect”
Installation options are evaluated during installation. Rerun the install step after changing the variable or configuration, and account for package-manager caches.
Or skip the browser setup
If your goal is simply to obtain a reliable website screenshot, ScreenshotNeo provides a GET request without requiring you to install or manage Puppeteer and Chrome. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and bills only clean shots. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; each response reports the page verdict and billing status in X-Page-Verdict and X-Billed headers.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for all options, including viewport and device settings, full-page capture, selectors, JavaScript, waits, headers, cookies, PDFs, caching, asynchronous jobs, bulk capture, and signed links. ScreenshotNeo also includes an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Operational and cost considerations
Build speed and image size
Skipping a browser download can reduce installation time and dependency-cache size, especially in ephemeral CI jobs. The trade-off is that your image or runner must supply a compatible browser and its system dependencies.
Reproducibility
Puppeteer-managed downloads tie installation to the browser revision selected by your Puppeteer release. A user-managed browser gives your team control over the operating-system image and patch schedule, but you must test compatibility and maintain that image.
Security and network policy
Skipping the download is useful where build networks cannot reach browser distribution hosts. It does not remove the need for a browser at runtime, nor does it eliminate the permissions and sandbox requirements of headless Chrome.
FAQ
Does the variable skip Chromium at runtime?
No. It skips Puppeteer’s installation-time browser download. Runtime launch still requires an available browser.
Can I set it in .env?
Only if your process loads that file before npm starts; npm does not automatically load arbitrary .env files for every installation workflow. CI environment settings or a shell assignment are more predictable.
Should I use puppeteer-core instead?
Use it when you always manage the browser separately and want no Puppeteer download/configuration behavior. Use puppeteer with skipDownload when you still want the full package and may use Puppeteer’s browser installer later.
Frequently Asked Questions
Does PUPPETEER_SKIP_DOWNLOAD reduce the installed Puppeteer package size?
It prevents the browser binaries from being downloaded during installation; the Node.js package itself is still installed.
What command restores a browser after a skipped install?
Run npx puppeteer browsers install after removing or changing the skip setting.
Free tools Windows power users keep installed
One-click scans. No signup required.
Why does puppeteer-core ignore my setting?
That package intentionally does not download Chrome and does not read Puppeteer’s configuration files or environment variables.
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.
