0
# Browser Installation
1

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

4
## Capabilities
5

6
### Install Function
7

8
Downloads and unpacks browser archives according to InstallOptions. Provides two modes: unpacking (default) and download-only.
9

10
```typescript { .api }
11
/**
12
 * Downloads and unpacks the browser archive according to InstallOptions
13
 * @param options - Installation configuration with unpack enabled (default)
14
 * @returns Promise resolving to InstalledBrowser instance
15
 */
16
function install(options: InstallOptions & {unpack?: true}): Promise<InstalledBrowser>;
17

18
/**
19
 * Downloads the browser archive without unpacking
20
 * @param options - Installation configuration with unpack disabled
21
 * @returns Promise resolving to absolute path of downloaded archive
22
 */
23
function install(options: InstallOptions & {unpack: false}): Promise<string>;
24

25
interface InstallOptions {
26
  /** Path to download browsers to */
27
  cacheDir: string;
28
  /** Target platform (auto-detected if not provided) */
29
  platform?: BrowserPlatform;
30
  /** Browser to install */
31
  browser: Browser;
32
  /** Build identifier for caching */
33
  buildId: string;
34
  /** Alias for the build ID (e.g., 'canary') */
35
  buildIdAlias?: string;
36
  /** Progress callback or 'default' for built-in progress bar */
37
  downloadProgressCallback?: 'default' | ((downloadedBytes: number, totalBytes: number) => void);
38
  /** Download host URL (uses default browser-specific URLs if not provided) */
39
  baseUrl?: string;
40
  /** Whether to unpack archives (default: true) */
41
  unpack?: boolean;
42
  /** Install system dependencies (default: false, Linux Chrome only) */
43
  installDeps?: boolean;
44
}
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { install, Browser, BrowserPlatform } from "@puppeteer/browsers";
51

52
// Install latest Chrome with default settings
53
const browser = await install({
54
  cacheDir: "./browsers-cache",
55
  browser: Browser.CHROME,
56
  buildId: "118.0.5993.70"
57
});
58

59
console.log("Installed at:", browser.path);
60
console.log("Executable:", browser.executablePath);
61

62
// Install with progress tracking
63
const browserWithProgress = await install({
64
  cacheDir: "./browsers-cache",
65
  browser: Browser.FIREFOX,
66
  buildId: "119.0",
67
  downloadProgressCallback: (downloaded, total) => {
68
    const percent = (downloaded / total * 100).toFixed(1);
69
    console.log(`Download progress: ${percent}%`);
70
  }
71
});
72

73
// Download archive without unpacking
74
const archivePath = await install({
75
  cacheDir: "./browsers-cache",
76
  browser: Browser.CHROMIUM,
77
  buildId: "1097615",
78
  unpack: false
79
});
80

81
console.log("Archive downloaded to:", archivePath);
82
```
83

84
### Uninstall Function
85

86
Removes a specific browser installation from the cache directory.
87

88
```typescript { .api }
89
/**
90
 * Uninstalls a browser from the cache directory
91
 * @param options - Uninstallation configuration
92
 */
93
function uninstall(options: UninstallOptions): Promise<void>;
94

95
interface UninstallOptions {
96
  /** Target platform (auto-detected if not provided) */
97
  platform?: BrowserPlatform;
98
  /** Path to cache directory */
99
  cacheDir: string;
100
  /** Browser to uninstall */
101
  browser: Browser;
102
  /** Build identifier to uninstall */
103
  buildId: string;
104
}
105
```
106

107
**Usage Example:**
108

109
```typescript
110
import { uninstall, Browser } from "@puppeteer/browsers";
111

112
// Uninstall specific browser version
113
await uninstall({
114
  cacheDir: "./browsers-cache",
115
  browser: Browser.CHROME,
116
  buildId: "118.0.5993.70"
117
});
118

119
console.log("Browser uninstalled successfully");
120
```
121

122
### Get Installed Browsers
123

124
Retrieves metadata about all browsers installed in the cache directory.
125

126
```typescript { .api }
127
/**
128
 * Returns metadata about browsers installed in the cache directory
129
 * @param options - Query configuration
130
 * @returns Promise resolving to array of installed browser instances
131
 */
132
function getInstalledBrowsers(options: GetInstalledBrowsersOptions): Promise<InstalledBrowser[]>;
133

134
interface GetInstalledBrowsersOptions {
135
  /** Path to cache directory */
136
  cacheDir: string;
137
}
138
```
139

140
**Usage Example:**
141

142
```typescript
143
import { getInstalledBrowsers } from "@puppeteer/browsers";
144

145
// List all installed browsers
146
const browsers = await getInstalledBrowsers({
147
  cacheDir: "./browsers-cache"
148
});
149

150
browsers.forEach(browser => {
151
  console.log(`${browser.browser}@${browser.buildId} (${browser.platform})`);
152
  console.log(`  Path: ${browser.path}`);
153
  console.log(`  Executable: ${browser.executablePath}`);
154
});
155
```
156

