How to Run Vibium in Docker

To run Vibium in Docker, start from a slim Python image, install Chrome's shared system libraries, then run pip install vibium and vibium install so Chrome for Testing is baked into an image layer. Your script launches with headless=True, and that is the only change from a desktop run. Vibium ships as a single Go binary that downloads its own Chrome for Testing, so the container never needs a system Chrome, ChromeDriver, or a desktop environment — just the handful of shared libraries Chrome links against, like libnss3, libgbm1, and libasound2. Modern headless Chrome renders without an X display, so there is no Xvfb to configure. Pre-downloading the browser at build time matters most: it keeps every cold start from re-fetching Chrome, which is the difference between a container that boots instantly and one that stalls on first request. The result is a small, reproducible image that runs the exact script you debugged locally.

What does a minimal Vibium Dockerfile look like?

A slim base plus Chrome's libraries plus a pre-fetched browser is the whole recipe. There is no system Chrome line because Vibium manages the browser itself:

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
WORKDIR /app
CMD ["python", "scrape.py"]

Because vibium install runs in its own layer, the Chrome for Testing binary is cached in the image — the container does not download Chrome on every start.

What goes in the script itself?

The container runs an ordinary headless Vibium script; the only Docker-specific choice is headless=True. Everything else is the standard sync API:

from vibium import browser_sync as browser
 
vibe = browser.launch(headless=True)
try:
    vibe.go("https://example.com")
    print(vibe.find("h1").text())
 
    png = vibe.screenshot(full_page=True)
    with open("/app/page.png", "wb") as f:
        f.write(png)
finally:
    vibe.quit()

The try/finally matters more in a container than on a laptop: if the script crashes, quit() still closes Chrome so the process does not linger when the container is reused. For the basics of find() and screenshot(), see the find-element command and the screenshot command.

Why does Vibium need system libraries but not system Chrome?

Vibium downloads its own Chrome for Testing, but that browser binary still dynamically links against shared libraries that slim base images omit. Installing libnss3, libgbm1, libasound2, and the X11 client libraries satisfies those links without pulling in a desktop. This split is what keeps the image small: you add a dozen libraries, not a full Chrome package and a matching driver. It is also why a missing-library error at launch is the most common first failure in containers — the fix is always to add the library, never to install a different browser.

How do I build and run the image?

Build once, then run the container like any other job. The first build pays the Chrome download cost; every run after that is fast:

docker build -t my-vibium-bot .
docker run --rm my-vibium-bot

For CI or batch jobs, --rm cleans up the container on exit. If your script writes screenshots or scraped data you want to keep, mount a volume:

docker run --rm -v "$PWD/out:/app/out" my-vibium-bot

How do I keep the image small and reliable?

A few habits keep Vibium containers lean and predictable:

• Pin the Vibium version with pip install vibium==26.2 so a rebuild cannot silently pull a newer Chrome for Testing. See how to pin the Chrome version for the full approach.
• Pre-fetch Chrome at build time with vibium install so cold starts never download the browser.
• Use --no-install-recommends and clean apt lists in the same RUN to avoid bloating layers.
• Set a viewport with window_size=(1280, 800) so headless layout matches what you expect.
• Always quit() in a finally block so a crash does not leak a Chrome process inside the container.

Where can Vibium containers run?

Anywhere a container runs: GitHub Actions, GitLab CI, Kubernetes jobs, cron on a VM, or a serverless container platform. Because the image is self-contained — Go binary, Chrome for Testing, and your script — there is nothing to install on the host. For a CI-specific walkthrough, see how to use Vibium in GitHub Actions, and for running outside containers on a plain box, how to run Vibium headless on a server.

Next steps

• How to use Vibium in GitHub Actions
• How to pin the Chrome version in Vibium
• What is Vibium?