0
# @puppeteer/browsers
1

2
@puppeteer/browsers is a comprehensive CLI tool and programmatic API for downloading, managing, and launching web browsers (Chrome, Chromium, Firefox) and browser drivers (ChromeDriver) for testing and automation purposes. It provides cross-platform support with built-in progress tracking, automatic extraction, and intelligent caching of browser installations.
3

4
## Package Information
5

6
- **Package Name**: @puppeteer/browsers
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @puppeteer/browsers`
10
- **CLI Usage**: `npx @puppeteer/browsers --help`
11

12
## Core Imports
13

14
```typescript
15
import { 
16
  install, 
17
  launch, 
18
  computeExecutablePath,
19
  Browser,
20
  BrowserPlatform,
21
  CLI
22
} from "@puppeteer/browsers";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { 
29
  install, 
30
  launch, 
31
  computeExecutablePath,
32
  Browser,
33
  BrowserPlatform 
34
} = require("@puppeteer/browsers");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { 
41
  install, 
42
  launch, 
43
  computeExecutablePath,
44
  Browser, 
45
  BrowserPlatform 
46
} from "@puppeteer/browsers";
47

48
// Install a browser
49
const installedBrowser = await install({
50
  cacheDir: "./browsers-cache",
51
  browser: Browser.CHROME,
52
  buildId: "118.0.5993.70"
53
});
54

55
// Compute executable path
56
const executablePath = computeExecutablePath({
57
  cacheDir: "./browsers-cache",
58
  browser: Browser.CHROME,
59
  buildId: "118.0.5993.70"
60
});
61

62
// Launch browser
63
const browserProcess = launch({
64
  executablePath,
65
  args: ["--no-sandbox"]
66
});
67

68
// Use the browser process
69
console.log("Browser launched with PID:", browserProcess.nodeProcess.pid);
70

71
// Clean up
72
await browserProcess.close();
73
```
74

75
## Architecture
76

77
@puppeteer/browsers is built around several key components:
78

79
- **Installation System**: Downloads and manages browser binaries with caching and version management
80
- **Launch System**: Advanced browser process management with signal handling and lifecycle control
81
- **Cache Management**: Intelligent storage and retrieval of browser installations with metadata support
82
- **Platform Detection**: Automatic detection of OS and architecture for cross-platform compatibility
83
- **CLI Interface**: Complete command-line tool for installation, launching, and management operations
84
- **Browser Data**: Comprehensive browser-specific configuration and version resolution
85

86
## Capabilities
87

88
### Browser Installation
89

90
Comprehensive browser download and installation management with support for multiple browsers, platforms, and version resolution. Handles progress tracking, archive extraction, and dependency installation.
91

92
```typescript { .api }
93
function install(options: InstallOptions): Promise<InstalledBrowser>;
94
function install(options: InstallOptions & {unpack: false}): Promise<string>;
95

96
interface InstallOptions {
97
  cacheDir: string;
98
  platform?: BrowserPlatform;
99
  browser: Browser;
100
  buildId: string;
101
  buildIdAlias?: string;
102
  downloadProgressCallback?: 'default' | ((downloadedBytes: number, totalBytes: number) => void);
103
  baseUrl?: string;
104
  unpack?: boolean;
105
  installDeps?: boolean;
106
}
107
```
108

109
[Browser Installation](./installation.md)
110

111
### Browser Launching
112

113
Advanced browser process management with customizable launch options, signal handling, and process lifecycle control. Supports both cached and system-installed browsers.
114

115
```typescript { .api }
116
function launch(opts: LaunchOptions): Process;
117
function computeExecutablePath(options: ComputeExecutablePathOptions): string;
118
function computeSystemExecutablePath(options: SystemOptions): string;
119

120
interface LaunchOptions {
121
  executablePath: string;
122
  pipe?: boolean;
123
  dumpio?: boolean;
124
  args?: string[];
125
  env?: Record<string, string | undefined>;
126
  handleSIGINT?: boolean;
127
  handleSIGTERM?: boolean;
128
  handleSIGHUP?: boolean;
129
  detached?: boolean;
130
  onExit?: () => Promise<void>;
131
}
132
```
133

134
[Browser Launching](./launching.md)
135

136
### Cache Management
137

138
Browser cache directory management with metadata handling, alias resolution, and installation tracking. Provides comprehensive control over browser storage and cleanup.
139

140
```typescript { .api }
141
class Cache {
142
  constructor(rootDir: string);
143
  get rootDir(): string;
144
  getInstalledBrowsers(): InstalledBrowser[];
145
  uninstall(browser: Browser, platform: BrowserPlatform, buildId: string): void;
146
  clear(): void;
147
  resolveAlias(browser: Browser, alias: string): string | undefined;
148
  computeExecutablePath(options: ComputeExecutablePathOptions): string;
149
}
150

