How to Install & Run Playwright Browsers in CI

Playwright ships three browser engines and a long list of OS dependencies. One command installs all of it correctly; skipping it is the #1 cause of CI failures.

Installing the @playwright/test npm package does not install the browsers - those are a separate download, and on Linux they need extra system libraries. The install --with-deps command handles both in one step.

Why it fails in CI

After npm ci, the browser binaries are missing until you run Playwright’s installer, so tests fail with Executable doesn’t exist at .../chromium-XXXX/chrome-linux/chrome. Even after the binaries download, a minimal runner lacks the shared libraries Chromium/Firefox/WebKit link against, which is why --with-deps exists.

Install & run it reliably

Run the official installer with system dependencies after installing node modules. This is the canonical fix:

.github/workflows/e2e.yml

npm ci
npx playwright install --with-deps
npx playwright test

# no root / locked-down base? use the official image instead:
#   mcr.microsoft.com/playwright:v1.XX.X-jammy
#   (pin the tag to your Playwright version)

Cache & speed

Playwright stores browsers in ~/.cache/ms-playwright. Cache it keyed on the Playwright version (read it from your lockfile) so you skip the ~300 MB download. Install only the browsers you test with - npx playwright install --with-deps chromium - to cut download time when you do not need Firefox and WebKit.

Common errors

Executable doesn’t exist at … → you never ran playwright install; add it after npm ci.
Host system is missing dependencies → use --with-deps or the official Docker image.
Browser-version mismatch in the Docker image → align the image tag with your installed Playwright version.
Slow first run every time → add the ~/.cache/ms-playwright cache.

Key takeaways

npx playwright install --with-deps installs browsers and OS libraries in one step.
The official mcr.microsoft.com/playwright image avoids apt entirely - pin its tag to your version.
Cache ~/.cache/ms-playwright keyed on the Playwright version.