Puppeteer Default Browser Launch Arguments: What They Do

Puppeteer’s default browser launch arguments are command-line flags that Puppeteer generates for the browser. They vary by Puppeteer version and launch options, so there is no single permanent list. To see the flags your installed package will use, call await puppeteer.defaultArgs(options). The args launch option adds your own flags; ignoreDefaultArgs controls whether Puppeteer’s generated flags are retained.

This guide uses the Puppeteer 25.12.0 API documentation and the current ChromeLauncher implementation as a reference. Treat implementation flags as version-specific: inspect your own runtime before relying on a particular string. See the official defaultArgs() API, LaunchOptions, and ChromeLauncher source.

What “default launch arguments” means

Keep three concepts separate:

• LaunchOptions: Puppeteer settings such as headless, devtools, args, and ignoreDefaultArgs.
• Generated default arguments: Browser command-line flags Puppeteer derives from those options.
• Your extra arguments: Flags you provide with args, generally added alongside the defaults.

Passing args does not replace the generated defaults. To remove defaults, use ignoreDefaultArgs, preferably to filter only a specific flag when that is all the task requires.

Inspect the arguments for your installed Puppeteer

Use the same relevant options for inspection and launch. This example is an ES module and can run in a project that has Puppeteer installed:

import puppeteer from 'puppeteer';

const options = { headless: true };
const args = await puppeteer.defaultArgs(options);
console.log(args);

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

defaultArgs() returns a Promise of the generated browser arguments. Its output is the practical answer to “How do I see Puppeteer’s default Chrome flags?” for your installed version and chosen configuration. It does not promise that every Chrome distribution or future Puppeteer version will use the same list.

What the common argument groups do

The following are representative flags in the current ChromeLauncher implementation. Not every flag appears under every combination of launch options, and implementation details can change between releases.

Purpose	Representative flags	What to know
Automation and startup	--enable-automation, --no-first-run	Identify an automation launch and skip first-run setup.
Feature configuration	--enable-features=..., --disable-features=...	Puppeteer configures Chrome feature names; user feature names can be merged into these lists.
Background activity	--disable-background-networking, --disable-background-timer-throttling, --disable-backgrounding-occluded-windows, --disable-component-update, --disable-sync	These affect browser background services and behavior. They do not disable a page’s network requests.
Crash reporting and component pages	--disable-breakpad, --disable-crash-reporter, --disable-component-extensions-with-background-pages	Change crash-reporting or component-extension behavior.
UI and interaction	--disable-popup-blocking, --disable-prompt-on-repost	Adjust browser UI behaviors relevant to automation.
Headless behavior	--headless=new or --headless, --hide-scrollbars, --mute-audio	Mode-dependent flags. The mode and Puppeteer version determine which are used.
PDF and color output	--export-tagged-pdf, --generate-pdf-document-outline, --force-color-profile=srgb	Present in the referenced implementation; they are not a promise of identical output across Chrome versions.
Runtime and process behavior	--disable-dev-shm-usage, --disable-hang-monitor, --disable-ipc-flooding-protection, --disable-renderer-backgrounding	Effects depend on the environment. Do not assume each is universally required for containers or performance.

For the exact meanings and availability of a flag, consult the matching Chrome and Puppeteer version documentation or source. The list above explains the purpose suggested by the implementation and flag names without treating it as a stable contract.

Headless mode changes the generated list

In Puppeteer 25.12.0, headless defaults to true, meaning current headless Chrome. The documented modes are:

• headless: true uses current headless Chrome. The implementation currently adds --headless=new.
• headless: 'shell' uses the separate chrome-headless-shell binary. The implementation currently adds --headless. The shell does not fully match regular Chrome behavior; Puppeteer describes it as currently more performant for automation tasks that do not need Chrome’s full feature set.
• headless: false launches a visible browser.

See Puppeteer’s headless modes guide. DevTools also affects launch behavior: with devtools: true, headless is forced off by default behavior, and the current implementation adds --auto-open-devtools-for-tabs. Extension configuration can affect whether the default argument that disables extensions is added. Inspect the output for the options you actually use.

Add, filter, or omit defaults

Add an argument while retaining defaults

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  args: ['--window-size=1440,900'],
});
try {
  // Use browser and pages here.
} finally {
  await browser.close();
}

The custom flag is additional; the default arguments remain.

Filter one default argument

The official launch API demonstrates filtering --mute-audio like this:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  ignoreDefaultArgs: ['--mute-audio'],
});
try {
  // Use browser and pages here.
} finally {
  await browser.close();
}

This is useful when you need to change one default while preserving the rest. Confirm the flag is present in the arguments generated by your version and mode.

