browser-use/docs/customize/browser-settings.mdx

---
title: "Browser Settings"
description: "Launch or connect to an existing browser and configure it to your needs."
icon: "globe"
---

Browser Use uses [playwright](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context) (or [patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)) to manage its connection with a real browser.

---

**To launch or connect to a browser**, pass any playwright / browser-use configuration arguments you want to `BrowserSession(...)`:

```python
from browser_use import BrowserSession, Agent

browser_session = BrowserSession(
    headless=True,
    viewport={'width': 964, 'height': 647},
    user_data_dir='~/.config/browseruse/profiles/default',
)
agent = Agent('fill out the form on this page', browser_session=browser_session)
```

<Note>
  The new `BrowserSession` & `BrowserProfile` accept all the same arguments that Playwright's [`launch_persistent_context(...)`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context) takes, giving you full control over browser settings at launch. (see below for the full list)
</Note>


---

## `BrowserSession`

- `BrowserSession(**params)` is Browser Use's object that tracks a connection to a running browser. It sets up:
  - the `playwright`, `browser`, `browser_context`, and `page` objects and tracks which tabs the agent/human are focused on
  - methods to interact with the browser window, apply config needed by the Agent, and run the `DOMService` for element detection
  - it can take a `browser_profile=BrowserProfile(...)` template containing some config defaults, and `**kwargs` session-specific config overrides

### Browser Connection Parameters

Provide any one of these options to connect to an existing browser. These options are session-specific and cannot be stored in a `BrowserProfile(...)` template.

#### `wss_url`

```python
wss_url: str | None = None
```

