Browser - Browser Use

The Browser class (alias for BrowserSession) manages browser lifecycle, configuration, and provides methods for direct browser control.

Browser is the recommended name. BrowserSession is the internal class name but both refer to the same class.

Constructor

from browser_use import Browser

browser = Browser(
    headless=False,
    window_size={'width': 1920, 'height': 1080},
)

Core Settings

str

Unique identifier for this browser session. Auto-generated if not provided.

cdp_url

str | None

CDP URL for connecting to existing browser instance (e.g., "http://localhost:9222").

browser_profile

BrowserProfile | None

Browser profile configuration. If not provided, direct parameters are used to create one.

is_local

bool

default:"True"

Whether this is a local browser instance. Set to False for remote browsers. Auto-detected from executable_path or cdp_url.

Display & Appearance

headless

bool | None

Run browser without UI. Auto-detects based on display availability. True = no UI, False = show window, None = auto-detect.

window_size

dict | ViewportSize

Browser window size for headful mode. Format: {'width': 1920, 'height': 1080}

window_position

dict

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

Window position from top-left corner in pixels.

viewport

dict | ViewportSize

Content area size. Format: {'width': 1280, 'height': 720}

no_viewport

bool | None

Disable viewport emulation, content fits to window size.

device_scale_factor

float

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

Browser Behavior

keep_alive

bool | None

Keep browser running after agent completes.

allowed_domains

list[str]

Restrict navigation to specific domains. Domain patterns:

'example.com' - Matches only https://example.com/*
'*.example.com' - Matches example.com and all subdomains
'http*://example.com' - Matches both HTTP and HTTPS
'chrome-extension://*' - Matches Chrome extensions

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

prohibited_domains

list[str]

Block navigation to specific domains. Uses same pattern format as allowed_domains. When both are set, allowed_domains takes precedence.

enable_default_extensions

bool

default:"True"

Load automation extensions (uBlock Origin, cookie handlers, ClearURLs).

cross_origin_iframes

bool

default:"False"

Enable cross-origin iframe support (may increase complexity).

User Data & Profiles

user_data_dir

str | Path | None

Directory for browser profile data. Use None for incognito mode. Auto-generated temp directory by default.

profile_directory

str

default:"'Default'"

Chrome profile subdirectory name (e.g., 'Profile 1', 'Work Profile').

storage_state

str | Path | dict[str, Any] | None

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

Network & Security

proxy

ProxySettings

Proxy configuration. Format: ProxySettings(server='http://host:8080', bypass='localhost', username='user', password='pass')

permissions

list[str]

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

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

headers

dict[str, str]

Additional HTTP headers for connect requests (remote browsers only).

Browser Launch

executable_path

str | Path

Path to browser executable. 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

str

Browser channel: 'chromium', 'chrome', 'chrome-beta', 'msedge', etc.

args

list[str]

Additional command-line arguments. Format: ['--disable-gpu', '--custom-flag=value']

env

dict[str, str | float | bool]

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

chromium_sandbox

bool

default:"True"

Enable Chromium sandboxing for security. Defaults to False in Docker.

devtools

bool

default:"False"

Open DevTools panel automatically (requires headless=False).

ignore_default_args

list[str] | Literal[True]

