Puppeteer defaultArgs(): Default Chrome Launch Arguments

puppeteer.defaultArgs(options) returns a Promise<string[]> containing the browser launch arguments Puppeteer would use for those options. Await it to inspect the array. The exact arguments depend on your installed Puppeteer version and launch configuration, so retrieve them locally instead of relying on a copied list. Puppeteer defaultArgs() API · PuppeteerNode.defaultArgs() API.

What does Puppeteer defaultArgs() return?

The method calculates the default command-line arguments for a browser launch. It does not launch Chrome. In Node.js, the documented method and top-level function accept optional LaunchOptions and resolve to an array of strings. The options you inspect should match the options relevant to your launch. Puppeteer’s current API reference documents this contract in version 25.12.0; check the reference and your installed package when version-specific details matter.

There is no single permanent list of flags that applies to every Puppeteer setup. Browser selection, headless mode, package version, and launch options affect the context. Puppeteer documents Chrome as the default browser, subject to configuration and environment overrides.

How to inspect the default arguments

Use the puppeteer package in a Node.js project. This example prints the arguments for headless Chrome without launching a browser:

import puppeteer from 'puppeteer';

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

Save it as inspect-args.mjs and run node inspect-args.mjs. For CommonJS, use const puppeteer = require('puppeteer'); and place the awaited call in an async function. The returned value is an array: inspect individual entries, filter it for a flag, or serialize it for a diagnostic log.

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

console.log(`Count: ${args.length}`);
console.log(args.join('\n'));
console.log('Has mute-audio:', args.includes('--mute-audio'));

This code demonstrates how to query the installed package; it does not promise a fixed result. To make the output meaningful, pass the same relevant launch options you use in production.

How to add or remove default Chrome arguments

The launch options have separate controls for adding arguments and changing Puppeteer’s defaults. LaunchOptions reference describes args as additional arguments and ignoreDefaultArgs as the option to suppress all defaults or filter selected entries.

Goal	Option	Effect
Add a browser flag	`args: ['--some-flag']`	Keeps Puppeteer’s defaults and passes an additional argument.
Filter one or more defaults	`ignoreDefaultArgs: ['--mute-audio']`	Removes the named argument or arguments from Puppeteer’s default set.
Suppress all defaults	`ignoreDefaultArgs: true`	Does not use Puppeteer’s default argument list.

Add an argument while keeping defaults

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  args: ['--start-maximized'],
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
} finally {
  await browser.close();
}

args adds arguments; it does not replace the default list. Select flags that are supported by the browser binary and appropriate for your environment.

Filter a particular default

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--mute-audio'],
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
} finally {
  await browser.close();
}

Puppeteer’s launch documentation uses filtering --mute-audio as an example. Replace it with the exact argument you have a reason to retain or remove. Check the inspected list first: spelling and presence can vary with versions and options.

Suppress the entire default set

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

This removes the defaults Puppeteer normally supplies. It can prevent Chrome from starting or functioning as expected because those arguments support Puppeteer’s launch assumptions. Puppeteer explicitly cautions users to use this option carefully and says they probably want the defaults. Prefer filtering a specific argument when a narrow change is enough.

Which options affect the launch context?

defaultArgs() accepts launch options, so make the inspection match your launch. The most relevant documented options include:

headless: defaults to true; true uses new headless mode, while 'shell' selects the old headless shell.
args: extra command-line arguments passed to the browser at launch. This option is useful when launching; do not confuse it with retrieving or replacing defaults.
ignoreDefaultArgs: true suppresses defaults; an array filters the named defaults.
browser: documented default is chrome, though configuration can change browser selection.
channel and executablePath: choose a regular Chrome channel or a specific browser binary rather than the bundled binary. Compatibility is your responsibility when using a different binary.

Other launch settings—such as devtools, userDataDir, pipe, timeout, and waitForInitialPage—change launch behavior. Consult the current LaunchOptions reference for their precise semantics and defaults. Do not infer that every launch setting maps to a Chrome argument; some control Puppeteer’s launch process.

