Implementation:Puppeteer Puppeteer LaunchOptions Configuration

Knowledge Sources	Puppeteer Puppeteer API
Domains	Browser_Automation, Cross_Browser_Testing
Last Updated	2026-02-11 23:00 GMT

Overview

Concrete configuration interface for specifying browser type, protocol, and launch settings in Puppeteer.

Description

The LaunchOptions interface defines the configuration contract for browser launching in Puppeteer. It extends ConnectOptions (which provides protocol selection) with browser-specific settings. The interface is used by PuppeteerNode.launch() and dispatched to ChromeLauncher or FirefoxLauncher.

This is a Pattern Doc — it documents a TypeScript interface (configuration pattern) rather than an executable function.

Usage

Construct a LaunchOptions object and pass it to puppeteer.launch(options) to configure browser type, protocol, headless mode, and other launch settings.

Code Reference

Source Location

Repository: puppeteer
File: packages/puppeteer-core/src/node/LaunchOptions.ts
Lines: 39-162

Signature

interface LaunchOptions extends ConnectOptions {
  executablePath?: string;                    // L54: Custom browser path
  handleSIGINT?: boolean;                     // L65: Handle SIGINT
  handleSIGTERM?: boolean;                    // L71: Handle SIGTERM
  handleSIGHUP?: boolean;                     // L77: Handle SIGHUP
  timeout?: number;                           // L82: Launch timeout ms
  dumpio?: boolean;                           // L88: Pipe browser I/O
  env?: Record<string, string | undefined>;   // L93: Environment vars
  pipe?: boolean;                             // L98: Use pipe transport
  browser?: SupportedBrowser;                 // L111: 'chrome' | 'firefox'
  extraPrefsFirefox?: Record<string, unknown>;// L115: Firefox preferences
  debuggingPort?: number;                     // L129: Remote debugging port
  headless?: boolean | 'shell';               // L137: Headless mode
  userDataDir?: string;                       // L143: User data directory
  args?: string[];                            // L157: Browser CLI args
}

Import

import type {LaunchOptions} from 'puppeteer';
// Used as parameter to puppeteer.launch()

I/O Contract

Inputs

Name	Type	Required	Description
browser	'chrome' or 'firefox'	No	Target browser (default: 'chrome')
protocol	'cdp' or 'webDriverBiDi'	No	Communication protocol (Chrome default: cdp, Firefox default: webDriverBiDi)
headless	boolean or 'shell'	No	Headless mode (default: true). 'shell' for old headless mode
executablePath	string	No	Custom browser executable path
args	string[]	No	Extra CLI arguments for the browser
extraPrefsFirefox	Record<string, unknown>	No	Firefox-specific preferences
userDataDir	string	No	Custom user data directory
timeout	number	No	Launch timeout in ms (default: 30000)

Outputs

Name	Type	Description
(configuration)	LaunchOptions	Passed to puppeteer.launch() which returns Promise<Browser>

Usage Examples

Launch Chrome (Default)

const browser = await puppeteer.launch();
// Equivalent to: { browser: 'chrome', protocol: 'cdp', headless: true }

Launch Firefox With BiDi

const browser = await puppeteer.launch({
  browser: 'firefox',
  protocol: 'webDriverBiDi',
});

Launch Chrome With BiDi

const browser = await puppeteer.launch({
  browser: 'chrome',
  protocol: 'webDriverBiDi',
});
const page = await browser.newPage();
await page.goto('https://example.com');
await page.pdf({path: 'test.pdf'});
await browser.close();

Launch With Proxy

const browser = await puppeteer.launch({
  args: ['--proxy-server=socks5://myproxy:8080'],
});

Related Pages

Implements Principle

Principle:Puppeteer_Puppeteer_Cross_Browser_Configuration

Requires Environment

Uses Heuristic

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment