What Is Puppeteer Core? – Definition and When to Use It
Learn how puppeteer-core differs from puppeteer, why it downloads no browser, and when the smaller package is the right choice.
puppeteer-core is the Puppeteer library without the bundled browser download. It is functionally the same API, and it expects you to supply the browser.
1. The Difference
| Package | Downloads a browser | Suits |
|---|---|---|
puppeteer |
Yes, on install | Local development, self-contained setups |
puppeteer-core |
No | Connecting to a remote browser, or using an installed one |
That is the whole distinction. The API is identical.
2. Why the Browser Download Matters
A bundled Chromium is large. In a container image, a serverless function, or a build pipeline, that size has real consequences: slower builds, larger images, and in some environments a hard size limit that the download exceeds.
Where the browser is not going to be used locally, downloading it is pure cost.
3. Connecting Instead of Launching
import puppeteer from 'puppeteer-core';
const browser = await puppeteer.connect({
browserWSEndpoint: process.env.BROWSER_WS_ENDPOINT,
});
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
The endpoint may belong to a browser service, a container running Chromium, or a managed cloud browser. Nothing else in the script changes.
4. Using a System Browser
It can also launch a browser already installed on the machine, given its path:
const browser = await puppeteer.launch({ executablePath: '/usr/bin/chromium' });
That suits images where the browser is installed by the package manager, which is often better maintained than a bundled download.
5. Version Compatibility Becomes Your Concern
With the bundled package, library and browser versions are matched for you. With core, they are not.
A significant mismatch produces protocol errors that are confusing to diagnose. Pinning both, and upgrading them together, is the practical discipline.
6. When to Choose Each
Use puppeteer for local development, quick scripts, and anywhere the convenience of a matched browser outweighs image size.
Use puppeteer-core when connecting to a remote or managed browser, when the browser is installed separately, when image size is constrained, or when the same code must run against different browser sources.
7. Latency Changes Script Design
Connecting to a remote browser adds a network round trip per command, so chatty scripts slow noticeably.
Batching work inside the page — one evaluation returning many fields rather than dozens of individual queries — is the pattern that keeps remote execution efficient.
8. Summary
puppeteer-core is Puppeteer without the bundled browser, with an identical API, intended for connecting to a browser you supply.
Choose it for remote and managed browsers, separately installed browsers, and size-constrained images — accepting that you now own version compatibility, and batching in-page work to absorb the added latency.