Browser class and lifecycle

Understanding the Browser class, its lifecycle, and how to create and manage browser instances

The Browser object is the root of the nodriver hierarchy and represents the browser process. It manages tabs, browser contexts, and the connection to the Chrome DevTools Protocol.

Creating a browser instance

You create browser instances using the asynchronous Browser.create() method, not through direct instantiation:

import nodriver as uc

browser = await uc.Browser.create()

The Browser object must be created using await Browser.create() rather than Browser(). Direct instantiation will raise a RuntimeError.

Configuration options

The create() method accepts several configuration parameters:

config · Config · default: "None"

A Config object with browser settings. If not provided, a default configuration is created.

user_data_dir · PathLike · default: "None"

Directory for browser profile data. If not specified, a temporary directory is created.

headless · bool · default: "False"

Run the browser in headless mode without a visible window.

browser_executable_path · PathLike · default: "None"

Path to the Chrome/Chromium executable. Auto-detected if not provided.

browser_args · List[str] · default: "None"

Additional command-line arguments to pass to the browser.

sandbox · bool · default: "True"

Enable or disable the browser sandbox. Automatically disabled when running as root.

host · str · default: "None"

Host address for the DevTools Protocol connection. Defaults to “127.0.0.1”.

port · int · default: "None"

Port for the DevTools Protocol connection. Auto-assigned if not provided.

Example with configuration

import nodriver as uc

browser = await uc.Browser.create(
    headless=False,
    sandbox=True,
    browser_args=['--window-size=1920,1080']
)

Key properties

Main tab

Access the primary tab that was launched with the browser:

tab = browser.main_tab

All tabs

Get a list of all open tabs (targets of type “page”):

tabs = browser.tabs

Cookies

Access the browser’s cookie jar for managing cookies across all tabs:

cookies = browser.cookies
all_cookies = await cookies.get_all()

Navigation and tab management

Navigate to a URL

Use the get() method to navigate in the current tab or open new tabs/windows:

# Navigate in existing tab
tab = await browser.get('https://example.com')

# Open in new tab
tab = await browser.get('https://example.com', new_tab=True)

# Open in new window
tab = await browser.get('https://example.com', new_window=True)

Accessing tabs

You can access tabs by index or search:

# By index
first_tab = browser[0]
second_tab = browser[1]

# By search string (matches target info)
google_tab = browser['google']

# Slice notation
first_three = browser[0:3]

Browser contexts

Create isolated browser contexts, useful for different proxy configurations:

tab = await browser.create_context(
    url='https://example.com',
    new_window=True,
    proxy_server='http://proxy.example.com:8080',
    dispose_on_detach=True
)

url · str · default: "'chrome://welcome'"

URL to open in the new context.

new_window · bool · default: "True"

Open in a new window instead of a tab.

proxy_server · str · default: "None"

Proxy server to use. Supports HTTP, HTTPS, and SOCKS5 with authentication. Format: http://username:password@server:port or socks://username:password@server:port

dispose_on_detach · bool · default: "True"

Automatically dispose the context when the debugging session disconnects.

Chrome typically only supports one proxy per browser instance. Use create_context() with different proxy settings to work around this limitation.

Permissions

Grant all browser permissions at once:

await browser.grant_all_permissions()

This grants permissions for:

• Audio and video capture
• Clipboard access
• Geolocation
• Notifications
• Sensors
• And many more

Window management

Tile windows

Arrange multiple browser windows in a grid layout:

await browser.tile_windows(max_columns=2)

Lifecycle management

Waiting and sleeping

Allow the browser to update its state:

# Wait and update targets
await browser.wait(0.5)

# Or use the alias
await browser.sleep(1)

Stopping the browser

Terminate the browser process:

browser.stop()

The browser automatically attempts to clean up on exit, but calling stop() explicitly ensures proper shutdown.

Using context manager

For automatic cleanup, use the BrowserContext context manager:

from nodriver import BrowserContext

async with BrowserContext(headless=False) as browser:
    tab = await browser.get('https://example.com')
    # ... do your work
# Browser automatically closes here

keep_open · bool · default: "False"

Set to True to prevent automatic browser closure when exiting the context.

Iteration

Iterate through all tabs:

for tab in browser:
    print(tab.target.url)

Connection details

Access the WebSocket debugger URL:

ws_url = browser.websocket_url

Check if the browser is still running:

if browser.stopped:
    print('Browser has been terminated')

Best practices

Use await for browser operations

Most browser operations are asynchronous. Always use await when calling browser methods.

Keep references to tabs

Store tab objects when you need to interact with specific tabs later. The browser maintains a list of all targets, but keeping your own references makes code clearer.

Handle browser cleanup

Always ensure the browser is properly closed using stop() or a context manager to avoid orphaned browser processes.

Connect to existing browsers

You can connect to an already-running Chrome instance by specifying both host and port parameters when creating the browser.

Related documentation

• Tab management - Learn about controlling individual tabs
• Configuration - Detailed configuration options
• Element interaction - Working with page elements