unclecode/crawl4ai · error · RuntimeError

psutil not available, cannot clean old browser

Error message

psutil not available, cannot clean old browser

What it means

On Windows only, BrowserManager kills stale Chromium processes that hold the same --remote-debugging-port/--user-data-dir before launching a new browser. That cleanup requires psutil; if psutil was not installed (it is an optional dependency), it raises this RuntimeError instead of proceeding.

Source

Thrown at crawl4ai/browser_manager.py:204

        # Create temp dir if needed
        if not self.user_data_dir:
            self.temp_dir = tempfile.mkdtemp(prefix="browser-profile-")
            self.user_data_dir = self.temp_dir

        # Get browser path and args based on OS and browser type
        # browser_path = self._get_browser_path()
        args = await self._get_browser_args()
        
        if self.browser_config.extra_args:
            args.extend(self.browser_config.extra_args)
            

        # ── make sure no old Chromium instance is owning the same port/profile ──
        try:
            if sys.platform == "win32":
                if psutil is None:
                    raise RuntimeError("psutil not available, cannot clean old browser")
                for p in psutil.process_iter(["pid", "name", "cmdline"]):
                    cl = " ".join(p.info.get("cmdline") or [])
                    if (
                        f"--remote-debugging-port={self.debugging_port}" in cl
                        and f"--user-data-dir={self.user_data_dir}" in cl
                    ):
                        p.kill()
                        p.wait(timeout=5)
            else:  # macOS / Linux
                # kill any process listening on the same debugging port
                try:
                    pids = (
                        subprocess.check_output(
                            shlex.split(f"lsof -t -i:{self.debugging_port}"),
                            stderr=subprocess.DEVNULL,
                        )
                        .decode()
                        .strip()

View on GitHub (pinned to 7e80152142)

Solutions

1. pip install psutil (or reinstall crawl4ai with the recommended extras).
2. Alternatively change browser_config so no stale-process cleanup is needed: use a different debugging_port and/or a fresh user_data_dir per run.
3. Kill the leftover Chrome/Chromium process manually (taskkill) that owns the port/profile, though the error will persist until psutil is installed.

Example fix

# before (env lacking psutil)
# RuntimeError: psutil not available, cannot clean old browser

# after
# pip install psutil
browser_config = BrowserConfig(use_managed_browser=True, debugging_port=9222)

import sys
if sys.platform == 'win32':
    try:
        import psutil  # noqa: F401
    except ImportError:
        raise SystemExit('pip install psutil before using managed browser on Windows')

try:
    async with AsyncWebCrawler(config=browser_config) as c:
        ...
except Exception as e:
    if 'psutil not available' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'psutil'])
        raise SystemExit('psutil installed; rerun the program')
    raise

When it happens

Trigger: Windows + browser_config.use_managed_browser (or a fixed debugging_port) + psutil missing from the environment. The check is explicit: sys.platform == 'win32' and psutil is None.

Common situations: Installing crawl4ai without extras on Windows; slim Docker/CI images based on windows containers lacking psutil; uninstalling psutil after install; using headless=False with a persistent user-data-dir on Windows.

Related errors

• C4A script compiler not available. Please ensure crawl4ai.sc
• Failed to start browser: {e}
• Browser type {self.browser_type} not supported
• CDP endpoint at {cdp_url} is not ready after startup
• Cannot create new browser contexts when using use_persistent

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