Omit all default arguments

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  ignoreDefaultArgs: true,
  args: ['--some-required-flag'],
});
try {
  // Use browser and pages here.
} finally {
  await browser.close();
}

ignoreDefaultArgs: true is a substantial change. Puppeteer may rely on defaults for expected startup and automation behavior, so omitting all of them can cause launch failures or unexpected browser behavior. Add only the flags your setup requires, and diagnose problems against the generated defaults before adopting this mode. See the LaunchOptions reference.

Keep Chrome’s sandbox enabled where possible

Puppeteer does not ordinarily add --no-sandbox to its default list. Chrome’s sandbox protects the host from untrusted web content. Puppeteer’s troubleshooting guidance recommends configuring a sandbox and strongly discourages running without one. Treat --no-sandbox as a last-resort workaround only when the content is fully trusted and a usable sandbox cannot be configured, not as a routine CI or Docker setting. Read the Puppeteer troubleshooting guide.

Or skip the browser setup

If your goal is to get a website screenshot rather than manage Chrome flags, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation.

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}`);
await Bun.write('shot.webp', res);

ScreenshotNeo accepts cookie and 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, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000. Every feature is on every plan.

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

Performance, reliability, and cost considerations

• Version reliability: Call defaultArgs() at runtime or inspect the source matching your installed package. Do not copy a flag list from an old issue and assume it still applies.
• Configuration reliability: Record the Puppeteer version, executable, headless mode, DevTools and extension options, custom args, and ignoreDefaultArgs setting when comparing two launches.
• Performance: Headless shell may be more performant for automation that does not need full Chrome behavior, according to Puppeteer’s current guide. Measure your own workload; flags that alter background behavior are not universal speed improvements.
• Startup timeout: The documented default LaunchOptions.timeout is 30 seconds while waiting for the browser to start. If startup is slow, investigate executable availability and environment configuration before simply increasing the timeout.
• Cost: Puppeteer itself does not charge per screenshot, but running a browser consumes your compute, memory, storage, and operational time. A hosted screenshot API trades browser management for service pricing; ScreenshotNeo’s free and paid tiers are listed above.

Troubleshooting common launch argument problems

Symptom	Likely cause	What to do
A copied flag is missing	The Puppeteer version or launch options differ; some flags are conditional.	Print await puppeteer.defaultArgs(options) with the same options passed to launch.
A custom flag appears ineffective	args adds flags but does not replace defaults; a default may conflict or a flag may not be supported by that Chrome build.	Inspect the full argument list, check the matching Chrome version, and selectively filter a confirmed conflicting default if appropriate.
Browser fails after setting ignoreDefaultArgs: true	Required Puppeteer defaults were removed.	Restore defaults, then filter only the single unwanted flag with an array.
Audio is muted in headless mode	The current headless defaults include --mute-audio.	Verify it appears in your generated list and filter it with ignoreDefaultArgs: ['--mute-audio'].
Browser is visible when headless was expected	devtools: true can force headless off by default, or options may differ between inspection and launch.	Check the effective options and inspect the generated arguments for that exact configuration.
Extensions do not load	The default disabling-extensions argument or launch mode may affect them.	Review the installed version’s extension guidance and generated args; check enableExtensions in the launch options documentation.
Chrome reports sandbox startup errors	The runtime cannot use the configured sandbox.	Configure the host/container sandbox as recommended by Puppeteer. Avoid routinely disabling it with --no-sandbox.
Browser times out during startup	Missing or incompatible executable, constrained resources, or environment setup can delay startup beyond the default timeout.	Check Puppeteer’s browser installation and compatibility guidance, then adjust the documented timeout only if the delay is expected.
Container crashes or behaves differently	Shared memory, permissions, Chrome build, or resource limits may differ from local development.	Compare the executable and runtime environment first; do not assume a particular environment flag is universally required.

Frequently asked questions

How do I print Puppeteer’s default Chrome flags?

Call await puppeteer.defaultArgs(options) and log the result. Pass the relevant launch options so mode-dependent arguments match your intended launch.

Does args replace Puppeteer’s defaults?

No. It adds extra browser command-line arguments. Use ignoreDefaultArgs to filter selected defaults or omit the full set.

Are Puppeteer’s defaults identical across Chrome versions?

No. Puppeteer version, browser executable, and launch options matter. Puppeteer recommends its downloaded Chrome for Testing version and does not guarantee operation with every other Chrome version; see the launch API documentation.

Should I use --no-sandbox in CI?

Not as a routine default. Configure Chrome’s sandbox where possible; Puppeteer strongly discourages running without one.

What is the difference between headless: true and headless: 'shell'?

true uses current headless Chrome. 'shell' uses the separate headless shell binary, which does not fully match regular Chrome but may suit automation that does not need its full feature set.