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
```