How to Fix Playwright Install Not Found Errors
Fix Playwright browser executable errors by installing matching binaries, Linux dependencies, shared caches, and correctly configured CI environments.
Most Playwright “install not found” errors mean the Playwright package is installed but its matching browser binary is missing, inaccessible, or unable to launch. From your project directory, check the CLI version and install the browser:
npx playwright --version
npx playwright installIf your tests use one browser, install only that browser:
npx playwright install chromium
# or
npx playwright install firefox
npx playwright install webkitOn Linux CI or a Linux container, install operating-system dependencies too:
npx playwright install --with-depsPlaywright package installation and browser installation are separate steps. Each Playwright release expects specific browser builds, so updating the package can require running the install command again. See the official browser installation guide.
1. Identify which failure you have
| Symptom | Likely cause | First fix |
|---|---|---|
| “Executable doesn’t exist” or “browserType.launch: Executable doesn’t exist” | The managed browser was never downloaded, or the cache is not visible to the process. | Run npx playwright install with the same user and environment that runs tests. |
| Browser starts then exits with missing shared-library errors | Linux system dependencies are absent. | Run npx playwright install --with-deps. |
| Works locally but fails in CI or Docker | Different users, containers, cache paths, package versions, or image versions. | Align versions and install browsers inside the CI/container environment. |
| Install fails with certificate, proxy, timeout, or connection errors | The runner cannot reach the browser download host. | Configure the documented proxy, CA, timeout, or artifact-host variables. |
2. Reinstall the browser that matches your package
Run these commands from the directory containing your project’s Playwright dependency:
npm ci
npx playwright --version
npx playwright install chromium
npx playwright testUse npm install instead of npm ci when you do not have a lockfile. If you use Python, install the package and then run its browser installer:
pip install playwright
playwright install chromiumInstalling Google Chrome or Microsoft Edge is not the normal repair. Playwright generally uses its own supported browser builds; arbitrary system executable paths can be incompatible. Branded browsers are a separate configuration choice documented by Playwright.
3. Install Linux dependencies separately when needed
A downloaded executable can still fail to launch when shared libraries, fonts, or other OS packages are missing. Install both the browser and dependencies in one operation:
npx playwright install --with-deps chromiumOr install dependencies explicitly:
npx playwright install-deps chromiumUse the browser name required by your tests. On a locked-down runner, you may need administrator privileges or a prebuilt image that already contains these packages.
4. Make the browser cache visible to the test process
Playwright stores downloaded browsers in an OS-specific cache by default:
- Windows:
%USERPROFILE%\AppData\Local\ms-playwright - macOS:
~/Library/Caches/ms-playwright - Linux:
~/.cache/ms-playwright
The install and test commands must resolve the same cache. Problems occur when installation runs as root, a different CI user, another job, or a different container.
Choose a shared cache explicitly:
export PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
npx playwright install chromium
PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers npx playwright testFor a hermetic install stored under playwright-core, set:
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromiumWhen diagnosing a failure, print the variable and inspect permissions:
echo "$PLAYWRIGHT_BROWSERS_PATH"
ls -la ~/.cache/ms-playwright
whoamiPlaywright can remove browser versions no longer required by installed clients. If a managed environment must retain old versions, the browser guide documents PLAYWRIGHT_SKIP_BROWSER_GC=1 and the CLI’s --no-remove option. Use these only when cleanup is the demonstrated cause.
5. Keep CI and Docker versions aligned
The reliable CI order is:
- Install the exact dependency versions from the lockfile.
- Install only the browsers your suite uses.
- Run tests in the same job image and user context.
npm ci
npx playwright install --with-deps chromium
npx playwright testPlaywright’s CI guidance recommends a Playwright Docker image or installing dependencies on Linux agents. The Docker documentation warns that a version mismatch between the image and the project can prevent Playwright from locating executables. Pin both to the same Playwright version and install or run in the intended image.
Browser caching is optional. If you cache browser binaries, include the Playwright package version in the cache key. Linux OS dependencies cannot be made available through a browser-binary cache alone.
6. Fix downloads behind proxies or private networks
The default browser source is Microsoft’s CDN. Configure the environment before running the installer when your network requires a proxy or internal artifact host:
export HTTPS_PROXY=http://proxy.example.test:8080
export NODE_EXTRA_CA_CERTS=/path/to/corporate-root.pem
export PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
npx playwright install chromiumFor an internal mirror, Playwright documents PLAYWRIGHT_DOWNLOAD_HOST and browser-specific download-host variables. A self-signed certificate-chain error usually needs NODE_EXTRA_CA_CERTS; a slow archive connection usually needs a higher download timeout. These settings address the download route, not an incorrect executable path.
7. Complete diagnostic checklist
- Run
npx playwright --versionin the failing environment. - Confirm the test browser name matches the installed browser.
- Run
npx playwright install chromium(or the required browser). - On Linux, run
npx playwright install --with-deps. - Check the effective
PLAYWRIGHT_BROWSERS_PATH. - Verify the install and test use the same user, container, and filesystem.
- Align the project package and Docker image Playwright versions.
- Inspect proxy, CA, timeout, and artifact-host settings.
- Re-run with the project lockfile and a clean, reproducible environment.
8. Common errors and fixes
| Error pattern | Cause | Fix |
|---|---|---|
Executable doesn't exist at ... |
Browser binary missing or cache path differs. | Install the matching browser and share PLAYWRIGHT_BROWSERS_PATH. |
Host system is missing dependencies |
Linux libraries are absent. | Use npx playwright install --with-deps or a compatible Playwright image. |
self-signed certificate in certificate chain |
HTTPS interception by a corporate CA. | Set NODE_EXTRA_CA_CERTS to the trusted root certificate. |
| Download hangs or times out | Proxy, firewall, or slow connection. | Set HTTPS_PROXY, increase PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT, or use an internal host. |
| Works on one machine only | User-specific cache or unpinned environment. | Pin versions and install browsers during environment setup. |
| Docker tests cannot find browsers | Image and project Playwright versions differ. | Use matching versions and run install/test in the same image. |
9. Performance, reliability, and cost considerations
- Install only what you use: installing Chromium alone reduces download and disk work compared with installing every browser. This is the recommended CI practice when the suite targets one engine.
- Prefer reproducibility: lock the Playwright package version, install browsers during image or job setup, and key any cache by that version.
- Separate download failures from launch failures: proxy and certificate settings affect downloads; Linux dependency installation affects launch; cache settings affect discovery.
- Choose Docker deliberately: a maintained Playwright image can provide browser and OS dependencies together, but its version must match the project.
- There is no browser-license purchase involved: the documented repair is package, browser-binary, dependency, cache, or network configuration.
Or skip the browser setup
If your goal is to obtain a page image rather than run Playwright code, ScreenshotNeo provides a hosted screenshot API. It handles the browser environment for you:
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}`);See the ScreenshotNeo API documentation for request options. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account and get 1,000 screenshots each month with no card.
FAQ
Does npm install playwright download browsers?
Treat package and browser installation as separate operations. Run the documented Playwright install command after installing or updating the package.
Should I set an executable path manually?
Usually no. Playwright-managed browser builds are the supported default. First repair installation, dependencies, cache visibility, and version alignment.
Why did an update break a previously working suite?
The new Playwright release can require different browser binaries. Re-run the browser installer for the new package version.
Is a browser cache required in CI?
No. Installing during the job or image build is often simpler. If you cache, include the Playwright version in the cache key and remember that OS dependencies are separate.
What if the browser is installed but still cannot launch?
On Linux, install system dependencies with --with-deps. Then verify that the runtime user can read the browser cache and that the container or image matches the project version.
