Introduction

Running headless Chromium inside Docker is a common way to make browser automation reproducible in CI, scraping jobs, and test environments. The two main challenges are installing the browser with its required system libraries and starting it with flags that match container constraints such as limited shared memory and lack of a desktop session.

A Minimal Ubuntu-Based Setup

A straightforward Docker image can install Chromium plus the shared libraries it needs:

1FROM ubuntu:24.04
2
3ENV DEBIAN_FRONTEND=noninteractive
4
5RUN apt-get update && apt-get install -y \
6    chromium-browser \
7    ca-certificates \
8    fonts-liberation \
9    libasound2t64 \
10    libatk-bridge2.0-0 \
11    libatk1.0-0 \
12    libcups2t64 \
13    libdbus-1-3 \
14    libgbm1 \
15    libgtk-3-0 \
16    libnss3 \
17    libxcomposite1 \
18    libxdamage1 \
19    libxrandr2 \
20    xdg-utils \
21 && rm -rf /var/lib/apt/lists/*
22
23CMD ["chromium-browser", "--headless", "--disable-gpu", "--no-sandbox", "--dump-dom", "https://example.com"]

The exact package names can differ between Ubuntu releases, but the structure is the same: install Chromium and the libraries it links against, then run it with headless-friendly flags.

Important Runtime Flags

The most common Chromium flags in containers are:

• '--headless'
• '--no-sandbox'
• '--disable-dev-shm-usage'
• '--remote-debugging-port=9222'

--disable-dev-shm-usage matters because Docker often provides a small shared-memory mount at /dev/shm. Without that flag, Chromium may crash in pages that use more shared memory than the container default allows.

--no-sandbox is common in containers, but it reduces isolation. If you can run Chromium in an environment that supports the sandbox safely, that is preferable. In many CI containers, though, the flag is used pragmatically to avoid permission and namespace issues.

Automating Chromium with Python

For automation, Playwright, Puppeteer, or Selenium can drive the browser. A minimal Selenium example looks like this:

1from selenium import webdriver
2from selenium.webdriver.chrome.options import Options
3
4options = Options()
5options.binary_location = "/usr/bin/chromium-browser"
6options.add_argument("--headless=new")
7options.add_argument("--no-sandbox")
8options.add_argument("--disable-dev-shm-usage")
9
10driver = webdriver.Chrome(options=options)
11driver.get("https://example.com")
12print(driver.title)
13driver.quit()

The browser path may vary by image. Verify it with which chromium-browser or which chromium.

Debugging in a Container

If Chromium fails to start, the root cause is often not "headless mode" itself. Common issues are:

• missing shared libraries
• wrong browser binary path
• not enough memory
• a driver/browser mismatch

A useful debugging step is to run the browser command directly inside the container:

docker run --rm my-chromium-image \
  chromium-browser --headless --no-sandbox --disable-dev-shm-usage --dump-dom https://example.com

If this fails, fix the browser image before debugging Selenium or application code.

Container Design Choices

For production-grade browser workloads, you have two broad options:

1. build your own Ubuntu image with Chromium
2. use a maintained browser automation image

A custom image gives you control and a smaller surface area. A maintained image can save time because it already packages the browser, driver, fonts, and dependencies together. The right choice depends on whether stability or customization is more important for your team.

Common Pitfalls

The biggest mistake is installing Chromium without the native libraries it needs. The browser then exits immediately with an unhelpful error.

Another common issue is forgetting --disable-dev-shm-usage in constrained containers. Chromium may appear flaky or crash on complex pages because /dev/shm is too small.

People also assume that --headless means "no graphics dependencies at all." Chromium still needs a substantial set of system libraries even when it never opens a visible window.

Finally, mixing a manually installed browser with a mismatched driver can cause session startup failures. Keep the browser and automation layer compatible.

Summary

• Headless Chromium in Docker requires both the browser package and its native dependencies.
• Use container-friendly flags such as --headless and often --disable-dev-shm-usage.
• Debug the raw browser command inside the container before blaming Selenium or test code.
• Browser path and dependency issues are more common than application bugs.
• Choose between a custom Ubuntu image and a maintained automation image based on your operational needs.