Browser Settings - Browser Use

The Browser class (alias for BrowserSession) configures how the browser launches and operates.

The Browser instance also provides all Actor methods for direct browser control.

Core Settings

cdp_url

string

Chrome DevTools Protocol URL for connecting to an existing browser instance.Example: "http://localhost:9222"Use this to connect to remote browsers or existing browser sessions.

Display & Appearance

headless

bool | None

default:"None"

Run browser without visible UI.

True - Headless mode (no window)
False - Headed mode (show browser window)
None - Auto-detect based on display availability

window_size

dict | ViewportSize

Browser window size for headed mode.Example: {'width': 1920, 'height': 1080}

window_position

dict

default:"{'width': 0, 'height': 0}"

Window position from top-left corner in pixels.Example: {'width': 100, 'height': 50}

viewport

dict | ViewportSize

Content area size (rendering area inside the window).Example: {'width': 1280, 'height': 720}Same format as window_size.

no_viewport

bool | None

default:"None"

Disable viewport emulation - content fits to window size.

device_scale_factor

float

Device scale factor (DPI multiplier).Set to 2.0 or 3.0 for high-resolution screenshots.

Browser Behavior

keep_alive

bool | None

default:"None"

Keep browser running after agent completes.Useful for debugging or manual inspection.

allowed_domains

list[string]

Restrict navigation to specific domains.Pattern formats:

'example.com' - Matches only https://example.com/*
'*.example.com' - Matches https://example.com/* and subdomains
'http*://example.com' - Matches both http and https
'chrome-extension://*' - Matches Chrome extension URLs

Security: Wildcards in TLD (e.g., example.*) are not allowedPerformance: Lists with 100+ domains are automatically optimized for O(1) lookupExample: ['*.google.com', 'https://example.com', 'chrome-extension://*']

prohibited_domains

list[string]

Block navigation to specific domains. Uses same pattern formats as allowed_domains.When both allowed_domains and prohibited_domains are set, allowed_domains takes precedence.Example: ['pornhub.com', '*.gambling-site.net']

enable_default_extensions

bool

default:"True"

Load automation extensions:

uBlock Origin (ad blocker)
Cookie handlers
ClearURLs (tracker removal)

cross_origin_iframes

bool

default:"False"

Enable cross-origin iframe support.Note: May increase complexity

is_local

bool

default:"True"

Whether this is a local browser instance.Set to False for remote browsers. Automatically set to True if executable_path is provided.This affects download behavior and file handling.

User Data & Profiles

user_data_dir

string | Path

default:"auto-generated temp"

Directory for browser profile data (cookies, history, extensions).Use None for incognito mode (no persistent data).

profile_directory

string

default:"Default"

Chrome profile subdirectory name.Examples: 'Profile 1', 'Work Profile'

storage_state

string | dict

Browser storage state (cookies, localStorage).Can be a file path (string) or a dict object.

Network & Security

proxy

ProxySettings

Proxy configuration.Example:

from browser_use.browser import ProxySettings

proxy = ProxySettings(
    server='http://proxy.example.com:8080',
    bypass='localhost,127.0.0.1',
    username='user',
    password='pass'
)

permissions

list[string]

default:"['clipboardReadWrite', 'notifications']"

Browser permissions to grant automatically.Example: ['camera', 'microphone', 'geolocation']

headers

dict

Additional HTTP headers for connect requests.Remote browsers only

Browser Launch

executable_path

string

Path to browser executable for custom installations.Platform examples:

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

channel

string

Browser channel to use.Options: 'chromium', 'chrome', 'chrome-beta', 'msedge'

args

list[string]

Additional command-line arguments for the browser.Example: ['--disable-gpu', '--custom-flag=value', '--another-flag']

env

dict

Environment variables for browser process.Example: {'DISPLAY': ':0', 'LANG': 'en_US.UTF-8', 'CUSTOM_VAR': 'test'}

chromium_sandbox

bool

default:"True (except Docker)"

Enable Chromium sandboxing for security.Automatically disabled in Docker environments.

devtools

bool

default:"False"

Open DevTools panel automatically.Requires: headless=False

ignore_default_args

list[string] | bool

List of default args to disable, or True to disable all.Example: ['--enable-automation', '--disable-extensions']

Timing & Performance

minimum_wait_page_load_time

float

default:"0.25"

Minimum time to wait before capturing page state (seconds).

wait_for_network_idle_page_load_time

