Setting up Playwright takes less than five minutes. Whether you're starting a new test automation project or adding Playwright to an existing codebase, this guide walks you through every step — from verifying prerequisites to running your first passing test.
We'll cover installation with npm, yarn, and pnpm, downloading browser binaries, setting up the VS Code extension, and getting Playwright running in Python, Java, and .NET. We'll also troubleshoot the most common installation problems — including corporate proxy issues, permission errors, and WSL quirks.
1. Prerequisites
Before installing Playwright, you need two things on your machine: Node.js and a code editor. If you're using the Python, Java, or .NET version of Playwright, you'll need the respective runtime instead — but the Node.js/TypeScript version is the most popular and what we'll focus on first.
Node.js
Playwright requires Node.js 18 or later. To check if Node.js is installed and see your version, open a terminal and run:
node --version
# Expected output: v18.x.x, v20.x.x, v22.x.x, or later
If Node.js isn't installed or your version is below 18, download the latest LTS version from nodejs.org. The LTS (Long Term Support) release is recommended for most users — it's the most stable and best-tested version.
Tip: Use a Node.js version manager like nvm (macOS/Linux) or nvm-windows to switch between Node.js versions easily. This avoids permission issues and lets you maintain different versions per project.
Code Editor (VS Code Recommended)
Visual Studio Code is the recommended editor for Playwright development. Microsoft maintains both Playwright and VS Code, and the official Playwright VS Code extension provides test discovery, debugging, and code generation directly inside the editor. You can download VS Code from code.visualstudio.com.
That said, Playwright works with any editor or IDE — IntelliJ IDEA, WebStorm, Sublime Text, Vim, or even Notepad. The VS Code extension is a convenience, not a requirement.
Operating System Support
- Windows — Windows 10 or later (x86-64 and arm64)
- macOS — macOS 12 (Monterey) or later (Intel and Apple Silicon)
- Linux — Ubuntu 20.04+, Debian 11+, Fedora, or other distributions with glibc 2.31+
You'll need approximately 500MB of free disk space for Playwright's browser binaries (Chromium, Firefox, and WebKit combined).
2. Install Playwright with npm
The fastest way to set up a new Playwright project is the interactive init command. This scaffolds everything you need in one step:
# Create a new Playwright project (interactive wizard)
npm init playwright@latest
The wizard asks you a few questions:
- Language — choose TypeScript (recommended) or JavaScript
- Test directory — where to put your test files (default:
tests) - GitHub Actions workflow — whether to generate a CI configuration file
- Install browsers — whether to download Chromium, Firefox, and WebKit now
Say yes to all defaults if you're unsure. After the wizard finishes, your project structure will look like this:
my-playwright-project/ playwright.config.ts # Configuration (browsers, timeouts, reporter) package.json # Dependencies package-lock.json tests/ example.spec.ts # Example test file tests-examples/ demo-todo-app.spec.ts # Full example: testing a to-do app .github/ workflows/ playwright.yml # GitHub Actions CI config (if selected)
Adding Playwright to an Existing Project
If you already have a Node.js project and want to add Playwright as a dev dependency:
# Install Playwright Test as a dev dependency npm install -D @playwright/test # Download browser binaries npx playwright install
Then create a playwright.config.ts file in your project root:
import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: 'html', use: { baseURL: 'http://localhost:3000', trace: 'on-first-retry', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, { name: 'firefox', use: { ...devices['Desktop Firefox'] }, }, { name: 'webkit', use: { ...devices['Desktop Safari'] }, }, ], });
Tip: The npm init playwright@latest command is the recommended approach for new projects. It handles everything — package installation, browser downloads, config generation, and example tests — in one step.
3. Install with Yarn and pnpm
Playwright works seamlessly with yarn and pnpm as alternative package managers. The commands mirror the npm workflow.
Yarn
# Scaffold a new Playwright project yarn create playwright # Or add to an existing project yarn add -D @playwright/test # Download browser binaries yarn playwright install
pnpm
# Scaffold a new Playwright project pnpm create playwright # Or add to an existing project pnpm add -D @playwright/test # Download browser binaries pnpm exec playwright install
All three package managers produce identical results. The Playwright package, browser binaries, and configuration are the same regardless of which tool you use. Choose whichever your team already standardizes on.
Note: If your project uses pnpm with strict mode (the default), Playwright's CLI commands may require pnpm exec prefix. For example: pnpm exec playwright test instead of npx playwright test.
4. Installing Browser Binaries
Playwright downloads and manages its own browser binaries — you don't need Chrome, Firefox, or Safari installed on your system. These are dedicated automation builds, versioned and pinned to your Playwright version, so you never hit the "browser driver version mismatch" problem that plagues Selenium users.
Install All Browsers
# Install Chromium, Firefox, and WebKit
npx playwright install
Install Specific Browsers
If you only need one or two browsers (common in CI pipelines to save time and disk space):
# Install only Chromium npx playwright install chromium # Install Chromium and Firefox (skip WebKit) npx playwright install chromium firefox # Install WebKit only (for Safari testing) npx playwright install webkit
Install System Dependencies (Linux)
On Linux, browsers require certain system libraries (like libgbm, libasound2, and others). Playwright can install these automatically with the --with-deps flag:
# Install browsers + system dependencies (requires sudo) npx playwright install --with-deps # Install only Chromium and its dependencies npx playwright install --with-deps chromium
Linux CI environments: Always use --with-deps on fresh Linux containers (Docker, GitHub Actions runners). Without it, browser launches will fail with cryptic errors about missing shared libraries.
Where Are Browsers Stored?
By default, Playwright stores browser binaries in a user-level cache directory:
- macOS:
~/Library/Caches/ms-playwright - Linux:
~/.cache/ms-playwright - Windows:
%LOCALAPPDATA%\ms-playwright
You can override this location by setting the PLAYWRIGHT_BROWSERS_PATH environment variable. This is useful in CI pipelines where you want to cache browsers in a known directory:
# Store browsers in a custom directory export PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers npx playwright install
5. Playwright for Python
Playwright has a first-class Python API. If you're a Python developer or your team uses pytest, this is the path for you.
# Install Playwright for Python pip install playwright # Download browser binaries playwright install
For the pytest integration (recommended), install the pytest plugin:
# Install both Playwright and the pytest plugin pip install pytest-playwright # Download browsers playwright install
Here's a minimal Python test using pytest-playwright:
import re from playwright.sync_api import Page, expect def test_has_title(page: Page): page.goto("https://playwright.dev/") expect(page).to_have_title(re.compile("Playwright")) def test_get_started_link(page: Page): page.goto("https://playwright.dev/") page.get_by_role("link", name="Get started").click() expect(page.get_by_role("heading", name="Installation")).to_be_visible()
Run it with: pytest. The pytest-playwright plugin automatically manages browser context creation and teardown.
Virtual environments: Always install Playwright inside a Python virtual environment (python -m venv .venv) to avoid polluting your global Python installation and to make dependency management reproducible.
6. Playwright for Java
Playwright offers a Java API for teams working in JVM-based environments. Add it to your project via Maven or Gradle.
Maven
<dependency> <groupId>com.microsoft.playwright</groupId> <artifactId>playwright</artifactId> <version>LATEST</version> </dependency>
Gradle
dependencies {
implementation 'com.microsoft.playwright:playwright:LATEST'
}
After adding the dependency, install browsers using the Playwright CLI bundled with the package:
# Maven: install browsers mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install" # Gradle: install browsers gradle playwright --args="install"
A minimal Java test looks like this:
import com.microsoft.playwright.*; import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat; public class TestExample { public static void main(String[] args) { try (Playwright playwright = Playwright.create()) { Browser browser = playwright.chromium().launch(); Page page = browser.newPage(); page.navigate("https://playwright.dev/"); assertThat(page).hasTitle(Pattern.compile("Playwright")); } } }
7. Playwright for .NET
For C# developers, Playwright provides a .NET SDK with NUnit and MSTest integration. Install it via the .NET CLI:
# Create a new NUnit test project dotnet new nunit -n PlaywrightTests cd PlaywrightTests # Add the Playwright NUnit package dotnet add package Microsoft.Playwright.NUnit # Build the project (required before installing browsers) dotnet build # Install browsers pwsh bin/Debug/net8.0/playwright.ps1 install
A minimal .NET test with NUnit:
using System.Text.RegularExpressions; using Microsoft.Playwright; using Microsoft.Playwright.NUnit; [Parallelizable(ParallelScope.Self)] [TestFixture] public class ExampleTest : PageTest { [Test] public async Task HasTitle() { await Page.GotoAsync("https://playwright.dev"); await Expect(Page).ToHaveTitleAsync(new Regex("Playwright")); } }
Note: The .NET Playwright SDK requires PowerShell to run the browser installation script. On macOS/Linux, install PowerShell with dotnet tool install --global PowerShell if it's not already available.
8. VS Code Extension Setup
The Playwright Test for VS Code extension transforms your editor into a full-featured test IDE. It's optional but strongly recommended.
Install the Extension
- Open VS Code
- Go to the Extensions panel (
Ctrl+Shift+X/Cmd+Shift+X) - Search for "Playwright Test for VS Code" by Microsoft
- Click Install
Alternatively, install from the terminal:
code --install-extension ms-playwright.playwright
What the Extension Provides
- Test discovery — automatically finds all
.spec.tsfiles and displays them in the Testing sidebar - Run/debug individual tests — click the green play button next to any test to run it; click the debug icon to step through it with breakpoints
- Pick locator — hover over any element in a live browser and copy the recommended Playwright locator
- Record new tests — click "Record New" to open a browser, perform actions manually, and generate test code automatically
- Show trace — open trace files directly in VS Code for debugging failed tests
- Watch mode — re-run tests automatically when you save a file
Pro tip: Use the "Pick Locator" feature when you're unsure which locator to use. It highlights elements in the browser and generates the most resilient locator automatically — usually a getByRole or getByText locator that won't break when CSS classes change.
9. Running Your First Test
If you used npm init playwright@latest, you already have an example test file. Let's run it and explore different execution modes.
Run All Tests (Headless)
# Run all tests across all configured browsers
npx playwright test
By default, tests run in headless mode — no visible browser window. This is the fastest execution mode and what you'll use in CI pipelines. You'll see results printed in the terminal:
Running 6 tests using 4 workers
✓ [chromium] › example.spec.ts:3:1 › has title (1.2s)
✓ [chromium] › example.spec.ts:9:1 › get started link (0.9s)
✓ [firefox] › example.spec.ts:3:1 › has title (1.4s)
✓ [firefox] › example.spec.ts:9:1 › get started link (1.1s)
✓ [webkit] › example.spec.ts:3:1 › has title (1.0s)
✓ [webkit] › example.spec.ts:9:1 › get started link (0.8s)
6 passed (4.8s)
Run in Headed Mode (See the Browser)
# Watch the browser as tests execute
npx playwright test --headed
Headed mode opens a visible browser window so you can watch Playwright interact with the page in real time. This is useful for debugging and understanding what your tests actually do.
UI Mode (Interactive Test Runner)
# Launch the interactive UI mode
npx playwright test --ui
UI mode is Playwright's visual test runner. It opens a dedicated application where you can:
- Browse and filter all your test files
- Run individual tests or entire suites with one click
- Watch tests execute with a live DOM snapshot at each step
- Inspect locators, network requests, and console output
- Re-run failed tests instantly
UI mode is the best way to develop and debug tests interactively. It's also a great tool for learning Playwright — you can see exactly what happens at each step.
View the HTML Report
# Open the HTML test report
npx playwright show-report
After every test run, Playwright generates an HTML report in the playwright-report/ directory. The report shows pass/fail status for every test across every browser, execution time, and links to trace files for failed tests.
Write your own test: Create a file called tests/my-first.spec.ts and write a simple test. For a complete guide on writing tests, see our Playwright for Beginners tutorial.
10. Common Installation Issues & Fixes
Most Playwright installations go smoothly, but certain environments can cause problems. Here are the issues you're most likely to encounter and how to solve them.
Permission Errors (EACCES)
If you see EACCES: permission denied errors when running npm install or npx playwright install, it usually means npm is trying to write to a directory your user doesn't own.
# Option 1: Use nvm (recommended — avoids permission issues entirely) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts nvm use --lts # Option 2: Fix npm global directory permissions mkdir ~/.npm-global npm config set prefix '~/.npm-global' # Add ~/.npm-global/bin to your PATH in ~/.bashrc or ~/.zshrc
Corporate Proxy / Firewall
Playwright downloads browser binaries from Microsoft's CDN during installation. Corporate proxies and firewalls often block these downloads. Symptoms include timeouts, ETIMEDOUT, or ECONNREFUSED errors during npx playwright install.
# Set proxy for browser downloads export HTTPS_PROXY=http://proxy.yourcompany.com:8080 export HTTP_PROXY=http://proxy.yourcompany.com:8080 # If your company uses custom SSL certificates export NODE_EXTRA_CA_CERTS=/path/to/company-ca-bundle.crt # Now install browsers npx playwright install
If proxy configuration alone doesn't work, you can download browsers from an internal mirror by setting a custom download host:
# Point Playwright to an internal mirror export PLAYWRIGHT_DOWNLOAD_HOST=https://playwright-mirror.internal.company.com npx playwright install
Missing System Dependencies (Linux)
On Linux, if browser launches fail with errors like error while loading shared libraries: libgbm.so.1, you're missing system-level dependencies.
# Install all system deps for all browsers npx playwright install-deps # Or install deps for a specific browser npx playwright install-deps chromium
Note: install-deps (without the browser name after it) installs system dependencies only. install --with-deps installs both browsers and system dependencies in one command.
WSL (Windows Subsystem for Linux)
Running Playwright in WSL requires a few extra steps because WSL doesn't include a display server by default. For headless execution, no extra configuration is needed. For headed mode or UI mode, you need either:
- WSL 2 with WSLg (Windows 11) — GUI apps work out of the box. Just run
npx playwright install --with-depsand you're set. - WSL 2 without WSLg (Windows 10) — install an X server like VcXsrv or Xming, then set
export DISPLAY=:0before running headed tests.
Docker
Playwright provides official Docker images with all browsers and dependencies pre-installed:
FROM mcr.microsoft.com/playwright:v1.48.0-noble WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . CMD ["npx", "playwright", "test"]
Docker image tag: Always pin the Playwright Docker image version to match the @playwright/test version in your package.json. Version mismatches between the npm package and the browser binaries in the Docker image will cause failures.
Browser Download Stuck or Slow
If browser downloads are extremely slow or appear to hang, try installing browsers one at a time:
# Install browsers individually to isolate the problem
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
This helps identify if one specific browser download is the problem (often WebKit on certain Linux distributions).
Frequently Asked Questions
How do I install Playwright with npm?
Run npm init playwright@latest in your terminal. This interactive command creates a new Playwright project with a configuration file, example tests, and optionally installs browser binaries. For adding Playwright to an existing project, use npm install -D @playwright/test followed by npx playwright install to download browser binaries.
What are the system requirements for Playwright?
Playwright requires Node.js 18 or later for the JavaScript/TypeScript version. It runs on Windows 10+, macOS 12+, and Ubuntu 20.04+ (or Debian 11+). You need approximately 500MB of free disk space for browser binaries. For Python, you need Python 3.8+. For Java, JDK 8+. For .NET, .NET 6 or later.
How do I install Playwright browsers separately?
Use npx playwright install to install all browsers (Chromium, Firefox, WebKit). To install a specific browser only, use npx playwright install chromium, npx playwright install firefox, or npx playwright install webkit. Add the --with-deps flag on Linux to automatically install system dependencies required by the browsers.
Can I install Playwright with yarn or pnpm?
Yes. With yarn, use yarn create playwright to scaffold a new project or yarn add -D @playwright/test to add it to an existing project. With pnpm, use pnpm create playwright or pnpm add -D @playwright/test. After installing the package, run npx playwright install (or the equivalent yarn/pnpm command) to download browser binaries.
Why does Playwright install fail behind a corporate proxy?
Playwright downloads browser binaries from Microsoft's CDN during installation, and corporate proxies or firewalls often block these downloads. Fix this by setting the HTTPS_PROXY environment variable (e.g., export HTTPS_PROXY=http://proxy.company.com:8080). If your company uses custom SSL certificates, set NODE_EXTRA_CA_CERTS to point to the certificate file. You can also set PLAYWRIGHT_BROWSERS_PATH to control where browsers are stored.
Asim Noaman
Senior QA Automation Engineer & AI Testing Specialist
With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.