Recommended Free Tools
The fix depends on which step failed: adding Playwright to the project, downloading its browser binaries, installing Linux system dependencies, or preparing a CI runner. Start with the exact command and first meaningful error, then follow the matching branch below. Installing the Playwright package and installing the browsers it controls are separate steps, so a successful package install does not prove that a browser is ready.
First identify which Playwright install step failed
Do not begin by changing unrelated Yarn settings or reinstalling everything. Record the command that failed and classify the failure by its stage:
- Package resolution: Yarn cannot add or resolve
@playwright/test. - CLI invocation: the package appears installed, but
yarn playwrightis not found or cannot run. - Browser download: the Playwright command starts, but downloading a browser archive fails, stalls, or reports a network or certificate error.
- Operating-system dependencies: the browser download completes, but launching it reports missing Linux libraries or packages.
- Test or CI runtime: installation appears successful, but the test process cannot find or launch the browser, often because the installed browser version or cache path differs from the one expected.
Keep the full terminal output, not just the last line. Also note the operating system, Node.js and Yarn versions, Playwright version if available, whether the failure is local or in CI, and whether a proxy or internal artifact host is involved. Those details distinguish the branches below; the phrase “Yarn Playwright install fails” by itself does not identify a single cause.
Install Playwright in the project and verify its CLI
For a new project, Playwright documents creating a project with yarn create playwright. To add the test package to an existing Yarn project, use:
#1 Best Overall
yarn add --dev @playwright/test@latestThen check whether the project can invoke the CLI:
yarn playwright --versionUse the project’s package manager context rather than assuming a global Playwright installation is required. If Yarn fails during the add command, the problem is at package resolution or installation—not browser download. If the add command completes but the version command fails, inspect the complete CLI error and confirm that you are running the command from the project directory where the package was added. The official installation guide documents these Yarn commands.
The @latest tag selects the newest package available when the command runs. If your project intentionally pins or constrains dependency versions, follow that project’s version policy instead of changing it merely to fix a browser download problem.
Install the browser binaries for the Playwright version in the project
Playwright uses browser binaries associated with its own version. Adding or upgrading the package and installing browser binaries are distinct operations. After adding Playwright, or after an upgrade when the required binaries are absent, run:
yarn playwright installIf the project needs only one browser, select it rather than installing every browser. The CLI documents browser selection; check its current help for the accepted browser names and options in your installed version:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchyarn playwright install --helpIf tests fail after a Playwright upgrade with a missing-browser or version-mismatch message, rerun the browser install command using the project’s current Playwright CLI. Do not assume that binaries downloaded for an earlier Playwright version are interchangeable. The browser installation guidance explains browser management and version matching; the CLI reference documents install options.
When “Playwright install with deps” fails on Linux
Downloading a browser and installing the operating-system packages needed to launch it are separate concerns. On Linux, when system dependencies are absent, use Playwright’s combined install command:
yarn playwright install --with-depsThe command may need the permissions required by the system package manager. If it fails while installing operating-system packages, treat that as a dependency or environment issue rather than a browser archive download failure. The CLI also provides a dependency-install command and a dry-run option; on Linux, a dry run can simulate apt-get and report missing packages without performing the installation:
yarn playwright install-deps --dry-runUse the output to identify which packages the environment lacks, then run the appropriate install command for that environment. Avoid copying package names from an unrelated distribution or solving a missing-library error by repeatedly downloading browser binaries. Consult the official CLI options and browser guide for the command behavior and platform details.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Fix browser download failures behind a proxy or custom certificate
Playwright downloads browser binaries from Microsoft’s CDN by default. A proxy, TLS inspection device, custom certificate authority, slow connection, or restricted outbound network can interrupt that step. Match the setting to the actual error instead of changing all of them at once.
Proxy required for outbound HTTPS
Configure HTTPS_PROXY in the environment where the install command runs. For example, in a POSIX shell, set it for the command’s process and replace the sample address with your organization’s actual proxy:
HTTPS_PROXY=http://proxy.example:8080 yarn playwright installThe value above is a syntax example, not a real proxy endpoint. Follow the shell syntax and authentication policy used by your environment. The proxy must permit access to the download host.
Untrusted custom root CA or self-signed certificate chain
If the download reports a self-signed certificate chain because the proxy presents a certificate signed by an internal authority, provide Node.js with the trusted CA bundle using NODE_EXTRA_CA_CERTS:
NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem yarn playwright installUse the certificate file supplied or approved by your organization. Do not disable certificate verification as a workaround; that weakens the security of the download connection.
Slow or stalled browser archive download
For a connection that is slow rather than blocked by trust or access policy, increase PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT. Its value is a timeout in milliseconds; choose a value suitable for the network rather than treating one duration as universal:
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 yarn playwright installInternal artifact repository
An organization that mirrors browser archives can configure PLAYWRIGHT_DOWNLOAD_HOST, or a browser-specific host variable, to point Playwright at its approved artifact host. Confirm that the mirror contains the browser revision required by the project’s Playwright version. These download settings and platform-specific examples are documented in the browser download guidance.
Check the browser cache path and version alignment
If installation succeeds but a later command says the browser is missing, check where it was installed. Playwright documents platform-specific cache directories and supports PLAYWRIGHT_BROWSERS_PATH to select a shared or hermetic location. The install process and the test process must use a consistent path:
Free tools Windows power users keep installed
One-click scans. No signup required.
PLAYWRIGHT_BROWSERS_PATH=/path/to/playwright-browsers yarn playwright install
PLAYWRIGHT_BROWSERS_PATH=/path/to/playwright-browsers yarn playwright testReplace the example path with the location appropriate to your system. Setting the variable for installation but not for the test process can make the binaries appear to be missing even though they were downloaded successfully. Also verify that the browser revision on disk belongs to the Playwright version currently installed. Playwright’s browser guide describes cache locations, the shared-path setting, and removal of unused browser versions: browser management.
Repair a Playwright install that fails in CI
A browser setup that works on a workstation may fail in CI because the runner lacks browser system dependencies, uses a different cache location, or restores binaries for a different Playwright version.
- Ensure the runner can launch browsers. Playwright’s CI guidance recommends using its Linux Docker image or installing the browser dependencies on the runner. A downloaded browser alone does not supply every operating-system library.
- Install the browser binaries during setup. Run the project’s Playwright install command in the CI setup stage, using the package version resolved for that job.
- Key a browser cache to the Playwright version. If the pipeline caches browser binaries, include the Playwright version in the cache key. Otherwise, a cache restored from another version can contain the wrong browser revision.
- Keep install and test environments consistent. If using
PLAYWRIGHT_BROWSERS_PATH, set it for both the install and test steps. Make sure the runner user can read and execute the cached files. - Read the failing stage in the CI log. A package-resolution error, a failed download, a missing Linux library, and a missing cached browser require different changes. Fix the first failing stage rather than adding retries indiscriminately.
The Playwright CI guide covers supported runner preparation and browser caching. The caching recommendation is to tie the browser cache to the Playwright version; a cache key that ignores that version can preserve incompatible browser binaries.
Check that Node.js and the operating system are supported
The current Playwright installation documentation lists Node.js latest 22.x, 24.x, or 26.x, and these platforms: Windows 11 or later, Windows Server 2019 or later, WSL, macOS 14 or later, Debian 12 or 13, and Ubuntu 22.04, 24.04, or 26.04 on x86-64 or arm64. These are documentation requirements, not a guarantee that every configuration has identical behavior. Confirm the current installation requirements for your environment before changing versions; support details can change.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →On a system outside the documented combinations, first reproduce the failure on a supported environment if possible. That helps determine whether the issue is a project configuration problem or a platform compatibility issue. Do not infer that an unlisted operating system is supported merely because the package installed.
Common error patterns and the next fix to try
| Symptom | Likely failing stage | Next check |
|---|---|---|
yarn add cannot resolve or fetch the package |
Yarn package resolution | Keep the package-manager error output; verify project registry and network access. Browser installation settings do not fix package resolution. |
yarn playwright is not found after setup |
Project package or CLI invocation | Run yarn playwright --version from the project directory and confirm the package was added there. |
| Browser download cannot connect or times out | Browser archive download | Check outbound network and proxy configuration; use the documented timeout setting only for slow connections. |
| Download reports a self-signed certificate chain | TLS trust during download | Provide the trusted internal CA through NODE_EXTRA_CA_CERTS if the organization’s proxy uses that CA. |
| Browser launches locally but reports missing system libraries on Linux | Operating-system dependencies | Use yarn playwright install --with-deps or inspect missing packages with yarn playwright install-deps --dry-run. |
| CI cannot find a browser after a successful install | Cache, path, or version alignment | Check the Playwright-version cache key and ensure install and test steps use the same PLAYWRIGHT_BROWSERS_PATH. |
| Failure begins after a Playwright upgrade | Browser binary mismatch | Run the browser install command for the upgraded project version and refresh a version-keyed CI cache. |
These are diagnostic mappings, not proof of a cause. The exact first error and the command that produced it should decide the next step.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is to save a website screenshot—not to run Playwright tests or automate browser interactions—you can use ScreenshotNeo, a website screenshot API and MCP server. A GET request returns a PNG, JPEG, WebP, or PDF; it is a screenshot service, not a substitute for Playwright’s test runner.
For example, this cURL request saves a WebP screenshot of Stripe. Create an API key first and replace YOUR_API_KEY:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. The equivalent Python request is:
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)Or use 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}`);- Cookie and consent banners are accepted and removed before capture; the same applies to more than 60 known consent platforms, newsletter popups, and chat widgets. Each of these cleanup steps can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
- An MCP server offers
take_screenshot,get_page_info, andcapture_pdftools for AI agents and MCP clients. - The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Every feature is available on every plan.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month without a card.
When the install still fails
If the documented branches do not match the error, share the complete command and output, Yarn and Node.js versions, operating system and architecture, Playwright version, whether the failure is local or CI, and whether downloads go through a proxy or internal host. Include the stage where it stops: package add, CLI startup, archive download, dependency installation, or browser launch. Without those details, there is no responsible single fix to recommend.
For a self-contained diagnostic record, these commands identify the relevant versions and confirm whether the project CLI starts:
node --version
yarn --version
yarn playwright --versionFrequently Asked Questions
Does fixing the install require adding Playwright globally?
No global installation is required by the documented Yarn setup; add the test package to the project and invoke its project CLI.
Can ScreenshotNeo run my Playwright test suite?
No. ScreenshotNeo captures website screenshots and PDFs; it does not replace Playwright’s test runner or browser automation.
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.
