How to Set Up Playwright on Windows
Install Playwright on Windows, download browsers, run a passing test, and fix common setup, cache, proxy, and runtime errors.
The shortest supported setup for Playwright Test on Windows is: install Node.js, run npm init playwright@latest in PowerShell, allow the browser download, then run npx playwright test. Playwright supports Windows 11 and Windows Server 2019+, and WSL is also supported. The exact Node.js versions change, so check the current stable Playwright installation guide and Node.js documentation before standardizing a version.
1. Check the Windows and Node.js prerequisites
- Use Windows 11 or Windows Server 2019 or newer for the Windows workflow.
- Install a current supported Node.js release from nodejs.org. The Playwright documentation’s Next installation page currently lists Node.js 22.x, 24.x, and 26.x; verify the stable documentation for your project.
- Open PowerShell in the folder that will contain your tests.
Confirm that Node.js and npm are available:
node --version
npm --version2. Create a Playwright Test project
For a new project, run the official initializer:
npm init playwright@latestThe prompts let you choose JavaScript or TypeScript (TypeScript is the default), the test directory name, whether to add a GitHub Actions workflow, and whether to download Playwright browser binaries. Choose to install the browsers when prompted. The initializer creates a starter test, playwright.config.ts, package metadata, and the required project structure. It can also add Playwright to an existing project, and running it again does not overwrite existing tests.
A typical generated project contains:
playwright.config.ts
package.json
tests/
example.spec.ts3. Run the generated test
Run all configured browser projects:
npx playwright testTests run headlessly by default and commonly execute in parallel across Chromium, Firefox, and WebKit. Useful variants are:
# Show the browser window
npx playwright test --headed
# Run only the Chromium project
npx playwright test --project=chromium
# Open Playwright UI Mode
npx playwright test --uiA passing run confirms that the package, configuration, test runner, browser executable, and basic test all work together.
4. Understand package installation versus browser installation
Installing the npm package and installing browser binaries are related but separate operations. Each Playwright release expects specific browser builds; as the official browser documentation says, “Each version of Playwright needs specific versions of browser binaries to operate.”
If you skipped the download prompt, or an executable is missing, install the default browsers:
npx playwright installInstall only Chromium when that is all your project uses:
npx playwright install chromiumAfter upgrading Playwright, rerun the install command if a test reports that a browser executable cannot be found:
npm install -D @playwright/test@latest
npx playwright installSee the complete Playwright browser installation guide for engine and command details.
5. Write and run a small Windows smoke test
Replace the generated example with this TypeScript test in tests/homepage.spec.ts:
import { test, expect } from '@playwright/test';
test('homepage has the expected title', async ({ page }) => {
await page.goto('https://playwright.dev/');
await expect(page).toHaveTitle(/Playwright/);
});Run that file directly:
npx playwright test tests/homepage.spec.tsFor JavaScript, save the same test as tests/homepage.spec.js; the test API and command are unchanged. The generated configuration controls browser projects, retries, reporters, base URL, timeouts, and other behavior. Start with the generated configuration and change only the settings your project needs.
6. Choose a browser, headed mode, and reports
Use a project name from playwright.config.ts to target one engine:
npx playwright test --project=firefox
npx playwright test --project=webkitUse headed mode while diagnosing selectors or navigation:
npx playwright test --headed --project=chromiumPlaywright records test output according to the configured reporter. The generated project is enough for a first run; add a custom reporter or trace settings only when your CI or debugging workflow requires them.
7. Browser cache location and custom storage
On Windows, Playwright normally stores downloaded browsers under %USERPROFILE%\AppData\Local\ms-playwright. The browser guide describes the download as occupying a few hundred megabytes. You can move the cache, which is useful on a machine with a small system drive or in a controlled CI image:
$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
npx playwright install
npx playwright testKeep PLAYWRIGHT_BROWSERS_PATH set for later test runs. If the variable is set during installation but not during execution, Playwright may look in a different location and report a missing executable.
8. Restricted networks, proxies, and certificates
Browser downloads can fail when a corporate network blocks the Microsoft CDN or intercepts TLS certificates. These settings are troubleshooting steps, not normal prerequisites.
Set an HTTPS proxy in PowerShell before installing:
$Env:HTTPS_PROXY="http://proxy.example.test:8080"
npx playwright installIf the proxy replaces certificates and installation reports a self-signed certificate-chain error, configure NODE_EXTRA_CA_CERTS with the path to a trusted certificate file, as described in the Playwright proxy and firewall documentation:
$Env:NODE_EXTRA_CA_CERTS="C:\certs\corporate-root.pem"
npx playwright installUse your organization’s approved certificate and proxy values. Do not disable certificate validation as a routine workaround.
9. Alternative language bindings on Windows
The Node.js commands above are for Playwright Test. The other language bindings use different package managers, project scaffolding, and browser-install commands.
| Binding | Install path | Browser command | Official guide |
|---|---|---|---|
| Python | pip install playwright |
playwright install |
Python guide |
| .NET | Create a .NET test project and add the Playwright package | pwsh bin/Debug/net8.0/playwright.ps1 install |
.NET guide |
| Java | Use the Maven-oriented Playwright setup | Follow the Maven project instructions | Java guide |
The Python documentation lists Python 3.8 or newer, and the .NET documentation recommends .NET 8. Keep each binding’s package and browser versions aligned.
10. Troubleshooting checklist
“’npm’ is not recognized”
Cause: Node.js is not installed or its install directory is not on the PATH available to PowerShell.
Fix: Install Node.js, close and reopen PowerShell, then run node --version and npm --version.
“Executable doesn’t exist” or a missing browser error
Cause: Browser binaries were not downloaded, were removed, or belong to a different Playwright version.
Fix: Run npx playwright install. If you use a custom cache, set the same PLAYWRIGHT_BROWSERS_PATH value for both installation and tests.
Browser download fails or hangs
Cause: Firewall, proxy, DNS, or certificate interception.
Fix: Check the proxy and certificate steps above, then retry the install. Ask your network administrator to allow the required download host if policy blocks it.
Tests pass headlessly but fail in headed mode
Cause: Timing, viewport, display, or an interaction that depends on visible state.
Fix: Run the single test with --headed, inspect the trace or UI Mode, and use Playwright’s locator assertions instead of fixed sleeps.
Tests use the wrong browser
Cause: Multiple configured projects run by default.
Fix: Select one explicitly with --project=chromium, or edit the projects in playwright.config.ts.
Downloads consume too much disk space
Cause: Chromium, Firefox, and WebKit are all installed.
Fix: Install only the engines required by your project and use a custom cache path on a suitable drive.
11. Performance, reliability, and maintenance
- Run one browser project locally while developing, then expand to the full browser matrix in CI.
- Reuse the browser cache between CI jobs when your CI provider supports caching; invalidate it when the Playwright package version changes.
- Keep browser installation in the same environment that runs tests so the executable path and permissions match.
- Prefer locator-based assertions and explicit readiness conditions over arbitrary delays.
- Pin package versions in a controlled project and rerun
npx playwright installafter intentional upgrades. - Expect the initial browser download to require hundreds of megabytes and network access; subsequent runs can reuse the local binaries.
Or skip the browser setup
If your goal is a clean screenshot rather than browser-test development, ScreenshotNeo provides a website screenshot API and MCP server. One request returns PNG, JPEG, WebP, or PDF output. It accepts cookie and consent banners before capture, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn each cleanup step off.
Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status.
Use the API directly; see the ScreenshotNeo API documentation for all options:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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}`);ScreenshotNeo also supports full-page and element captures, dark mode, device presets, retina scale, PDF settings, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, timezone and geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous webhooks, bulk capture, usage data, and an OpenAPI specification. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
There are 1,000 free shots each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
Why is Playwright asking me to install browsers?
The npm package does not guarantee that the matching browser binaries are present. Run npx playwright install for the version installed in your project.
Can I use Playwright on Windows with WSL?
WSL is listed as a supported environment. Follow the Linux-oriented instructions inside your WSL distribution and keep its package, browser cache, and filesystem paths consistent.
Do I need all three browsers?
No. Install the engines your compatibility policy requires. Use npx playwright install chromium for Chromium alone.
Where should browser binaries live on a build server?
The default per-user cache works for many builds. Set PLAYWRIGHT_BROWSERS_PATH when you need a shared or larger cache location, and set it consistently during installation and execution.
