Environment:Microsoft Playwright Browser Binaries Environment

Knowledge Sources	Microsoft Playwright Playwright Browsers
Domains	Infrastructure, Browser_Automation
Last Updated	2026-02-11 22:00 GMT

Overview

Managed browser binaries (Chromium 145, Firefox 146, WebKit 26) with platform-specific native library dependencies for Playwright automation.

Description

Playwright ships and manages its own browser binaries separately from the npm packages. The `browsers.json` registry defines exact browser versions pinned to each Playwright release. The `Registry.install()` method downloads, extracts, and validates these binaries using a lock-based mechanism with exponential backoff. Each browser requires specific native shared libraries on Linux (libasound, libnss3, libgtk, etc.), which can be installed via `npx playwright install-deps`. The browser cache is shared across Playwright installations and subject to garbage collection.

Usage

Use this environment for any workflow that launches a browser — end-to-end testing, codegen recording, browser automation CLI, tracing, and AI agent testing. API-only testing (using `APIRequestContext`) does not require browser binaries.

System Requirements

Category	Requirement	Notes
Disk	500MB–2GB	Per browser engine; varies by platform
Network	Internet access	Required for initial download (can be skipped with `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD`)
Linux Libraries	Browser-specific native deps	Install via `npx playwright install-deps`

Dependencies

Browser Versions (browsers.json)

Chromium (Chrome for Testing): 145.0.7632.26 (revision 1210) — installed by default
Chromium Headless Shell: 145.0.7632.26 (revision 1210) — installed by default
Firefox: 146.0.1 (revision 1509) — installed by default
WebKit: 26.0 (revision 2258) — installed by default
- Revision overrides: mac14=2251, debian11=2105, ubuntu20.04=2092
FFmpeg: revision 1011 — installed by default (video encoding support)
Android: revision 1001 — not installed by default

Linux Native Dependencies (Ubuntu 20.04 — Chromium)

`libasound2`, `libatk-bridge2.0-0`, `libatk1.0-0`, `libatspi2.0-0`
`libcairo2`, `libcups2`, `libdbus-1-3`, `libdrm2`, `libegl1`
`libgbm1`, `libglib2.0-0`, `libgtk-3-0`, `libnspr4`, `libnss3`
`libpango-1.0-0`, `libx11-6`, `libx11-xcb1`, `libxcb1`
`libxcomposite1`, `libxdamage1`, `libxext6`, `libxfixes3`, `libxrandr2`

Linux Native Dependencies (Ubuntu 20.04 — Firefox)

`ffmpeg`, `libatk1.0-0`, `libcairo-gobject2`, `libcairo2`
`libdbus-1-3`, `libdbus-glib-1-2`, `libfontconfig1`, `libfreetype6`
`libgdk-pixbuf2.0-0`, `libglib2.0-0`, `libgtk-3-0`
`libpango-1.0-0`, `libx11-6`, `libx11-xcb1`, `libxcb1`

Common Tools (All Browsers)

`xvfb` (X Virtual Framebuffer — for headless Linux without display)
`fonts-noto-color-emoji`, `fonts-liberation`, `fonts-ipafont-gothic`, `fonts-wqy-zenhei`

Credentials

The following environment variables control browser binary management:

`PLAYWRIGHT_BROWSERS_PATH`: Custom browser binary installation directory (default: platform cache dir)
`PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD`: Set to `1` to skip browser download during `npm install`
`PLAYWRIGHT_SKIP_BROWSER_GC`: Set to `1` to skip stale browser garbage collection
`PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS`: Set to `1` to skip native dependency validation
`PLAYWRIGHT_DOWNLOAD_HOST`: Custom mirror for browser downloads
`PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`: Chromium-specific download mirror
`PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST`: Firefox-specific download mirror
`PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST`: WebKit-specific download mirror
`PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT`: Download socket timeout in milliseconds

Quick Install

# Install all default browsers (Chromium, Firefox, WebKit)
npx playwright install

# Install a specific browser
npx playwright install chromium

# Install system dependencies (Linux only, requires sudo)
npx playwright install-deps

# Install browsers AND system dependencies
npx playwright install --with-deps

Code Evidence

Browser version registry from `packages/playwright-core/browsers.json:3-10`:

{
  "name": "chromium",
  "revision": "1210",
  "installByDefault": true,
  "browserVersion": "145.0.7632.26",
  "title": "Chrome for Testing"
}

Download retry logic from `packages/playwright-core/src/server/registry/browserFetcher.ts:48-49`:

const retryCount = 5;
for (let attempt = 1; attempt <= retryCount; ++attempt) {
  debugLogger.log('install', `downloading ${title} - attempt #${attempt}`);
  const url = downloadURLs[(attempt - 1) % downloadURLs.length];

Registry lock with exponential backoff from `packages/playwright-core/src/server/registry/index.ts:1060-1067`:

releaseLock = await lockfile.lock(registryDirectory, {
  retries: {
    // Retry 20 times during 10 minutes with
    // exponential back-off.
    retries: 20,
    factor: 1.27579,
  },

Skip browser download from `packages/playwright-core/src/server/registry/index.ts:1458-1460`:

if (getAsBooleanFromENV('PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD')) {
  logPolitely('Skipping browsers download because `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` env variable is set');

Native dependency definitions from `packages/playwright-core/src/server/registry/nativeDeps.ts:21-36`:

export const deps: any = {
  'ubuntu20.04-x64': {
    tools: [
      'xvfb', 'fonts-noto-color-emoji', 'ttf-unifont', 'libfontconfig',
      'libfreetype6', 'xfonts-cyrillic', 'xfonts-scalable', 'fonts-liberation',
      'fonts-ipafont-gothic', 'fonts-wqy-zenhei', 'fonts-tlwg-loma-otf',
      'ttf-ubuntu-font-family',
    ],

Common Errors

Error Message	Cause	Solution
`Executable doesn't exist at ...`	Browser binary not installed	Run `npx playwright install`
`Host system is missing dependencies`	Missing native Linux libraries	Run `npx playwright install-deps` or `npx playwright install --with-deps`
`browserType.launch: Browser closed`	Missing shared libraries or GPU issues	Install deps: `npx playwright install-deps`; or try `--disable-gpu` flag
Lock file errors during install	Concurrent Playwright installations	Wait for other installation to complete (retries for 10 minutes automatically)

Compatibility Notes

Linux: Requires distribution-specific native dependencies. Officially supported: Ubuntu 20.04/22.04/24.04, Debian 11/12/13. Best-effort support for Pop!_OS, Linux Mint, KDE Neon, TUXEDO OS, Raspbian.
macOS: Requires macOS 10.13+. Apple Silicon (arm64) supported from macOS 11+. Metal GPU support checked for WebKit.
Windows: Requires Windows 7 SP1 or later (x64 only). Media Foundation required for video features.
WebKit revision overrides: Older platforms (mac14, debian11, ubuntu20.04) use older WebKit revisions for compatibility.
Docker/CI: Use `npx playwright install --with-deps` to install both browsers and system dependencies in one step.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment