How to Download Playwright Browsers

Direct answer: In a Node.js project with Playwright installed, run npx playwright install. This downloads Playwright’s default browser binaries. To download only selected engines, name them: npx playwright install chromium or npx playwright install chromium webkit. Playwright browser binaries are version matched, so run the install command again after upgrading Playwright.

1. Install Playwright and download browsers

Install Playwright in your project, then download the browser builds required by your tests or automation scripts.

npm install -D playwright
npx playwright install

The package installation and browser download are separate steps. Installing the npm package does not always place browser binaries on the machine automatically.

Install one or more browsers

# Chromium only
npx playwright install chromium

# Firefox only
npx playwright install firefox

# WebKit only
npx playwright install webkit

# A selected set
npx playwright install chromium webkit

Use Chromium, Firefox, and WebKit when your compatibility matrix requires all three. Download only the engines your project actually launches to reduce disk use and setup time.

Verify what is installed

npx playwright install --list

This lists browser revisions known to the current Playwright installation. Each Playwright release expects specific browser versions; an installed browser from another release may not satisfy the current package.

2. Install Linux system dependencies

On Linux, browser binaries may require operating-system libraries. Install the browsers and those dependencies together:

npx playwright install --with-deps

To install only the system dependencies, use:

npx playwright install-deps

Run these commands in the same environment where the tests or automation process will run. A browser installed on a developer laptop does not provide libraries inside a container or CI runner.

3. Choose the right browser download

Need	Command or setting	Notes
Cross-browser testing	`npx playwright install`	Downloads the default supported Chromium, Firefox, and WebKit builds.
Chromium-only tests	`npx playwright install chromium`	Smaller install when Firefox and WebKit are unnecessary.
Headless shell only	`npx playwright install --only-shell`	Can avoid downloading full Chromium when tests use Chromium’s headless shell and do not select a `channel`.
Newer Chromium headless mode	`npx playwright install --no-shell`	Skips the headless shell for setups using the newer headless mode.
Branded Chrome or Edge	Use a browser `channel`	Playwright can use Chrome or Edge installed on the machine. Their installation location is controlled by the operating system.
Custom executable	`executablePath`	Supported only with caution; bundled Playwright builds are the supported path.

Playwright’s Chromium, Firefox, and WebKit downloads are patched builds intended for Playwright. They are different from your regular browser installation. Playwright does not use branded Firefox or Safari in the same way. For Safari-like behavior, WebKit is the relevant engine; the official guide notes that macOS WebKit is closer to Safari for cases such as video playback, while Linux WebKit can be a lower-cost CI choice. See the official browser guide for current channel and platform details.

4. Complete runnable example

The following script launches Chromium, navigates to a page, and saves a screenshot. Run the browser install first.

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const page = await browser.newPage({
  viewport: { width: 1440, height: 900 },
});

await page.goto('https://example.com', { waitUntil: 'networkidle' });
await page.screenshot({ path: 'example.png', fullPage: true });

await browser.close();

Save it as screenshot.mjs and run:

node screenshot.mjs

For Firefox or WebKit, change the import and launch call:

import { firefox, webkit } from 'playwright';

const firefoxBrowser = await firefox.launch();
await firefoxBrowser.close();

const webkitBrowser = await webkit.launch();
await webkitBrowser.close();

5. Configure browser locations

By default, Playwright stores browser binaries in these cache directories:

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

Set PLAYWRIGHT_BROWSERS_PATH before both installation and execution to use a shared cache:

# macOS/Linux
export PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
npx playwright install chromium
node screenshot.mjs

# Windows PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH = 'C:\playwright-browsers'
npx playwright install chromium
node screenshot.mjs

For a hermetic install inside the project’s dependency tree, set the variable to 0:

PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromium

This places browsers beneath node_modules/playwright-core/.local-browsers. The setting does not change where branded Chrome or Edge are installed.

6. Proxies and internal mirrors

Playwright normally downloads browsers from Microsoft’s CDN. If your network requires a proxy, set HTTPS_PROXY before installing:

HTTPS_PROXY=http://proxy.example.internal:8080 npx playwright install

For an internal artifact mirror, set PLAYWRIGHT_DOWNLOAD_HOST. You can override the host per browser:

PLAYWRIGHT_DOWNLOAD_HOST=https://mirror.example.internal npx playwright install
PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST=https://chromium-mirror.example.internal npx playwright install chromium
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=https://firefox-mirror.example.internal npx playwright install firefox
PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST=https://webkit-mirror.example.internal npx playwright install webkit

