Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Puppeteer settings fall into three different layers: installation and runtime defaults in Configuration, options for starting a browser in LaunchOptions, and options for attaching to a browser in ConnectOptions. Put each setting in the layer that owns it; a configuration file does not replace launch options, and neither config files nor their environment-variable overrides configure puppeteer-core.
Choose the right configuration layer
| Layer | Use it for | Typical settings |
|---|---|---|
Configuration |
Project-wide installation and runtime defaults | Browser downloads, browser choice, executable path, cache directory, download skipping |
LaunchOptions |
Starting a new browser process | Headless mode, launch arguments, environment, startup timeout, user data directory |
ConnectOptions |
Connecting to an existing browser, and settings shared with launch behavior | Viewport, protocol timeouts, endpoints, target filtering |
The relevant API pages are Puppeteer’s Configuration, LaunchOptions, and ConnectOptions references. Check the documentation version that matches the Puppeteer package installed in your project; the API details here correspond to documentation identifying Puppeteer 25.12.0, while configuration-guide details may vary by documentation branch.
As an Amazon Associate I earn from qualifying purchases.
Set project-wide defaults with a configuration file
Puppeteer recommends configuration files for defaults. It searches the project file tree for supported names, including package.json, .puppeteerrc variants, and puppeteer.config variants. The configuration interface includes options such as defaultBrowser, executablePath, skipDownload, cacheDirectory, temporaryDirectory, and logLevel, along with browser-specific settings and experiments. See the configuration guide and the matching Configuration API for supported file formats and exact keys.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11The documented default browser cache directory is ~/.cache/puppeteer. Set cacheDirectory if your deployment needs a different location, for example because the default home directory is temporary or not writable. Configuration files are useful when a setting should apply consistently across runs; settings specific to one browser process still belong in the launch call.
#1 Best Overall
Environment-variable precedence and proxies
When a documented environment variable applies to a setting, it overrides the configuration-file value. HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are environment-only proxy settings. Browser downloads through a proxy also require Puppeteer’s optional proxy-agent peer dependency. Consult the configuration guide for current variable names and applicability.
These files and environment variables configure the puppeteer package, not puppeteer-core. With puppeteer-core, provide the browser details and behavior through the API instead.
Apply browser download changes
Changing a download-related configuration value does not itself replace or refresh the browser already on disk. After changing browser download settings, rerun installation with puppeteer browsers install. Puppeteer’s guide documents package-manager-specific equivalents as well. Starting with Puppeteer v23, the guide says you can enable settings for multiple browsers and install them. Check the configuration guide for the command appropriate to your package manager and version.
Configure a new browser with LaunchOptions
Pass LaunchOptions to puppeteer.launch() when the setting controls the browser process being started. The current API documents browser selection, release channel, executable path, arguments, environment variables, user data directory, DevTools, headless mode, signal handling, startup timeout, and whether to wait for an initial page. Refer to the LaunchOptions API for the full, version-specific type.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
headless: true,
timeout: 30_000,
devtools: false,
// args: ['--some-chrome-flag'],
// userDataDir: './puppeteer-profile',
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}In the documented defaults, headless is true, timeout is 30,000 milliseconds, devtools is false, and Puppeteer installs process signal handlers. Current types also accept headless: 'shell' for the old headless shell mode; true selects the new headless mode. Setting devtools: true forces headless mode off. Defaults and accepted values can change, so verify them against the API for your installed version.
Pick a browser binary deliberately
The standard puppeteer package downloads a specific Chrome for Testing version, which Puppeteer documents as its best-supported choice. For puppeteer-core, specify either executablePath or channel when launching. A system Chrome path or another executable may work, but Puppeteer guarantees compatibility only with its bundled browser; other executables are used at your own compatibility risk. See the installation guide and LaunchOptions API.
Rank #3
A custom executable path selects a binary already available in your environment; it does not make Puppeteer validate that binary against every feature in your installed version. If you choose a system browser, pin and test the browser version alongside Puppeteer rather than assuming the pair will remain compatible.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Connect to an existing browser with ConnectOptions
Use puppeteer.connect() rather than launch() when another process or service owns the browser. ConnectOptions also describes options shared by launching or connecting. Documented values include defaultViewport (800 × 600 by default), protocol, protocolTimeout (180 seconds by default), endpoints, WebSocket options, and target filtering. Consult the ConnectOptions API for endpoint requirements and the options accepted by the version you use.
Do not treat a connection timeout and a launch timeout as interchangeable: LaunchOptions.timeout controls browser startup, while the connection API has protocol-related timeouts for communication with the browser.
Experimental URL allowlist and blocklist
The API documents allowlist and blocklist as experimental URL-pattern controls. They require Chrome 149 or later, work only with Chrome when Puppeteer is attached to CDP targets, and cannot be used together. Puppeteer cautions that these controls are not a complete network sandbox: other mechanisms or features that omit the network service may still make network requests. For real isolation, use container- or operating-system-level controls as well. See the ConnectOptions API.
Choose and verify an installation source
Installation options cover the browser, build ID, cache directory, platform, and an optional expected SHA-256 hash for the downloaded archive. Supplying the expected hash makes installation fail if the archive does not match; omitting it means installation proceeds without that integrity verification. Puppeteer says custom browser providers are not officially supported and that it tests and guarantees compatibility only for default binaries. Review the installation options API before changing how browser artifacts are obtained.
Recommended Free Tools
For a reproducible setup, record the Puppeteer package version, browser source and version, relevant configuration, and any custom launch arguments. When changing a browser binary or installation source, run your own compatibility checks; the official guarantee does not extend to custom providers.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common configuration problems and fixes
- A config edit appears to have no effect: confirm the package is
puppeteer, notpuppeteer-core; check that the config file name and location are supported; then check whether an applicable environment variable overrides the file value. - The browser version did not change after editing download settings: rerun
puppeteer browsers install(or the documented package-manager equivalent). A config edit alone does not refresh downloaded browser files. puppeteer-corecannot find a browser: setexecutablePathorchannelin the launch options, as required by the LaunchOptions API.- A custom Chrome executable behaves differently or fails: test with the Chrome for Testing version Puppeteer downloads by default. Custom executables are not covered by Puppeteer’s compatibility guarantee.
- Download through a proxy fails: check
HTTP_PROXY,HTTPS_PROXY, andNO_PROXY, and confirm the optional proxy-agent peer dependency is installed when needed. - Headless mode is unexpectedly disabled: check whether
devtools: trueis forcing it off. Useheadless: truefor new headless mode or'shell'for the old headless shell where supported. - URL filtering does not block all network traffic: allowlist/blocklist controls have the documented Chrome, CDP, and version restrictions and are not a full sandbox. Enforce isolation at the container or operating-system level.
Capture a website screenshot without managing Puppeteer
If your goal is to capture a page rather than control a browser session, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It returns PNG, JPEG, WebP, or PDF from a GET request. Puppeteer gives you browser-level control; ScreenshotNeo is an alternative when you want a capture endpoint without installing and configuring a browser in your application.
Or skip the browser setup
Make a single request with a URL and API key. See the ScreenshotNeo API documentation for request options and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with verdict and billing information in response headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Free tools Windows power users keep installed
One-click scans. No signup required.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Do Puppeteer configuration files work with puppeteer-core?
No. Puppeteer’s configuration files and environment-variable configuration do not apply to puppeteer-core.
Can I use Puppeteer’s URL allowlist as a complete network security boundary?
No. It is an experimental, restricted guardrail; use container- or operating-system-level sandboxing when complete isolation is required.
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.
