How to Install Chromium for Puppeteer Without Downloading Chrome

Direct answer: Puppeteer does not install Chromium when you use puppeteer-core, or when you configure the regular puppeteer package to skip its browser download. You must install Chromium separately and pass its real executable path to launch(). The download setting does not install or locate Chromium for you.

Puppeteer works best with the Chrome for Testing version it downloads by default, and does not guarantee compatibility with arbitrary system Chromium versions. Pin and validate your browser and Puppeteer versions in the environment where your automation runs. See Puppeteer’s installation guide and launch API documentation.

1. Choose how Puppeteer should handle the browser

Approach	Use it when	What to know
`puppeteer-core`	Your application or deployment image manages the browser.	It does not download Chrome. You provide a browser executable path or supported channel when launching.
`puppeteer` with `skipDownload`	You want the regular Puppeteer package but need to manage the browser installation separately.	Configure the download skip before installing dependencies. The browser still must be present at runtime.

The regular puppeteer package downloads a Chrome for Testing build during installation (and a chrome-headless-shell binary). Puppeteer’s installation guide gives approximate download sizes of 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows; actual sizes can vary by release. puppeteer-core is the documented choice when you manage the browser yourself.

2. Install Chromium separately

Install Chromium using the package manager, base image, or browser-management process for the operating system that will run your application. Package names and executable locations differ across distributions and installation methods, so discover the path on the target system rather than copying a path from another machine.

For example, Puppeteer’s troubleshooting guide uses /usr/bin/chromium-browser as an example existing Chromium path. That is an example for a particular environment, not a universal path. The guide also covers Linux shared-library dependencies and warns that Chrome does not support Alpine out of the box. Check the troubleshooting guide for your deployment platform.

3. Option A: use puppeteer-core

This runnable example uses an environment variable for the executable path. Install the package with your project’s package manager, and set PUPPETEER_EXECUTABLE_PATH to the actual Chromium binary path before running it.

npm install puppeteer-core

// save as capture.mjs
import puppeteer from 'puppeteer-core';

const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
if (!executablePath) {
  throw new Error('Set PUPPETEER_EXECUTABLE_PATH to the installed Chromium executable');
}

const browser = await puppeteer.launch({
  executablePath,
  headless: true,
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  await page.screenshot({ path: 'shot.png', fullPage: true });
} finally {
  await browser.close();
}

Run it with the path set in your shell or deployment configuration:

PUPPETEER_EXECUTABLE_PATH=/path/to/chromium node capture.mjs

Replace /path/to/chromium with the path on the machine that runs Node.js. With puppeteer-core, explicitly select the browser using executablePath or a supported Chrome channel. It does not use Puppeteer configuration files or environment defaults in the same way as the full package.

4. Option B: keep puppeteer and skip its download

To retain the regular package, set PUPPETEER_SKIP_DOWNLOAD=true in the install environment:

PUPPETEER_SKIP_DOWNLOAD=true npm install puppeteer

Then launch it with the separately installed browser path:

// save as capture.mjs
import puppeteer from 'puppeteer';

const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
if (!executablePath) {
  throw new Error('Set PUPPETEER_EXECUTABLE_PATH to the installed Chromium executable');
}

const browser = await puppeteer.launch({ executablePath, headless: true });
try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  await page.screenshot({ path: 'shot.png', fullPage: true });
} finally {
  await browser.close();
}

Alternatively, put the setting in Puppeteer’s project configuration. For example, save this as .puppeteerrc.js in a project configured for ES modules:

export default {
  chrome: { skipDownload: true },
};

Puppeteer’s configuration API defines skipDownload, and environment variables can override configuration values. If changing the config to affect installation, use the project’s dependency installation workflow so the setting is applied during installation. See the configuration reference.

5. Confirm the browser path and runtime

On the deployment machine or in the container image, identify the installed Chromium executable. Use that exact path in PUPPETEER_EXECUTABLE_PATH.
Install the Node dependencies with the selected download configuration.
Run the capture script in the same environment that will run the application. A browser path on a developer laptop may not exist inside a container or CI runner.
Check that the browser launches, loads a representative page, and produces the expected screenshot or automation result.
Pin the Puppeteer and Chromium versions in your deployment process, then repeat the launch check when either version changes.