157
### Can Download Check
158

159
Checks if a browser can be downloaded with the given options.
160

161
```typescript { .api }
162
/**
163
 * Checks if a browser can be downloaded with given options
164
 * @param options - Installation configuration to check
165
 * @returns Promise resolving to boolean indicating download availability
166
 */
167
function canDownload(options: InstallOptions): Promise<boolean>;
168
```
169

170
**Usage Example:**
171

172
```typescript
173
import { canDownload, Browser } from "@puppeteer/browsers";
174

175
// Check if browser version is available for download
176
const isAvailable = await canDownload({
177
  cacheDir: "./browsers-cache",
178
  browser: Browser.CHROME,
179
  buildId: "118.0.5993.70"
180
});
181

182
if (isAvailable) {
183
  console.log("Browser is available for download");
184
} else {
185
  console.log("Browser version not found");
186
}
187
```
188

189
### Get Download URL
190

191
Retrieves the URL for downloading a browser binary archive.
192

193
```typescript { .api }
194
/**
195
 * Retrieves URL for downloading browser binary archive
196
 * @param browser - Browser type
197
 * @param platform - Target platform
198
 * @param buildId - Build identifier
199
 * @param baseUrl - Optional base URL override
200
 * @returns Download URL
201
 */
202
function getDownloadUrl(
203
  browser: Browser, 
204
  platform: BrowserPlatform, 
205
  buildId: string, 
206
  baseUrl?: string
207
): URL;
208
```
209

210
**Usage Example:**
211

212
```typescript
213
import { getDownloadUrl, Browser, BrowserPlatform } from "@puppeteer/browsers";
214

215
// Get download URL for specific browser
216
const url = getDownloadUrl(
217
  Browser.CHROME,
218
  BrowserPlatform.LINUX,
219
  "118.0.5993.70"
220
);
221

222
console.log("Download URL:", url.toString());
223
```
224

225
### Progress Callback Factory
226

227
Creates a default progress callback function for browser downloads.
228

229
```typescript { .api }
230
/**
231
 * Creates default progress callback for browser downloads
232
 * @param browser - Browser type
233
 * @param buildId - Build identifier
234
 * @returns Progress callback function with built-in progress bar
235
 */
236
function makeProgressCallback(
237
  browser: Browser, 
238
  buildId: string
239
): (downloadedBytes: number, totalBytes: number) => void;
240
```
241

242
**Usage Example:**
243

244
```typescript
245
import { install, makeProgressCallback, Browser } from "@puppeteer/browsers";
246

247
// Install with default progress callback
248
const progressCallback = makeProgressCallback(Browser.CHROME, "118.0.5993.70");
249

250
const browser = await install({
251
  cacheDir: "./browsers-cache",
252
  browser: Browser.CHROME,
253
  buildId: "118.0.5993.70",
254
  downloadProgressCallback: progressCallback
255
});
256
```
257

258
## Installation Process
259

260
The installation process follows these steps:
261

262
1. **Platform Detection**: Automatically detects OS and architecture if not specified
263
2. **Download URL Resolution**: Resolves appropriate download URL for browser/platform/build combination  
264
3. **Cache Check**: Checks if browser is already installed to avoid duplicate downloads
265
4. **Download**: Downloads browser archive with optional progress tracking
266
5. **Extraction**: Unpacks archive to cache directory (unless `unpack: false`)
267
6. **Metadata**: Updates cache metadata with installation information and aliases
268
7. **Dependencies**: Installs system dependencies if `installDeps: true` (Linux Chrome only)
269

270
## Supported Browsers and Platforms
271

272
### Browsers
273
- **Chrome**: Chrome for Testing binaries with stable/dev/canary/beta channels
274
- **Chromium**: Chromium snapshots from tip-of-tree builds
275
- **Firefox**: Firefox releases including stable/nightly/devedition channels
276
- **Chrome Headless Shell**: Headless Chrome for automation
277
- **ChromeDriver**: WebDriver implementation for Chrome
278

279
### Platforms
280
- **Linux**: x64 and ARM64 architectures
281
- **macOS**: Intel and Apple Silicon (ARM64) architectures  
282
- **Windows**: 32-bit and 64-bit architectures
283

284
## Error Handling
285

286
Installation functions may throw errors for:
287

288
- **Network Issues**: Download failures, connection timeouts
289
- **File System Issues**: Permission errors, disk space, invalid paths
290
- **Platform Issues**: Unsupported platform/browser combinations
291
- **Version Issues**: Invalid build IDs, unavailable versions
292
- **Archive Issues**: Corrupted downloads, extraction failures
293

294
Always wrap installation calls in try-catch blocks for proper error handling.