puppeteer versus puppeteer-core

puppeteer is the Node package that ordinarily downloads and uses its supported Chrome for Testing browser. Puppeteer says it works best with that downloaded version and does not guarantee compatibility with other Chrome versions. For puppeteer-core, provide executablePath or channel when calling launch().

import puppeteer from 'puppeteer-core';

const options = {
  executablePath: '/path/to/chrome',
  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');
} finally {
  await browser.close();
}

Replace the example path with the actual browser executable on the host. A local inspection cannot validate that the binary exists or is compatible. For repeatable deployments, pin the Puppeteer package and browser source together and inspect arguments in that same environment.

Why does Puppeteer use default Chrome flags?

Puppeteer supplies defaults to make the browser launch in a way that supports its automation workflow. The exact list is implementation and version dependent; the API reference documents how to obtain it, not a universal canonical sequence. Treat the returned array as diagnostic output for your selected version and configuration, rather than as a stable interface to copy across projects.

Troubleshooting

Symptom	Likely cause	What to do
`args` is undefined or iteration fails	The promise was not awaited, or the function result was not captured.	Use `const args = await puppeteer.defaultArgs(options)` inside an async function or an ES module.
Output differs from a blog post or another machine	Different Puppeteer version, browser choice, options, or configuration.	Log the installed package version and inspect with the options used by the actual launch.
Chrome exits immediately after customizing arguments	A required default may have been suppressed, a flag may be unsupported, or the chosen browser binary may be incompatible.	Remove `ignoreDefaultArgs: true`, restore defaults, then make one change at a time. Use Puppeteer’s bundled Chrome for Testing when possible.
`puppeteer-core` reports missing browser path	No browser binary or release channel was provided.	Pass `executablePath` or `channel` to `launch()`.
A filtered flag remains in output	The filter was used at launch but the inspected options or package differ, or the spelling does not match the default entry.	Inspect the exact array returned for the relevant options and filter the precise string.
Launch timeout	The browser could not start before the configured timeout, which defaults to 30 seconds in the documented LaunchOptions reference.	Check the browser executable, runtime environment, and launch logs. Increase `timeout` only when startup legitimately needs longer; setting it to `0` disables that timeout.

Performance, reliability, and cost

Calling defaultArgs() computes and returns launch configuration; it does not start Chrome or capture a page. Its main practical value is diagnosis and controlled configuration. The expensive work is browser startup and page processing, not printing the argument array. Avoid repeatedly launching a browser just to discover the defaults when one inspection in the target runtime answers the question.

For reliability, retain Puppeteer’s defaults unless a specific flag causes a demonstrated problem. Pin versions in deployed environments, use the browser version Puppeteer installs when feasible, and include the selected browser source and launch options in diagnostic records. If a launch breaks after a customization, revert that customization before changing several flags at once.

Puppeteer and Chrome are software rather than a per-screenshot API, so this API reference does not establish a usage price. Operational costs depend on where you run the browser and the resources your workload consumes; no benchmark or cost figure is implied here.

Or skip the browser setup

If your goal is a website screenshot rather than browser automation, ScreenshotNeo can return an image or PDF with one GET request. Its API accepts common screenshot API parameter names, 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://example.com \
  -o shot.webp

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)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const data = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing status. ScreenshotNeo also provides an MCP server so AI agents can take screenshots. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does defaultArgs() launch Chrome?

No. It returns the arguments as a promise; use launch() to start a browser.

Can I depend on the returned array staying the same?

No. Treat it as dependent on Puppeteer version, browser selection, configuration, and supplied options.

Should I set ignoreDefaultArgs to true?

Usually not. Puppeteer advises caution because its defaults are generally needed; filter a specific argument only when you have a clear reason.

Can I inspect arguments for a custom Chrome binary?

You can pass the launch options used by your application, but inspecting the array does not prove that the custom binary supports those arguments or is compatible with Puppeteer.