List of default args to disable, or True to disable all. Format: ['--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.

dom_highlight_elements

bool

default:"True"

Alternative name for highlight_elements.

paint_order_filtering

bool

default:"True"

Optimize DOM tree by removing elements hidden behind others. Slightly experimental.

filter_highlight_ids

bool

Filter highlight IDs from DOM output.

Downloads & Files

accept_downloads

bool

default:"True"

Automatically accept all downloads.

downloads_path

str | Path

Directory for downloaded files. Format: './downloads' or Path object.

auto_download_pdfs

bool

default:"True"

Automatically download PDFs instead of viewing in browser.

Device Emulation

user_agent

str

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

screen

dict

Screen size information. Same format as window_size.

Recording & Debugging

record_video_dir

str | Path

Directory to save video recordings as .mp4 files.

record_video_size

dict | ViewportSize

Frame size (width, height) of video recording.

record_video_framerate

int

default:"30"

Framerate for video recording.

record_har_path

str | Path

Path to save network trace files as .har format.

traces_dir

str | Path

Directory to save complete trace files for debugging.

record_har_content

str

default:"'embed'"

HAR content mode: 'omit', 'embed', or 'attach'.

record_har_mode

str

default:"'full'"

HAR recording mode: 'full' or 'minimal'.

Cloud Browser

use_cloud

bool

Use Browser Use cloud browser service. Requires BROWSER_USE_API_KEY environment variable.

cloud_browser

bool

Deprecated: Use use_cloud instead. Alias for backward compatibility.

cloud_browser_params

CloudBrowserParams

Cloud browser configuration parameters.

cloud_profile_id

UUID | str

UUID of cloud browser profile.

cloud_proxy_country_code

ProxyCountryCode

Country code for cloud proxy: 'us', 'uk', 'fr', 'it', 'jp', 'au', 'de', 'fi', 'ca', 'in'

cloud_timeout

int

Session timeout in minutes (free: max 15 min, paid: max 240 min).

DOM Configuration

max_iframes

int

Maximum number of iframes to process.

max_iframe_depth

int

Maximum iframe nesting depth.

Domains to whitelist for cookie handling.

Advanced Options

disable_security

bool

default:"False"

⚠️ NOT RECOMMENDED - Disables all browser security features.

deterministic_rendering

bool

default:"False"

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

demo_mode

bool

Enable demo mode with browser overlay UI.

Methods

start()

Start the browser session.

await browser.start()

stop()

Stop the browser session without killing the process.

await browser.stop()

kill()

Force-stop the browser and clean up all resources.

await browser.kill()

reset()

Clear all cached CDP sessions.

await browser.reset()

get_browser_state_summary()

Get current browser state including DOM and screenshot.

state = await browser.get_browser_state_summary(
    include_screenshot=True,
    cached=False,
)

include_screenshot

bool

default:"True"

Include screenshot in the state.

cached

bool

default:"False"

Use cached state if available.

include_recent_events

bool

default:"False"

Include recent browser events.

return

BrowserStateSummary

Complete browser state with URL, DOM, tabs, and optional screenshot.

get_current_page()

Get the current page as an Actor Page object.

page = await browser.get_current_page()

return

Page | None

Current page actor, or None if no page is open.

get_pages()

Get all open pages.

pages = await browser.get_pages()

return

list[Page]

List of all open page actors.

new_page()

Create a new page (tab).

page = await browser.new_page(url="https://example.com")

url

str | None

Initial URL to navigate to. Defaults to 'about:blank'.

return

Page

New page actor.

close_page()

Close a page by Page object or target ID.

await browser.close_page(page)

page

Page | str

required

Page object or target ID string.

cookies()

Get all browser cookies.

cookies = await browser.cookies()

return

list[Cookie]

List of browser cookies.

clear_cookies()

Clear all browser cookies.

await browser.clear_cookies()

export_storage_state()

Export browser cookies and storage to storage_state format.

storage = await browser.export_storage_state(
    output_path="./storage_state.json"
)

output_path

str | Path | None

Optional path to save storage_state.json.

return

dict[str, Any]

Storage state dict with cookies in Playwright format.

set_extra_headers()

Set extra HTTP headers for all requests.

await browser.set_extra_headers(
    headers={"Authorization": "Bearer token"},
    target_id=None,
)

headers

dict[str, str]

required

Dictionary of header name -> value pairs.

target_id

str | None

Target to set headers on. Defaults to current focus.

Properties

cdp_client

CDPClient

CDP client for direct CDP communication.

browser_profile

BrowserProfile

Browser profile configuration.

agent_focus_target_id

str | None

Target ID of the currently focused tab.

session_manager

SessionManager

Session manager that owns all targets and sessions.

downloaded_files

list[str]

List of files downloaded during this session.

Example Usage

import asyncio
from browser_use import Browser

async def main():
    # Create browser with custom configuration
    browser = Browser(
        headless=False,
        window_size={'width': 1920, 'height': 1080},
        user_data_dir='./profile',
    )
    
    # Start the browser
    await browser.start()
    
    # Create a new page
    page = await browser.new_page("https://example.com")
    
    # Get browser state
    state = await browser.get_browser_state_summary()
    print(f"Current URL: {state.url}")
    print(f"Page title: {state.title}")
    
    # Clean up
    await browser.stop()

if __name__ == "__main__":
    asyncio.run(main())

Core Classes

LLM Providers

Actions

Configuration

Documentation Index

​Constructor

​Core Settings

​Display & Appearance

​Browser Behavior

​User Data & Profiles

​Network & Security

​Browser Launch

​Timing & Performance

​AI Integration

​Downloads & Files

​Device Emulation

​Recording & Debugging

​Cloud Browser

​DOM Configuration

​Advanced Options

​Methods

​start()

​stop()

​kill()

​reset()

​get_browser_state_summary()

​get_current_page()

​get_pages()

​new_page()

​close_page()

​cookies()

​clear_cookies()

​export_storage_state()

​set_extra_headers()

​Properties

​cdp_client

​browser_profile

​agent_focus_target_id

​session_manager

​downloaded_files

​Example Usage

​See Also

Constructor

Core Settings

Display & Appearance

Browser Behavior

User Data & Profiles

Network & Security

Browser Launch

Timing & Performance

AI Integration

Downloads & Files

Device Emulation

Recording & Debugging

Cloud Browser

DOM Configuration

Advanced Options

Methods

start()

stop()

kill()

reset()

get_browser_state_summary()

get_current_page()

get_pages()

new_page()

close_page()

cookies()

clear_cookies()

export_storage_state()

set_extra_headers()

Properties

cdp_client

browser_profile

agent_focus_target_id

session_manager

downloaded_files

Example Usage

See Also