Introduction: What Does the Playwright Browser Not Installed Error Mean?
The playwright browser not installed error occurs when the Playwright package is installed but the browser binary required to run a test is missing, inaccessible, or incompatible.
A common message looks like:
Executable doesn’t exist at …
Looks like Playwright Test or Playwright was just installed or updated.
Please run the following command to download new browsers:
This can be confusing for beginners because installing the npm package and installing browser binaries are two different things.
Playwright Test can use Chromium, Firefox, and WebKit, and each Playwright release is tied to specific browser versions. After updating Playwright, browser binaries may need to be installed again.
Common Playwright Browser Installation Error Messages
You may see messages such as:
Executable doesn’t exist at …
browserType.launch: Executable doesn’t exist
Looks like Playwright Test or Playwright was just installed or updated.
Failed to launch browser
Chromium executable not found
These usually indicate one of four problems:
- Browser binaries were never installed.
- The installed browser doesn’t match the Playwright version.
- Browser system dependencies are missing.
- Playwright is looking in a different browser cache location.
Why Playwright Browsers Are Not Installed
There are several common reasons.
1. Only the npm package was installed
For example:
npm install -D @playwright/test
installs the Playwright Test package, but you may still need to download the required browser binaries.
2. Browser installation was skipped
The project generator normally offers to install browsers, but installation can be skipped or fail because of network restrictions.
3. Playwright was updated
Each Playwright version expects compatible browser binaries. After updating Playwright, you may need:
npx playwright install
Playwright’s documentation specifically recommends reinstalling browsers after updating Playwright.
4. CI/CD installed npm packages but not browsers
A common pipeline mistake is:
npm ci
npx playwright test
without:
npx playwright install –with-deps
Installing Playwright Browsers Correctly
The simplest Playwright browser installation command is:
npx playwright install
This downloads the supported default browsers.
You can verify the installed browsers with:
npx playwright install –list
Playwright provides this command to list browsers associated with Playwright installations on the machine.
Check your Playwright version:
npx playwright –version
Then run:
npx playwright install
This is the first solution to try for a Playwright Browser Missing error.
Playwright Chromium Installation Fix
If your project only needs Chromium:
npx playwright install chromium
This is useful when you want to reduce installation time and disk usage.
Test it:
npx playwright test –project=chromium
For CI, Playwright recommends installing only the browsers you actually use when possible.
Installing Firefox and WebKit
Install Firefox:
npx playwright install firefox
Install WebKit:
npx playwright install webkit
Install multiple browsers:
npx playwright install chromium firefox webkit
You can then configure browser projects:
import { defineConfig, devices } from ‘@playwright/test’;
export default defineConfig({
projects: [
{
name: ‘chromium’,
use: {
…devices[‘Desktop Chrome’]
}
},
{
name: ‘firefox’,
use: {
…devices[‘Desktop Firefox’]
}
},
{
name: ‘webkit’,
use: {
…devices[‘Desktop Safari’]
}
}
]
});
Run a specific browser:
npx playwright test –project=firefox
Playwright’s WebKit and Firefox builds are Playwright-specific builds rather than simply controlling your installed Safari or branded Firefox.
Playwright Package vs Browser Binary vs System Dependencies
This distinction is critical for a Playwright browser not installed error tutorial.
| Component | Purpose |
| @playwright/test | Test framework |
| Playwright browser binary | Chromium, Firefox, or WebKit executable |
| System dependencies | Linux libraries required by browsers |
| Executable path | Location where Playwright expects the browser |
For example:
npm install -D @playwright/test
installs the package.
Then:
npx playwright install chromium
downloads Chromium.
On Linux CI:
npx playwright install –with-deps chromium
installs Chromium plus required operating-system dependencies. Playwright documents –with-deps specifically for installing browser dependencies alongside the browsers.
Fixing Browser Errors in Existing Projects
If an existing project suddenly reports:
Executable doesn’t exist
try this sequence:
npm ci
npx playwright install
npx playwright test
If only Chromium is required:
npm ci
npx playwright install chromium
npx playwright test
If you’re on Linux and dependencies may be missing:
npx playwright install –with-deps chromium
Then verify:
npx playwright install –list
Checking Playwright and Browser Version Compatibility
Suppose you previously had:
Playwright 1.x
and then update the dependency:
npm install -D @playwright/test@latest
The browser binaries associated with the older version may no longer be appropriate.
Run:
npx playwright –version
Then:
npx playwright install
Playwright’s browser versions are tied to Playwright releases, so keeping the package and browser installation synchronized is important.
For reproducible projects, commit your package-lock.json and use:
npm ci
in CI rather than installing arbitrary dependency versions.
Fixing Playwright Browser Installation in CI/CD
This is one of the most common real-world causes of the playwright browser not installed error.
A basic GitHub Actions workflow should include:
– name: Install dependencies
run: npm ci
– name: Install Playwright browsers
run: npx playwright install –with-deps
– name: Run Playwright tests
run: npx playwright test
Playwright’s CI guidance follows this general sequence: install npm dependencies, install browsers and dependencies, then execute tests.
Chromium-only CI
If your project only tests Chromium:
– name: Install Chromium
run: npx playwright install chromium –with-deps
This reduces unnecessary browser downloads.
CI best practice
Use:
npx playwright install –with-deps
on Linux CI unless your runner already provides all required browser dependencies.
Fixing Playwright Browser Errors in Docker
Docker introduces another common problem: the container may have Node.js and your project but not the correct Playwright browsers.
You can use a Playwright Docker image or build your own image.
Example:
FROM node:20-bookworm
WORKDIR /app
COPY package*.json ./
RUN npm ci
RUN npx playwright install –with-deps
COPY . .
CMD [“npx”, “playwright”, “test”]
Playwright also publishes Docker images containing Playwright browsers and their system dependencies. If using one, keep the image’s Playwright version aligned with the version in your project. A mismatch can prevent Playwright from locating compatible browser executables.
Important Docker warning
Avoid assuming:
Playwright package version = Docker image version
automatically.
Pin compatible versions.
Browser Cache and Executable-Path Issues
Playwright stores browser binaries in OS-specific cache directories.
Typical locations include:
Windows:
%USERPROFILE%\AppData\Local\ms-playwright
macOS:
~/Library/Caches/ms-playwright
Linux:
~/.cache/ms-playwright
You can check available browsers:
npx playwright install –list
If the browser exists in a custom location, check whether PLAYWRIGHT_BROWSERS_PATH is configured.
For example:
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install
and:
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test
The installation and execution environments must point to the same browser location.
Browser Download Problems Behind a Proxy or Firewall
Corporate networks can prevent Playwright from downloading browsers.
For example:
HTTPS_PROXY=https://proxy.example.com:8080 \
npx playwright install
On PowerShell:
$Env:HTTPS_PROXY=”https://proxy.example.com:8080″
npx playwright install
Playwright downloads browser archives from Microsoft’s CDN by default and documents proxy and custom certificate configuration for restricted corporate environments.
For slow connections, you can increase the browser download connection timeout:
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 \
npx playwright install
Debugging Playwright Browser Installation Problems
Start with:
npx playwright –version
Then:
npx playwright install –list
Then:
npx playwright install –dry-run
If necessary, force a fresh installation:
npx playwright install –force
The CLI supports options such as –force, –with-deps, and –dry-run.
Verify with a simple TypeScript test
import { test, expect } from ‘@playwright/test’;
test(‘verify browser installation’, async ({ page }) => {
await page.goto(‘https://playwright.dev/’);
await expect(page).toHaveTitle(/Playwright/);
});
Run:
npx playwright test
If this works, your basic browser setup is functional.
Real-World Playwright Browser Troubleshooting Examples
Scenario 1: Chromium Not Installed
Problem
Executable doesn’t exist
Root cause: Chromium binary is missing.
Fix:
npx playwright install chromium
Best practice: Install only the browsers required by the project.
Scenario 2: Works Locally, Fails in CI
Problem: Local tests pass, CI says browser executable is missing.
Root cause: CI installed npm dependencies but skipped browser installation.
Fix:
npm ci
npx playwright install –with-deps
npx playwright test
Best practice: Treat browser installation as an explicit CI setup step.
Scenario 3: Docker Browser Version Mismatch
Problem: Browser exists but Playwright cannot locate or use it.
Root cause: Docker image and project use incompatible Playwright versions.
Fix: Align the Playwright package and Docker image versions.
Best practice: Pin the versions rather than using unrelated latest tags.
Scenario 4: Corporate Firewall Blocks Installation
Problem: Browser download fails.
Root cause: Proxy/firewall restrictions.
Fix:
HTTPS_PROXY=https://proxy.example.com:8080 \
npx playwright install
If your organization uses an internal certificate authority, configure NODE_EXTRA_CA_CERTS appropriately.
Common Mistakes and Solutions
| Mistake | Solution |
| Install npm package only | Run npx playwright install |
| Install all browsers unnecessarily | Install only required browsers |
| Skip Linux dependencies | Use –with-deps |
| Ignore Playwright version changes | Reinstall browsers after updates |
| Use mismatched Docker image | Align Playwright versions |
| Ignore proxy restrictions | Configure HTTPS_PROXY |
| Use custom browser path incorrectly | Check PLAYWRIGHT_BROWSERS_PATH |
| Don’t verify installation | Run install –list |
| Hard-code executable paths | Prefer Playwright-managed browsers |
Playwright Browser Installation Best Practices
Use this checklist:
- Install Playwright with a pinned project dependency.
- Run npx playwright install after installation or upgrades.
- Install only the browsers your tests require.
- Use –with-deps on Linux CI when needed.
- Keep Docker and npm Playwright versions aligned.
- Use npm ci for reproducible CI installs.
- Don’t manually copy browser binaries between machines.
- Check npx playwright install –list when troubleshooting.
- Configure proxy settings in restricted networks.
- Keep browser installation in the CI pipeline.
- Avoid unnecessary custom executablePath configuration.
For CI, Playwright specifically recommends optimizing browser downloads and installing only the required browsers.
Playwright Browser Installation Interview Questions
1. Why does Playwright require browser installation?
Playwright controls specific browser binaries that correspond to its supported versions. Installing the npm package alone does not guarantee those binaries are available.
2. How do you install Playwright browsers?
npx playwright install
3. How do you install only Chromium?
npx playwright install chromium
4. How do you install browser dependencies on Linux?
npx playwright install –with-deps
5. How do you verify installed browsers?
npx playwright install –list
6. Why can a browser disappear after updating Playwright?
Playwright versions use specific browser revisions. Updating Playwright can require downloading the corresponding browser binaries again.
7. How do you fix browser installation in CI?
npm ci
npx playwright install –with-deps
npx playwright test
8. Why is Docker version matching important?
The Playwright package expects compatible browser executables. A mismatched Docker image can cause executable-location or compatibility problems.
FAQs: Playwright Browser Not Installed Error
What causes Playwright browser not installed error?
The most common causes are missing browser binaries, version mismatches, missing Linux dependencies, failed downloads, incorrect browser cache paths, and CI/Docker configuration problems.
How do I fix Playwright browser not installed error?
Run:
npx playwright install
For Linux CI:
npx playwright install –with-deps
Then rerun your tests.
What is the Playwright install browsers command?
The standard command is:
npx playwright install
For a specific browser:
npx playwright install chromium
How do I fix Chromium not installed in Playwright?
Run:
npx playwright install chromium
Then verify:
npx playwright install –list
Do I need to install Chrome separately?
Usually no. Playwright normally uses its own Chromium build. It can also work with installed branded Chrome or Edge through browser channels, but those browsers are not installed by default by Playwright.
Why does Playwright work locally but fail in CI?
The CI runner may not have browser binaries or required operating-system dependencies. Add:
npx playwright install –with-deps
to the pipeline.
Does npm install @playwright/test install browsers?
The project setup flow can install browsers, but in an existing project you should explicitly run the Playwright install command when browser binaries are missing or after relevant version updates.