You install Playwright, write your first test, run it, and nothing runs:
Error: browserType.launch: Executable doesn't exist at
/Users/you/Library/Caches/ms-playwright/chromium-1234/chrome-mac/Chromium.app/...
Looks like Playwright Test or Playwright was just installed or updated.
Please run the following command to download new browsers:
npx playwright install
The message tells you the fix, so this one is quick. But the reason behind it is worth two minutes, because it explains a whole class of problems you will meet later in CI and Docker.
Why the browsers are separate
npm install @playwright/test installs the library: the code that drives a browser. It does not install the browsers themselves.
Playwright uses its own downloaded builds of Chromium, Firefox and WebKit rather than whatever is on your machine. That sounds like extra work, and it buys something important: everyone on the team, and CI, runs the exact same browser build. A test that passes for you passes for them, and a failure is not explained away by someone having a different Chrome version.
Those builds are large, so they are not bundled in the npm package. They are downloaded once and cached outside your project:
- macOS:
~/Library/Caches/ms-playwright - Linux:
~/.cache/ms-playwright - Windows:
%USERPROFILE%\AppData\Local\ms-playwright
Cached outside the project is why deleting node_modules does not lose them, and why a fresh CI machine has none.
The fix
npx playwright install
That downloads all three engines. If you only need one:
npx playwright install chromium
In CI, add --with-deps
On a Linux CI runner the browsers alone are not enough. They need system libraries that a minimal container does not ship, and without them you get a launch failure whose message reads like nonsense.
npx playwright install --with-deps
That installs the browsers and the operating system packages they need. On a GitHub Actions runner it is the difference between a green pipeline and twenty minutes of confusion.
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
If you would rather not download browsers on every CI run, the official Playwright Docker image ships with them already present.
Using the Chrome you already have
You do not have to use Playwright's build. If you want the real branded Google Chrome or Microsoft Edge, ask for the channel:
// playwright.config.ts
export default defineConfig({
projects: [
{ name: 'chrome', use: { ...devices['Desktop Chrome'], channel: 'chrome' } },
],
});
That runs against the Chrome installed on the machine instead of a downloaded Chromium.
Worth knowing the trade before you reach for it. Chromium is the open source engine Chrome is built on, and Playwright's build is pinned, so everyone gets the same one. Branded Chrome updates itself on the machine's schedule, which means your test environment changes without you choosing it. Use the channel when you specifically need branded Chrome behaviour, such as certain media codecs, rather than by default.
When it happens again after it worked
Two common cases.
You upgraded Playwright. Each version pins its own browser builds, so a new version needs a new download. The error message even says so: "just installed or updated". Run the install command again.
A fresh machine or container. The cache lives outside the project, so a new laptop or a clean CI image starts with nothing. This is expected, not a bug.
Remember this
The npm package is the library, and the browsers are a separate download cached outside your project. npx playwright install fetches them, and in CI use --with-deps so the system libraries come too. Upgrading Playwright means downloading again, because each version pins its own builds. Use channel: 'chrome' only when you genuinely need branded Chrome, since a pinned build is what makes runs repeatable.
Once it runs, the graded practice is the fastest way to find out whether the tests you write actually catch bugs: each one is run against a working app, then against a copy where the behaviour is broken.
Related: Timeout 30000ms exceeded and strict mode violation, the next two errors most people meet.
Reference: Playwright browsers.