How to Install Puppeteer and Set Up Chrome
Install Puppeteer, get its compatible Chrome browser, and fix common setup problems. Includes runnable examples and a self-managed browser option.
For a typical Node.js project, install puppeteer. Its install process downloads a compatible Chrome for Testing build, so you usually do not need to install Google Chrome separately. If your package manager blocked install scripts, install the browser explicitly with npx puppeteer browsers install.
Use puppeteer-core instead when your application already has a remote browser or manages Chrome itself. That package does not download a browser; configure its executable path or channel when launching.
1. Check the prerequisites
The Puppeteer documentation lists Node.js 22.12 or later for version 25.12.0. TypeScript users need TypeScript 5.0.1 or later; the documentation specifies an ES2022-or-later target when type checking node_modules. These requirements can change, so check the system requirements for the version your project installs.
- Use a supported platform: Windows x64, macOS x64 or arm64, Debian/Ubuntu Linux x64 or arm64, or openSUSE/Fedora Linux x64 or arm64.
- On Windows, Chrome archive extraction requires
tar.exeor PowerShell. - On macOS and Linux, extraction uses
unzipunless the optionalyauzlpackage is installed.
See Puppeteer’s system requirements for the current version-specific requirements.
2. Install Puppeteer and its browser
Run the command for the package manager already used by your project, from the project directory:
# npm
npm install puppeteer
# Yarn
yarn add puppeteer
# pnpm
pnpm add puppeteer
# Bun
bun add puppeteerThe full puppeteer package downloads Chrome for Testing. Since Puppeteer 21.6.0 it also downloads a chrome-headless-shell binary. The documented approximate browser download sizes are 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. The default cache is ~/.cache/puppeteer (or the equivalent home-directory cache path); this global cache behavior is documented from Puppeteer 19.0.0 onward.
Installation and browser downloads are separate concerns: if the package is present but the browser is missing, use the explicit browser installation command in the troubleshooting section.
3. Run a first screenshot
Create screenshot.js in the project directory. This runnable CommonJS example launches Puppeteer’s managed browser, opens a page, saves a full-page PNG, and closes the browser even if capture fails:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'example.png', fullPage: true });
} finally {
await browser.close();
}
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});Run it with node screenshot.js. puppeteer.launch() defaults to Chrome in headless mode. headless: true uses the new headless mode; headless: 'shell' selects the separate headless shell. See the LaunchOptions reference for the launch settings supported by your installed release.
4. Choose who manages Chrome
| Setup | Install | Browser configuration | Use it when |
|---|---|---|---|
| Puppeteer-managed browser | puppeteer |
Normally none; Puppeteer downloads its compatible Chrome | You want the straightforward local setup and browser version managed with Puppeteer |
| Self-managed or remote browser | puppeteer-core |
Supply a browser endpoint, executable path, or channel as appropriate | Your deployment provides Chrome or a remote browser independently |
Puppeteer documents its bundled browser as the compatibility-guaranteed option. If you choose an independently installed Chrome version or channel, verify that combination in the environment where the code will run.
Use a locally managed Chrome executable
Install the core package when you do not want Puppeteer to download a browser:
npm install puppeteer-coreThen point launch at the Chrome executable available on that machine. Replace the example path with the actual path for your operating system and deployment:
const puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
executablePath: '/path/to/Chrome',
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'example.png', fullPage: true });
} finally {
await browser.close();
}
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});The path above is a placeholder, not a universal Chrome location. You can use channel instead when Chrome is installed in a standard location known to Puppeteer, for example puppeteer.launch({ channel: 'chrome' }). A channel finds a regular Chrome installation; it does not download that browser for puppeteer-core.
5. Configure browser downloads and cache
Puppeteer supports configuration files and environment variables for browser download behavior. Environment variables take precedence where applicable. Its configuration guide recommends configuration files and documents the default cache location. Configuration files and environment variables are ignored by puppeteer-core.
If you change a browser download setting or cache directory, rerun the browser installation so the new configuration takes effect. This matters in build pipelines: a browser cached on one machine may not exist on a fresh runner, and a browser artifact moved to a new environment must still be discoverable from the configured cache or executable path. See the Puppeteer configuration guide and check it against your installed stable version.
6. Install Chrome explicitly when needed
Some package managers or project policies block dependency install scripts. If puppeteer installed but its browser did not, install Chrome for Testing with Puppeteer’s browser CLI:
# npm
npx puppeteer browsers install
# Yarn
yarn dlx puppeteer browsers install
# pnpm
pnpm dlx puppeteer browsers install
# Bun
bun x puppeteer browsers installAlternatively, allow Puppeteer’s install script in your package-manager settings, then reinstall as appropriate. The installation guide documents both paths.
Linux dependencies on Debian or Ubuntu
If Chrome downloads but cannot start because system libraries are missing, the Puppeteer browsers documentation gives this Debian/Ubuntu-specific command:
npx puppeteer browsers install chrome --install-depsIt attempts to install required system packages and needs root privileges. It is not a general Linux command for every distribution or environment. Review the browser CLI documentation and use your distribution’s package management process where this command does not apply.
7. Version and platform details
The supported-browser table maps Puppeteer 25.12.0 to Chrome for Testing 154.0.8037.57. That mapping is version-sensitive; consult the supported browsers table for the release you are installing rather than pinning this example blindly. Puppeteer documentation says Chrome for Testing has been its managed Chrome since Puppeteer 20.0.0.
For reproducible deployments, keep the Puppeteer version and its managed browser installation together in the build environment, or explicitly manage and verify the externally supplied Chrome version. Avoid assuming that a developer workstation’s browser path or cached download will exist on a container, server, or CI runner.
8. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Could not find Chrome (ver. ...) |
The package manager blocked Puppeteer’s install script, or the browser cache is absent in this environment. | Run npx puppeteer browsers install with the equivalent command for your package manager. If you configured a custom cache, ensure that path exists in this runtime. |
puppeteer-core cannot launch a browser |
The core package does not download Chrome and has no managed browser path to use. | Install/provide a browser and set executablePath, use a supported channel, or connect to the remote browser using the appropriate connection flow. |
| Chrome executable path is not found | The configured path is a placeholder, differs by OS, or is not present in the runtime/container. | Inspect the target environment’s actual browser location and set the exact path; for standard installations consider a supported channel. |
| Browser downloads but launch reports missing libraries on Linux | Required operating-system packages are absent. | On Debian/Ubuntu, consider npx puppeteer browsers install chrome --install-deps with root privileges. For other distributions, install the required packages using that distribution’s supported process. |
| Browser install cannot extract its archive | The platform’s extraction utility is unavailable. | On Windows, provide tar.exe or PowerShell; on macOS/Linux provide unzip, or use optional yauzl. |
| It works locally but fails in CI or a new container | The browser cache is not present or the configured cache path differs between build and runtime. | Install the browser in the build/runtime environment or make the configured cache available there; verify configuration and executable paths in that environment. |
| System Chrome behaves differently from Puppeteer’s downloaded browser | The external Chrome release may not match the Puppeteer version’s expected browser. | Prefer the bundled compatible browser, or verify the external version and Puppeteer pairing for the target deployment. |
9. Performance, reliability, and cost
The initial browser download is a setup cost: the documented approximate sizes are 170 MB for macOS, 282 MB for Linux, and 280 MB for Windows. Cache the browser in a controlled build environment when appropriate, and account for the cache location when moving artifacts. A cold environment may need to fetch the browser again.
For reliability, use the bundled browser when you want Puppeteer’s documented compatibility guarantee. Make launch configuration explicit when using a separately managed browser, and ensure the executable and OS dependencies are available wherever the program runs. Always close the browser in a finally block so failures during navigation or screenshot capture do not leave the process running.
Puppeteer and Chrome for Testing are software downloads; no topic-specific hardware purchase is needed. The main setup costs are download bandwidth, storage, and the resources used by the browser process at runtime. This guide does not assign a benchmark or fixed runtime cost because those depend on the page and environment.
Or skip the browser setup
If you only need website screenshots and do not need to operate a local browser, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture can accept cookie consent and remove more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. AI agents can use its MCP tools to take screenshots, get page information, or capture PDFs.
See the ScreenshotNeo API documentation for the request options. 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,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', bytes));Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.
FAQ
Do I have to install Google Chrome separately?
No. The ordinary puppeteer installation downloads its managed Chrome for Testing browser. Install a separate browser only when you are deliberately managing Chrome yourself or using puppeteer-core.
Which package should I use in a serverless or container deployment?
Use the package and browser arrangement your deployment can supply reliably. The full package manages its browser download; puppeteer-core is appropriate if the environment supplies a remote browser or stable executable. Check the target runtime’s platform and OS requirements.
Can Puppeteer use a system-installed Chrome?
Yes. With puppeteer-core, set executablePath or a supported channel. The compatibility guarantee applies to Puppeteer’s bundled browser, so verify an external pairing yourself.
Where does Puppeteer keep its browser?
The documented default cache is ~/.cache/puppeteer. Configuration can change download settings and cache location; make sure the configured location is available at runtime.
