playwright Host system is missing dependencies to run browsers in CI docker - how to fix

TL;DR

Playwright's bundled Chromium, Firefox, and WebKit link against OS libraries like libnss3 and libatk that slim CI docker images do not ship. The error even lists what is missing, which makes this one of the more honest CI failures. Either install the libraries with npx playwright install --with-deps, which needs apt privileges in the image, or switch the job to the official Playwright docker image, which ships every dependency preinstalled.

The query

playwright Host system is missing dependencies to run browsers in CI docker  -  how to fix

Use this when

• Host system is missing dependencies to run browsers appears in CI
• the CI job runs in a custom or slim docker image
• the error lists missing .so libraries

Not for

• Executable doesn't exist at ... ms-playwright (browsers were never downloaded; run npx playwright install)
• the job does not use docker at all (the hosted runner already has the libraries)
• the browser launches but the page crashes (that is a memory problem, not missing libraries)

Steps

1. Read the missing-dependency list from the error

The error names the exact libraries. Save them; you will verify they are gone after the fix.

Host system is missing dependencies to run browsers.
Please install them with the following command:
  npx playwright install --with-deps chromium
Missing libraries:
    libnss3.so
    libatk-1.0.so.0

Expected output: you have the concrete library names, not a guess.

2. Option A: install the dependencies in your image

Run the install with --with-deps before the tests. This needs root or sudo in the container, and it needs network access to the apt mirrors.

npx playwright install --with-deps chromium
npx playwright test

Expected output: apt installs the libraries and the browser launches.

3. Option B: use the official Playwright docker image

When you cannot apt-install in CI, base the job on the image the Playwright team publishes. Match the image tag to your Playwright version.

jobs:
  e2e:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.55.0-noble

Expected output: the job starts with all browser dependencies present and no install step needed.

4. Cache the browsers between runs

Browser downloads are large. Cache the ms-playwright directory keyed by the Playwright version so only the first run pays for it.

- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-[playwright version]

Expected output: subsequent runs skip the download and start testing immediately.

Tool compatibility

• Playwright 1.40 - 1.55
• docker-based CI (GitHub Actions container jobs, GitLab, Jenkins agents)

Variant phrasings

• Host system is missing dependencies to run browsers
• libnss3.so: cannot open shared object file in CI
• playwright browsers fail to launch in docker with missing libraries

Why it happens

Playwright bundles the browsers but not the OS libraries they link against, by design: the libraries belong to the OS. Slim base images strip everything not needed to run the language runtime, so the first browser launch in CI discovers the gap. The official image exists precisely to close it.

Edge cases / pitfalls

• --with-deps needs root: it fails silently or loudly in rootless containers, which is the signal to switch to the official image
• corporate proxies and allowlisted apt mirrors break the apt step; the official image avoids apt entirely
• the image tag must match the Playwright version in package.json, or the browsers and the driver disagree
• installing all three browsers triples the download; pass the browser name to install only what the suite uses

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0w7jZ85VcEe3yMpXzwnHrw