Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Usually, no. Installing the standard puppeteer package downloads a compatible Chrome for Testing browser, so you generally do not need to install Chrome separately. The exceptions are puppeteer-core, configurations that skip browser downloads, and package managers that block Puppeteer’s install script. In those cases, provide a browser yourself or connect to one managed elsewhere.

What Puppeteer installs depends on the package

Puppeteer is a Node.js library that automates a browser. Its package choice determines who supplies that browser:

Package Does installation download a browser? What you need to do
puppeteer Yes, by default. It downloads a compatible Chrome for Testing browser and a chrome-headless-shell binary. Normally install the package and launch Puppeteer. Ensure the downloaded browser remains available where your code runs.
puppeteer-core No. Manage the browser yourself, select an installed browser with executablePath or channel, or connect to a remote browser.

The default behavior is documented in the Puppeteer installation guide; package configuration can change whether downloads occur. The configuration guide describes those settings.

Install and run the standard package

For the usual local setup, install puppeteer. Its install process downloads the browser needed for Puppeteer’s managed default.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. Install a current Node.js release appropriate for your project.

  2. In your project directory, run npm install puppeteer.

  3. Use Puppeteer’s default launch configuration:

    const puppeteer = require('puppeteer');
    
    (async () => {
      const browser = await puppeteer.launch();
      try {
        const page = await browser.newPage();
        await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
        console.log(await page.title());
      } finally {
        await browser.close();
      }
    })();

Save this as a JavaScript file and run it with node. With the browser download complete and the operating system dependencies present, it should launch the managed browser, visit the page and print its title. The installation guide gives approximate download sizes of 170 MB for macOS, 282 MB for Linux and 280 MB for Windows; these are approximate figures for the documented downloads and can change as browser builds change.

Use puppeteer-core or a separately installed Chrome

Provide an executable path

puppeteer-core does not download Chrome. Specify the browser binary your environment manages:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/absolute/path/to/chrome',
    headless: true,
  });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
    console.log(await page.title());
  } finally {
    await browser.close();
  }
})();

Replace the example path with the real executable path on the machine or container running the script. A path on your laptop will not necessarily exist in CI or inside a container.

Select a regular Chrome installation by channel

If Chrome is installed in a standard location recognized by Puppeteer, the channel launch option can select it instead of a path:

const browser = await puppeteer.launch({ channel: 'chrome' });

For example, use that option with the standard package when you explicitly want to use a regular Chrome installation. Puppeteer’s launch-options reference documents the available options and cautions that compatibility is guaranteed only for the bundled browser: launch options. A separately installed browser may work, but its version may not match the one expected by your Puppeteer release.

Connect to a browser managed remotely

puppeteer-core is also intended for applications that manage a browser separately or connect to a remote browser. That can keep browser installation out of an application package, but shifts responsibility for browser availability, version, connectivity and access controls to the system managing it. The installation guide describes this as a puppeteer-core use case: Puppeteer installation.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Fix “Could not find Chrome”

This error often means Puppeteer expected a managed browser but its download did not run, was skipped, or is not visible to the running process. Package managers may block dependency install scripts, preventing Puppeteer’s postinstall browser download. The official installation guide documents installing the browser after package installation.

  1. Check which package your project uses. With puppeteer-core, no browser download is expected; provide a browser in your launch options.

  2. If you use puppeteer, check whether your package manager allowed Puppeteer’s install script to run and whether browser downloads were disabled through configuration or environment variables.

  3. Install the managed browser explicitly after the package is installed: npx puppeteer browsers install. If you use another package manager, follow its equivalent command and install-script procedure in the installation guide.

    Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  4. Confirm that the browser cache used during installation is available to the runtime process. The default cache is ~/.cache/puppeteer; PUPPETEER_CACHE_DIR can configure a different location.

  5. If installation happens in a build stage and execution happens in another container or stage, ensure the browser files and cache are carried into the runtime environment.

Download skipping and cache location are described in the configuration guide. A successful package installation alone does not prove that the expected browser is present at runtime.

Match the browser to the Puppeteer release

Puppeteer publishes a version mapping between its releases and Chrome for Testing. Check the row for the version installed in your project rather than assuming that the newest system Chrome is the best match. The supported-browser page identifies Chrome for Testing as the supported browser and the bundled/downloaded version as the one Puppeteer guarantees: supported browsers.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

If you choose a system browser, verify it against that release-specific mapping and test it in the target environment. Puppeteer’s API reference puts the distinction plainly: “Note that Puppeteer is only guaranteed to work with the bundled browser, so use this setting at your own risk.” This warning appears in the official launch-options documentation.

Account for operating-system and container dependencies

Finding the Chrome binary is only one part of a successful launch. The browser also needs compatible system libraries and environment configuration. In containers and Linux deployments, a browser can be installed and still fail because dependencies are missing or sandbox behavior differs from the target environment.

Choose who manages the browser

Setup Browser owner Selection Main consideration
puppeteer default Puppeteer’s install process downloads the compatible browser. Managed default Keep its download and cache available in the runtime environment.
puppeteer-core with local browser Your application or deployment executablePath or channel Manage installation and check browser compatibility yourself.
puppeteer-core with remote browser Your remote-browser system Connect to the remote browser Manage connectivity, browser version and remote service availability.

For most projects that want the simplest supported local setup, use puppeteer and its downloaded browser. Choose puppeteer-core when you deliberately want your application or another system to own the browser lifecycle.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If your task is to capture a website image or PDF rather than automate a browser interaction, a screenshot API can avoid installing and maintaining Chrome in your application environment. ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP or PDF.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For example, using cURL:

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

Replace YOUR_API_KEY with your key. The call saves the returned image as shot.webp. See the ScreenshotNeo documentation for request options and response details. The API is a screenshot alternative, not a replacement for Puppeteer when you need arbitrary browser actions or application logic.

Sign up for ScreenshotNeo and get 1,000 free screenshots a month, with no card required.

Common setup problems and fixes

Symptom Likely cause What to check
Could not find Chrome The install script was blocked, the browser download was skipped, or the browser is absent from the runtime cache. Run npx puppeteer browsers install, review download configuration, and check cache visibility.
puppeteer-core fails to launch without a path The package does not supply a browser. Set a valid executablePath, use a recognized channel, or connect to a managed remote browser.
Works locally but not in CI The CI image lacks the browser, cache, libraries or configuration present locally. Inspect the actual runtime image and ensure the build’s browser files are available there.
Browser binary exists but launch fails Operating-system dependencies, sandbox configuration or platform compatibility may be wrong. Use the platform troubleshooting guide and test dependencies in the target image.
System Chrome launches inconsistently Its version may not match the Puppeteer release’s expected browser. Check the supported-browser mapping; try the bundled browser to isolate a compatibility mismatch.

Frequently Asked Questions

Does puppeteer-core download Chrome?

No. It does not download a browser; provide one or connect to a remote browser.

Can Puppeteer use my installed Chrome?

Yes. Select it with a recognized channel or its executablePath, but Puppeteer guarantees compatibility only with its bundled browser.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Does Puppeteer need Chrome installed on the host when running in a container?

Not necessarily. The standard package downloads its managed browser, but that browser and its required operating-system dependencies must be available in the container that runs Puppeteer.

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.