The official system requirements are version-sensitive. The cited documentation lists Node 22.12+ and supported Chrome for Testing platforms including Windows x64, macOS x64/arm64, Debian/Ubuntu Linux x64/arm64, and openSUSE/Fedora Linux x64/arm64. Check the requirements for the Puppeteer version you install; Chrome for Testing support does not mean every system Chromium build is supported.

6. Configuration options and behavior

Setting	Purpose	Important detail
`puppeteer-core`	Use Puppeteer without its automatic browser download.	Pass `executablePath` or a supported `channel` to launch.
`PUPPETEER_SKIP_DOWNLOAD=true`	Skip automatic browser download with the full package.	Set it in the environment where dependencies are installed.
`chrome.skipDownload`	Skip the Chrome download in Puppeteer configuration.	Environment variables may override configuration.
`executablePath`	Select a specific installed browser binary.	Must point to a real executable accessible to the Node process.
`channel`	Select a supported Chrome channel instead of a path.	Use only where supported and available in the runtime; for a system Chromium install, an explicit executable path is often clearer.

The configuration API also exposes browser-specific download settings. Consult its current reference if your project needs to manage more than the Chrome download.

7. Common problems and fixes

Symptom	Likely cause	Fix
Installation still downloads Chrome	The skip variable was absent during installation, or the configuration was not loaded by the installation workflow.	Set `PUPPETEER_SKIP_DOWNLOAD=true` in the dependency installation environment, or verify the project config location and rerun the install step.
`Could not find Chrome` or browser launch fails before opening a page	No browser was installed, or Puppeteer is still resolving its managed browser instead of the system binary.	Install Chromium separately and pass its actual path with `executablePath`.
`Failed to launch` or the executable is missing	The path is wrong for this OS, container, or runtime user.	Inspect the target environment, correct the path, and ensure the executable is readable and executable by the Node process.
Browser process exits immediately on Linux	Required shared libraries may be absent.	Install the OS dependencies described by Puppeteer’s troubleshooting guide for the distribution, then retry.
Launch works locally but fails in CI or a container	The runtime image may have a different filesystem, architecture, browser installation, or system libraries.	Install Chromium and its dependencies in the runtime image, and set the path there rather than relying on the host machine.
Unexpected browser behavior or protocol errors	The independently installed Chromium version may not match the Puppeteer version’s expected browser.	Test the versions together, pin a known working pair, or use the browser version bundled by the regular Puppeteer installation.
Alpine Linux launch problems	Chrome does not support Alpine out of the box, and its environment can differ from distributions covered by the standard instructions.	Review Puppeteer’s current platform guidance and choose a supported runtime or a browser setup compatible with your image.

Do not treat --no-sandbox as a routine fix for a missing executable or missing shared library. First identify the actual launch failure and address its cause.

8. Performance, reliability, and cost

Skipping the download reduces installation-time network transfer and avoids storing Puppeteer’s managed browser in the package-install workflow. It does not remove the browser from the system: Chromium still needs to be installed, kept available, and updated by your deployment process. The approximate default download sizes above indicate why teams may want to manage that transfer, but they are not fixed release sizes.

Managing Chromium yourself gives you control over the browser version and image lifecycle, while adding responsibility for compatibility checks, operating-system libraries, executable paths, and security updates. Puppeteer’s compatibility guarantee applies to its bundled browser; validate page behavior and launch reliability whenever you change Puppeteer, Chromium, the operating system image, or architecture.

9. Or skip the browser setup

If your goal is to capture website screenshots rather than run browser automation, ScreenshotNeo provides a website screenshot API and MCP server. It returns PNG, JPEG, WebP, or PDF from one GET request. The API documentation covers the available options.

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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before the shot, along with supported consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots.

10. FAQ

Does skipping the download install Chromium?

No. It only stops Puppeteer from downloading its browser. Install Chromium separately.

Can I use Google Chrome instead of Chromium?

The launch API can select an executable path or a supported Chrome channel. The browser must be available in the runtime, and compatibility with a version outside Puppeteer’s bundled browser is not guaranteed.

Which executable path should I use?

Use the path reported by the system where your code runs. Package and installation choices vary, so there is no single cross-platform path.

Should I choose puppeteer-core or the full package with skipDownload?

Choose puppeteer-core when your application explicitly manages the browser. Keep puppeteer with skipDownload when you need the full package but want the deployment environment to supply the browser.

Will any Chromium version work?

There is no compatibility guarantee for arbitrary versions. Test the browser and Puppeteer version together using the pages and features your application needs.