Puppeteer "error while loading shared libraries: libX11.so" in CI

By Kaveh Alemi·Latchkey

The Chromium binary downloaded fine but the dynamic linker cannot resolve a shared library it needs at startup, commonly libX11.so.6, libatk-1.0.so.0, or libnss3.so. The runner image simply does not have those OS packages installed.

What this error means

The launch fails with "Failed to launch the browser process!" and a process line like "chrome: error while loading shared libraries: libX11.so.6: cannot open shared object file" on a minimal image.

Puppeteer

Error: Failed to launch the browser process!
/root/.cache/puppeteer/chrome/linux-124/chrome-linux64/chrome:
error while loading shared libraries: libX11.so.6: cannot open shared object file:
No such file or directory

Common causes

A slim base image without browser libraries

Minimal Node or Debian images omit the X11, ATK, GTK, and NSS libraries that Chromium links at launch.

No install step for the browser OS dependencies

Puppeteer downloads Chrome but does not install its system libraries, so the linker fails on the first missing .so.

How to fix it

Install the Chromium system libraries

Add the apt packages Chromium needs before launching.

Terminal

sudo apt-get update
sudo apt-get install -y libx11-6 libnss3 libatk-bridge2.0-0 libgbm1 \
  libgtk-3-0 libasound2

Use an image that bundles the dependencies

A Puppeteer-ready base image ships the browser libraries so nothing is missing.

.github/workflows/ci.yml

container:
  image: ghcr.io/puppeteer/puppeteer:latest

How to prevent it

Install Chromium's OS libraries in a setup step on slim images.
Prefer a maintained Puppeteer image that includes the dependencies.
Read the first "cannot open shared object file" line to know which package to add.

Frequently asked questions

What causes ""error while loading shared libraries: libX11.so""?