Browser Settings

Configuration options for controlling browser behavior and appearance

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

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

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

window_size · dict | ViewportSize

Browser window size for headed mode.

Example: {'width': 1920, 'height': 1080}

window_position

window_position · dict · default: "{'width': 0, 'height': 0}"

Window position from top-left corner in pixels.

Example: {'width': 100, 'height': 50}

viewport

viewport · dict | ViewportSize

Content area size (rendering area inside the window).

Example: {'width': 1280, 'height': 720}

Same format as window_size.

no_viewport

no_viewport · bool | None · default: "None"

Disable viewport emulation - content fits to window size.

device_scale_factor

device_scale_factor · float

Device scale factor (DPI multiplier).

Set to 2.0 or 3.0 for high-resolution screenshots.

---

Browser Behavior

keep_alive

keep_alive · bool | None · default: "None"

Keep browser running after agent completes.

Useful for debugging or manual inspection.

allowed_domains

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 allowed

Performance: Lists with 100+ domains are automatically optimized for O(1) lookup

Example: ['*.google.com', 'https://example.com', 'chrome-extension://*']

prohibited_domains

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

enable_default_extensions · bool · default: "True"

Load automation extensions:

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

cross_origin_iframes

cross_origin_iframes · bool · default: "False"

Enable cross-origin iframe support.

Note: May increase complexity

is_local

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

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

profile_directory · string · default: "Default"

Chrome profile subdirectory name.

Examples: 'Profile 1', 'Work Profile'

storage_state

storage_state · string | dict

Browser storage state (cookies, localStorage).

Can be a file path (string) or a dict object.

---

Network & Security

proxy

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

permissions · list[string] · default: "['clipboardReadWrite', 'notifications']"

Browser permissions to grant automatically.

Example: ['camera', 'microphone', 'geolocation']

headers

headers · dict

Additional HTTP headers for connect requests.

Remote browsers only

---

Browser Launch

executable_path

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

channel · string

Browser channel to use.

Options: 'chromium', 'chrome', 'chrome-beta', 'msedge'

args

args · list[string]

Additional command-line arguments for the browser.

Example: ['--disable-gpu', '--custom-flag=value', '--another-flag']

env

env · dict

Environment variables for browser process.

Example: {'DISPLAY': ':0', 'LANG': 'en_US.UTF-8', 'CUSTOM_VAR': 'test'}

chromium_sandbox

chromium_sandbox · bool · default: "True (except Docker)"

Enable Chromium sandboxing for security.

Automatically disabled in Docker environments.

devtools

devtools · bool · default: "False"

Open DevTools panel automatically.

Requires: headless=False

ignore_default_args

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

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

wait_for_network_idle_page_load_time · float · default: "0.5"

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

wait_between_actions

wait_between_actions · float · default: "0.5"

Time to wait between agent actions (seconds).

---

AI Integration

highlight_elements

highlight_elements · bool · default: "True"

Highlight interactive elements for AI vision.

Adds visual markers to clickable elements in screenshots.

paint_order_filtering

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

accept_downloads · bool · default: "True"

Automatically accept all downloads.

downloads_path

downloads_path · string | Path

Directory for downloaded files.

Example: './downloads'

auto_download_pdfs

auto_download_pdfs · bool · default: "True"

Automatically download PDFs instead of viewing in browser.

---

Device Emulation

user_agent

user_agent · string

Custom user agent string.

Example: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)'

screen

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

record_video_dir · string | Path

Directory to save video recordings as .mp4 files.

record_video_size

record_video_size · ViewportSize · default: "viewport size"

Frame size (width, height) for video recording.

record_video_framerate

record_video_framerate · int · default: "30"

Framerate for video recording.

record_har_path

record_har_path · string | Path

Path to save network trace files as .har format.

traces_dir

traces_dir · string | Path

Directory to save complete trace files for debugging.

record_har_content

record_har_content · 'omit' | 'embed' | 'attach' · default: "embed"

HAR content mode.

record_har_mode

record_har_mode · 'full' | 'minimal' · default: "full"

HAR recording mode.

---

Advanced Options

disable_security

disable_security · bool · default: "False"

⚠️ NOT RECOMMENDED - Disables all browser security features.

Only use for testing in controlled environments.

deterministic_rendering

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()

---

Related Configuration

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