151
class InstalledBrowser {
152
  browser: Browser;
153
  buildId: string;
154
  platform: BrowserPlatform;
155
  readonly executablePath: string;
156
  get path(): string;
157
}
158
```
159

160
[Cache Management](./cache.md)
161

162
### Command Line Interface
163

164
Full-featured CLI for browser management operations including installation, launching, listing, and cleanup. Supports all programmatic features through command-line interface.
165

166
```typescript { .api }
167
class CLI {
168
  constructor(opts?: string | CLIOptions, rl?: readline.Interface);
169
  run(argv: string[]): Promise<void>;
170
}
171
```
172

173
**Available Commands:**
174
- `install [browser]` - Download and install browsers
175
- `launch <browser>` - Launch installed browsers  
176
- `clear` - Remove all installed browsers
177
- `list` - List all installed browsers
178

179
[Command Line Interface](./cli.md)
180

181
### Browser Data and Platform Support
182

183
Browser-specific configuration, version resolution, and platform detection utilities. Supports Chrome, Chromium, Firefox, Chrome Headless Shell, and ChromeDriver across multiple platforms.
184

185
```typescript { .api }
186
function detectBrowserPlatform(): BrowserPlatform | undefined;
187
function resolveBuildId(browser: Browser, platform: BrowserPlatform, tag: string | BrowserTag): Promise<string>;
188
function getVersionComparator(browser: Browser): (a: string, b: string) => number;
189
function createProfile(browser: Browser, opts: ProfileOptions): Promise<void>;
190

191
enum Browser {
192
  CHROME = 'chrome',
193
  CHROMEHEADLESSSHELL = 'chrome-headless-shell',
194
  CHROMIUM = 'chromium',
195
  FIREFOX = 'firefox',
196
  CHROMEDRIVER = 'chromedriver'
197
}
198

199
enum BrowserPlatform {
200
  LINUX = 'linux',
201
  LINUX_ARM = 'linux_arm',
202
  MAC = 'mac',
203
  MAC_ARM = 'mac_arm',
204
  WIN32 = 'win32',
205
  WIN64 = 'win64'
206
}
207
```
208

209
[Browser Data](./browser-data.md)
210

211
## Core Types
212

213
```typescript { .api }
214
interface ComputeExecutablePathOptions {
215
  cacheDir: string | null;
216
  platform?: BrowserPlatform;
217
  browser: Browser;
218
  buildId: string;
219
}
220

221
interface SystemOptions {
222
  platform?: BrowserPlatform;
223
  browser: Browser;
224
  channel: ChromeReleaseChannel;
225
}
226

227
interface UninstallOptions {
228
  platform?: BrowserPlatform;
229
  cacheDir: string;
230
  browser: Browser;
231
  buildId: string;
232
}
233

234
interface GetInstalledBrowsersOptions {
235
  cacheDir: string;
236
}
237

238
interface ProfileOptions {
239
  preferences: Record<string, unknown>;
240
  path: string;
241
}
242

243
enum ChromeReleaseChannel {
244
  STABLE = 'stable',
245
  DEV = 'dev',
246
  CANARY = 'canary',
247
  BETA = 'beta'
248
}
249

250
enum BrowserTag {
251
  CANARY = 'canary',
252
  NIGHTLY = 'nightly',
253
  BETA = 'beta',
254
  DEV = 'dev',
255
  DEVEDITION = 'devedition',
256
  STABLE = 'stable',
257
  ESR = 'esr',
258
  LATEST = 'latest'
259
}
260

261
class Process {
262
  get nodeProcess(): childProcess.ChildProcess;
263
  close(): Promise<void>;
264
  hasClosed(): Promise<void>;
265
  kill(): void;
266
  waitForLineOutput(regex: RegExp, timeout?: number): Promise<string>;
267
}
268

269
class TimeoutError extends Error {
270
  constructor(message?: string);
271
}
272

273
const CDP_WEBSOCKET_ENDPOINT_REGEX: RegExp;
274
const WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX: RegExp;
275
```
276

277
## Utility Functions
278

279
```typescript { .api }
280
function canDownload(options: InstallOptions): Promise<boolean>;
281
function uninstall(options: UninstallOptions): Promise<void>;
282
function getInstalledBrowsers(options: GetInstalledBrowsersOptions): Promise<InstalledBrowser[]>;
283
function getDownloadUrl(browser: Browser, platform: BrowserPlatform, buildId: string, baseUrl?: string): URL;
284
function makeProgressCallback(browser: Browser, buildId: string): (downloadedBytes: number, totalBytes: number) => void;
285
```