Configure Puppeteer in three places: use a project configuration file for browser installation and shared defaults, supported environment variables to override those values in a deployment, and puppeteer.launch() options for each browser process. The examples below target the Puppeteer 25.12.0 documentation; check the reference for your installed version before using version-specific options.
Choose the right configuration layer
| Layer | Use it for | Important behavior |
|---|---|---|
| Configuration file | Persistent project settings for browser selection, downloads, cache and temporary directories, logging, and browser-specific behavior. | Puppeteer searches up the file tree for recognized configuration files. A change to browser-download behavior may require reinstalling the browser. |
| Environment variables | Deployment-specific overrides, such as the executable path, whether downloads are skipped, or cache location. | Where an environment override exists, it takes precedence over the corresponding file value. |
puppeteer.launch() |
Settings for one browser process: executable, channel, arguments, headless mode, timeout, and user-data directory, among others. | Launch options do not replace installation configuration: the browser binary and required system libraries must still be available. |
For example, the documented configuration options include defaultBrowser, executablePath, skipDownload, cacheDirectory, temporaryDirectory, and logLevel. Supported environment overrides include PUPPETEER_EXECUTABLE_PATH, PUPPETEER_SKIP_DOWNLOAD, PUPPETEER_CACHE_DIR, PUPPETEER_TMP_DIR, and PUPPETEER_BROWSER. Exact names and supported options can vary by release; use the versioned configuration reference for the version installed in your project.
As an Amazon Associate I earn from qualifying purchases.
The puppeteer-core package ignores Puppeteer configuration files and these Puppeteer environment-variable settings. Configure its browser through launch options instead.
PC 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 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteInstall Puppeteer and its browser
The puppeteer package downloads a compatible Chrome for Testing build during installation by default. Current releases also install a chrome-headless-shell binary. The default browser cache is ~/.cache/puppeteer. If a package manager blocks dependency install scripts, the package may be present while its browser is missing.
#1 Best Overall
- Intel Celeron N4120: 4 Cores & Threads, 1.1GHz Base Clock, Up to 2.6GHz Boost Clock, 4MB Cache, Intel UHD Graphics 600. The perfect combination of performance, power consumption, and value helps your device handle multitasking smoothly and reliably with four processing cores to divide up the work.
- Install
puppeteerusing your project’s package manager. - If the install script was blocked, run
npx puppeteer browsers installfrom the project directory, or configure the package manager to allow Puppeteer’s install script. - Run your script in the same environment where the browser was installed, or configure a shared cache directory that is accessible to the runtime user.
A missing browser commonly produces an error such as “Could not find Chrome (ver. …).” Running the browser installation command is the documented remedy when installation scripts were skipped. See the installation guide for package-manager details and the current browser installation procedure.
Set project defaults in a configuration file
Puppeteer recommends configuration files for persistent project settings. Put the settings shared by local development, CI, or a deployment in the recognized configuration format for your installed release. Puppeteer searches upward from the project for recognized files, so keep the file in a location that is an ancestor of the working project directory.
Use the file for choices that affect installation or shared defaults, such as whether to download a browser and where browser files are cached. If you change a download-related setting after installing dependencies, rerun the browser installation command so the available browser matches the new configuration. Environment variables override corresponding file options when supported.
Rank #2
- Storage: 16GB Flash Memory
- OS: Chrome OS
- Screen Size: 11.6"
Do not assume a config file governs every package: with puppeteer-core, these configuration-file and Puppeteer environment-variable settings are ignored. Consult the configuration guide alongside the versioned reference; the guide is for the next documentation and may describe options not present in an older installed release.
Configure a browser process with launch options
Use launch options for decisions specific to a process. The following CommonJS example uses the bundled browser installed by puppeteer and saves a page screenshot:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: true,
timeout: 30_000,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'page.png', fullPage: true });
} finally {
await browser.close();
}
})();The example uses the default headless browser mode and a 30-second launch timeout. The current launch reference documents options including browser, channel, executablePath, args, headless, timeout, userDataDir, process signal handling, and I/O controls. See PuppeteerNode.launch() for the complete options and types for your version.
Rank #3
- Intel Processor Up to 2.80GHz, 4GB DDR4, 128GB Storage
- 15" FHD IPS Display, Intel UHD Graphics
- 1x USB Type C, 1 x USB Type A, 1x Headphone/Microphone Combo Jack, HDMI
- Fast WiFi and Bluetooth, Integrated Webcam
- Chrome OS, AC Charger Included, Pastel Silver
Headless mode
headless: true uses new headless mode by default. Set headless: 'shell' to use the old headless shell. Choose intentionally: these modes are not interchangeable assumptions, and the installed browser binaries must support the mode you select.
Custom browser arguments
Pass browser flags in args only when you know why the process needs them. Replacing default arguments can remove flags Puppeteer relies on, so avoid changing defaults as a generic troubleshooting step. Review the launch options reference before setting ignoreDefaultArgs or adding security-sensitive flags.
Use a browser you manage yourself
If your environment installs or provisions Chrome separately, use puppeteer-core and explicitly identify the browser with executablePath or channel when launching. These are required for puppeteer-core; it does not download Chrome for you.
Rank #4
- THE BETTER WAY TO LAPTOP – Imagine a Chromebook that’s as flexible as your day: thin and lightweight with built-in Google apps and stress-free security.
- TAKE HITS KEEP MOVING – Sleek, light, and built to last- the Chromebook 2-in-1 is just 0.69” thick and 3.3lbs. Enjoy long-lasting battery life, fast charging, and military-grade durability for nonstop productivity wherever life takes you.
- PERFORMANCE THAT MATCHES YOUR HUSTLE – Fuel your ideas with an Intel Core processor and 128GB storage. Boot up in under 10 seconds to start the day powerfully efficient.
- FLEX YOUR CREATIVITY ANYWHERE, ANYTIME – Create, work, or unwind your way with a versatile 2-in-1 design. Flip easily between laptop, tent, and tablet modes with a responsive touchscreen built for flexibility.
- BRILLIANT VIEWS AND IMMERSIVE AUDIO – See, hear, and create with awesome clarity. The WUXGA display brings rich detail to your work and play, while audio tuned by Waves MaxxAudio provides immersive, balanced sound.
const puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
console.log(await page.title());
} finally {
await browser.close();
}
})();Set PUPPETEER_EXECUTABLE_PATH to the actual browser executable path in the runtime environment, or provide the appropriate installed Chrome channel with the channel option. Puppeteer says it works best with its downloaded Chrome for Testing build and does not guarantee that another Chrome version will work. A managed browser therefore shifts compatibility and browser-update responsibility to your project.
Check deployment before debugging code
A script that works on a workstation can fail in a container or serverless image because the browser, system packages, architecture, or sandbox policy differs. Puppeteer’s current system requirements page lists Node.js 22.12 or later and describes supported Chrome for Testing operating systems and architectures. Verify the requirements against the actual target image rather than treating local success as proof of deployment compatibility.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →- Confirm the deployed Node.js version meets the current system requirements.
- Confirm the browser binary exists at the configured path and is executable by the runtime user.
- Match the operating system and CPU architecture to a supported browser build.
- On Linux, install the packages required by Chrome for the chosen distribution and image.
- Ensure the cache directory is available and writable when using Puppeteer’s downloaded browser.
- Check the sandbox configuration and container permissions before changing browser flags.
Troubleshoot common configuration failures
| Symptom | Likely cause | What to check or do |
|---|---|---|
| “Could not find Chrome (ver. …)” | Browser download was skipped or the runtime cannot see the browser cache. | Run npx puppeteer browsers install or allow Puppeteer’s package install script; then verify the runtime cache path and user. |
| Executable path not found | A configured path is wrong, unavailable in the deployed image, or set only in a different environment. | Check PUPPETEER_EXECUTABLE_PATH and the process environment; verify the file exists and is executable in the target runtime. |
| Chrome exits immediately or reports missing shared libraries | Linux system dependencies required by Chrome are absent from the image. | Install the required packages for the target distribution and architecture; compare the image against the system-requirements and troubleshooting documentation. |
| Browser launch fails in Docker | The image may lack browser dependencies, have incompatible architecture, or impose incompatible permissions. | Validate the exact container image, installed browser, libraries, runtime user, and sandbox policy. Use the official troubleshooting guide. |
| Sandbox-related launch error | Chrome cannot establish its sandbox under the environment’s permissions or configuration. | Configure a working sandbox for the environment and investigate its permission requirements. Do not treat --no-sandbox as a routine fix: Puppeteer strongly discourages running Chrome without a sandbox. |
| Config change appears to have no effect | The setting may be unsupported in the installed version, overridden by an environment variable, outside the searched project tree, or ignored because the package is puppeteer-core. |
Check the versioned reference, inspect environment overrides, place the recognized file in the project ancestry, and use launch options with puppeteer-core. |
Or skip the browser setup
If your goal is to capture a website rather than manage a local Chrome process, ScreenshotNeo is a screenshot API and MCP server for developers. One GET request returns an image or PDF; its cleanup can accept cookie banners and remove known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with response headers identifying the page verdict and billing status. Its MCP server provides screenshot and PDF tools for AI agents.
cURL example (see the ScreenshotNeo API documentation):
Best Value
- FOR HOME, WORK, & SCHOOL – With an Intel processor, 14-inch display, custom-tuned stereo speakers, and long battery life, this Chromebook laptop lets you knock out any assignment or binge-watch your favorite shows..Voltage:5.0 volts
- HD DISPLAY, PORTABLE DESIGN – See every bit of detail on this micro-edge, anti-glare, 14-inch HD (1366 x 768) display (1); easily take this thin and lightweight laptop PC from room to room, on trips, or in a backpack.
- ALL-DAY PERFORMANCE – Reliably tackle all your assignments at once with the quad-core, Intel Celeron N4120—the perfect processor for performance, power consumption, and value (2).
- 4K READY – Smoothly stream 4K content and play your favorite next-gen games with Intel UHD Graphics 600 (3) (4).
- MEMORY AND STORAGE – Enjoy a boost to your system’s performance with 4 GB of RAM while saving more of your favorite memories with 64 GB of reliable flash-based eMMC storage (5).
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpPython:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account to get started.
Frequently Asked Questions
Does puppeteer-core read Puppeteer config files?
No. Configure its browser through launch options such as executablePath or channel.
Recommended Free Tools
Does setting headless to true use the old headless shell?
No. In the documented current API, true uses new headless mode; ‘shell’ selects the old headless shell.
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.