WSS URL of the playwright-protocol browser server to connect to. See here for [WSS connection instructions](https://docs.browser-use.com/customize/real-browser#method-d%3A-connect-to-remote-playwright-node-js-browser-server-via-wss-url).

#### `cdp_url`

```python
cdp_url: str | None = None
```

CDP URL of the browser to connect to (e.g. `http://localhost:9222`). See here for [CDP connection instructions](https://docs.browser-use.com/customize/real-browser#method-e%3A-connect-to-remote-browser-via-cdp-url).

#### `browser_pid`

```python
browser_pid: int | None = None
```

PID of a running chromium-based browser process to connect to on localhost. See here for [connection via pid](https://docs.browser-use.com/customize/real-browser#method-c%3A-connect-to-local-browser-using-browser-pid) instructions.

<Note>
  For web scraping tasks on sites that restrict automated access, we recommend
  using [our cloud](https://browser-use.com) or an external browser provider for better reliability. 
  See the [Connect to your Browser](real-browser) guide for detailed connection instructions.
</Note>

### Session-Specific Parameters

#### `browser_profile`

```python
browser_profile: BrowserProfile = BrowserProfile()
```

Optional `BrowserProfile` template containing default config to use for the `BrowserSession`. (see below for more info)

#### `playwright`

```python
playwright: Playwright | None = None
```

Optional playwright or patchright API client handle to use, the result of `(await async_playwright().start())` or `(await async_patchright().start())`, which spawns a node.js child subprocess that relays commands to the browser over CDP.

See here for [more detailed usage instructions](https://docs.browser-use.com/customize/real-browser#method-b%3A-connect-using-existing-playwright-objects).

#### `browser`

```python
browser: Browser | None = None
```

Playwright Browser object to use (optional). See here for [more detailed usage instructions](https://docs.browser-use.com/customize/real-browser#method-b%3A-connect-using-existing-playwright-objects).

#### `browser_context`

```python
browser_context: BrowserContext | None = None
```

Playwright BrowserContext object to use (optional). See here for [more detailed usage instructions](https://docs.browser-use.com/customize/real-browser#method-b%3A-connect-using-existing-playwright-objects).

#### `page` *aka* `agent_current_page`

<a name="page"></a><a name="agent-current-page"></a>

```python
page: Page | None = None
```

Foreground Page that the agent is focused on, can also be passed as `page=...` as a shortcut. See here for [more detailed usage instructions](https://docs.browser-use.com/customize/real-browser#method-b%3A-connect-using-existing-playwright-objects).

#### `human_current_page`

```python
human_current_page: Page | None = None
```

Foreground Page that the human is focused on to start, not necessary to set manually.

#### `initialized`

```python
initialized: bool = False
```

Mark BrowserSession as already initialized, skips launch/connection (not recommended)


#### `**kwargs`

`BrowserSession` can also accept *all* of the parameters [below](#browserprofile).
(the parameters *above* this point are specific to `BrowserSession` and cannot be stored in a `BrowserProfile` template)

Extra `**kwargs` passed to `BrowserSession(...)` act as session-specific overrides to the `BrowserProfile(...)` template.

```python
base_iphone13 = BrowserProfile(
    storage_state='/tmp/auth.json',     # share cookies between parallel browsers
    **playwright.devices['iPhone 13'],
    timezone_id='UTC',
)
usa_phone = BrowserSession(
    browser_profile=base_iphone13,
    timezone_id='America/New_York',     # kwargs override values in base_iphone13
)
eu_phone = BrowserSession(
    browser_profile=base_iphone13,
    timezone_id='Europe/Paris',
)

usa_agent = Agent(task='show me todays schedule...', browser_session=usa_phone)
eu_agent = Agent(task='show me todays schedule...', browser_session=eu_phone)
await asyncio.gather(agent1.run(), agent2.run())
```

---


## `BrowserProfile`

A `BrowserProfile` is a 📋 config template for a 🎭 `BrowserSession(...)`.

It's basically just a typed + validated version of a `dict` to hold config.

When you find yourself storing or re-using many browser configs, you can upgrade from:

```diff
- config = {key: val, key: val, ...}
- BrowserSession(**config)
```
To this instead:
```diff
+ config = BrowserProfile(key=val, key=val, ...)
+ BrowserSession(browser_profile=config)
```

<Tip>
You don't ever *need* to use a `BrowserProfile`, you can always pass config parameters directly to `BrowserSession`:
```python
session = BrowserSession(headless=True, storage_state='auth.json', viewport={...}, ...)
```
</Tip>

`BrowserProfile` is optional, but it provides a number of benefits over a normal `dict` for holding config:

- has type hints and pydantic field descriptions that show up in your IDE
- validates config at runtime quickly without having to start a browser
- provides helper methods to autodetect screen size, set up local paths, save/load config as json, and more...

<Tip>
`BrowserProfiles`s are designed to easily be given 🆔 `uuid`s and put in a database + made editable by users. 
`BrowserSession`s get their own 🆔 `uuid`s and be linked by 🖇 foreign key to whatever `BrowserProfiles` they use.  

This cleanly separates the per-connection rows from the bulky re-usable config and avoids wasting space in your db.
This is useful because a user may only have 2 or 3 profiles, but they could have 100k+ sessions within a few months.
</Tip>


`BrowserProfile` and `BrowserSession` can both take any of the:

- [Playwright parameters](#playwright)
- [Browser-Use parameters](#browser-use-parameters) (extra options we provide on top of `playwright`)

The only parameters `BrowserProfile` can NOT take are the session-specific connection parameters and live playwright objects:  
`cdp_url`, `wss_url`, `browser_pid`, `page`, `browser`, `browser_context`, `playwright`, etc.

### Basic Example

```python
from browser_use.browser import BrowserProfile

profile = BrowserProfile(
    stealth=True,
    storage_state='/tmp/google_docs_cookies.json',
    allowed_domains=['docs.google.com', 'https://accounts.google.com'],
    viewport={'width': 396, 'height': 774},
    # ... playwright args / browser-use config args ...
)

phone1 = BrowserSession(browser_profile=profile, device_scale_factor=1)
phone2 = BrowserSession(browser_profile=profile, device_scale_factor=2)
phone3 = BrowserSession(browser_profile=profile, device_scale_factor=3)
```

### Browser-Use Parameters

These parameters control Browser Use-specific features, and are outside the standard playwright set. They can be passed to `BrowserSession(...)` and/or stored in a `BrowserProfile` template.

#### `keep_alive`

```python
keep_alive: bool | None = None
```

If `True` it wont close the browser after the first `agent.run()` ends. Useful for running multiple tasks with the same browser instance. If this is left as `None` and the Agent launched its own browser, the default is to close the browser after the agent completes. If the agent connected to an existing browser then it will leave it open.

#### `stealth`

```python
stealth: bool = False
```
Set to `True` to use [`patchright`](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) to avoid bot-blocking. (Might cause issues with some sites, requires manual testing.)

<a name="restrict-urls"></a>

#### `allowed_domains`

```python
allowed_domains: list[str] | None = None
```

List of allowed domains for navigation. If None, all domains are allowed.
Example: `['google.com', '*.wikipedia.org']` - Here the agent will only be able to access `google.com` exactly and `wikipedia.org` + `*.wikipedia.org`.
  
Glob patterns are supported:
- `['example.com']` ✅ will match only `https://example.com/*` exactly, subdomains will not be allowed.
  It's always the most secure to list all the domains you want to give the access to explicitly w/ schemes e.g.
  `['https://google.com', 'http*://www.google.com', 'https://myaccount.google.com', 'https://mail.google.com', 'https://docs.google.com']`
- `['*.example.com']` ⚠️ **CAUTION** this will match `https://example.com` and *all* its subdomains.
  Make sure *all* the subdomains are safe for the agent! `abc.example.com`, `def.example.com`, ..., `useruploads.example.com`, `admin.example.com`

#### `disable_security`

```python
disable_security: bool = False
```

<Warning>
⚠️ Setting this to `True` is NOT RECOMMENDED.  
It completely disables all basic browser security features.
</Warning>

This option is for debugging and interacting across cross-origin iFrames when there are no cookies or sensitive data in use.
It's very INSECURE, under no circumstances should you enable this while using real cookies or sensitive data, visiting a single untrusted URL in this mode can immediately compromise all the profile cookies instantly. Consider a less nuclear option like `bypass_csp=True` instead.

#### `deterministic_rendering`

```python
deterministic_rendering: bool = False
```

<Warning>
⚠️ Setting this to `True` is NOT RECOMMENDED.  
It can be glitchy & slow, and it increases chances of getting blocked by anti-bot systems. It's mostly useful for QA applications.
</Warning>



It's a shortcut for adding these launch args:

- `--deterministic-mode`
- `--js-flags=--random-seed=1157259159`
- `--force-color-profile=srgb`
- `--font-render-hinting=none`
- `--force-device-scale-factor=2`
- `--enable-webgl`

With these options fonts will look slightly worse than macOS and slightly than Windows, but rendering will be more consistent between OSs and runs. The cost is performance and stability. Software rendering is slower, easier to fingerprint as a bot, and sometimes glitchy. You likely *don't need this option* unless you're trying to do screenshot diffing.

#### `highlight_elements`

```python
highlight_elements: bool = True
```

Highlight interactive elements on the screen with colorful bounding boxes.

#### `viewport_expansion`

```python
viewport_expansion: int = 500
```

Viewport expansion in pixels. With this you can control how much of the page is included in the context of the LLM:
- `-1`: All elements from the entire page will be included, regardless of visibility (highest token usage but most complete).
- `0`: Only elements which are currently visible in the viewport will be included.
- `500` (default): Elements in the viewport plus an additional 500 pixels in each direction will be included, providing a balance between context and token usage.

#### `include_dynamic_attributes`

```python
include_dynamic_attributes: bool = True
```

Include dynamic attributes in selectors for better element targeting.

#### `minimum_wait_page_load_time`

```python
minimum_wait_page_load_time: float = 0.25
```

Minimum time to wait before capturing page state for LLM input.

#### `wait_for_network_idle_page_load_time`

```python
wait_for_network_idle_page_load_time: float = 0.5
```

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`

```python
maximum_wait_page_load_time: float = 5.0
```

Maximum time to wait for page load before proceeding.

#### `wait_between_actions`

```python
wait_between_actions: float = 0.5
```

Time to wait between agent actions.

#### `cookies_file`

```python
cookies_file: str | None = None
```

JSON file path to save cookies to.

<Warning>
This option is DEPRECATED. Use [`storage_state`](#storage-state) instead, it's the standard playwright format and also supports `localStorage` and `indexedDB`!

The library will automatically save a new `storage_state.json` next to any `cookies_file` path you provide, just use `storage_state='path/to/storage_state.json' to switch to the new format:

`cookies_file.json`: `[{cookie}, {cookie}, {cookie}]`  
⬇️
`storage_state.json`: `{"cookies": [{cookie}, {cookie}, {cookie}], "origins": {... optional localstorage state ...}}`

Or run `playwright open https://example.com/ --save-storage=storage_state.json` and log into any sites you need to generate a fresh storage state file.
</Warning>


#### `profile_directory`

```python
profile_directory: str = 'Default'
```

Chrome profile subdirectory name inside of your `user_data_dir` (e.g. `Default`, `Profile 1`, `Work`, etc.).
No need to set this unless you have multiple profiles set up in a single `user_data_dir` and need to use a specific one.

#### `window_position`

```python
window_position: dict | None = {"width": 0, "height": 0}
```

Window position from top-left corner.

#### `save_recording_path`

```python
save_recording_path: str | None = None
```

Directory path for saving video recordings.

#### `trace_path`

```python
trace_path: str | None = None
```

Directory path for saving Agent trace files. Files are automatically named as `{trace_path}/{context_id}.zip`.


---

<a name="playwright-parameters"></a><a name="playwright"></a>

### Playwright Launch Options


All the parameters below are standard playwright parameters and can be passed to both `BrowserSession` and `BrowserProfile`.
They are defined in `browser_use/browser/profile.py`. See here for the [official Playwright documentation](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context) for all of these options.

#### `headless`

```python
headless: bool | None = None
```

Runs the browser without a visible UI. If None, auto-detects based on display availability. If you set `headless=False` on a server with no monitor attached, the browser will fail to launch (use `xvfb` + vnc to give a headless server a virtual display you can remote control). 

`headless=False` is recommended for maximum stealth and is required for human-in-the-loop workflows.

#### `channel`

```python
channel: BrowserChannel = 'chromium'
```

Browser channel: `['chromium']` (default when `stealth=False`), `'chrome'` (default when `stealth=True`), `'chrome-beta'`, `'chrome-dev'`, `'chrome-canary'`, `'msedge'`, `'msedge-beta'`, `'msedge-dev'`, `'msedge-canary'`

Don't worry, other chromium-based browsers not in this list (e.g. `brave`) are still supported if you provide your own [`executable_path`](#executable_path), just set it to `chromium` for those.

#### `executable_path`

```python
executable_path: str | Path | None = None
```

Path to browser executable for custom installations.

#### `user_data_dir`

```python
user_data_dir: str | Path | None = '~/.config/browseruse/profiles/default'
```

Directory for browser profile data. Set to `None` to use an ephemeral temporary profile (aka incognito mode).

Multiple running browsers **cannot share a single `user_data_dir` at the same time**. You must set it to `None` or
provide a unique `user_data_dir` per-session if you plan to run multiple browsers.

The browser version run must always be equal to or greater than the version used to create the `user_data_dir`.
If you see errors like `Failed to parse Extensions` or similar and failures when launching, you're attempting to run an older browser with an incompatible `user_data_dir` that's already been migrated to a newer schema version.

#### `args`

```python
args: list[str] = []
```
Additional command-line arguments to pass to the browser. See here for the [full list of available chrome launch options](https://peter.sh/experiments/chromium-command-line-switches/).



#### `ignore_default_args`

```python
ignore_default_args: list[str] | bool = ['--enable-automation', '--disable-extensions']
```

List of default CLI args to stop playwright from including when launching chrome. Set it to `True` to disable *all* default options (not recommended).

#### `env`

```python
env: dict[str, str] = {}
```

Extra environment variables to set when launching browser. e.g. `{'DISPLAY': '1'}` to use a specific X11 display.

#### `chromium_sandbox`

```python
chromium_sandbox: bool = not IN_DOCKER
```

Whether to enable Chromium sandboxing (recommended for security). Should always be `False` when running inside Docker
because Docker provides its own sandboxing can conflict with Chrome's.

#### `devtools`

```python
devtools: bool = False
```

Whether to open DevTools panel automatically (only works when `headless=False`).

#### `slow_mo`

```python
slow_mo: float = 0
```

Slow down actions by this many milliseconds.

#### `timeout`

```python
timeout: float = 30000
```

Default timeout in milliseconds for connecting to a remote browser.

#### `accept_downloads`

```python
accept_downloads: bool = True
```

Whether to automatically accept all downloads.

#### `proxy`

```python
proxy: dict | None = None
```

Proxy settings. Example: `{"server": "http://proxy.com:8080", "username": "user", "password": "pass"}`. 

#### `permissions`

```python
permissions: list[str] = ['clipboard-read', 'clipboard-write', 'notifications']
```

Browser permissions to grant. See here for the [full list of available permission](https://playwright.dev/python/docs/api/class-browsercontext#browser-context-grant-permissions).

#### `storage_state`

```python
storage_state: str | Path | dict | None = None
```

Browser storage state (cookies, localStorage). Can be file path or dict. See here for the [Playwright `storage_state` documentation](https://playwright.dev/python/docs/api/class-browsercontext#browser-context-storage-state) on how to use it.
This option is only applied when launching a new browser using the default builtin playwright chromium and `user_data_dir=None` is set.

```bash
# to create a storage state file, run the following and log into the sites you need once the browser opens:
playwright open https://example.com/ --save-storage=./storage_state.json
# then setup a BrowserSession with storage_state='./storage_state.json' and user_data_dir=None to use it
```

### Playwright Timing Settings

These control how the browser waits for CDP API calls to complete and pages to load.

#### `default_timeout`

```python
default_timeout: float | None = None
```

Default timeout for Playwright operations in milliseconds (e.g. `10000` if you want 10s).

#### `default_navigation_timeout`

```python
default_navigation_timeout: float | None = None
```

Default timeout for page navigation in milliseconds (e.g. `30000` if you want 30s).


### Playwright Viewport Options

Configure browser window size, viewport, and display properties:

#### `user_agent`

```python
user_agent: str | None = None
```

Specific user agent to use in this context. See [`playwright.devices`](https://playwright.dev/python/docs/emulation).

#### `is_mobile`

```python
is_mobile: bool = False
```

Whether the meta viewport tag is taken into account and touch events are enabled.

#### `has_touch`

```python
has_touch: bool = False
```

Specifies if viewport supports touch events.

#### `geolocation`

```python
geolocation: dict | None = None
```

Geolocation coordinates. Example: `{"latitude": 59.95, "longitude": 30.31667}`

#### `locale`

```python
locale: str | None = None
```

Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect the `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.

#### `timezone_id`

```python
timezone_id: str | None = None
```

Timezone identifier (e.g. `'America/New_York'` or `'UTC'`).

#### `window_size`

```python
window_size: dict | None = None
```

Browser window size for headful mode. Example: `{"width": 1920, "height": 1080}`

#### `viewport`

```python
viewport: dict | None = None
```

Viewport size with `width` and `height`. Example: `{"width": 1280, "height": 720}`

#### `no_viewport`

```python
no_viewport: bool | None = not headless
```

Disable fixed viewport. Content will resize with window.

*Tip:* don't use this parameter, it's a playwright standard parameter but it's redundant and only serves to override the `viewport` setting above.
A viewport is *always* used in headless mode regardless of this setting, and is *never* used in headful mode unless you pass `viewport={width, height}` explicitly.

#### `device_scale_factor`

```python
device_scale_factor: float | None = None
```

Device scale factor (DPI). Useful for high-resolution screenshots (set it to 2 or 3).

#### `screen`

```python
screen: dict | None = None
```

Screen size available to browser. Auto-detected if not specified.

#### `color_scheme`

```python
color_scheme: ColorScheme = 'light'
```

Preferred color scheme: `'light'`, `'dark'`, `'no-preference'`

#### `contrast`

```python
contrast: Contrast = 'no-preference'
```

Contrast preference: `'no-preference'`, `'more'`, `'null'`

#### `reduced_motion`

```python
reduced_motion: ReducedMotion = 'no-preference'
```

Reduced motion preference: `'reduce'`, `'no-preference'`, `'null'`

#### `forced_colors`

```python
forced_colors: ForcedColors = 'none'
```

Forced colors mode: `'active'`, `'none'`, `'null'`

#### `**playwright.devices[...]`

Playwright provides launch & context arg presets to [emulate common device fingerprints](https://playwright.dev/python/docs/emulation).

```python
BrowserProfile(
    ...
    **playwright.devices['iPhone 13'],    # playwright = await async_playwright().start()
)
```

Because `BrowserSession` and `BrowserProfile` take all the standard playwright args, we are able to support these device presets as well.

### Playwright Security Options

> See `allowed_domains` above too!

#### `offline`

```python
offline: bool = False
```

Emulate network being offline.

#### `http_credentials`

```python
http_credentials: dict | None = None
```

Credentials for HTTP authentication.

#### `extra_http_headers`

```python
extra_http_headers: dict[str, str] = {}
```

Additional HTTP headers to be sent with every request.

#### `ignore_https_errors`

```python
ignore_https_errors: bool = False
```

Whether to ignore HTTPS errors when sending network requests.

#### `bypass_csp`

```python
bypass_csp: bool = False
```

<Warning>
Enabling this can increase security risk and makes the bot very easy to fingerprint. (Cloudflare, Datadome, etc. will block you)
</Warning>

Toggles bypassing Content-Security-Policy. Enabling reduces some CSP-related errors that can arise from automation scripts injected into pages with strict policies that forbid inline scripts.

#### `java_script_enabled`

```python
java_script_enabled: bool = True
```

<Warning>
Not recommended, untested with Browser Use and likely breaks things.
</Warning>

Whether or not to enable JavaScript in the context.

#### `service_workers`

```python
service_workers: ServiceWorkers = 'allow'
```

Whether to allow sites to register Service workers: `'allow'`, `'block'`

#### `base_url`

```python
base_url: str | None = None
```

Base URL to be used in `page.goto()` and similar operations.

#### `strict_selectors`

```python
strict_selectors: bool = False
```

If true, selector passed to Playwright methods will throw if more than one element matches.

#### `client_certificates`

```python
client_certificates: list[ClientCertificate] = []
```

Client certificates to be used with requests.


### Playwright Recording Options

Note: Browser Use also provides some of our own recording-related options not listed below (see above).

#### `record_video_dir`

<a name="record-video-dir"></a>
<a name="save-recording-path"></a>

```python
record_video_dir: str | Path | None = None
```

Directory to save `.webm` video recordings. [Playwright Docs: `record_video_dir`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-record-video-dir)

<Note>
This parameter also has an alias `save_recording_path` for backwards compatibility with past versions, but we recommend using the standard Playwright name `record_video_dir` going forward.
</Note>

#### `record_video_size`

```python
record_video_size: dict | None = None. [Playwright Docs: `record_video_size`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-record-video-size)

```

Video size. Example: `{"width": 1280, "height": 720}`

#### `record_har_path`

<a name="record-har-path"></a>
<a name="save-har-path"></a>

```python
record_har_path: str | Path | None = None
```

Path to save `.har` network trace files. [Playwright Docs: `record_har_path`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-record-har-path)

<Note>
This parameter also has an alias `save_har_path` for backwards compatibility with past versions, but we recommend using the standard Playwright name `record_har_path` going forward.
</Note>

#### `record_har_content`

```python
record_har_content: RecordHarContent = 'embed'
```

How to persist HAR content: `'omit'`, `'embed'`, `'attach'`

#### `record_har_mode`

```python
record_har_mode: RecordHarMode = 'full'
```

HAR recording mode: `'full'`, `'minimal'`

#### `record_har_omit_content`

```python
record_har_omit_content: bool = False
```

Whether to omit request content from the HAR.

#### `record_har_url_filter`

```python
record_har_url_filter: str | Pattern | None = None
```

URL filter for HAR recording.

#### `downloads_path`

```python
downloads_path: str | Path | None = '~/.config/browseruse/downloads'
```

(aliases: `downloads_dir`, `save_downloads_path`)

Local filesystem directory to save browser file downloads to.

#### `traces_dir`

<a name="traces-dir"></a>
<a name="trace-path"></a>

```python
traces_dir: str | Path | None = None
```

Directory to save all-in-one trace files. Files are automatically named as `{traces_dir}/{context_id}.zip`. [Playwright Docs: `traces_dir`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-traces-dir)

<Note>
This parameter also has an alias `trace_path` for backwards compatibility with past versions, but we recommend using the standard Playwright name `traces_dir` going forward.
</Note>

#### `handle_sighup`

```python
handle_sighup: bool = True
```

Whether playwright should swallow SIGHUP signals and kill the browser.

#### `handle_sigint`

```python
handle_sigint: bool = False
```

Whether playwright should swallow SIGINT signals and kill the browser.

#### `handle_sigterm`

```python
handle_sigterm: bool = False
```

Whether playwright should swallow SIGTERM signals and kill the browser.

---

## Full Example

```python
from browser_use import BrowserSession, BrowserProfile, Agent

browser_profile = BrowserProfile(
    headless=False,
    storage_state="path/to/storage_state.json",
    wait_for_network_idle_page_load_time=3.0,
    viewport={"width": 1280, "height": 1100},
    locale='en-US',
    user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36',
    highlight_elements=True,
    viewport_expansion=500,
    allowed_domains=['*.google.com', 'http*://*.wikipedia.org'],
    user_data_dir=None,
)

browser_session = BrowserSession(
    browser_profile=browser_profile,
    headless=True,                          # extra kwargs to the session override the defaults in the profile
)

# you can drive a session without the agent / reuse it between agents
await browser_session.start()
page = await browser_session.get_current_page()
await page.goto('https://example.com/first/page')

async def run_search():
    agent = Agent(
        task='Your task',
        llm=llm,
        page=page,                        # optional: pass a specific playwright page to start on
        browser_session=browser_session,  # optional: pass an existing browser session to an agent
    )
```

---

## Summary

- **BrowserSession** (defined in `browser_use/browser/session.py`) handles the live browser connection and runtime state
- **BrowserProfile** (defined in `browser_use/browser/profile.py`) is a template that can store default config parameters for a `BrowserSession(...)`

Configuration parameters defined in both scopes consumed by these calls depending on whether we're connecting/launching:

- `BrowserConnectArgs` - args for `playwright.BrowserType.connect_over_cdp(...)`
- `BrowserLaunchArgs` - args for `playwright.BrowserType.launch(...)`
- `BrowserNewContextArgs` - args for `playwright.BrowserType.new_context(...)`
- `BrowserLaunchPersistentContextArgs` - args for `playwright.BrowserType.launch_persistent_context(...)`
- Browser Use's own internal methods

For more details on Playwright's browser context options, see their [launch args documentation](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context).

---