For a typical Node.js project, install Puppeteer with the package manager the project already uses—for example, npm i puppeteer. The full puppeteer package normally downloads a compatible Chrome for Testing browser during installation. If you manage the browser yourself or connect to a remote one, install puppeteer-core instead and configure the browser connection explicitly.
This guide covers prerequisites, npm, Yarn, pnpm and Bun commands, browser downloads, a local smoke test, configuration, and common install or launch failures. The current Puppeteer system requirements page specifies Node.js 22.12 or later; check the linked documentation for changes before installing.
Choose the right Puppeteer package
Puppeteer is a Node.js library for controlling a browser. For most new projects, use puppeteer: it includes Puppeteer’s default setup and normally downloads a compatible browser as part of installation. Use puppeteer-core when a deployment supplies its own browser or your code connects to a remote browser; it does not download Chrome.
| Package | Best fit | Browser handling |
|---|---|---|
puppeteer |
Projects that want the standard local setup | Downloads a compatible browser by default; configurable |
puppeteer-core |
Projects using a separately managed or remote browser | No automatic browser download; provide connection or executable details |
The distinctions and install commands are documented in the Puppeteer installation guide. A package and downloaded browser are software components, not a separate physical purchase.
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 →#1 Best Overall
Check prerequisites and platform support
The Puppeteer system requirements page currently specifies Node.js 22.12 or later, following the latest maintenance LTS version of Node. If you use TypeScript, that page specifies TypeScript 5.0.1 or later; for type-checking node_modules, use an ES2022-or-later target. Requirements can change, so verify the current system requirements for your install date.
The documented Chrome for Testing platforms include Windows x64; macOS x64 and arm64; Debian/Ubuntu Linux x64 and arm64; and openSUSE/Fedora Linux x64 and arm64. Browser libraries and system dependencies vary across Linux distributions. On Windows, browser archives need tar.exe or PowerShell; on macOS and Linux, they need unzip, unless optional yauzl is installed. Consult the system requirements page if your platform or architecture is not listed.
Install Puppeteer with your package manager
Run the command from the project directory, using the manager already used to maintain its dependencies:
- npm:
npm i puppeteer - Yarn:
yarn add puppeteer - pnpm:
pnpm add puppeteer - Bun:
bun add puppeteer
During a normal install, Puppeteer downloads Chrome for Testing and the headless-shell binary selected to work with its API. The default browser cache is $HOME/.cache/puppeteer, documented since Puppeteer v19.0.0. The install may take longer or use more disk space than a JavaScript-only dependency because browser binaries are downloaded too.
If install scripts are blocked
Some package-manager policies prevent dependency install scripts from running. The package can then be present even though the browser download was skipped. After installing, run:
Rank #2
npx puppeteer browsers installAlternatively, allow Puppeteer’s install script using the mechanism supported by your package manager and its version. Do not assume one manager’s configuration applies to another. If you change settings that affect which browser is downloaded, rerun the browser-install command. See the installation guide for the current options.
Install puppeteer-core for a separately managed browser
Choose puppeteer-core if a container, remote browser service, or your own deployment process handles the browser. Install it with the corresponding manager, for example:
npm i puppeteer-coreThen pass the browser executable path when launching a locally managed browser. The path below is illustrative; replace it with the path provided by your operating system or deployment. Do not expect puppeteer-core to download or configure Chrome.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
executablePath: '/path/to/your/chrome',
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}The independently managed browser must be compatible with the Puppeteer version you installed. Use the current supported browsers table to check the pairing. For example, the documentation currently surfaces Puppeteer 25.12.0 paired with Chrome for Testing 154.0.8037.57 and Firefox 156.0.1; these are version-specific mappings, not permanent recommendations.
Verify the installation with a local smoke test
Save this as smoke-test.mjs in the project directory. It uses the full puppeteer package, opens a page, visits a public URL and writes a screenshot. Run it locally with node smoke-test.mjs. This example is a starting-point check, not a guarantee that a particular machine, site, network or deployment will work without additional configuration.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log('Page title:', await page.title());
await page.screenshot({ path: 'example.png', fullPage: true });
} finally {
await browser.close();
}A successful run prints the page title and creates example.png in the working directory. The finally block closes the browser even if navigation or screenshot capture throws an error. For an application-specific test, replace the example URL with a page you are authorized to access.
Use the matching module style
The file above uses ECMAScript modules and an .mjs extension. If your project is already configured for ES modules, you can instead use a .js file with the project’s existing module configuration. For a CommonJS project, use const puppeteer = require('puppeteer'); and place the same asynchronous browser work inside an async function. Keep the test consistent with the module format already in your project rather than changing the whole project just for this example.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Configure browser downloads and cache location
Puppeteer recommends configuration files for supported settings; environment variables are also available, and some settings are environment-only. The browser cache defaults to ~/.cache/puppeteer. You can change it through supported configuration or the PUPPETEER_CACHE_DIR environment variable. Check the configuration guide for exact setting names and supported methods.
Configuration and Puppeteer environment variables are ignored by puppeteer-core. In a custom-browser workflow, set the executable path or remote connection in your launch code instead of relying on full-package defaults. When a build downloads a browser in one environment but runs in another, make sure the configured cache is available to the runtime; a fresh container or deployment may not contain the build machine’s files.
Or skip the browser setup
If your goal is to get a website screenshot rather than build general browser automation, ScreenshotNeo is a screenshot API and MCP server: one GET request can return a PNG, JPEG, WebP or PDF. Its API handles the browser setup for the capture. See the ScreenshotNeo API documentation.
Rank #4
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Puppeteer remains the fit when you need to write and control a general-purpose browser workflow.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common install and launch failures
Package installed, but Puppeteer reports a missing browser
The install script may have been blocked or the browser download otherwise skipped. Run npx puppeteer browsers install from the project, then retry. If the package manager is configured to block scripts, allow Puppeteer’s install script using that manager’s own documented mechanism. Confirm that the install and runtime use the same configuration and cache location.
Browser downloads but will not launch on Linux
A downloaded browser can still need operating-system libraries that are not installed. Check the current Puppeteer troubleshooting guide and your distribution’s requirements; package names and prerequisites differ by Linux distribution. Also check the documented supported OS and architecture combinations.
Chrome reports a sandbox error
Follow Puppeteer’s supported Linux sandbox setup rather than treating sandbox disabling as a routine fix. The troubleshooting guide strongly discourages running without a sandbox. Only make a security trade-off after understanding the environment and the consequences; do not add --no-sandbox as a generic installation workaround.
Recommended Free Tools
A custom browser launches unreliably or fails at startup
Check that the executable path points to the intended browser and compare its version with Puppeteer’s supported-browser table. Update the pairing or configure the correct executable path in puppeteer.launch. Full-package configuration defaults do not apply to puppeteer-core.
It works during build but fails after deployment
The browser cache may not exist in the runtime environment, particularly if deployment uses a fresh container or relocates the build output. Configure a cache path available at runtime, ensure the browser is installed there, and verify the runtime user can access it. For a separately managed browser, use the explicit executable path or remote connection instead of depending on a cache that is not shipped.
Keep install time, reliability and deployment in view
Puppeteer’s default convenience comes with a browser download, so account for network access and storage during installation and for the browser files in the environment where the script runs. If policy blocks install scripts, make the browser-install step explicit in the build process. If the runtime is isolated from the build environment, arrange for the browser and its cache to be present there.
For Linux, browser files alone may not be sufficient: system dependencies and sandbox configuration also matter. For a custom or remote browser, you gain control over browser provisioning but take responsibility for version compatibility, connectivity and executable or endpoint configuration. The right choice depends on whether the project should let Puppeteer download a compatible browser or should use a browser managed elsewhere.
Frequently Asked Questions
Does installing Puppeteer install a browser extension or a desktop app?
No. Puppeteer is a Node.js library used by scripts and applications to control a browser; its default install downloads browser binaries for automation rather than adding a browser extension.
Where should I check when Puppeteer releases a new version?
Use the official installation, system requirements, configuration and supported-browser documentation linked above, since Node requirements and browser-version pairings can change.
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.
