How to Manually Install Playwright

Playwright has two installation layers: the language package and the browser binaries that match that package version. Installing the package alone does not guarantee that Chromium, Firefox, or WebKit is available. Playwright’s documentation states: “Each version of Playwright needs specific versions of browser binaries to operate.” Read the official browser guide.

The reliable manual process is:

1. Install and pin the language package.
2. Download the browser binaries required by your tests or application.
3. Install Linux system dependencies when the runner needs them.
4. Verify the Playwright version and browser list.
5. Make the cache, proxy, certificates, and CI behavior explicit.

1. Install Playwright manually in Node.js

Use Node.js when your project is JavaScript or TypeScript based. Run these commands from the project directory:

npm install --save-dev playwright
npx playwright install
npx playwright --version
npx playwright install --list

npm install adds the library. npx playwright install downloads the supported browser binaries for that installed version. The final two commands show the CLI version and the browsers currently present.

Install one browser only

Downloading only the engine you use reduces network traffic and cache size:

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

Playwright also publishes browser-specific packages. They are useful when you want a narrower dependency surface:

npm install --save-dev @playwright/browser-chromium
npx playwright install chromium

Check every available installer option with:

npx playwright install --help

Run a first screenshot

import { chromium } from 'playwright';

const browser = await chromium.launch();
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 this as an ES module or run it through your project’s TypeScript setup. If the executable is missing, rerun npx playwright install chromium with the same package version used by the project.

2. Install Playwright for Python, Java, and .NET

Python

python -m venv .venv
source .venv/bin/activate
pip install playwright
playwright install

On Linux CI, install operating-system libraries at the same time:

pip install playwright
playwright install --with-deps

To install only one engine, use playwright install chromium, firefox, or webkit.

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page(viewport={"width": 1440, "height": 900})
    page.goto("https://example.com", wait_until="networkidle")
    page.screenshot(path="example.png", full_page=True)
    browser.close()

Java

Install the Java binding with your build tool, then invoke the Playwright CLI supplied by that dependency. The exact command depends on whether your project uses Maven or Gradle; keep the binding version pinned and run its browser installation command in the build environment. The same two-stage rule applies: Java package first, matching browser binaries second.

.NET

Add the Microsoft.Playwright package, build the project, and run the generated browser installation script. A typical PowerShell sequence is:

dotnet add package Microsoft.Playwright
dotnet build
pwsh bin/Debug/net8.0/playwright.ps1 install

Use the framework directory produced by your build if it differs from net8.0. On Linux CI, use the generated script’s dependency option when available.

3. Install Linux dependencies and prepare CI

Browser binaries can exist while startup still fails because shared libraries, fonts, or video dependencies are missing. On Linux, install both the browser and its operating-system dependencies:

npx playwright install --with-deps

If you only run Chromium:

npx playwright install-deps chromium
npx playwright install chromium

A reproducible CI sequence is:

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

The official CI guidance recommends one worker in CI for stability unless the runner is intentionally sized for parallel work. Pin your package-lock file and keep the browser installation in the same job or image that runs the tests.

GitHub Actions example

name: Playwright
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test

4. Configure proxies, mirrors, and private certificates

Playwright normally downloads browsers from Microsoft’s CDN. Configure network settings before running the install command.

• HTTPS proxy: set HTTPS_PROXY to the proxy URL.
• Internal mirror: set PLAYWRIGHT_DOWNLOAD_HOST. Browser-specific host variables take precedence when configured.
• Private certificate authority: set NODE_EXTRA_CA_CERTS to your organization’s trusted CA file before downloading.

export HTTPS_PROXY=http://proxy.example.internal:8080
export PLAYWRIGHT_DOWNLOAD_HOST=https://artifacts.example.internal/playwright
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-root.pem
npx playwright install chromium

Do not add credentials to shell history. Prefer your CI secret store and environment-level variables.

5. Control browser cache location and reproducibility

Playwright stores browsers outside the project by default:

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

Set PLAYWRIGHT_BROWSERS_PATH to share a cache between jobs or move it to a mounted volume:

export PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
npx playwright install chromium

For a hermetic project-local installation, set the value to 0:

PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromium

This places browsers under node_modules/playwright-core/.local-browsers or the equivalent package directory. Hermetic installs simplify artifact packaging, while a shared cache avoids repeated downloads across jobs.

