unclecode/crawl4ai · error · RuntimeError

This function must be run in Google Colab environment.

Error message

This function must be run in Google Colab environment.

What it means

start_colab_display_server (crawl4ai/utils.py:3240) raises RuntimeError when `import google.colab` fails, i.e. the function — which starts an Xvfb virtual display plus fluxbox inside a Colab VM so headless-browser previews can render — is executed outside Google Colab. The check is purely import-based: any normal Linux/macOS/Windows Python process lacks the google.colab module and gets this error.

Source

Thrown at crawl4ai/utils.py:3240

            
        return result
    
    except Exception as e:
        # Fallback for parsing errors
        return html_content[:max_size] if len(html_content) > max_size else html_content    

def start_colab_display_server():
    """
    Start virtual display server in Google Colab.
    Raises error if not running in Colab environment.
    """
    # Check if running in Google Colab
    try:
        import google.colab
        from google.colab import output
        from IPython.display import IFrame, display
    except ImportError:
        raise RuntimeError("This function must be run in Google Colab environment.")
    
    import os, time, subprocess
    
    os.environ["DISPLAY"] = ":99"
    
    # Xvfb
    xvfb = subprocess.Popen(["Xvfb", ":99", "-screen", "0", "1280x720x24"])
    time.sleep(2)
    
    # minimal window manager
    fluxbox = subprocess.Popen(["fluxbox"])
    
    # VNC → X
    x11vnc = subprocess.Popen(["x11vnc",
                              "-display", ":99",
                              "-nopw", "-forever", "-shared",
                              "-rfbport", "5900", "-quiet"])

View on GitHub (pinned to 7e80152142)

Solutions

  1. Run the notebook inside Google Colab if you need this helper.
  2. Outside Colab, skip the helper and use the standard headless crawl (AsyncWebcrawler with default BrowserConfig) — no virtual display is required.
  3. For a local interactive preview, start Xvfb/fluxbox yourself (or run in a desktop environment) and set DISPLAY manually.
  4. pip install google-colab only if you truly replicate the Colab environment (rarely worth it).

Example fix

# before
from crawl4ai.utils import start_colab_display_server
start_colab_display_server()  # RuntimeError locally

# after
import sys
if "google.colab" in sys.modules:
    from crawl4ai.utils import start_colab_display_server
    start_colab_display_server()
else:
    async with AsyncWebcrawler() as crawler:
        result = await crawler.arun("https://example.com")
Defensive patterns

Strategy: validation

Validate before calling

import sys

def in_colab() -> bool:
    return "google.colab" in sys.modules or _colab_importable()

def _colab_importable() -> bool:
    try:
        import google.colab  # noqa
        return True
    except ImportError:
        return False

# if not in_colab(): skip start_colab_display_server()

Try / catch

try:
    start_colab_display_server()
except RuntimeError as e:
    if "Colab" in str(e):
        logger.info("Skipping display server outside Colab")
    else:
        raise

Prevention

When it happens

Trigger: Calling crawl4ai's Colab display-server helper (used to embed interactive browser output in a Colab notebook) from a local Jupyter notebook, a script, or CI; calling it in Colab after google-colab package was uninstalled or in a kernel where the package is not on sys.path.

Common situations: Copying a Colab tutorial notebook and running it locally; trying to get a live preview of the browser during crawling outside Colab; environment where 'google-colab' pip package is absent.

Related errors

AI-assisted analysis of unclecode/crawl4ai@7e80152142 (2026-08-14). Data as JSON: /api/errors/c2ee4f4a2e16a34a. Report an issue: GitHub.