Puppeteer Default Browser Arguments Explained

Puppeteer’s default browser arguments are the flags it generates for a launch. To inspect them for your installed Puppeteer version and launch options, call puppeteer.defaultArgs(options). To add a flag, use args; to remove one or more Puppeteer defaults, use ignoreDefaultArgs. The exact returned list depends on the package version, options, browser, and platform, so don’t treat an online list as universal.

Inspect the arguments for your configuration

defaultArgs(options) is Puppeteer’s documented public inspection method. It returns a string array of the default arguments used for a browser launch. Pass the launch options you are investigating, then inspect the result from the Puppeteer package installed in your project.

import puppeteer from 'puppeteer';

const options = {
  headless: true,
};

const args = puppeteer.defaultArgs(options);
console.log(args);

const browser = await puppeteer.launch(options);
try {
  console.log(await browser.version());
} finally {
  await browser.close();
}

Save or log the array when diagnosing a launch issue. Compare it after changing Puppeteer versions or launch options. The inspection call tells you the generated defaults; the browser version call can help establish which browser actually launched.

Add a custom argument or filter a default

These options solve different problems:

Intent	Option	Effect
Add a custom browser flag	args: ['--example-flag']	Adds command-line arguments; it does not replace Puppeteer’s defaults.
Remove one selected Puppeteer default	ignoreDefaultArgs: ['--mute-audio']	Filters the named flag from the defaults.
Suppress all Puppeteer defaults	ignoreDefaultArgs: true	Does not use the generated default argument set.

Add a flag

import puppeteer from 'puppeteer';

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

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

Replace the illustrative value with a flag supported by the browser you launch. Puppeteer documents args as additional command-line arguments.

Remove one default selectively

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();
}

This follows Puppeteer’s documented example. Use selective filtering when you have a specific reason to remove a particular default. Puppeteer cautions that its defaults are usually wanted.

Suppress the whole default set only when necessary

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

This is a broad change: Puppeteer will not use the arguments returned by defaultArgs(). The browser may need launch configuration that Puppeteer normally supplies. Use this only when you understand the requirements of your browser and environment, and verify the resulting launch.

Options, browser choice, and version context

The returned defaults are tied to the options and Puppeteer release you use. For a useful inspection, pass the relevant options instead of assuming the no-argument output describes a different launch. Consult the API documentation for your installed release; the documented reference in the research dossier is Puppeteer 25.12.0.

Puppeteer’s documented launch options use Chrome by default. The executablePath option can select a custom executable, but Puppeteer says it is guaranteed to work with its bundled browser and works best with the Chrome for Testing version it downloads. Other Chrome versions are not guaranteed. With puppeteer-core, provide executablePath or channel.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  executablePath: '/path/to/chrome',
  // or specify a supported channel instead
});

try {
  console.log(await browser.version());
} finally {
  await browser.close();
}

Replace the path with the browser executable available in your environment. If you use a custom executable, set the browser option when appropriate; Puppeteer documents Chrome as the default browser and recommends identifying the browser when using a custom path. Browser-launcher package APIs have their own option surfaces, so check the documentation for the method and package your code actually calls.

Common errors and troubleshooting

Symptom	Likely cause	What to check
The browser no longer starts after changing arguments	A required default was filtered or the full default set was suppressed.	Remove the ignoreDefaultArgs change, confirm the baseline launch works, then filter only the one flag you need to change.
A custom flag appears to have no effect	The value may not be supported by the selected browser, or the launched executable may differ from the one you expected.	Inspect defaultArgs(options), check the executable or channel, and confirm the launched browser version.
The printed arguments differ from a blog post or another machine	The reference may use another Puppeteer version, option set, platform, or browser.	Run defaultArgs() from the package installed in your project and pass the launch options you use.
puppeteer-core cannot locate a browser	The browser location or channel has not been supplied.	Set executablePath or channel as required by the launch configuration.
A custom Chrome version behaves differently	Puppeteer does not guarantee compatibility with arbitrary Chrome versions.	Try the bundled Chrome for Testing binary, which Puppeteer says it works best with, or validate the specific custom version you need.

Performance, reliability, and cost

Argument inspection is a local API call and does not itself launch a browser. Browser startup and page work depend on the browser, environment, and page; the supplied sources do not establish universal performance figures. Avoid removing defaults as a routine optimization: first identify the specific startup or behavior issue, then make the narrowest supported change and verify it under your target configuration.

For reliability, keep the Puppeteer version and browser choice explicit in deployment, inspect the generated defaults when upgrading, and exercise the same launch options used in production. Puppeteer’s compatibility guarantee is centered on its bundled browser, not arbitrary installed Chrome versions. Browser hosting and runtime costs are determined by your environment; the cited API documentation gives no cost benchmark.

Or skip the browser setup

If your goal is to capture a website rather than control a local browser launch, ScreenshotNeo provides a one-request screenshot API. 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.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);

• Cookie banners are accepted and removed before capture; more than 60 known consent platforms, newsletter popups, and chat widgets can be removed, with each step configurable.
• Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and whether it was billed.
• An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Learn about ScreenshotNeo, then sign up for 1,000 free screenshots a month with no card.

FAQ

How do I see Puppeteer’s default launch arguments?

Call puppeteer.defaultArgs(options) and inspect the returned string array.

Does args replace Puppeteer’s defaults?

No. It adds command-line arguments. Use ignoreDefaultArgs to filter or suppress defaults.

What does ignoreDefaultArgs accept?

The documented default is false. Set it to true to suppress the defaults, or pass a string array to filter selected arguments.

Is there one universal list of Puppeteer arguments?

No. Inspect the installed package with the launch options you actually use; version and configuration affect the result.