Inspect and clean installations with:

npx playwright install --list
npx playwright uninstall
npx playwright uninstall --all

Playwright performs stale-browser garbage collection. Use PLAYWRIGHT_SKIP_BROWSER_GC=1 or the installer’s --no-remove option when an environment must retain multiple versions.

6. Use Docker for Linux CI

The official Playwright Docker image provides browsers and Linux dependencies in one installation boundary. Select an image whose Playwright version matches the version pinned in your project. A mismatch can prevent Playwright from locating browser executables even when the browser files exist.

FROM mcr.microsoft.com/playwright:v1.XX.X-jammy
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test", "--workers=1"]

Replace v1.XX.X with the exact version used by your lockfile. Treat the image as an alternative installation boundary, not a substitute for version pinning.

7. Troubleshoot missing executables and failed installs

Error or symptom	Cause	Fix
Executable doesn’t exist	The package is installed but browsers were not downloaded, or the cache path changed.	Run npx playwright install chromium (or the required engine) with the same environment variables used at runtime.
Browser launches locally but fails in CI	Linux system libraries are absent.	Run npx playwright install --with-deps or install dependencies for one browser.
Download times out	Firewall, proxy, or restricted egress.	Set HTTPS_PROXY, use PLAYWRIGHT_DOWNLOAD_HOST, or pre-seed the cache in the build image.
Self-signed certificate error	TLS interception uses a private CA unknown to Node.	Set NODE_EXTRA_CA_CERTS to the trusted CA file before installation.
Docker cannot find the browser	Image and project Playwright versions differ.	Align the image tag and package version, then rebuild without a stale layer.
Tests use an old browser	Multiple Playwright versions share a cache.	Inspect with npx playwright install --list; pin versions and use a controlled cache path.
Permission denied in shared cache	The install user cannot write to the mounted directory.	Change ownership or use a user-writable PLAYWRIGHT_BROWSERS_PATH.

When diagnosing, print npx playwright --version, the effective cache environment variable, and npx playwright install --list in the failing job. These three values usually reveal a package, path, or version mismatch.

8. Performance, reliability, and cost considerations

• Download less: install only Chromium, Firefox, or WebKit when cross-browser coverage does not require all three.
• Cache deliberately: persist the browser cache between CI jobs, but invalidate it when the Playwright version changes.
• Use one worker by default in CI: increase parallelism only when CPU, memory, and process limits are known.
• Pin everything: lock the language package, browser image, Node/Python runtime, and operating-system base.
• Prefer a mirror for restricted networks: an internal artifact host makes installs repeatable and avoids external egress.
• Budget storage: three browser engines and their dependencies require substantially more disk than a single engine; inspect actual cache usage in your runner.

Manual browser management also means handling consent banners, newsletter popups, chat widgets, bot checks, blank pages, and failed loads in your own automation code. If you only need a reliable URL-to-image or PDF result, a hosted capture API can remove that operational work.

9. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF output, so your application does not need to download or maintain Playwright browsers.

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

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)

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

See the complete option list and parameter reference in the ScreenshotNeo documentation. It supports full-page shots with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or custom viewports, retina scale, PDF paper sizes and ranges, HTML/CSS rendering, custom JavaScript and CSS, clicks, selector or network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs with signed webhooks, bulk capture for 100 URLs per call, a usage API, and an OpenAPI specification.

Before capture, ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status with X-Page-Verdict and X-Billed. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Create a free ScreenshotNeo account.

10. Frequently asked questions

Does npm install playwright install browsers?

It installs the Node.js package. Run npx playwright install separately to download matching browser binaries.

Where should browsers live in CI?

Use the default cache, a persisted PLAYWRIGHT_BROWSERS_PATH, or a project-local hermetic path when packaging the complete build artifact.

Should I install all three browsers?

Only when your test matrix requires Chromium, Firefox, and WebKit. Otherwise install the specific engine to reduce download and storage costs.

Why does a Docker image still fail to launch?

The image’s Playwright version may not match the project package. Align both versions and rebuild the image.

Can Playwright install through a corporate proxy?

Yes. Set HTTPS_PROXY before the install, or point PLAYWRIGHT_DOWNLOAD_HOST at an internal mirror. Add NODE_EXTRA_CA_CERTS when the proxy uses a private certificate authority.