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=true before installing the full puppeteer package, or set skipDownload: true in Puppeteer’s project configuration. Both settings stop Puppeteer’s installation step from downloading its browser; neither installs, finds, or launches a browser for your application. If your code will run a browser, provide one separately with puppeteer-core, an explicit executablePath, a supported Chrome channel, or a remote browser connection.
What skipping the download actually does
The full puppeteer package normally installs a browser version selected by Puppeteer. Skipping the download changes only that installation behavior. Your application still needs a browser binary at runtime, and Puppeteer must be told how to reach it unless your own browser-management layer handles that step.
Puppeteer’s documentation pages currently identify the configuration and launch API as version 25.12.0. The installation and configuration guides use the next documentation path, so check the pages against the version in your lockfile before standardizing a deployment. Operating system, package-manager policy and Puppeteer version can affect the exact browser location and compatibility.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsChoose the approach that matches your deployment
| Approach | Browser download during install | Who installs and updates the browser | How runtime selects it |
|---|---|---|---|
puppeteer with skipDownload |
No | Your image, host or provisioning process | executablePath, a Chrome channel, or your own connection code |
puppeteer-core |
No automatic Chrome download | Your team or a remote-browser provider | Your launch or connection options |
Normal puppeteer installation |
Yes | Puppeteer’s browser installer | Usually the browser managed by Puppeteer |
The normal installation is the least operationally complex and is the compatibility path Puppeteer documents as guaranteed: Puppeteer is tested against its bundled browser. A system Chrome or another externally managed browser can work, but test it with the Puppeteer version you deploy.
#1 Best Overall
Option 1: set PUPPETEER_SKIP_DOWNLOAD=true
Set the variable in the environment used by the dependency installation command. The setting must be present when the package’s install process runs, not only when your application starts.
macOS and Linux
export PUPPETEER_SKIP_DOWNLOAD=true
npm ciFor a one-time install:
PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteerWindows PowerShell
$env:PUPPETEER_SKIP_DOWNLOAD = "true"
npm ciWindows Command Prompt
set PUPPETEER_SKIP_DOWNLOAD=true
npm ciUse the variable in your CI job, Docker build stage or other environment that runs npm install or npm ci. Puppeteer also exposes browser-specific skip-download controls; use the variable documented for the browser you have configured rather than assuming the generic name applies to every browser target. See the configuration interface for the available names.
Option 2: set skipDownload: true in Puppeteer configuration
Create a project configuration file and set the option to a Boolean value. A JavaScript configuration is straightforward:
Free tools Windows power users keep installed
One-click scans. No signup required.
/** @type {import('puppeteer').Configuration} */
module.exports = {
skipDownload: true,
};Place the file where Puppeteer’s configuration discovery can find it (for example, the project root alongside package.json), then install the dependency. This option is for the full puppeteer package. Configuration files and Puppeteer environment variables are ignored by puppeteer-core.
If you change the setting after dependencies are already installed, rerun Puppeteer’s postinstall process or reinstall the dependency so the changed download policy takes effect. A configuration edit alone does not undo a browser that was already downloaded, and it does not provide a replacement binary.
The official configuration guide explains the file format and discovery rules at Puppeteer configuration.
Option 3: install puppeteer-core for external browser management
Use puppeteer-core when a container image, workstation policy, remote browser or separate provisioning service owns browser installation. The package does not download Chrome, so there is no skip flag to configure. Do not add skipDownload and expect it to have an effect; puppeteer-core ignores Puppeteer configuration files and environment variables.
npm install puppeteer-coreThis choice makes the ownership boundary explicit: your deployment must install a compatible browser and your code must select it or connect to it.
Tell Puppeteer which browser to launch
Use an explicit executable path
When Chrome or Chromium is installed by your operating system, container image or build script, pass its full path:
const puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
executablePath: '/path/to/Chrome',
headless: true,
});
const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'networkidle2'});
console.log(await page.title());
await browser.close();
})();Replace the placeholder with the path in your image or host. Linux, macOS and Windows use different installation paths, and a container may intentionally place the binary outside a standard desktop location. Keep the path in deployment configuration rather than hard-coding a developer laptop path.
Use a recognized Chrome channel
The launch API supports a Chrome channel for regular installations in known system locations:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallconst browser = await puppeteer.launch({
channel: 'chrome',
headless: true,
});A channel asks Puppeteer to locate that installed Chrome channel; it does not install Chrome. Availability and channel names depend on the operating system and installed browser. The LaunchOptions interface documents the current launch fields.
Connect to a remote browser
If a browser runs in another service, use that service’s endpoint and connection method instead of supplying a local executable. The remote service remains responsible for browser availability, versioning and network access. Keep credentials out of source control and verify that the endpoint is reachable from the application network.
Container and CI patterns
Build-time skip, runtime browser
A common image build sets the variable before installing Node dependencies, then installs Chrome or Chromium in a separate image layer. At runtime, launch with the resulting path. This keeps the dependency layer from downloading Puppeteer’s browser while preserving a reproducible browser installation under your control.
ENV PUPPETEER_SKIP_DOWNLOAD=true
RUN npm ci
# Install your approved browser in another build step.
Record the browser package version and rebuild when you intentionally update it. Because Puppeteer guarantees compatibility with its bundled browser rather than every system build, run your page and PDF tests against the exact pair shipped in the image.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Offline or restricted package networks
Skipping the download helps when the install environment cannot fetch a large browser archive, but the runtime environment still needs a browser. Copying a browser from an unrelated machine can introduce missing shared libraries, sandbox restrictions or an unsupported version. Prefer an approved base image or an internal artifact process that can be reproduced in CI.
When installation scripts were blocked
Some package-manager policies disable dependency install scripts. In that case Puppeteer may not download its browser even though you did not set a skip option, and launching can fail with a “Could not find Chrome” error.
- If you want Puppeteer-managed browser installation, configure the package manager to allow Puppeteer’s install script and reinstall.
- If you intentionally manage the browser, install one separately and launch with
executablePath, a suitablechannelor a remote connection. - For a manual Puppeteer-managed installation, use the Puppeteer browsers command documented in the installation guide, then verify the cache or executable location used by your deployment.
Do not treat a successful npm install as proof that a browser exists. Add a startup check that reports the resolved path and fails early with an actionable message.
Rank #4
Verify the setup before shipping
- Install dependencies with the environment variable or configuration option in place.
- Confirm that the browser binary exists in the build or runtime image and that its shared libraries are present.
- Run a minimal launch-and-close script using the same user, working directory and environment as production.
- Open a known test page and wait for the condition your application needs, such as
domcontentloadedornetworkidle2. - Run your screenshot, PDF and interaction tests against the exact Puppeteer and browser versions you will deploy.
A useful diagnostic distinguishes three failures: no binary (path or installation problem), binary cannot start (permissions, sandbox or missing libraries), and browser starts but is incompatible (version or launch-option problem).
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Troubleshooting common failures
“Could not find Chrome”
Cause: the download was skipped, an install script was blocked, or the expected cache was not copied into the runtime image.
Fix: install a browser yourself and set executablePath or channel, connect to a remote browser, or allow the normal Puppeteer install. Check the path from inside the running container, not only on the build host.
The variable appears to be ignored
Cause: it was set after installation, misspelled, scoped to a different shell or used with puppeteer-core.
Fix: print the variable in the install job, set it before npm ci, use the exact spelling PUPPETEER_SKIP_DOWNLOAD, and remember that puppeteer-core has no automatic browser download to suppress.
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 →A configuration change had no effect
Cause: Puppeteer’s postinstall step already ran.
Fix: rerun the postinstall script or reinstall after changing skipDownload. Remove stale browser caches only if your build policy requires it; deleting a cache does not install a replacement.
Chrome starts locally but not in CI
Cause: the CI image uses another path, user, architecture or set of system libraries; sandbox policy may also differ.
Fix: inspect the binary path inside CI, install the required OS dependencies, run the minimal launch test as the production user, and keep browser provisioning in the same image or environment that runs Puppeteer.
Pages behave differently with the system browser
Cause: Puppeteer’s compatibility guarantee applies to its bundled browser, while system channels and manually installed builds can update independently.
Fix: pin or intentionally update the browser, test the pair together, and use the bundled browser when minimizing compatibility variables matters more than download size.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance, reliability and cost trade-offs
- Install time and image size: skipping the automatic archive download can shorten dependency installation and avoid storing Puppeteer’s browser in the dependency layer. Your separately managed browser still consumes storage and must be delivered somehow.
- Reproducibility: Puppeteer-managed browsers provide a known pairing. System channels are convenient but can change when the host updates; pin externally managed browser packages when deterministic output matters.
- Security and maintenance: external ownership means your team must schedule browser security updates, test them and remove vulnerable builds.
- Operational debugging: explicit paths make failures visible, while remote browsers add network, authentication and service-availability dependencies.
- Offline operation: the install can be offline only if the Node packages and runtime browser are already available through your approved artifact process.
Or skip the browser setup
If your goal is simply to obtain reliable website images or PDFs, ScreenshotNeo provides a one-request API instead of requiring local Chromium provisioning. It accepts a URL and returns PNG, JPEG, WebP or PDF; before capture it accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets, with controls to turn each step off.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for authentication, output and options. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; response headers identify the page verdict and whether the request was billed. Its MCP server includes 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 shots. Create a free ScreenshotNeo account to try it.
Frequently asked questions
Frequently Asked Questions
Does skipping Chromium download make Puppeteer faster at runtime?
No. It changes dependency installation, not page execution. Runtime speed depends on the browser you provide, launch mode, page workload and network conditions.
Recommended Free Tools
Can I use skipDownload with puppeteer-core?
No. puppeteer-core does not perform the automatic Chrome download and ignores Puppeteer configuration files and environment variables. Select or connect to your externally managed browser in application code.
Is a system Chrome guaranteed to work with every Puppeteer release?
No. Puppeteer guarantees compatibility with its bundled browser. Validate the system browser and Puppeteer version together, especially after either one changes.
Will an already downloaded browser be removed by setting the skip flag?
No. The flag prevents an installation download; it does not delete existing browser files. Remove caches separately only when that is appropriate for your build or host policy.
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.
