How to Specify CUSTOM_BROWSER_PATH for Chrome or Edge in MediaCrawler CDP Mode

Set the CUSTOM_BROWSER_PATH variable in config/base_config.py to the absolute path of your Chrome or Edge binary when CDP_CONNECT_EXISTING is set to False, allowing MediaCrawler to launch a specific browser version via the Chrome DevTools Protocol.

MediaCrawler supports driving browsers through the Chrome DevTools Protocol (CDP) for enhanced automation capabilities. When operating in CDP mode with a new browser instance, you can override the default system browser by specifying a custom executable path, enabling the use of portable installations, specific versions, or Microsoft Edge instead of Google Chrome.

Understanding CUSTOM_BROWSER_PATH in MediaCrawler

The CUSTOM_BROWSER_PATH configuration option lives in config/base_config.py as an empty string by default. When populated, this variable instructs the CDP browser manager in tools/cdp_browser.py to launch a specific Chromium-based executable rather than searching the system PATH for chrome or msedge.

According to the MediaCrawler source code, the validation logic at lines 202–206 checks for file existence when a custom path is provided:

# From tools/cdp_browser.py (lines 202-206)

if config.CUSTOM_BROWSER_PATH:
    browser_path = Path(config.CUSTOM_BROWSER_PATH)
    if browser_path.exists():
        logger.info(f"Using custom browser path: {browser_path}")
        # Path is passed to the launcher

If the specified file does not exist, the system logs a fallback message at line 214 and proceeds with default detection mechanisms.

Prerequisites for Using a Custom Browser Path

CDP Mode Requirements

The custom browser path applies only when MediaCrawler launches a fresh browser instance. This requires two specific configuration states:

• ENABLE_CDP_MODE must be set to True
• CDP_CONNECT_EXISTING must be set to False

When CDP_CONNECT_EXISTING is True, MediaCrawler attaches to an already-running browser instance via a remote debugging port, bypassing the launcher entirely and ignoring the CUSTOM_BROWSER_PATH setting.

Configuration Steps

Step 1: Locate Your Browser Binary

Identify the absolute path to your Chrome or Edge executable. The docs/CDP模式使用指南.md file (lines 90–105) documents standard installation locations across platforms:

• Windows: r"C:\Program Files\Google\Chrome\Application\chrome.exe"
• macOS: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
• Linux: "/usr/bin/google-chrome"

For Microsoft Edge on Windows, use: r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"

Step 2: Set CUSTOM_BROWSER_PATH in base_config.py

Modify your configuration file to point to the browser binary:

# config/base_config.py or config/local_config.py

CUSTOM_BROWSER_PATH = r"C:\Program Files\Google\Chrome\Application\chrome.exe"  # Windows Chrome

# CUSTOM_BROWSER_PATH = "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"  # macOS Edge

# CUSTOM_BROWSER_PATH = "/usr/bin/chromium-browser"  # Linux Chromium

Step 3: Verify CDP Connection Settings

Ensure MediaCrawler launches a new browser rather than connecting to an existing one:

# CDP configuration

ENABLE_CDP_MODE = True
CDP_CONNECT_EXISTING = False  # Required for custom browser path to take effect

CDP_HEADLESS = False         # Optional: set to True for headless operation

How the Custom Path is Validated

Inside tools/cdp_browser.py, the CDPBrowserManager class processes the configuration during initialization. The launch command construction occurs in tools/browser_launcher.py, where the binary path supplied by config.CUSTOM_BROWSER_PATH replaces the default executable name.

The actual subprocess execution uses the validated path, logged at line 204 of cdp_browser.py as confirmation that the custom binary is selected. This architecture allows MediaCrawler to support portable Chrome installations, development builds, and enterprise-managed browser locations that don't reside in standard system directories.

Platform-Specific Browser Paths

Use the following absolute paths as reference for your CUSTOM_BROWSER_PATH setting:

Platform	Chrome Path	Edge Path
Windows	r"C:\Program Files\Google\Chrome\Application\chrome.exe"	r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
macOS	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"	"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
Linux	"/usr/bin/google-chrome" or "/usr/bin/chromium"	"/usr/bin/microsoft-edge"

Always use raw strings (r"...") on Windows to avoid escape character issues with backslashes.

Common Use Cases

• Portable Chrome: Point to a portable Chrome folder's executable to run isolated browser versions without system installation.
• Microsoft Edge Automation: Edge shares the CDP interface; specify the Edge binary to utilize Microsoft's Chromium implementation with different memory management or enterprise policies.
• Version Testing: Switch between Chrome 113 and Chrome 116 by changing the path, allowing regression testing against specific browser versions without altering system defaults.

Summary

• CUSTOM_BROWSER_PATH in config/base_config.py specifies an absolute path to any Chromium-based browser executable.
• The setting only functions when CDP_CONNECT_EXISTING is False, forcing MediaCrawler to launch a new browser instance via tools/cdp_browser.py.
• Platform-specific paths for Windows, macOS, and Linux are documented in docs/CDP模式使用指南.md.
• The system validates file existence at lines 202–214 of cdp_browser.py, falling back to default detection if the path is invalid.
• This configuration supports portable installations, Microsoft Edge, and non-standard browser locations.

Frequently Asked Questions

Why is CUSTOM_BROWSER_PATH ignored when I connect to an existing browser?

When CDP_CONNECT_EXISTING is set to True, MediaCrawler attaches to a browser already running on a remote debugging port. The executable has already launched, so the custom path setting is bypassed in favor of the existing process. Set CDP_CONNECT_EXISTING = False to force a new browser launch that respects your custom path.

Can I use Microsoft Edge instead of Google Chrome?

Yes. Microsoft Edge is Chromium-based and fully supports the Chrome DevTools Protocol. Set CUSTOM_BROWSER_PATH to your Edge executable (e.g., msedge.exe on Windows or Microsoft Edge on macOS), and MediaCrawler will launch Edge via the same CDP mechanism used for Chrome.

What happens if the specified binary does not exist?

If the path in CUSTOM_BROWSER_PATH points to a non-existent file, tools/cdp_browser.py detects the failure at line 214, logs a warning message, and falls back to automatic browser detection. The crawler attempts to locate a system-installed Chrome or Edge rather than failing entirely.

Does this work with portable or portable Chromium builds?

Absolutely. Portable builds are a primary use case for CUSTOM_BROWSER_PATH. Provide the absolute path to the portable executable (e.g., C:\Tools\ChromePortable\Chrome.exe), and MediaCrawler will launch that specific binary regardless of system PATH settings or registry entries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}