How to Install Playwright on Windows, Mac, and Linux

Playwright has rapidly become the go-to framework for web automation and end-to-end testing. Its power lies in its consistency across different operating systems and its support for all modern rendering engines—Chromium, Firefox, and WebKit.

However, a successful installation is the first critical step. While the Playwright team has made this process smooth, there are nuances depending on whether you are using Windows, macOS, or Linux.

This guide provides a detailed, platform-by-platform walkthrough to get Playwright installed and running on your machine.

Prerequisites: The Universal Requirement

Before diving into OS-specific instructions, there is one non-negotiable prerequisite for using Playwright with JavaScript/TypeScript: Node.js.

Playwright requires a recent version of Node.js. As of 2026, you should be running Node.js 20.x, 22.x, or 24.x.

• Check your version: Open your terminal (Command Prompt, PowerShell, or Terminal app) and run:

  bash

  node -v

• Don't have Node.js? Download the latest LTS version from the official Node.js website. The installer is available for all platforms.

For Python Developers: Playwright also offers an official Python library. If you are using Python, you'll need Python 3.8 or higher and pip . This guide will focus on the Node.js installation, which is the most common path, but we'll note the Python alternatives.

Installation Method 1: The Automated Way (Recommended for All)

Playwright provides a fantastic initialization command that handles the entire setup for you. It creates a configuration file, installs the browsers, and even sets up a sample test. This is the best way to get started, regardless of your OS.

Open your terminal in your desired project folder and run:

bash

# From your project's root directory
npm init playwright@latest

You will be guided through a simple interactive setup:

1. Choose Language: Select TypeScript or JavaScript (TypeScript is the default and highly recommended).

2. Name Test Folder: Accept the default (tests or e2e) or type a custom name.

3. Add GitHub Actions: Choose 'Y' to get a CI/CD workflow file (optional for now).

4. Install Browsers: Confirm 'Y' to install Chromium, Firefox, and WebKit.

This single command installs the @playwright/test npm package and downloads the browser binaries. Once it's done, you're ready to run your first test.

Installation Method 2: The Manual Way

If you prefer more control or are adding Playwright to an existing project, you can install it manually.

1. Initialize Your Project (If Needed)

If you don't already have a package.json file, create one:

bash

npm init -y

2. Install the Playwright Test Library

Install the Playwright test runner as a development dependency :

bash

npm install --save-dev @playwright/test

3. Install the Browsers

After installing the library, you need to download the browser binaries. This command downloads the latest stable versions of Chromium, Firefox, and WebKit :

bash

npx playwright install

You can also install a specific browser, like only Chromium, by adding its name:

bash

npx playwright install chromium

Platform-Specific Installation Guides

While the core commands are the same, each operating system has its own "gotchas." Here’s how to navigate them.

Installing Playwright on Windows

Windows is a first-class citizen for Playwright. The installation is straightforward, especially if you use the integrated terminal in VS Code.

Step-by-Step Guide:

1. Open your terminal: You can use PowerShell, Command Prompt, or the terminal in VS Code (View > Terminal).

2. Navigate to your project:

   bash

   cd path\to\your\project

3. Run the init command:

   bash

   npm init playwright@latest

Follow the prompts as described above.

Post-Installation Note:
Playwright will work immediately in your local terminal. For the best experience, install the VS Code Extension from the marketplace. It allows you to run tests with a single click, debug with breakpoints, and use the trace viewer directly in your editor.

Installing Playwright on macOS

macOS users will find the installation process almost identical to Windows, thanks to the cross-platform nature of Node.js and npm.

Step-by-Step Guide:

1. Open Terminal: You can find it in Applications/Utilities.

2. Navigate to your project:

   bash

   cd path/to/your/project

3. Run the init command:

   bash

   npm init playwright@latest

A Note on Apple Silicon (M1/M2/M3):

Playwright runs natively and flawlessly on Apple Silicon Macs. The browsers downloaded by npx playwright install are universal binaries or native ARM64 versions, ensuring excellent performance.

Installing Playwright on Linux

