How to Set Default Browser Arguments in Puppeteer

Set browser command-line flags in Puppeteer with the args array passed to puppeteer.launch(). Puppeteer still adds its own default arguments. To remove one specific default, pass its exact string in ignoreDefaultArgs; to omit all Puppeteer defaults, set ignoreDefaultArgs: true. You can inspect the default list with puppeteer.defaultArgs().

For most cases, add the flag you need and leave Puppeteer’s defaults enabled. The LaunchOptions reference cautions that those defaults are usually wanted.

Runnable example: add a browser argument

Install Puppeteer, then save this as launch.mjs and run it with Node.js. Puppeteer downloads a compatible Chrome for Testing browser by default.

npm install puppeteer

// launch.mjs
import puppeteer from 'puppeteer';

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

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

Replace --start-maximized with a flag supported by the browser and version you use. Browser switches are not guaranteed to behave identically across Chrome versions or other Chromium-based browsers.

Choose the right option

Goal	Option	Effect
Add one or more flags	args: ['--flag', '--other-flag']	Adds arguments while retaining Puppeteer’s defaults.
Remove one Puppeteer default	ignoreDefaultArgs: ['--exact-default-flag']	Filters only the specified default argument.
Omit all Puppeteer defaults	ignoreDefaultArgs: true	Leaves the caller responsible for the browser arguments needed for the launch.
Inspect defaults	await puppeteer.defaultArgs()	Returns the default argument list as an array of strings.

Remove one default argument

Use an array of exact strings in ignoreDefaultArgs when a particular Puppeteer-supplied switch conflicts with your use case. The official launch documentation demonstrates filtering --mute-audio:

import puppeteer from 'puppeteer';

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

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

Use the precise argument string that appears in the default list. A similar-looking string or a value with different formatting may not filter the intended argument.

Inspect Puppeteer’s default arguments

defaultArgs() returns a Promise<string[]>. Print the result to see which switches Puppeteer would supply:

import puppeteer from 'puppeteer';

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

The method accepts options. If your launch depends on options that affect the default list, consult the defaultArgs API reference and inspect the list for your setup.

When to use ignoreDefaultArgs: true

Setting ignoreDefaultArgs: true suppresses the complete Puppeteer default argument set. This gives you broad control, but you must supply and maintain the arguments your browser launch needs. Removing defaults can cause launch behavior to fail or differ from normal Puppeteer behavior, so start by filtering a single exact default when that is enough.

import puppeteer from 'puppeteer';

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

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

This is a structural example, not a complete recommended argument set. The required flags depend on the browser and environment; do not copy a minimal array into production without validating the launch and behavior you need.

Browser selection is configured separately

Arguments control switches passed to the browser process. They do not select which browser executable Puppeteer launches. Options such as executablePath and channel configure browser selection. The configuration reference also describes environment variables that can influence configuration values.

Puppeteer works best with the Chrome for Testing version it downloads by default and does not guarantee operation with arbitrary Chrome versions. The current launch reference says puppeteer-core requires either executablePath or channel.

import puppeteer from 'puppeteer-core';

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

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

Replace the executable path with one that exists in your environment, or configure a supported channel. Verify compatibility against the installed browser version.

Common errors and fixes

Symptom	Likely cause	Fix
Browser launch fails after changing arguments	All defaults were disabled, or a required argument was omitted.	Remove ignoreDefaultArgs: true and add only the needed flag. If you must disable defaults, inspect and maintain the full argument set for your environment.
A default switch is still present	The string in ignoreDefaultArgs does not exactly match the default argument.	Print await puppeteer.defaultArgs() and copy the exact argument string.
A flag has no visible effect	The browser may not support that switch, the switch may be version-specific, or it may require a value.	Check the browser’s supported flags and version, then pass the required flag and value in the documented command-line form.
puppeteer-core cannot find a browser	No executable path or channel was configured.	Set executablePath or channel, and verify the selected browser is available.
Behavior differs from local Chrome	The installed Chrome version differs from Puppeteer’s downloaded Chrome for Testing browser.	Use the bundled browser where practical, or validate the installed browser version and flags in the target environment.

Performance, reliability, and cost

• Performance: Adding a small number of launch arguments generally changes browser configuration rather than page code. The effect of a particular flag depends on what it changes; measure that behavior in your own workload instead of assuming a speedup.
• Reliability: Keep Puppeteer’s defaults unless there is a specific reason to change them. Browser switches and compatibility can vary by browser version and runtime environment.
• Cost: Puppeteer itself does not charge per screenshot. Your costs come from the machine or hosted browser environment you run and maintain.

Or skip the browser setup

If you only need a website screenshot, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. The request below saves a WebP screenshot; see the ScreenshotNeo API documentation for options 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}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; 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 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 shots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Does args replace Puppeteer’s default arguments?

No. It adds arguments. Use ignoreDefaultArgs to filter defaults or suppress the whole default set.

Can I pass several browser flags?

Yes. Put each switch in the args string array. Include any value using the browser’s expected argument syntax.

Where can I confirm the option names?

See the official LaunchOptions, launch method, defaultArgs method, and configuration interface references.