Puppeteer Configuration: How to Configure Puppeteer
Learn where Puppeteer settings belong: project config, environment variables, or launch options. Fix missing-browser and deployment issues with runnable examples.
Puppeteer configuration has three layers: use a project configuration file for installation and browser-download behavior, supported environment variables to override those settings in a deployment, and puppeteer.launch() options for a particular browser process. The puppeteer package downloads a compatible Chrome for Testing browser by default; puppeteer-core does not download Chrome and ignores Puppeteer configuration files and environment variables.
For new projects, the simplest reliable setup is to install puppeteer, let it manage its compatible browser, and use launch options only for process-specific needs. If you manage Chrome yourself, use puppeteer-core and provide a browser path or channel. See the Puppeteer configuration guide, installation guide, and launch API reference for the documentation version matching your installed release.
1. Choose the right configuration layer
| Layer | Use it for | Examples |
|---|---|---|
| Project configuration file | Persistent project settings, especially browser selection, downloads, and cache locations | defaultBrowser, cacheDirectory, skipDownload |
| Environment variables | Deployment-specific overrides without changing the checked-in project config | PUPPETEER_EXECUTABLE_PATH, PUPPETEER_SKIP_DOWNLOAD, PUPPETEER_CACHE_DIR |
puppeteer.launch() |
Choices that govern one browser process | headless, args, timeout, userDataDir |
Environment variables override corresponding configuration-file values where Puppeteer supports an override. A setting that affects browser installation may require rerunning the browser installation command. Confirm supported keys against the configuration reference for your Puppeteer version: the guide and the installed package can differ, especially when using documentation labeled “next.”
2. Install Puppeteer and its browser
Install puppeteer when you want Puppeteer to download and use its compatible Chrome for Testing build. Current releases also install a chrome-headless-shell binary. By default, downloaded browsers are cached under ~/.cache/puppeteer.
npm install puppeteerSome package managers or deployment build systems block dependency install scripts. If that happens, the JavaScript package may be present while the browser is missing. Run the documented browser installation command after dependencies are installed:
npx puppeteer browsers installAlternatively, configure your package manager to allow Puppeteer’s install script. Use the browser installation command supported by your installed release, then ensure the build artifact or runtime environment can access the browser cache.
3. Add a project configuration file
Puppeteer searches up the file tree for recognized configuration files. A project config keeps installation behavior with the project rather than scattering it across launch calls. For example, a supported JavaScript config can specify a browser choice and cache directory:
// .puppeteerrc.cjs
/** @type {import('puppeteer').Configuration} */
module.exports = {
defaultBrowser: 'chrome',
cacheDirectory: './.cache/puppeteer',
};The exact file formats and option names are version-dependent. Check the official configuration guide before copying settings into a project. Keep generated browser files out of source control unless your deployment process specifically requires them. If you change the browser or download configuration, rerun browser installation so the cache matches the new settings.
4. Override settings in deployment
Set an environment variable in the deployment environment when a runtime needs a different browser path or cache location. Common documented variables include PUPPETEER_EXECUTABLE_PATH, PUPPETEER_SKIP_DOWNLOAD, PUPPETEER_CACHE_DIR, PUPPETEER_TMP_DIR, and PUPPETEER_BROWSER. Verify each variable and its precedence in the reference for your release.
# Example shell environment for a deployment
export PUPPETEER_CACHE_DIR=/app/.cache/puppeteer
export PUPPETEER_TMP_DIR=/app/tmp
node app.jsSet PUPPETEER_SKIP_DOWNLOAD only when another step supplies a usable browser. Skipping download without installing or mounting a compatible browser commonly causes launch to fail. The puppeteer-core package ignores Puppeteer config files and these Puppeteer environment settings; configure its browser directly in launch options.
5. Configure the browser process with launch options
Here is a runnable Node.js example using the default bundled browser. Save it as capture.js and run node capture.js:
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: 'example.png', fullPage: true });
} finally {
await browser.close();
}
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});Common launch options include:
| Option | Purpose and guidance |
|---|---|
browser |
Selects the browser type where supported by the installed release. |
channel |
Selects an installed Chrome channel. Useful when managing Chrome separately. |
executablePath |
Points to a specific browser binary. Required for a managed browser with puppeteer-core unless a channel is used. |
args |
Passes command-line arguments to Chrome. Add only arguments needed by the environment. |
headless |
Defaults to headless operation. true uses new headless; 'shell' selects the old headless shell where supported. |
timeout |
Sets the launch timeout. Increase only when browser startup is legitimately slow; it does not fix a missing binary or dependency. |
userDataDir |
Chooses a profile directory. Use isolated writable directories for concurrent jobs instead of making unrelated browser jobs share one profile. |
| Signal and I/O controls | The API also exposes process signal handling and standard I/O controls; use them when integrating browser lifecycle with your process supervisor. |
Be careful when changing default browser arguments: Puppeteer supplies arguments needed for its normal operation. Consult the LaunchOptions reference before replacing defaults. Browser-version compatibility is strongest with the Chrome for Testing version bundled for Puppeteer; other versions are not guaranteed to work.
6. Use a browser managed outside Puppeteer
Use puppeteer-core when the browser binary is managed by your operating system, container image, or another browser-management process. It does not download Chrome. Supply executablePath or channel at launch:
npm install puppeteer-coreconst puppeteer = require('puppeteer-core');
(async () => {
const browser = await puppeteer.launch({
executablePath: process.env.CHROME_BIN,
headless: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.screenshot({ path: 'example.png' });
} finally {
await browser.close();
}
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});Set CHROME_BIN to the actual executable path in the target environment. Since you own the browser version and installation, also own compatibility checks and system-library installation. Puppeteer says it works best with the Chrome for Testing version it downloads by default and does not guarantee other Chrome versions.
7. Check deployment compatibility
- Check Node.js. The current system requirements page lists Node.js 22.12 or newer. Confirm the requirement for your installed Puppeteer release.
- Check OS and architecture. Match the target container or host to the supported Chrome for Testing platform and architecture; local success does not establish that a different deployment image can run Chrome.
- Install Linux dependencies. Use the Chrome Linux package requirements linked from Puppeteer’s system requirements and troubleshooting pages. A present browser binary can still fail to start if shared libraries are absent.
- Check browser availability and permissions. Confirm the configured path exists, is executable, and the process can read the cache and write temporary/profile data.
- Keep the sandbox enabled where possible. Diagnose the environment’s sandbox configuration. Puppeteer strongly discourages running Chrome with
--no-sandbox; treat it as an exceptional, environment-specific security decision rather than a standard fix.
See the official system requirements and troubleshooting guide for current platform details.
8. Troubleshoot common configuration failures
| Symptom | Likely cause | Fix |
|---|---|---|
Could not find Chrome (ver. ...) |
The install script was blocked, download was skipped, or the browser cache is not available in the runtime. | Run npx puppeteer browsers install, allow Puppeteer’s install script, or configure the actual executable path for a managed browser. Verify the runtime can access the configured cache. |
| Launch fails with a missing shared library or dependency | The deployment OS image lacks Chrome’s required Linux packages. | Install the packages listed for your target platform in the Chrome requirements and Puppeteer troubleshooting documentation. Rebuild and check the same image that runs the app. |
| Chrome exits immediately in Docker or a container | Browser dependencies, writable directories, resource limits, or sandbox setup differ from local development. | Check the container’s OS and architecture, dependencies, cache and temporary-directory permissions, and sandbox policy. Use the official Puppeteer container troubleshooting guidance. |
| Sandbox error | The runtime cannot initialize Chrome’s sandbox under its current user or container configuration. | Configure a working sandbox for the target environment. Do not make --no-sandbox the default; Puppeteer labels running without a sandbox strongly discouraged. |
| Config change has no effect | The config file was not found, its format is unsupported, an environment override takes precedence, or puppeteer-core is in use. |
Confirm the file is in the searched project tree and recognized by your version, inspect deployment variables, and remember that puppeteer-core ignores Puppeteer config and environment configuration. |
| Browser version behaves unexpectedly | The separately managed Chrome version is outside the version Puppeteer is designed to use. | Prefer Puppeteer’s bundled Chrome for Testing browser, or pin and validate the managed browser against the installed Puppeteer version. |
9. Performance, reliability, and cost
- Startup and caching: Download the browser during the build or installation phase when practical, then preserve or recreate the cache in the runtime. A fresh or ephemeral environment may otherwise repeat installation work or start without a browser.
- Concurrency: Use separate browser contexts or processes according to your isolation and resource needs. Avoid concurrent jobs writing to the same user profile. Close pages and browsers in a
finallypath so failed navigations do not leave processes behind. - Navigation waits: Choose a wait condition that fits the page. Waiting for full network idleness can stall on pages with persistent connections;
domcontentloadedmay be sufficient when the task does not require every resource. - Reliability: Test the actual production image, architecture, browser path, permissions, and sandbox policy. Set realistic launch and navigation timeouts, and report launch failures separately from page navigation failures.
- Cost: Puppeteer itself is an open-source library, but operating a browser requires compute, memory, storage for browser downloads and profiles, and engineering time for patches and deployment compatibility. The dossier supplies no benchmark or operating-cost estimate, so measure resource use with your own pages and workload.
10. Or skip the browser setup
If your goal is to get a website screenshot rather than operate Chrome, ScreenshotNeo offers a single GET request that returns an image or PDF. Its API accepts screenshot options, and its parameter names also work with those used by other screenshot APIs, which can make switching easier. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)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}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the page verdict and billing status in response headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.
11. Frequently asked questions
Does Puppeteer need a configuration file?
No. You can use defaults and configure a specific process at launch. A config file is useful for settings that should persist across installation and project runs.
Should I use puppeteer or puppeteer-core?
Use puppeteer when you want Puppeteer to download its compatible browser. Use puppeteer-core when your environment supplies and manages the browser.
Why does my local setup work but deployment fail?
The deployment may use a different Node version, operating system, architecture, browser cache, Linux dependency set, file permissions, or sandbox policy. Validate these in the target runtime.
Can I point Puppeteer at any Chrome version?
You can configure a path or channel, but Puppeteer only says it works best with its bundled Chrome for Testing version and does not guarantee compatibility with other versions.
Does puppeteer-core read .puppeteerrc?
No. It ignores Puppeteer config files and Puppeteer environment-variable configuration, so provide browser details directly where needed.
