Fix: Vibium Headless Crashes on Linux

Vibium headless crashes on Linux are almost always missing Chrome system libraries, an undersized /dev/shm, or a missing sandbox flag in containers — not a Vibium defect. Vibium ships as a single Go binary and auto-downloads its own Chrome for Testing, so there is no driver to match, but the host operating system still has to provide the shared libraries Chrome links against. On a minimal server or slim container image those libraries are absent, so Chrome fails to start the moment you call launch(). The two other classic causes are Docker's tiny default shared-memory partition, which makes Chrome tabs crash under load, and the user namespace sandbox failing inside an unprivileged container. Each has a known fix. Modern headless Chrome renders without an X display, so you do not need Xvfb. This guide covers the libraries, the container flags, and the shared-memory fix in Python.

Why does Vibium crash headless on Linux?

The most common headless crash is Chrome failing to launch because the host is missing its shared libraries. Vibium brings the browser binary, but the OS must supply dependencies such as libnss3, libgbm1, and libasound2. When they are absent, Chrome exits immediately and launch() fails.

sudo apt-get update
sudo apt-get install -y \
  libnss3 libatk-bridge2.0-0 libgbm1 libasound2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libdrm2 libpango-1.0-0 libcairo2

Install these once on the host, then the same script that ran on your laptop runs headless on the server. See how to run Vibium headless on a server for the full deployment walkthrough.

How do I confirm the script itself is fine?

Confirm your code works headless with the smallest possible script, so you can separate a code bug from an environment problem. The only difference from a desktop run is headless=True.

from vibium import browser_sync as browser
 
vibe = browser.launch(headless=True)
vibe.go("https://example.com")
print(vibe.find("h1").text())
vibe.quit()

If this minimal script crashes, the cause is the environment — libraries, shared memory, or the sandbox — not your automation logic. Fix the environment first.

How do I fix Vibium crashes in Docker?

Inside containers the crash usually has two extra causes: Chrome's user-namespace sandbox failing, and Docker's default 64 MB /dev/shm being too small for Chrome. The fix is to give the container more shared memory and, when running unprivileged, disable the in-process sandbox.

# Give Chrome enough shared memory so tabs don't crash under load
docker run --shm-size=1g my-vibium-image

If the sandbox still fails in an unprivileged container, launch Chrome with sandbox-disabling flags. Pass extra Chrome arguments through Vibium's launch options:

# Conceptual: forward Chrome flags via launch args.
# Check the Vibium docs at vibium.com for your version's exact option name.
vibe = browser.launch(
    headless=True,
    args=["--no-sandbox", "--disable-dev-shm-usage"],
)

--disable-dev-shm-usage makes Chrome write to /tmp instead of /dev/shm, sidestepping the small partition; --no-sandbox is the standard workaround for sandboxing inside locked-down containers. If the argument-passing option name is unclear for your version, confirm it in the official docs rather than guessing.

How do I build a slim image that doesn't crash?

A reliable image installs Chrome's shared libraries, pre-fetches Chrome at build time, and is run with enough shared memory. Pre-downloading the browser keeps the first run from paying the download cost — and from timing out on slow networks, which can look like a crash.

FROM python:3.12-slim
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    libnss3 libatk-bridge2.0-0 libgbm1 libasound2 \
    libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
    libxrandr2 libdrm2 libpango-1.0-0 libcairo2 \
    && rm -rf /var/lib/apt/lists/*
 
RUN pip install --no-cache-dir vibium && vibium install
 
COPY scrape.py /app/scrape.py
CMD ["python", "/app/scrape.py"]

Build this image, then run it with --shm-size=1g. The libraries are present, Chrome is already downloaded, and shared memory is sufficient — the three crashes above are all covered.

Do I need Xvfb on Linux?

No. Modern headless Chrome renders without an X display, so launching with headless=True is enough on a typical server. Xvfb is only needed for the rare tool that demands a real display, which Vibium's headless mode does not. Reaching for Xvfb to fix a crash usually masks the real cause, which is one of the issues above.

Tips for stable headless runs on Linux

• Install the shared libraries first — the single most common crash is a missing libnss3 or libgbm1.
• Raise /dev/shm — run containers with --shm-size=1g or pass --disable-dev-shm-usage.
• Use --no-sandbox only in containers — it is the standard fix for unprivileged sandbox failures.
• Pre-fetch Chrome at build time — vibium install avoids first-run download timeouts that look like crashes.

Next steps

• How to run Vibium headless on a server
• Fix: Vibium timeout errors
• What is Vibium?