All topics·Advanced·10 / 24

Browsers

Playwright bundles its own browser builds — they're separate from anything you have installed. After every Playwright version bump I always run 'npx playwright install' again, otherwise tests run with mismatched binaries. The flag I use most often: '--with-deps' for CI runners that need OS-level libraries too.

Introduction

Each version of Playwright expects matching browser builds. Install them with the Playwright CLI (npx playwright install) so local runs and CI use the same binaries as your test package.

After upgrading @playwright/test, run npx playwright install again so browsers stay in sync.

Install browsers

Install the default browser bundle (Chromium, Firefox, WebKit) for your project:

bash

npx playwright install

Install only one engine when you do not need the full set:

bash

npx playwright install webkit

List supported browser names and installer flags:

bash

npx playwright install --help

Install system dependencies

On Linux CI runners, install OS packages Playwright needs (fonts, libraries). This is what '--with-deps' does — it's the shortcut I use on fresh agents:

bash

npx playwright install-deps

Install dependencies for a single browser only:

bash

npx playwright install-deps chromium

Install browsers and system dependencies in one step — what I always use on CI:

bash

npx playwright install --with-deps chromium

Keep Playwright and browsers in sync

Bump the test runner, then reinstall browsers so versions match:

bash

npm install -D @playwright/test@latest
npx playwright install

Print the CLI version you are on:

bash

npx playwright --version

Configure browsers

Playwright Test targets Chromium, WebKit, Firefox, emulated mobile profiles, and branded Chrome/Edge through projects in playwright.config. Device presets live in Playwright's device registry.

Example: multiple projects

Define one project per browser or device. Each entry sets use (and optional channel for branded builds):

typescript

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' },
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' },
    },
  ],
});

Run every project (all browsers) from the CLI:

bash

npx playwright test

Running 7 tests using 5 workers

  ✓ [chromium] › example.spec.ts:3:1 › basic test (2s)
  ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
  ✓ [webkit] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Mobile Chrome] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Mobile Safari] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Google Chrome] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Microsoft Edge] › example.spec.ts:3:1 › basic test (2s)

Run a single project by name:

bash

npx playwright test --project=firefox

Running 1 test using 1 worker

  ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)

Chromium

For Chrome, Edge, and other Chromium-based browsers Playwright defaults to open-source Chromium builds. Chromium tip often tracks ahead of stable branded channels.

Chromium: headless shell

Headless runs can use the dedicated headless shell. On CI, if you only need that shell, save download time:

bash

npx playwright install --with-deps --only-shell

Chromium: new headless (`channel`)

Opt into the newer headless stack with the chromium channel in config:

typescript

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], channel: 'chromium' },
    },
  ],
});

If you rely on that mode, skip downloading the legacy headless shell during install:

bash

npx playwright install --with-deps --no-shell

Google Chrome and Microsoft Edge

Playwright can drive locally installed Chrome or Edge (chrome, msedge, beta/dev/canary channels). It does not install them automatically — use npx playwright install msedge (or chrome) when you need the installer to fetch a branded build.

bash

npx playwright install msedge

Point projects at branded channels when policy requires testing the same binaries users run:

typescript

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' },
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' },
    },
  ],
});

Firefox

Playwright bundles a recent Firefox stable build patched for automation. Stock Firefox installs are not used directly.

WebKit

Playwright's WebKit tracks upstream WebKit; it may differ slightly from consumer Safari builds. Use it for cross-engine coverage on macOS or Linux CI.

Install behind a firewall or a proxy

Playwright downloads browsers from Microsoft's CDN by default. Behind a corporate proxy, set HTTPS_PROXY before npx playwright install.

bash

HTTPS_PROXY=https://192.0.2.1 npx playwright install

Custom CA for TLS interception — point Node at your root bundle before installing:

bash

export NODE_EXTRA_CA_CERTS="/path/to/cert.pem"

Slow link to the CDN? Increase the download connection timeout (milliseconds):

bash

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

When running install-deps with sudo on Linux, export proxy variables in the same root shell so apt sees them.

bash

sudo HTTPS_PROXY=https://192.0.2.1 npx playwright install-deps

Managing browser binaries

Caches live under %USERPROFILE%\AppData\Local\ms-playwright (Windows), ~/Library/Caches/ms-playwright (macOS), or ~/.cache/ms-playwright (Linux). Check disk usage:

bash

du -hs ~/Library/Caches/ms-playwright/*
281M  chromium-XXXXXX
187M  firefox-XXXX
180M  webkit-XXXX

Share a single download directory across workspaces with PLAYWRIGHT_BROWSERS_PATH:

bash

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install

Point test runs at the same path:

bash

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test

Hermetic install

Keep binaries inside node_modules for reproducible CI caches:

bash

PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install

Skip browser downloads

If browsers are provisioned elsewhere, skip the download step during installs:

bash

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npx playwright install

List and uninstall

bash

npx playwright install --list

bash

npx playwright uninstall

bash

npx playwright uninstall --all

Take the quiz