Browser Use allows you to customize how the browser behaves through two main configuration classes: BrowserConfig and BrowserContextConfig. These settings control everything from headless mode to proxy settings and page load behavior.

​

Browser Configuration

The BrowserConfig class controls the core browser behavior and connection settings.

from browser_use import BrowserConfig

# Basic configuration
config = BrowserConfig(
    headless=False,
    disable_security=True
)

​

Core Settings

• headless (default: False)
  Runs the browser without a visible UI. Note that some websites may detect headless mode.

• disable_security (default: True)
  Disables browser security features. While this can fix certain functionality issues (like cross-site iFrames), it should be used cautiously, especially when visiting untrusted websites.

​

Additional Settings

• extra_chromium_args (default: [])
  Additional arguments passed to the browser at launch. See the full list of available arguments.

• proxy (default: None)
  Standard Playwright proxy settings for using external proxy services.

• new_context_config (default: BrowserContextConfig())
  Default settings for new browser contexts. See Context Configuration below.

​

Alternative Initialization

These settings allow you to connect to external browser providers or use a local Chrome instance.

​

External Browser Provider (wss)

Connect to cloud-based browser services for enhanced reliability and proxy capabilities.

config = BrowserConfig(
    wss_url="wss://your-browser-provider.com/ws"
)

• wss_url (default: None)
  WebSocket URL for connecting to external browser providers (e.g., anchorbrowser.com, steel.dev, browserbase.com, browserless.io).

​

External Browser Provider (cdp)

Connect to cloud or local Chrome instances using Chrome DevTools Protocol (CDP) for use with tools like headless-shell or browserless.

config = BrowserConfig(
    cdp_url="http://localhost:9222"
)

• cdp_url (default: None)
  URL for connecting to a Chrome instance via CDP. Commonly used for debugging or connecting to locally running Chrome instances.

​

Local Chrome Instance (binary)

Connect to your existing Chrome installation to access saved states and cookies.

config = BrowserConfig(
    chrome_instance_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
)

• chrome_instance_path (default: None)
  Path to connect to an existing Chrome installation. Particularly useful for workflows requiring existing login states or browser preferences.

​

Context Configuration

The BrowserContextConfig class controls settings for individual browser contexts.

from browser_use.browser.context import BrowserContextConfig

config = BrowserContextConfig(
    cookies_file="path/to/cookies.json",
    wait_for_network_idle_page_load_time=3.0,
    browser_window_size={'width': 1280, 'height': 1100}
)

​

Configuration Options

​

Page Load Settings

• minimum_wait_page_load_time (default: 0.5)
  Minimum time to wait before capturing page state for LLM input.

• wait_for_network_idle_page_load_time (default: 1.0)
  Time to wait for network activity to cease. Increase to 3-5s for slower websites. This tracks essential content loading, not dynamic elements like videos.

• maximum_wait_page_load_time (default: 5.0)
  Maximum time to wait for page load before proceeding.

​

Display Settings

• browser_window_size (default: {'width': 1280, 'height': 1100})
  Browser window dimensions. The default size is optimized for general use cases and interaction with common UI elements like cookie banners.

​

Debug and Recording

• save_recording_path (default: None)
  Directory path for saving video recordings.

• trace_path (default: None)
  Directory path for saving trace files. Files are automatically named as {trace_path}/{context_id}.zip.