Puppeteer BrowserLauncher defaultArgs: How to Set Browser Launch Arguments

Direct answer: To add browser command-line switches when launching Puppeteer, pass them in the args array. To omit one or more switches Puppeteer supplies by default, pass their names in ignoreDefaultArgs. Use puppeteer.defaultArgs(options) to inspect the computed list; in the Node.js API it returns a promise, so await it.

BrowserLauncher.defaultArgs(options) is the launcher-level API documented as accepting LaunchOptions and returning string[]. The public Node-facing puppeteer.defaultArgs(options?) and documented defaultArgs(options?) function return Promise<string[]>. See the official BrowserLauncher.defaultArgs reference, PuppeteerNode.defaultArgs reference, and defaultArgs function reference.

1. Inspect the arguments Puppeteer will use

Install Puppeteer in a Node.js project, then run this script to print the options-derived defaults:

const puppeteer = require('puppeteer');

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

The returned array is useful for diagnostics and for understanding how options affect the browser command line. It is an inspection result; changing this array does not change a later launch. Pass launch customizations to puppeteer.launch().

2. Add a browser launch argument

Use args for additional Chrome switches. This example launches a page at a chosen viewport size:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    args: ['--window-size=1280,800'],
  });

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

Each entry in args is a command-line argument string. Keep each switch and its value in the format expected by Chrome, commonly one string such as --window-size=1280,800. Puppeteer documents args as additional browser command-line arguments in its LaunchOptions reference.

3. Omit selected defaults with ignoreDefaultArgs

If a specific Puppeteer-supplied default is incompatible with your setup, filter only that argument by name and preserve the rest. Puppeteer’s launch reference demonstrates this pattern with --mute-audio:

const puppeteer = require('puppeteer');

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

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

The choices have different scopes:

Option	Effect	When it fits
args: ['--flag=value']	Adds a switch to Puppeteer’s normal launch arguments.	Ordinary launch customization.
ignoreDefaultArgs: ['--flag']	Filters the named default argument or arguments and preserves other defaults.	A targeted compatibility change.
ignoreDefaultArgs: true	Disables all Puppeteer default arguments.	Only when you understand and intentionally manage the consequences.

Puppeteer’s launch documentation cautions that the defaults are generally wanted. Prefer a targeted list over true when only one default needs to change. Removing all defaults can disrupt assumptions Puppeteer makes about launching Chrome. See the official launch reference and LaunchOptions reference.

4. Combine inspection and launch configuration

This complete CommonJS example prints the defaults for the selected options, then launches with an added switch while leaving Puppeteer’s defaults enabled:

const puppeteer = require('puppeteer');

(async () => {
  const launchOptions = {
    headless: true,
    args: ['--window-size=1280,800'],
  };

  const defaults = await puppeteer.defaultArgs({ headless: launchOptions.headless });
  console.log('Default arguments:', defaults);

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

Use the same relevant launch options when inspecting and launching so the printed list corresponds to the configuration you intend to examine. Check the API reference for the Puppeteer version installed in your project; the reviewed official references display version 25.12.0.

5. Browser and version compatibility

Puppeteer works best with its bundled Chrome for Testing version. Its launch documentation does not guarantee operation with other Chrome versions. If using puppeteer-core, provide an executablePath or channel as appropriate for your browser installation. Confirm the option signatures and compatibility notes for your installed Puppeteer release in the official launch documentation.

6. Troubleshooting launch arguments

Symptom	Likely cause	What to do
The browser fails to start after changing defaults.	ignoreDefaultArgs: true removed arguments Puppeteer expects.	Remove the boolean override and restore defaults. If a single default is the issue, filter only that name with an array.
A custom switch appears to have no effect.	The switch may be malformed, unsupported by the selected browser, or not applicable to the page behavior.	Check the switch spelling and value format, then verify it is intended for the Chrome version being launched. Inspect the computed defaults separately with puppeteer.defaultArgs().
The requested browser executable is missing or incompatible.	The project uses puppeteer-core without selecting a browser, or uses a Chrome version outside Puppeteer’s supported pairing.	Set a valid executablePath or channel for puppeteer-core, and prefer Puppeteer’s bundled Chrome for Testing where possible.
The printed argument list differs from what you expected.	The list is computed from the options passed to defaultArgs; it may not reflect options supplied only to a separate launch call.	Pass corresponding options to defaultArgs when inspecting, and remember that inspection itself does not modify a launch.
The script exits before printing the list.	The asynchronous result was not awaited or the call is outside an async context.	Use await puppeteer.defaultArgs(...) inside an async function, or use a promise handler.

7. Performance, reliability, and cost

Calling defaultArgs() computes and returns a list; the reference provides no benchmark or timing guarantee. The larger operational cost is usually the browser launch and the page work your application performs. Avoid repeatedly launching browsers when your workload can safely reuse a browser process, and close browsers in a finally block so failures do not leave processes running.

For reliability, keep Puppeteer’s defaults unless a documented need requires a change, make one targeted argument adjustment at a time, and confirm the browser version and executable configuration. A custom switch can affect browser behavior and compatibility, so validate it in the environment where the script will run. No cost or performance figures are asserted here.

8. Or skip the browser setup

If your goal is a website screenshot rather than browser automation, ScreenshotNeo is a website screenshot API and MCP server for developers. Its single GET request accepts a URL and returns an image or PDF; the API documentation describes the available parameters.

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());
require('node:fs').writeFileSync('shot.webp', bytes);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with response headers indicating the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free account and get 1,000 screenshots a month with no card.

9. FAQ

Does defaultArgs launch Chrome?

No. It returns the argument list for the supplied options. Call puppeteer.launch() to start a browser.

Can args replace Puppeteer’s defaults?

args adds switches. Use ignoreDefaultArgs when you need to filter default arguments.

Should I set ignoreDefaultArgs to true?

Usually not. Puppeteer’s documentation advises that you probably want its defaults. Filter a specific argument when that is sufficient.

Is defaultArgs synchronous?

The abstract BrowserLauncher.defaultArgs method is documented as returning string[]; the Node-facing public API returns Promise<string[]>, so use await in Node.js.