How to Install Playwright Browsers When They Are Missing

Use the Playwright CLI that belongs to your project, then install the browser revision that version expects:

npx playwright install

If only one browser is needed, name it explicitly:

npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

On Linux, combine the browser download with operating-system libraries:

npx playwright install --with-deps chromium

Playwright browser binaries are tied to the Playwright package version. When Playwright is upgraded, its required browser revisions can change, so run the install command again. The official Browsers documentation explains that each Playwright version needs specific browser binaries.

1. Confirm which Playwright installation you are using

A frequent cause of “Executable doesn’t exist” is running a global or different Playwright CLI from the one used by the project. In a Node project, invoke the local package through npx:

npx playwright --version
npm ls @playwright/test playwright playwright-core

For a project that uses Playwright Test, the package is commonly @playwright/test. Library users may have playwright or playwright-core. Install browsers after installing or updating that package:

npm install -D @playwright/test
npx playwright install

With pnpm or Yarn, use their project-local runners:

pnpm exec playwright install
yarn playwright install

Do not rely on a browser downloaded for an unrelated Playwright version. The package and browser revisions must match.

2. Install all browsers or one target browser

Install the default managed browsers

npx playwright install

This is the normal repair when you do not know which browser the test suite will launch.

Install only the browser you use

Need	Command
Chromium	`npx playwright install chromium`
Firefox	`npx playwright install firefox`
WebKit	`npx playwright install webkit`

Installing one target reduces download time and disk usage. Install every browser if your configuration projects run against Chromium, Firefox, and WebKit.

Install a browser and Linux dependencies together

npx playwright install --with-deps chromium
npx playwright install --with-deps firefox
npx playwright install --with-deps webkit

--with-deps installs the browser plus the operating-system packages Playwright needs. Package-manager operations can require root privileges on Linux.

3. Fix missing Linux libraries

If the executable exists but launching it fails with messages about shared libraries, sandboxing, fonts, or display dependencies, install the OS dependencies:

npx playwright install-deps chromium

Or perform both operations in one command:

npx playwright install --with-deps chromium

Use the browser name that your suite launches. In a minimal CI image, the combined command is usually the simplest setup. If your environment does not permit package installation, update the base image or ask an administrator to provide the required libraries before running Playwright.

4. Handle proxies, private CAs, and slow downloads

Playwright normally downloads browser archives from Microsoft’s CDN. Corporate networks may require a proxy, an additional trusted certificate, a longer connection timeout, or an internal download host.

HTTPS proxy

HTTPS_PROXY=https://proxy.example npx playwright install

Set the variable in the same shell or CI step that performs the install. Include proxy credentials only through your secret-management system.

Self-signed certificate or TLS interception

For self signed certificate in certificate chain, point Node at your organization’s trusted root certificate:

export NODE_EXTRA_CA_CERTS=/path/to/cert.pem
npx playwright install

The certificate file must be readable by the user running the install.

Slow or high-latency connections

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

This increases the download connection timeout to 120 seconds. It does not make an unavailable proxy or blocked host reachable.

Internal artifact repository

PLAYWRIGHT_DOWNLOAD_HOST=https://artifacts.example.internal/playwright npx playwright install

Browser-specific variables such as PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST take precedence for that browser. Configure the host according to your repository’s Playwright mirror layout.

5. Choose the browser cache location

By default, managed browsers are stored in a platform-specific cache:

Platform	Default location
Windows	`%USERPROFILE%\AppData\Local\ms-playwright`
macOS	`~/Library/Caches/ms-playwright`
Linux	`~/.cache/ms-playwright`

Use a shared cache

Set the same PLAYWRIGHT_BROWSERS_PATH during installation and execution:

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test

This is useful for CI jobs that reuse a persistent volume or for multiple jobs that run under the same account. Ensure every job can read the directory.

Use a project-local hermetic install

PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install

This places browsers under node_modules/playwright-core/.local-browsers. A project-local cache makes the dependency self-contained, but increases the size of the project or CI workspace.

PLAYWRIGHT_BROWSERS_PATH does not change where Google Chrome or Microsoft Edge are installed. It controls Playwright-managed browser binaries.

6. Verify the installation and inspect revisions

List the browser revisions known to the current Playwright installation:

npx playwright install --list

Run a small smoke test using the same package and environment as your test suite:

npx playwright test --list

Then launch the browser from a minimal script or your normal test command. If the list is empty, the install ran with a different cache path or a different Playwright package than the runtime.

7. Remove stale or conflicting browser revisions

Remove browsers associated with the current Playwright installation:

npx playwright uninstall

Remove browsers for all Playwright installations on the machine:

npx playwright uninstall --all

Playwright tracks which packages use each browser and can garbage-collect revisions that are no longer needed. If your build system manages the cache itself, prevent automatic removal:

npx playwright install --no-remove

Or set:

