ScreenshotNeo
Sign in Get a free key

BlogGuides

Puppeteer Chrome Settings Explained

Understand Puppeteer’s Chrome launch options, browser modes, flags, profiles, viewports, and timeouts, with runnable examples and fixes for common errors.

By the ScreenshotNeo team4 October 20268 min read

Puppeteer’s Chrome settings are JavaScript options passed to puppeteer.launch(), plus optional Chrome command-line flags in args. Start with the defaults: Puppeteer launches headless Chrome using its bundled browser. Change a setting only when your task requires it. The examples below use the current Puppeteer API concepts documented for v25.12.0; verify defaults against the documentation version installed in your project.

Quick start: a configurable launch

Install Puppeteer, then save this as settings.mjs and run it with Node.js. The regular puppeteer package downloads a compatible browser by default.

npm install puppeteer
node settings.mjs
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  timeout: 30_000,
  defaultViewport: { width: 1440, height: 900 },
  args: [],
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  await browser.close();
}

These values make the viewport explicit while retaining the default headless mode and browser arguments. Remove args if you have no additional flags to pass. See the LaunchOptions API and ConnectOptions API for the version-specific reference.

Choose a Chrome mode

The headless option has three documented choices:

Value What it starts Use it when
true Modern headless Chrome. This is the default. You need ordinary browser automation without a visible window.
'shell' The separate chrome-headless-shell program. The shell’s narrower behavior supports your task and its automation performance is useful.
false A visible browser window. You need to see browser behavior while debugging or interacting.

Puppeteer’s guide says headless shell does not completely match regular Chrome behavior, though it can be more performant for automation tasks that do not need the complete Chrome feature set. Treat shell mode as a compatibility choice, not a universal speed setting. The mode guide is at Puppeteer headless modes.

const browser = await puppeteer.launch({ headless: 'shell' });

To open a visible browser, use headless: false. Setting devtools: true also forces headful mode and opens DevTools for each tab.

Select the browser binary

By default, Puppeteer uses the Chrome for Testing build it downloads. The official documentation says Puppeteer works best with that bundled browser and does not guarantee compatibility with arbitrary Chrome versions.

Option Effect Consideration
browser Selects the supported browser; Chrome is the default in the generic API. Choose another supported browser only when your use case calls for it.
channel Asks Puppeteer to use a regular Chrome installation at a known system location. The installed version may differ from the bundled version.
executablePath Specifies the browser executable directly. Compatibility with a custom binary is not guaranteed. 
// Use a locally installed Chrome channel.
const browser = await puppeteer.launch({ channel: 'chrome' });

// Or point to an explicit executable path.
const otherBrowser = await puppeteer.launch({ executablePath: '/path/to/chrome' });

Use the bundled browser for the documented compatibility baseline. Choose a channel or explicit path when your project specifically needs that installed version, and validate it in the deployment environment. With puppeteer-core, supply channel or executablePath; the package does not choose a bundled browser for you. See supported browsers and the launch method.

Chrome arguments and Puppeteer defaults

args adds command-line arguments to the browser process. Use it for a specific Chrome flag your environment requires:

const browser = await puppeteer.launch({
  args: ['--some-chrome-flag'],
});

The example flag is a placeholder; use a real flag appropriate to your browser and deployment. Puppeteer also supports ignoreDefaultArgs:

// Remove one default argument, only when you understand its effect.
const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--mute-audio'],
});

Setting ignoreDefaultArgs: true removes all Puppeteer defaults. An array removes only the listed defaults. Puppeteer warns that its defaults are likely needed, so removing them can impair expected behavior. Prefer adding a necessary flag with args; alter defaults only when you know what the affected argument does.

Profile, viewport, and timeouts

These settings control different parts of the session:

Setting Controls Documented default or note
userDataDir The user-data directory path. Set a path when your task needs a specific profile directory. The API describes the path option but does not establish broader profile-sharing or lifecycle guarantees.
defaultViewport Page dimensions applied to each page. 800 × 600 by default; null is accepted.
timeout How long to wait for browser startup. 30,000 ms; 0 disables this timeout.
protocolTimeout How long to wait for an individual Chrome DevTools Protocol call. 180,000 ms.
slowMo Adds a delay to Puppeteer operations. Useful for debugging; it slows operations deliberately. 
const browser = await puppeteer.launch({
  userDataDir: './puppeteer-profile',
  defaultViewport: { width: 1280, height: 800 },
  timeout: 45_000,
  protocolTimeout: 180_000,
  slowMo: 0,
});

Use a profile directory only when the task needs one, and avoid assuming that separate processes can safely share the same profile. Set the viewport to the dimensions your page behavior depends on; viewport size is independent of whether Chrome is headless. Increase startup timeout for slow browser startup, and protocol timeout for a particular slow browser operation. Disabling a timeout with 0 means the affected wait has no time limit, which can leave a job waiting indefinitely if the browser never responds.

Other launch options

