Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
The reliable setup is two commands run from the project directory: install Playwright locally, then download the browser binaries that match that package.
npm i -D @playwright/test
npx playwright installIf you use Playwright as a browser automation library instead of its test runner, install playwright rather than @playwright/test. On Linux or in CI, add --with-deps when required operating-system libraries are not present.
Use the command that matches your project
npx playwright install is a local-project command. It downloads the browser revisions required by the Playwright version installed in that project; it does not replace installing the npm package itself. Keep the package and browser install in the same project so the CLI and binaries stay in sync.
Playwright Test projects
npm i -D @playwright/test
npx playwright install@playwright/test supplies the test runner and the playwright command. Run both commands in the directory containing your package.json.
#1 Best Overall
Playwright library projects
npm i playwright
npx playwright installChoose this form when your code imports Playwright for automation but does not use the Playwright Test runner.
Install one browser only
Without a browser name, Playwright installs its default browser set. To limit download and storage, name the browser:
npx playwright install chromium
npx playwright install firefox
npx playwright install webkitRun npx playwright install --help to see the options supported by the CLI version in your project.
What each installation command does
| Command | Use it when | What it changes |
|---|---|---|
npm i -D @playwright/test |
You are building Playwright Test suites | Adds the test package to devDependencies |
npm i playwright |
You are using the automation library directly | Adds the library to project dependencies |
npx playwright install |
You need the standard browser set | Downloads browser binaries for the installed Playwright version |
npx playwright install chromium (or firefox/webkit) |
You only run one engine | Downloads that named browser |
npx playwright install --with-deps |
Linux or CI lacks required system libraries | Downloads browsers and installs supported OS dependencies |
npx playwright install-deps |
Browsers are already present but Linux libraries are missing | Installs the operating-system dependencies without downloading browsers |
Fix “npx playwright” not recognized
- Confirm your location. Change into the application directory that contains
package.json. A globally installed package in another directory will not supply this project’s local CLI. - Check the dependency. Look for
@playwright/testorplaywrightinpackage.json. If neither is present, run the appropriatenpm icommand above. - Retry through npx. Run
npx playwright --version. A version number confirms that npm can resolve the local executable. - Install the matching browsers. Run
npx playwright install, or name only the browser your tests use.
If npm reports that a package cannot be found, inspect the spelling and registry configuration before trying a global install. A local dependency is preferable because the CLI, browser revisions and lockfile then move together.
Fix missing Linux libraries and browser launch failures
A successful browser download does not guarantee that the operating system can launch it. Errors mentioning shared libraries, sandbox support or missing GTK-related components usually indicate absent Linux dependencies.
Install browsers and dependencies together
npx playwright install --with-depsTo limit the operation to one engine, append its name:
npx playwright install --with-deps chromium
npx playwright install --with-deps firefox
npx playwright install --with-deps webkitInstall only the operating-system dependencies
npx playwright install-depsUse this when the browser binaries are already cached and the failure specifically concerns Linux libraries. These dependency commands are intended for environments where you have permission to install system packages; on managed runners, ask the image administrator or use a runner image that permits the operation.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsMake browser installation work behind a proxy or TLS inspection
Playwright normally downloads from Microsoft’s CDN. Corporate networks can block that host, require an outbound proxy, or replace certificates during TLS inspection. Set the variables in the same shell invocation or export them before running the install.
Corporate HTTPS proxy
HTTPS_PROXY=https://proxy.example npx playwright installInternal artifact repository
Set PLAYWRIGHT_DOWNLOAD_HOST to the repository approved by your organization. Browser-specific download-host variables are also available when different engines use different mirrors.
Organization root certificate
NODE_EXTRA_CA_CERTS=/path/to/root.crt npx playwright installUse the path to the trusted root certificate that signed your organization’s intercepted connection. Do not disable certificate verification as a workaround.
Slow or high-latency downloads
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright installThe value is in milliseconds. Increase it only as much as your network requires; a longer timeout does not repair an unreachable proxy or an invalid certificate.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose a browser cache location
Playwright caches downloaded browsers outside the project by default:
- Windows:
%USERPROFILE%AppDataLocalms-playwright - macOS:
~/Library/Caches/ms-playwright - Linux:
~/.cache/ms-playwright
Share one cache
Set PLAYWRIGHT_BROWSERS_PATH to a directory that your build users or CI jobs can read and write. A shared cache avoids downloading identical revisions repeatedly, but permissions must be consistent for every user and job.
Use a project-local, hermetic cache
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright installThis places the browsers under node_modules/playwright-core/.local-browsers. It makes the project self-contained, which is useful for isolated builds, at the cost of storing a separate copy for each project.
GitHub Actions: install in the right order
Install npm dependencies first so the CLI version comes from the lockfile, then install browsers and operating-system dependencies, and only then run tests.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright testnpm ci should use the committed lockfile. Running the browser step after dependency installation ensures that the downloaded revisions correspond to the package version selected by CI. If your runner already provides the required Linux libraries, npx playwright install may be sufficient; use --with-deps when the image does not.
Version mismatches after an upgrade
Each Playwright release expects specific browser binary versions. After changing the Playwright package, run the install command again so the revisions are refreshed.
npx playwright --version
npx playwright installCommit the package-lock or other npm lockfile change along with the package upgrade. In CI, a stale cache can continue serving old files; clear or rotate that cache when the error identifies an incompatible executable, then rerun the install.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Storage, speed and reliability considerations
Storage
The official guidance describes browser downloads as taking a few hundred megabytes of disk space. The exact amount varies by operating system, browser set and release, so reserve capacity rather than relying on a single universal number. Installing one named browser uses less space than installing the full set.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Download time
Use a shared cache for repeated local or CI jobs, or a project-local cache when reproducibility and isolation matter more than deduplication. A cache does not remove the need to rerun installation after a Playwright upgrade.
Failure handling
- Keep network variables in CI secrets or runner configuration rather than committing credentials in workflow files.
- Run the install step explicitly in every clean CI environment; do not assume a developer’s browser cache exists on a new runner.
- Install only the engines your test matrix exercises when download time and storage are constrained.
- Capture the output of
npx playwright --versionin diagnostics so a browser error can be compared with the package version.
Troubleshooting by error symptom
| Symptom | Likely cause | Fix |
|---|---|---|
playwright: command not found or npx cannot resolve it |
Wrong directory or missing local package | Enter the directory with package.json, install @playwright/test or playwright, then run npx playwright --version. |
| “Executable doesn’t exist” | Browser revision was never downloaded or the cache path changed | Run npx playwright install with the required browser and verify PLAYWRIGHT_BROWSERS_PATH. |
| Shared-library or launch errors on Linux | Operating-system dependencies are absent | Run npx playwright install --with-deps, or npx playwright install-deps when binaries are already present. |
| Download hangs or times out | Proxy, firewall or slow connection | Configure HTTPS_PROXY, an approved download host, or increase PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT. |
self signed certificate in certificate chain |
TLS interception certificate is not trusted by Node | Set NODE_EXTRA_CA_CERTS to the organization’s root certificate and retry. |
| Permission denied in the browser cache | Cache directory is owned by another user or is not writable | Choose a writable PLAYWRIGHT_BROWSERS_PATH; in CI, ensure all steps use the same user. |
| Tests fail immediately after a package upgrade | Browser revisions are from an older Playwright release | Check npx playwright --version, refresh with npx playwright install, and invalidate a stale CI cache if necessary. |
Or skip the browser setup
If you only need a rendered website screenshot—not Playwright test execution—you can call ScreenshotNeo’s website screenshot API instead of maintaining a local browser install. It accepts a URL and returns PNG, JPEG, WebP or PDF; its cleanup steps can accept cookie banners and remove more than 60 known consent platforms, newsletter popups and chat widgets before capture.
Install nothing locally. The API base is https://api.screenshotneo.com/v1/shot; the complete options and response headers are documented at https://screenshotneo.com/docs/.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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 reports whether a response was a clean page and whether it was billed through the X-Page-Verdict and X-Billed headers. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed. It also provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. Every plan includes the features; the free tier provides 1,000 screenshots per month without a card, and paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
