Implementation:Microsoft Playwright Playwright Install CLI
| Knowledge Sources | |
|---|---|
| Domains | Testing, Browser_Automation |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Concrete tool for setting up a Playwright testing project by installing browser binaries and scaffolding the project structure, provided by the Playwright library.
Description
The playwright install CLI command is the primary mechanism for downloading and managing browser binaries in a Playwright project. It is implemented as a commander.js subcommand within the playwright-core package. The command resolves which browsers need to be installed by consulting a built-in Registry singleton, downloads platform-specific binaries to a local cache, and optionally installs operating system dependencies required by those browsers.
The command supports selective installation (installing only specific browsers), forced re-downloads, dry-run mode for CI validation, and shell/no-shell options for dependency installation. It uses proper-lockfile to prevent concurrent installations from corrupting the browser cache.
Usage
Use this command when setting up a new Playwright project, after upgrading Playwright to a new version, or when configuring CI pipelines that need browser binaries. It is also used to install individual browsers when a project only targets a subset of supported engines.
Code Reference
Source Location
- Repository: playwright
- File:
packages/playwright-core/src/cli/program.ts(lines 139-211)
Signature
program
.command('install [browser...]')
.description('ensure browsers necessary for this version of Playwright are installed')
.option('--with-deps', 'install system dependencies for browsers')
.option('--force', 'force reinstall of stable browser channels')
.option('--dry-run', 'do not execute installation, only print information')
.option('--only-shell', 'only install shell dependencies (Linux only)')
.option('--no-shell', 'do not install shell dependencies (Linux only)')
.action(async (args: string[], options: {
withDeps?: boolean;
force?: boolean;
dryRun?: boolean;
onlyShell?: boolean;
noShell?: boolean;
}) => Promise<void>)
Import
npx playwright install [browser...]
This is a CLI command, not a programmatic API. It is invoked from the command line or from scripts.
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| args | string[] |
No | Optional list of browser names to install (e.g., chromium, firefox, webkit, msedge, chrome). If omitted, all default browsers are installed.
|
| --with-deps | boolean |
No | When set, also installs operating system dependencies required by the browsers (e.g., shared libraries on Linux). Requires elevated privileges on some systems. |
| --force | boolean |
No | Forces re-download of browsers even if they already exist in the cache. Useful when a cached binary is corrupted. |
| --dry-run | boolean |
No | Prints what would be installed without actually downloading anything. Useful for CI validation and debugging. |
| --only-shell | boolean |
No | Only installs shell-level system dependencies without downloading browser binaries. Linux only. |
| --no-shell | boolean |
No | Skips installation of shell dependencies. Linux only. |
| Registry singleton | Registry |
Internal | The browser registry at registry/index.ts:L575 that maps browser names to download URLs and expected versions.
|
Outputs
| Name | Type | Description |
|---|---|---|
| Browser binaries | Files on disk | Downloaded and extracted browser executables placed in the Playwright cache directory (typically ~/.cache/ms-playwright/ on Linux, ~/Library/Caches/ms-playwright/ on macOS, %LOCALAPPDATA%\ms-playwright on Windows).
|
| Console output | string |
Progress information during download, including browser names, versions, download sizes, and installation paths. |
| Exit code | number |
0 on success, non-zero on failure (e.g., network errors, permission issues).
|
Usage Examples
Basic Example
# Install all default browsers
npx playwright install
# Install only Chromium
npx playwright install chromium
# Install Chromium and Firefox with system dependencies
npx playwright install --with-deps chromium firefox
# Dry run to see what would be installed
npx playwright install --dry-run
# Force re-download of all browsers
npx playwright install --force
CI Pipeline Example
# In a Dockerfile or CI setup step
npx playwright install --with-deps chromium
Programmatic Context
// The install command internally uses the Registry singleton:
// At packages/playwright-core/src/server/registry/index.ts:L575
//
// const registry = new Registry(browsersPath);
// await registry.install(browsers, { force, dryRun });
//
// The Registry resolves download URLs, manages the cache directory,
// and coordinates browser extraction using proper-lockfile for
// concurrent safety.