Option Use Documented behavior
devtools Browser debugging. Opens DevTools for each tab; true forces headful mode.
dumpio Diagnosing browser-process output. Pipes browser stdout and stderr to the Node.js process streams when enabled.
handleSIGHUP, handleSIGINT, handleSIGTERM Control shutdown handling when Node receives those signals. Each defaults to true.
pipe Browser communication transport. Uses pipe transport instead of WebSocket; documented as Chrome-only.
waitForInitialPage Control waiting for Chrome’s initial page. Disabling it can be useful when Chrome is explicitly started without a startup window.
env Environment variables visible to the browser. Defaults to inheriting process.env.

For example, enable browser output when diagnosing startup or protocol issues:

const browser = await puppeteer.launch({
  dumpio: true,
});

Signal handling affects how Puppeteer manages the browser process when the Node process receives a signal. Change those options only if your process supervisor or shutdown design requires different behavior.

Per-launch options versus global configuration

Launch options shape a particular browser session. Puppeteer’s configuration API covers installation and runtime behavior across the project, including the default browser, executable path, browser cache directory, temporary directory, log level, and whether browser downloads are skipped. Some configuration settings have environment-variable overrides.

Use per-launch options for session-specific needs such as headless mode, viewport, and arguments. Use configuration when you need to control installation or a project-wide browser choice. Check the current Puppeteer configuration guide for exact setting names and environment variables; these can change between releases.

Common errors and fixes

Symptom Likely cause What to check
Browser executable cannot be found Browser downloads were skipped, the cache path changed, or a custom executable path is wrong. Check installation/configuration, the effective cache directory, and that the executable exists. With puppeteer-core, supply channel or executablePath.
Launch fails with a selected system Chrome The selected Chrome version may not match what Puppeteer expects. Try the bundled Chrome for Testing version, or validate the selected browser version in the same environment.
Pages behave differently between environments Different browser binaries, headless modes, viewport sizes, or flags can change behavior. Make the browser choice, mode, viewport, and necessary flags explicit; compare those settings across environments.
Browser starts but an operation hangs timeout only governs startup; a protocol call may be waiting on its own limit or the page may never reach the requested state. Review protocolTimeout and the page wait condition separately. Avoid setting timeouts to zero unless an unbounded wait is intended.
Chrome starts without the expected page Initial-page waiting behavior may not suit the way Chrome was started. Review waitForInitialPage and the launch flow, especially if Chrome is explicitly started without a startup window.
Removing default arguments breaks launch or page behavior ignoreDefaultArgs: true removed arguments Puppeteer relies on. Restore defaults, then filter only a specific default if its effect is understood.
Hard to see why the browser process exited Browser output is not visible in the Node process. Set dumpio: true and inspect the emitted stdout and stderr.

Performance, reliability, and cost considerations

  • Use the smallest configuration that works. Extra flags and custom binaries add compatibility variables to investigate.
  • Choose headless shell deliberately. The official guide describes it as potentially more performant for some automation, with behavior that does not fully match regular Chrome. Confirm that the task works in that mode.
  • Keep waits bounded where possible. Longer timeouts accommodate slow starts or protocol calls, but also make a failed job take longer to surface. A timeout of zero can wait indefinitely.
  • Make capture geometry explicit. A fixed viewport improves consistency when layout depends on dimensions. It does not make content itself deterministic.
  • Account for browser installation and execution. Puppeteer runs a browser process, so your deployment must provide the downloaded or selected browser and enough resources for the workload. The cited API documentation does not provide cost or resource benchmarks.
  • Do not infer reliability from one successful launch. Browser compatibility can differ by version and environment; pin and validate the browser choice used by your deployment.

Or skip the browser setup

If your goal is a website screenshot rather than managing a local browser, ScreenshotNeo provides a screenshot API and MCP server for developers. The single GET request below returns a screenshot; see the API documentation for parameters 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.webp
import 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}`);
const bytes = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));
  • Cookie and consent banners are accepted before capture, and 60+ known consent platforms, newsletter popups, and chat widgets are removed. Each step can be turned off.
  • Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses identify the page verdict and billing status in headers.
  • An MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs.
  • The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, no card required.

FAQ

Does headless: true mean Puppeteer uses headless shell?

No. true selects modern headless Chrome. Use the explicit value 'shell' for chrome-headless-shell.

Does defaultViewport set the screen size of a visible desktop?

It sets the page viewport dimensions. It is separate from choosing headless or visible mode.

Should I set every launch option explicitly?

No. Keep the defaults unless a requirement calls for a change; extra settings create more variables when diagnosing behavior.

Where should I check exact defaults for my installed Puppeteer version?

Use the API reference shipped for or linked from that release. The values in this guide reflect the v25.12.0 documentation and can change later.

Keep reading

7 min read

LinkedIn Open to Work Image

Learn what LinkedIn’s Open to Work photo frame means, who can see it, how to add or remove it, and how to choose the right privacy setting.