Browser

Browser session management and configuration

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

id · 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.

cookie_whitelist_domains · list[str]

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

cdp_client · CDPClient

CDP client for direct CDP communication.

browser_profile

browser_profile · BrowserProfile

Browser profile configuration.

agent_focus_target_id

agent_focus_target_id · str | None

Target ID of the currently focused tab.

session_manager

session_manager · SessionManager

Session manager that owns all targets and sessions.

downloaded_files

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

See Also

• Browser Basics
• Browser All Parameters
• Real Browser
• Remote Browser