Make sure the mirror contains the exact revisions required by the installed Playwright version and that certificates are trusted by the runner.

7. CI and container setup

A basic CI sequence is:

npm ci
npx playwright install --with-deps
npm test

Run the install after npm ci so the browser revision matches the lockfile. Browser downloads can consume a few hundred megabytes each; the exact size changes by platform and release. The official CI guide says caching browser binaries is not recommended by default because restoring a cache can take about as long as downloading them. If you cache them anyway, key the cache by the Playwright version and operating system.

In a container, install dependencies in the image or startup step and run as the same user that launches Playwright. A cache owned by another user can produce permissions errors.

8. Updating, listing, and removing browsers

After upgrading Playwright, reinstall the required browsers:

npm install -D playwright@latest
npx playwright install

Remove browsers associated with the current Playwright installation:

npx playwright uninstall

Remove browsers from all Playwright installations:

npx playwright uninstall --all

Playwright normally removes unused browser revisions during client updates. To opt out of that cleanup, use --no-remove or set PLAYWRIGHT_SKIP_BROWSER_GC=1.

9. Troubleshooting

“Executable doesn’t exist” or browser missing

Cause: The npm package is installed but its matching browser was not downloaded, or the process uses a different cache path.

Fix: Run npx playwright install chromium (or the engine you launch) and ensure PLAYWRIGHT_BROWSERS_PATH has the same value during install and execution.

Browser revision is out of date

Cause: Playwright was upgraded without downloading its new browser revision.

Fix: Run npx playwright install after the package update and commit the updated lockfile.

Linux shared-library errors

Cause: Required OS packages are absent.

Fix: Run npx playwright install --with-deps in the Linux environment. If package installation is restricted, ask the image owner to add the dependencies listed by the command.

Download fails behind a proxy

Cause: The installer cannot reach the CDN directly or the proxy certificate is not trusted.

Fix: Set HTTPS_PROXY, verify outbound access, or configure PLAYWRIGHT_DOWNLOAD_HOST for an approved mirror.

Permission denied in CI

Cause: The browser cache was created by a different user or points to a read-only directory.

Fix: Choose a writable shared path, set PLAYWRIGHT_BROWSERS_PATH consistently, or install and run under the same user.

Branded Chrome or Edge is not found

Cause: Bundled browser binaries and branded channels have different installation locations.

Fix: Install the branded browser through the operating system, then select the appropriate Playwright channel. Do not expect PLAYWRIGHT_BROWSERS_PATH to relocate it.

Custom executable behaves unpredictably

Cause: The executable is not a Playwright-supported build or is incompatible with the API revision.

Fix: Prefer the bundled browser. Use executablePath only when you control the compatibility trade-offs.

10. Performance, reliability, and cost considerations

Download less: Install only the engines and headless variant your workload needs.
Keep versions aligned: Pin Playwright in your lockfile and reinstall browsers during dependency updates.
Make CI repeatable: Install with --with-deps on Linux and use a versioned cache only if it improves your pipeline.
Plan disk space: Each browser can occupy a few hundred megabytes; platform and release affect the total.
Separate setup from capture: Browser downloads add startup time and network dependency. A persistent worker or prebuilt image can avoid repeating installation on every job.
Control network access: Proxies and mirrors improve reliability in restricted environments, but the mirror must serve matching revisions.

11. Or skip the browser setup

If your goal is to obtain reliable website screenshots rather than manage browser binaries, ScreenshotNeo provides a website screenshot API. The request below returns an image without installing Playwright locally. Read the ScreenshotNeo API documentation for all options.

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 removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. It also provides an MCP server for AI agents, including Claude and Cursor, with take_screenshot, get_page_info, and capture_pdf tools. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and start with 1,000 screenshots a month at no charge.

12. FAQ

Do I need to install all three browsers?

No. Install only the engines your tests launch. Use all three for cross-browser coverage.

Does Playwright download my installed Chrome?

No. The default commands download Playwright-managed builds. Branded Chrome and Edge are separate channels installed by the operating system.

Should I commit browser binaries to Git?

Usually no. Install them in CI or provide a controlled shared cache keyed to the Playwright version.

Why did an update require another download?

Playwright releases can require different browser revisions. Re-running the install command keeps the binaries compatible with the package.

Can I install browsers into the project?

Yes. Set PLAYWRIGHT_BROWSERS_PATH=0 during installation for a hermetic install beneath node_modules/playwright-core/.local-browsers.

For command details and current platform guidance, consult the Playwright Browsers documentation, CLI reference, CI guide, Library guide, and BrowserType API reference.