Linux System Dependencies

PyWee downloads and manages its own Chromium executable, but it does not bundle the native libraries supplied by a Linux distribution. These are Chromium host requirements, not Python application dependencies, and pip cannot install them.

Most complete Linux desktop installations already provide these libraries. A missing dependency is more likely on a minimal installation, a server, a container, or a custom desktop image.

Upstream Requirements

The current PyWee runtime lock uses the Chromium build provided by Playwright 1.54.0. The matching upstream sources are:

• Playwright 1.54.0 native dependency manifest, including separate Chromium lists for supported Debian and Ubuntu releases;
• Chromium's Linux dependency documentation;
• Chromium's additional Debian runtime dependencies, which covers dependencies discovered outside normal shared-library linking.

The upstream lists are authoritative for the browser build. Package names vary between distributions and releases even when the underlying shared-library names remain the same.

Debian And Ubuntu

On a minimal Debian or Ubuntu installation, the following packages cover the Chromium runtime libraries used by PyWee and the normal headed desktop path:

sudo apt-get update
sudo apt-get install --yes --no-install-recommends \
  fonts-liberation gsettings-desktop-schemas \
  libasound2 libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 libcairo2 \
  libcups2 libdbus-1-3 libdrm2 libgbm1 libgl1 libglib2.0-0 \
  libnspr4 libnss3 libpango-1.0-0 libx11-6 libxcb1 libxcomposite1 \
  libxdamage1 libxext6 libxfixes3 libxkbcommon0 libxrandr2 xdg-utils

Newer Debian and Ubuntu releases may automatically select equivalent package names with a t64 suffix. That substitution is expected.

Do not run this command routinely on an already working desktop. It is a recovery recipe for systems where Chromium reports a missing native library.

What The Packages Provide

Area	Typical packages	Purpose
Core runtime	libglib2.0-0, libnspr4, libnss3	OS integration, TLS, certificates, and Chromium support services.
Window system	libx11-6, libxcb1, libxcomposite1, libxdamage1, libxrandr2	X11 windows, input, and composition.
Rendering	libdrm2, libgbm1, libgl1, Cairo, and Pango	Graphics buffers, OpenGL loading, 2D drawing, and text.
Desktop integration	D-Bus, ATK/AT-SPI, GSettings, and xdg-utils	Desktop communication, accessibility, settings, and URL/file integration.
User-facing features	ALSA, CUPS, and Liberation fonts	Audio, printing, and predictable fallback fonts.

Some libraries are linked directly into the Chromium executable. Others are loaded only when a graphics or desktop feature is initialized, and fonts and GSettings schemas are data rather than shared libraries. For that reason, a successful ldd check does not prove that every optional desktop path is available.

Diagnose A Missing Library

Use the executable path printed by:

pywee chromium status

Then inspect its direct shared-library dependencies:

ldd /path/to/pywee/chromium/linux-x64/chrome | grep 'not found'

Common messages have different meanings:

• libnspr4.so: cannot open shared object file means a required Chromium library is absent;
• Could not dlopen libGL.so.1 means the selected graphics path cannot find an OpenGL provider;
• a g_settings_schema_source_lookup warning means GSettings schemas are not installed;
• Authorization required or a missing DISPLAY concerns access to the Linux display server, not a missing Chromium library.

After installing a missing dependency, repeat:

pywee chromium install
pywee chromium verify
pywee run your-app