Linux installations are also smooth, but they require an extra step to ensure all necessary system libraries are present for the browsers to run, especially in headless environments.

Step-by-Step Guide:

1. Open your Terminal.

2. Navigate to your project:

   bash

   cd /path/to/your/project

3. Run the init command:

   bash

   npm init playwright@latest

4. 
   

5. The "Secret" Linux Step: Install System Dependencies
   Playwright browsers (especially Chromium and WebKit) rely on shared system libraries for audio, video, fonts, and rendering. If you try to run a test now, it might fail with a cryptic error about missing .so files. The solution is to use Playwright's built-in command to install all required dependencies.

   bash

   # This installs all necessary system packages (like libgdk-pixbuf2.0-0, libgtk-3-0, etc.)
   npx playwright install-deps

   You can combine browser installation and dependency installation in one command, which is highly recommended for Linux:

   bash

   npx playwright install --with-deps chromium

Verifying Your Installation

No matter which OS you used, you should verify that everything is working correctly.

1. Run the Sample Test

If you used npm init playwright@latest, a sample test file (example.spec.ts) was created in your tests folder. Run it with this command :

bash

npx playwright test

You should see output in your terminal indicating that all tests passed.

2. See the Browser in Action (Headed Mode)

By default, Playwright runs in "headless" mode (no visible UI). To see the browser window, use the --headed flag :

bash

npx playwright test --headed

A browser window will pop up, and you can watch the test navigate to the Playwright website and perform its checks.

3. Try the UI Mode

For a more interactive experience, launch Playwright's UI mode :

bash

npx playwright test --ui

This opens a graphical interface where you can watch a timeline of your test, inspect each step, and debug easily.

Python Installation (Alternative)

For those using the Python version, the process is slightly different but just as simple.

1. Install the Playwright Python library:

   bash

   pip install playwright

2. Install the browser drivers:

   bash

   playwright install

3. Verify with a simple script:

   python

   from playwright.sync_api import sync_playwright
   
   with sync_playwright() as p:
       # Launch Chromium (set headless=False to see the browser)
       browser = p.chromium.launch(headless=False)
       page = browser.new_page()
       page.goto("https://playwright.dev")
       print("Page Title:", page.title())
       browser.close()

Save this as test.py and run it with python test.py.

Troubleshooting Common Installation Issues

Even with a smooth process, issues can arise. Here’s how to fix the most common ones.

Issue 1: "browserType.launch: Executable doesn't exist"

The Problem: This error means the browser binaries were not downloaded correctly or Playwright can't find them.
The Fix: Reinstall the browsers explicitly:

bash

npx playwright install

For Linux, also run:

bash

npx playwright install-deps

Issue 2: Linux - Missing Libraries

The Problem: On a clean Linux installation, you might see errors like error while loading shared libraries: libgbm.so.1.
The Fix: Playwright has a dedicated command for this :

bash

npx playwright install-deps

This command detects your Linux distribution (Ubuntu, Debian, etc.) and uses the native package manager (apt) to install all necessary libraries.

Issue 3: Slow Downloads / Timeouts

The Problem: The browser binaries are large and can sometimes fail to download due to network issues.
The Fix: You can set a custom host for downloading the browsers, which is especially useful behind a corporate firewall or in certain geographic regions.

bash

# On Windows PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"
npx playwright install

# On macOS/Linux
export PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"
npx playwright install

Conclusion: Your Playwright Environment is Ready

You have successfully installed Playwright on your operating system. Whether you used the automated init command on Windows or the manual steps with install-deps on Linux, your machine is now equipped to write and run powerful automation scripts.

The beauty of Playwright is that once installed, the developer experience is identical across all platforms. The same test code will run on your Windows desktop, your MacBook, and your Linux CI server without any changes.

Next Steps:

• Explore the tests/ folder and modify the example test.

• Learn about Playwright's powerful locators.

• Set up GitHub Actions to run your tests automatically.

Happy automating!

Recommended Next Reads

• Playwright Locators Explained: Best Practices

• Your First Playwright Script: Step-by-Step

• Auto-Waiting in Playwright

• API Testing with Playwright: UI + API Hybrid Tests