How to Run Puppeteer in CI Without Chromium Errors

Puppeteer downloads a Chromium build, but Chromium itself needs a long list of shared libraries that slim CI images do not ship.

Puppeteer installs a matching Chromium into its cache. Launch failures in CI are almost always missing system libraries or sandbox restrictions, not Puppeteer itself.

Why it fails in CI

Chromium dependencies (libnss3, libatk, libgbm, fonts) are missing → "Failed to launch the browser process".
The Chromium sandbox cannot start in a container without --no-sandbox.
PUPPETEER_SKIP_DOWNLOAD was set, so no browser is present.

Install and run it reliably

Install the Chromium system libraries, let Puppeteer download its browser, and launch headless with the sandbox flags appropriate for CI.

Terminal

# Debian/Ubuntu Chromium deps
apt-get update && apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
  libpango-1.0-0 libasound2 libxshmfence1 fonts-liberation

npm ci   # puppeteer downloads its Chromium

Cache & speed

Cache the Puppeteer browser cache so Chromium is not re-downloaded every run. Key on the Puppeteer version. Chromium launches are flaky; faster managed runners and auto-retry of transient launch failures reduce noise.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/puppeteer
    key: puppeteer-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Common errors

error while loading shared libraries: libnss3.so → install the Chromium deps above.
No usable sandbox! → add --no-sandbox in containerized CI.
Could not find Chromium → PUPPETEER_SKIP_DOWNLOAD was set, or the cache path is wrong.

Key takeaways

Chromium needs libnss3/libgbm/fonts and friends - install them in slim images.
Use --no-sandbox in containers, judiciously.
Cache ~/.cache/puppeteer keyed on the Puppeteer version.