float

default:"0.5"

Time to wait for network activity to cease (seconds).

wait_between_actions

float

default:"0.5"

Time to wait between agent actions (seconds).

AI Integration

highlight_elements

bool

default:"True"

Highlight interactive elements for AI vision.Adds visual markers to clickable elements in screenshots.

paint_order_filtering

bool

default:"True"

Enable paint order filtering to optimize DOM tree.Removes elements hidden behind others. Slightly experimental.

Downloads & Files

accept_downloads

bool

default:"True"

Automatically accept all downloads.

downloads_path

string | Path

Directory for downloaded files.Example: './downloads'

auto_download_pdfs

bool

default:"True"

Automatically download PDFs instead of viewing in browser.

Device Emulation

user_agent

string

Custom user agent string.Example: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)'

screen

dict | ViewportSize

Screen size information. Same format as window_size.

Recording & Debugging

Video recording requires optional dependencies:

pip install "browser-use[video]"

Or:

pip install imageio[ffmpeg] numpy

record_video_dir

string | Path

Directory to save video recordings as .mp4 files.

record_video_size

ViewportSize

default:"viewport size"

Frame size (width, height) for video recording.

record_video_framerate

int

default:"30"

Framerate for video recording.

record_har_path

string | Path

Path to save network trace files as .har format.

traces_dir

string | Path

Directory to save complete trace files for debugging.

record_har_content

'omit' | 'embed' | 'attach'

default:"embed"

HAR content mode.

record_har_mode

'full' | 'minimal'

default:"full"

HAR recording mode.

Advanced Options

disable_security

bool

default:"False"

⚠️ NOT RECOMMENDED - Disables all browser security features.Only use for testing in controlled environments.

deterministic_rendering

bool

default:"False"

⚠️ NOT RECOMMENDED - Forces consistent rendering but reduces performance.

Example

from browser_use import Agent, Browser, ChatBrowserUse

browser = Browser(
    headless=False,
    window_size={'width': 1920, 'height': 1080'},
    allowed_domains=['*.example.com', '*.google.com'],
    highlight_elements=True,
    record_video_dir='./recordings',
)

agent = Agent(
    task="Search and extract data",
    llm=ChatBrowserUse(),
    browser=browser
)

await agent.run()

Agent Settings - Configure agent behavior
Sandbox Settings - Configure cloud execution

​Core Settings

​cdp_url

​Display & Appearance

​headless

​window_size

​window_position

​viewport

​no_viewport

​device_scale_factor

​Browser Behavior

​keep_alive

​allowed_domains

​prohibited_domains

​enable_default_extensions

​cross_origin_iframes

​is_local

​User Data & Profiles

​user_data_dir

​profile_directory

​storage_state

​Network & Security

​proxy

​permissions

​headers

​Browser Launch

​executable_path

​channel

​args

​env

​chromium_sandbox

​devtools

​ignore_default_args

​Timing & Performance

​minimum_wait_page_load_time

​wait_for_network_idle_page_load_time

​wait_between_actions

​AI Integration

​highlight_elements

​paint_order_filtering

​Downloads & Files

​accept_downloads

​downloads_path

​auto_download_pdfs

​Device Emulation

​user_agent

​screen

​Recording & Debugging

​record_video_dir

​record_video_size

​record_video_framerate

​record_har_path

​traces_dir

​record_har_content

​record_har_mode

​Advanced Options

​disable_security

​deterministic_rendering

​Example

​Related Configuration

Core Settings

cdp_url

Display & Appearance

headless

window_size

window_position

viewport

no_viewport

device_scale_factor

Browser Behavior

keep_alive

allowed_domains

prohibited_domains

enable_default_extensions

cross_origin_iframes

is_local

User Data & Profiles

user_data_dir

profile_directory

storage_state

Network & Security

proxy

permissions

headers

Browser Launch

executable_path

channel

args

env

chromium_sandbox

devtools

ignore_default_args

Timing & Performance

minimum_wait_page_load_time

wait_for_network_idle_page_load_time

wait_between_actions

AI Integration

highlight_elements

paint_order_filtering

Downloads & Files

accept_downloads

downloads_path

auto_download_pdfs

Device Emulation

user_agent

screen

Recording & Debugging

record_video_dir

record_video_size

record_video_framerate

record_har_path

traces_dir

record_har_content

record_har_mode

Advanced Options

disable_security

deterministic_rendering

Example

Related Configuration