Chromium/Chrome fails to start inside Docker container (FailedToStartBrowser)

[pedrohcleal]

Description of the Issue

I am attempting to run pydoll inside a Docker container, but the embedded browser (Chrome/Chromium) never starts. I consistently receive the following error:

Browser failed to start within timeout
pydoll.exceptions.FailedToStartBrowser: Failed to start the browser

This happens even after installing Chrome Stable, Chromium, Firefox ESR, xvfb, and all required browser dependencies.

---

Full Error Logs

Error 1

Browser failed to start within timeout
Traceback (most recent call last):
  File "/app/test_pydoll.py", line 35, in <module>
    asyncio.run(silent_download_automation())
  ...
  File "/usr/local/lib/python3.12/site-packages/pydoll/browser/chromium/base.py", line 759, in _verify_browser_running
    raise FailedToStartBrowser()
pydoll.exceptions.FailedToStartBrowser: Failed to start the browser

Error 2 (minimal example)

Browser failed to start within timeout
...
raise FailedToStartBrowser()

---

Minimal Reproducible Code

import asyncio
from pydoll.browser.chromium import Chrome

async def main():
    async with Chrome() as browser:
        tab = await browser.start()
        await tab.go_to("https://github.com/autoscrape-labs/pydoll")

        star_button = await tab.find(
            tag_name="button",
            timeout=5,
            raise_exc=False
        )
        if not star_button:
            print("Button not found.")
            return

        await star_button.click()
        await asyncio.sleep(3)

asyncio.run(main())

---

Dockerfile Used

FROM python:3.12-bookworm

WORKDIR /app

COPY . .

RUN apt-get update \
    && apt-get install -y \
        git-all iproute2 build-essential zlib1g-dev \
        libncurses5-dev libgdbm-dev libnss3-dev libssl-dev \
        libreadline-dev libffi-dev libsqlite3-dev wget libbz2-dev \
        libfontconfig1 libdbus-glib-1-2 libx11-xcb1 \
        xvfb firefox-esr \
    && apt-get autoremove -yqq --purge \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Google Chrome Stable
RUN wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb http://dl.google.com/linux/chrome/deb/ stable main" \
        > /etc/apt/sources.list.d/google-chrome.list

RUN apt-get update && apt-get install -y google-chrome-stable --no-install-recommends
RUN apt-get update && apt-get install -y chromium --no-install-recommends

RUN pip install --upgrade pip \
    && pip install -r requirements.txt \
    && pip install torch==2.3.0+cpu torchvision==0.18.0+cpu --extra-index-url https://download.pytorch.org/whl/cpu \
    && pip install docling==2.43.0

# Playwright (for comparison/testing)
RUN playwright install chromium \
    && playwright install-deps chromium

---

Expected Behavior

Chromium/Chrome should start normally inside the container and allow browser.start() to connect to the WebSocket endpoint.

---

Observed Behavior

The browser process attempts to start but apparently crashes or exits before pydoll can connect. pydoll eventually raises:

FailedToStartBrowser: Browser failed to start within timeout

This occurs even with:

• google-chrome-stable installed
• chromium installed
• Firefox ESR installed
• xvfb installed
• All necessary Chrome libraries present
• Debian Bookworm base image
• Python 3.12

---

Additional Notes

• The same code works perfectly on the host machine (Linux).

• Inside the container, the error occurs consistently.

• I have tried:

  • /usr/bin/chromium
  • /usr/bin/google-chrome
  • /usr/bin/google-chrome-stable
  • Running with xvfb-run

• It appears the browser starts, then immediately exits before WebSocket initialization.

---

Possible Causes (Hypotheses)

1. pydoll may need extra browser flags such as:

   • --no-sandbox
   • --disable-dev-shm-usage

2. /dev/shm inside the container may be too small (common issue with Chrome).

3. pydoll might rely on an environment variable or system library not available inside Docker.

4. The Chrome process might be crashing silently before WS endpoint is created.

---

Questions for the Maintainers

• Is Docker officially supported by pydoll?
• Is there a recommended configuration for running Chromium/Chrome in containers?
• Is there a way to override or add additional launch flags when starting the browser?
• Does pydoll require any specific system libraries that are not listed in the docs?

---

[pedrohcleal]

❓ Does anyone have a working Dockerfile?

I'm running into the exact same issue when trying to use Pydoll inside a Docker container.
Chrome installs correctly, Python installs correctly, but the browser never starts.

---

Dockerfile I'm using

FROM ubuntu:latest

ENV DEBIAN_FRONTEND=noninteractive

# install python
RUN apt-get update && apt-get install -y \
    python3 python3-pip python3-venv wget pipx

# create virtual env
RUN python3 -m venv /venv
ENV PATH="/venv/bin:$PATH"

# install chrome
RUN wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \
    apt-get install -y ./google-chrome-stable_current_amd64.deb || true && \
    apt --fix-broken install -y && \
    rm google-chrome-stable_current_amd64.deb

WORKDIR /app

RUN pip install --upgrade pip wheel
RUN pip install pydoll-python

COPY . /app/

ENV PYTHONPATH=/app

---

Test code

import asyncio
from pydoll.browser.chromium import Chrome

async def main():
    print("Starting browser...")
    async with Chrome() as browser:
        tab = await browser.start(headless=True)
        print("Browser started. Navigating to GitHub...")
        await tab.go_to('https://github.com/autoscrape-labs/pydoll')

        star_button = await tab.find(
            tag_name='button',
            timeout=5,
            raise_exc=False
        )
        if not star_button:
            print("Button not found.")
            return

        await star_button.click()
        print("Button clicked successfully!")
        await asyncio.sleep(3)

asyncio.run(main())

---

Error

Starting browser...
DeprecationWarning: The 'headless' parameter is deprecated [...]
Browser failed to start within timeout
pydoll.exceptions.FailedToStartBrowser: Failed to start the browser

---

❗ Summary

Everything installs fine, but Pydoll is unable to start Chrome inside Docker.
Has anyone managed to get this working? A functional Dockerfile or any guidance would be greatly appreciated.

[pedrohcleal]

Resolvi adicionando essas parametros na config do browser:

options.add_argument('--no-sandbox')
options.add_argument('--disable-gpu')
options.add_argument('--disable-dev-shm-usage')
options.add_argument('--no-zygote')
options.add_argument('--disable-setuid-sandbox')