export PLAYWRIGHT_SKIP_BROWSER_GC=1

After cleanup, reinstall with the exact project-local CLI and, when needed, the exact shared or hermetic cache path.

8. CI and headless browser choices

CI images should install operating-system dependencies together with the browser:

npx playwright install --with-deps chromium

If your tests use only Chromium’s headless shell, Playwright documents:

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

With the newer Chromium headless mode, --no-shell can avoid downloading the separate shell:

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

Choose these flags only when the launch mode in your project matches the binary you install. Cache the resulting browser directory in CI when the runner image and Playwright version are stable. Invalidate that cache when the lockfile or Playwright version changes.

9. Runnable checks in Node.js and Python

Node.js: install and launch Chromium

const { execFileSync } = require('node:child_process');

execFileSync('npx', ['playwright', 'install', 'chromium'], { stdio: 'inherit' });

(async () => {
  const { chromium } = require('playwright');
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
  await browser.close();
})();

Python: install and launch Chromium

import subprocess
import sys

subprocess.run([sys.executable, "-m", "playwright", "install", "chromium"], check=True)

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto("https://example.com", wait_until="domcontentloaded")
    print(page.title())
    browser.close()

The Python package must already be installed in the active environment, for example with pip install playwright. Keep the package version and browser installation in the same virtual environment.

cURL: what it can and cannot do

Browser installation is performed by Playwright’s CLI, so cURL is not a replacement for npx playwright install. Use cURL only to test whether your network can reach an approved internal artifact host:

curl -I https://artifacts.example.internal/playwright/

Replace the host with the repository approved by your organization; do not infer a download path from this example.

10. Troubleshooting common errors

Error or symptom	Cause	Fix
`Executable doesn't exist`	The browser revision is not installed, or runtime and install use different package/cache paths.	Run `npx playwright install <browser>` with the project-local CLI; compare `PLAYWRIGHT_BROWSERS_PATH` in both steps.
Browser executable exists but will not start	Linux shared libraries or fonts are missing.	Run `npx playwright install --with-deps <browser>` or install dependencies with `install-deps`.
`self signed certificate in certificate chain`	TLS interception uses a private certificate authority.	Set `NODE_EXTRA_CA_CERTS` to the organization’s root certificate and retry.
Download times out	Proxy latency, bandwidth limits, or a blocked CDN.	Set `HTTPS_PROXY`, increase `PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT`, or configure `PLAYWRIGHT_DOWNLOAD_HOST`.
Install succeeds, tests fail on another user	The browser is in a per-user cache.	Use a shared `PLAYWRIGHT_BROWSERS_PATH` and grant the runtime user read access.
CI works once, then fails after dependency updates	The cache contains revisions for an older Playwright version.	Key the cache by the lockfile and Playwright version, then run install on cache misses.
Only one browser project fails	That browser was not installed or its revision was removed.	Install the named browser and inspect `npx playwright install --list`.
Unexpected browser removal	Playwright garbage-collected an unused revision.	Use `--no-remove` or `PLAYWRIGHT_SKIP_BROWSER_GC=1` when another tool owns lifecycle management.

11. Performance, reliability, and cost considerations

Download less: install only the browser projects your suite runs.
Prepare hosts once: use --with-deps in a base image or provisioning step instead of repeating package installation in every test job.
Reuse safely: cache a shared browser directory, but invalidate it when Playwright changes.
Keep installs reproducible: use the lockfile, the project-local CLI, and a fixed cache path in CI.
Plan for permissions: Linux dependency installation may require root; browser execution should use the same readable cache path as installation.
Separate browser cost from test cost: Playwright downloads are local storage and bandwidth costs controlled by your build environment; they are independent of any hosted screenshot API.

12. Or skip the browser setup

If your goal is to obtain website screenshots rather than maintain a local Playwright runtime, ScreenshotNeo provides a hosted screenshot API. One GET request returns PNG, JPEG, WebP, or PDF output, so there is no browser binary to install in your application.

See the ScreenshotNeo API documentation for request options. A minimal call is:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing state. It also includes an MCP server for AI agents with take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to start with 1,000 screenshots a month and no card.

13. FAQ

Do I need to install browsers after every test run?

No. Install them during environment setup and reuse the cache. Reinstall when the Playwright package version changes or when the cache is discarded.

Can I use system Chrome instead?

Playwright’s managed browsers are versioned for the package. A system browser has a separate update lifecycle, so use it only when your project explicitly configures that arrangement.

Why does `npx playwright install` download more than I need?

The command installs the default managed browser set. Add chromium, firefox, or webkit to limit the scope.

Should the cache be checked into Git?

No. Keep browser binaries in a cache, artifact store, or image layer and key that storage by the Playwright version.

Which command gives the fastest diagnosis?

Run npx playwright install --list, then compare the package version, cache path, and browser project that fails.