Implementation:Microsoft Playwright Registry Install

Knowledge Sources	Playwright Playwright CLI
Domains	Browser_Automation, CLI
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for downloading, caching, and validating browser binaries provided by the Playwright library.

Description

The Registry Install implementation is the core mechanism by which Playwright resolves, downloads, and caches browser binaries. It consists of two tightly coupled entry points:

The CLI command playwright install [browser...], defined in program.ts, which parses user arguments and delegates to the Registry.
The Registry.install() method, which performs the actual filesystem operations: acquiring a directory lock, removing stale browsers, downloading missing binaries, and writing installation markers.

The CLI layer handles argument validation, the --with-deps flag (which triggers system dependency installation via installDeps()), --dry-run mode (which prints download URLs and install locations without executing), --list mode (which enumerates installed browsers grouped by Playwright version), and the --force flag (which forces re-download of already installed browsers). The --only-shell and --no-shell flags control whether the Chromium headless shell variant is included.

Browser resolution is performed by resolveBrowsers(), which maps human-readable names like chromium, firefox, webkit, chrome, or msedge to Executable instances. Each Executable carries its name, browser name, install type (download-by-default, download-on-demand, install-script, or none), directory path, download URLs, and methods for locating and validating the binary.

After installation completes, validateHostRequirementsForExecutablesIfNeeded() checks that the host system provides required shared libraries, and reports any missing dependencies as warnings.

Usage

Use this implementation when:

Installing browser binaries for the first time after adding Playwright to a project.
Upgrading Playwright to a new version that requires newer browser revisions.
Setting up CI runners or Docker images with pre-installed browsers.
Diagnosing missing-browser or missing-dependency errors.

Code Reference

Source Location

Repository: playwright
CLI command: packages/playwright-core/src/cli/program.ts (lines 139-211)
Registry.install(): packages/playwright-core/src/server/registry/index.ts (lines 1052-1132)
resolveBrowsers(): packages/playwright-core/src/server/registry/index.ts (lines 1397-1435)
Executable interface: packages/playwright-core/src/server/registry/index.ts (lines 554-567)
registryDirectory: packages/playwright-core/src/server/registry/index.ts (lines 455-469)

Signature

// CLI command registration
program
  .command('install [browser...]')
  .option('--with-deps', 'install system dependencies for browsers')
  .option('--dry-run', 'do not execute installation, only print information')
  .option('--list', 'prints list of browsers from all playwright installations')
  .option('--force', 'force reinstall of already installed browsers')
  .option('--only-shell', 'only install headless shell when installing chromium')
  .option('--no-shell', 'do not install chromium headless shell')
  .action(async function(args: string[], options: {
    withDeps?: boolean,
    force?: boolean,
    dryRun?: boolean,
    list?: boolean,
    shell?: boolean,
    noShell?: boolean,
    onlyShell?: boolean,
  }) { ... });

// Registry.install method
async install(
  executablesToInstall: Executable[],
  options?: { force?: boolean }
): Promise<void>;

// Browser resolution
resolveBrowsers(
  aliases: string[],
  options: { shell?: 'no' | 'only' }
): Executable[];

// Executable interface
interface Executable {
  name: string;
  browserName: BrowserName | undefined;
  installType: 'download-by-default' | 'download-on-demand' | 'install-script' | 'none';
  directory: string | undefined;
  downloadURLs?: string[];
  title?: string;
  revision?: string;
  browserVersion?: string;
  executablePathOrDie(sdkLanguage: string): string;
  executablePath(): string | undefined;
  _validateHostRequirements(sdkLanguage: string): Promise<void>;
}

Import

# CLI usage (most common)
npx playwright install
npx playwright install chromium firefox webkit
npx playwright install --with-deps
npx playwright install --force chromium

# Programmatic usage (internal)
import { registry } from '../server';

I/O Contract

Inputs

Name	Type	Required	Description
args	string[]	No	Browser names to install: `chromium`, `firefox`, `webkit`, `chrome`, `msedge`, `ffmpeg`. Empty array installs all default browsers.
--with-deps	boolean	No	Also install system-level dependencies (shared libraries, fonts) for the selected browsers. Requires sudo on Linux.
--force	boolean	No	Force reinstall of browsers even if they are already present. Required for non-hermetic installations like Chrome or Edge.
--dry-run	boolean	No	Print download URLs and install locations without performing the actual download.
--list	boolean	No	List all installed browsers grouped by Playwright version.
--only-shell	boolean	No	When installing chromium, only install the headless shell variant.
--no-shell	boolean	No	When installing chromium, do not install the headless shell variant.

Outputs

Name	Type	Description
Browser binaries	Files on disk	Downloaded and extracted browser executables, stored in the platform-dependent cache directory (Linux: `~/.cache/ms-playwright`, macOS: `~/Library/Caches/ms-playwright`, Windows: `%LOCALAPPDATA%\ms-playwright`). Overridable via `PLAYWRIGHT_BROWSERS_PATH`.
INSTALLATION_COMPLETE marker	File	A marker file written into each browser directory upon successful installation.
Validation warnings	stderr	Warnings emitted if the host system is missing shared libraries required by the installed browsers.

Usage Examples

Basic Example

# Install all default browsers for the current Playwright version
npx playwright install

Install Specific Browsers

# Install only Chromium and Firefox
npx playwright install chromium firefox

Install with System Dependencies

# Install browsers and their OS-level dependencies (Linux, requires sudo)
npx playwright install --with-deps

Force Reinstall

# Force reinstall of Chrome (non-hermetic installation)
npx playwright install --force chrome

Dry Run

# Preview what would be downloaded without actually downloading
npx playwright install --dry-run

Headless Shell Only

# Install only the Chromium headless shell (smaller footprint for CI)
npx playwright install --only-shell chromium

Related Pages

Implements Principle

Principle:Microsoft_Playwright_Install_Browsers

Requires Environment

Uses Heuristic

Heuristic:Microsoft_Playwright_Test_Stability_Practices

Page Connections

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

Principle

Implementation

Heuristic

Environment