mirror of
https://github.com/browser-use/browser-use
synced 2026-05-06 17:52:15 +02:00
142 lines
4.7 KiB
Plaintext
142 lines
4.7 KiB
Plaintext
---
|
|
title: "Browser Settings"
|
|
description: "Configure browser behavior and context settings"
|
|
icon: "globe"
|
|
---
|
|
|
|
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.
|
|
|
|
<Note>
|
|
We are currently working on improving how browser contexts are managed. The
|
|
system will soon transition to a "1 agent, 1 browser, 1 context" model for
|
|
better stability and developer experience.
|
|
</Note>
|
|
|
|
# Browser Configuration
|
|
|
|
The `BrowserConfig` class controls the core browser behavior and connection settings.
|
|
|
|
```python
|
|
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](https://github.com/browser-use/browser-use/blob/main/browser_use/browser/browser.py#L154).
|
|
|
|
- **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.
|
|
|
|
<Note>
|
|
For web scraping tasks on sites that restrict automated access, we recommend
|
|
using external browser or proxy providers for better reliability.
|
|
</Note>
|
|
|
|
## 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.
|
|
|
|
```python
|
|
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).
|
|
|
|
<Note>
|
|
This overrides local browser settings and uses the provider's configuration.
|
|
Refer to their documentation for settings.
|
|
</Note>
|
|
|
|
### 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`.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
<Note>This will overwrite other browser settings.</Note>
|
|
|
|
# Context Configuration
|
|
|
|
The `BrowserContextConfig` class controls settings for individual browser contexts.
|
|
|
|
```python
|
|
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`.
|