How to Switch Between Chromium, Firefox, and WebKit Browsers in Crawl4AI

Set the browser_type parameter in BrowserConfig to "chromium", "firefox", or "webkit" to instantly switch between Playwright engines without changing your crawling logic.

Crawl4AI provides seamless multi-browser support through a unified configuration interface. Whether you need to test cross-browser compatibility, bypass anti-bot measures, or leverage engine-specific rendering, you can switch between Chromium, Firefox, and WebKit browsers in Crawl4AI using a single configuration field. The library abstracts Playwright's browser management through the BrowserConfig dataclass in crawl4ai/async_configs.py and the BrowserManager orchestrator in crawl4ai/browser_manager.py.

Understanding the Browser Configuration Architecture

The BrowserConfig Dataclass

In crawl4ai/async_configs.py, the BrowserConfig dataclass defines the browser_type field that controls engine selection. According to the source code at lines 62-65, this parameter accepts three string values: "chromium", "firefox", or "webkit". This configuration object centralizes all launch parameters—including headless mode, viewport dimensions, proxy settings, and user-agent strings—ensuring that switching browsers requires modifying only one property.

The BrowserManager Orchestrator

The BrowserManager class in crawl4ai/browser_manager.py handles the actual browser instantiation. When BrowserManager.start() executes, it reads the browser_type value from the provided configuration and calls the corresponding Playwright launch method at lines 710-716. The implementation uses conditional logic to invoke playwright.chromium.launch(), playwright.firefox.launch(), or playwright.webkit.launch() based on your configuration, making the browser selection completely transparent to the crawling logic.

Methods to Switch Browsers in Crawl4AI

Python SDK Configuration

Instantiate BrowserConfig with your desired browser_type and pass it to AsyncWebCrawler. This approach provides programmatic control and allows dynamic browser selection at runtime.

from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig

# Configure Firefox browser

browser_cfg = BrowserConfig(
    browser_type="firefox",   # ← Switch engine here

    headless=False,
    viewport_width=1280,
    viewport_height=800,
)

crawler_cfg = CrawlerRunConfig(url="https://example.com")

async with AsyncWebCrawler(config=browser_cfg) as crawler:
    result = await crawler.arun(config=crawler_cfg)
    print(result.markdown)

To switch to WebKit, simply change the browser_type value:

browser_cfg = BrowserConfig(
    browser_type="webkit",    # ← Use WebKit engine

    headless=True
)

CLI Configuration with YAML Files

Create a configuration file specifying the browser type and load it using the -B (or --browser-config) flag. This method is ideal for reproducible crawls and CI/CD pipelines.

Create browser.yml:

browser_type: firefox       # Options: chromium | firefox | webkit

headless: true
viewport_width: 1080
viewport_height: 720

Execute the crawl:

crwl https://example.com -B browser.yml

CLI Inline Overrides

For rapid testing without creating configuration files, use the -b flag with comma-separated key-value pairs. The CLI parser converts these directly into BrowserConfig parameters.

Switch to WebKit with specific options:

crwl https://example.com -b "browser_type=webkit,headless=false"

Or use Firefox in headless mode:

crwl https://example.com -b "browser_type=firefox,headless=true"

Key Source Files and Implementation Details

The browser switching mechanism relies on these core files:

• crawl4ai/async_configs.py (Line 354+): Defines the BrowserConfig dataclass that stores browser_type and all other launch options. The browser_type field validation appears at lines 62-65.

• crawl4ai/browser_manager.py (Lines 710-716): Contains the BrowserManager.start() method that reads the configuration and launches the appropriate Playwright browser instance.

• crawl4ai/cli.py: Parses the -b/--browser-config arguments and constructs BrowserConfig objects from YAML, JSON, or inline key-value strings.

• crawl4ai/__init__.py: Re-exports BrowserConfig for public API access (from crawl4ai import BrowserConfig).

Because the same BrowserConfig object is used across the Python SDK and CLI interfaces, changing the browser_type parameter affects all subsequent crawls while preserving other settings like proxy configurations and viewport sizes.

Summary

• Single Parameter Control: The browser_type field in BrowserConfig accepts "chromium", "firefox", or "webkit" to select your Playwright engine.

• Universal Application: Browser configuration works identically in both the Python SDK (BrowserConfig instantiation) and the CLI (-b or -B flags).

• Zero Logic Changes: Switching browsers requires no modifications to crawling code; the BrowserManager handles all engine-specific instantiation internally.

• Cross-Platform Support: All three browser engines inherit the same configuration options for headless mode, viewport sizing, and network settings.

Frequently Asked Questions

What values does the browser_type parameter accept?

The browser_type parameter accepts three string values: "chromium", "firefox", and "webkit". These correspond to the three browser engines supported by Playwright. According to the source code in crawl4ai/async_configs.py at lines 62-65, any other value will result in a validation error when the configuration is processed.

Do I need to install separate browsers to use Firefox or WebKit?

Playwright automatically manages browser binaries. When you specify browser_type="firefox" or browser_type="webkit", Playwright downloads and caches the required browser binaries on first use. You do not need to manually install Firefox or WebKit on your system; Crawl4AI handles the dependencies through Playwright's built-in browser management.

Can I switch browsers between different crawls in the same Python script?

Yes. Because BrowserConfig is passed to each AsyncWebCrawler instance, you can create multiple crawler instances with different browser_type values in the same script. Each crawler maintains its own browser context, allowing you to run Chromium, Firefox, and WebKit crawls simultaneously or sequentially without conflicts.

Does changing the browser affect the markdown output format?

No. The markdown extraction and content processing logic remains identical across all browser engines. Changing from Chromium to Firefox or WebKit affects only the rendering engine and JavaScript execution environment. The final markdown structure, link extraction, and metadata parsing remain consistent regardless of which browser type you configure in BrowserConfig.

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