Skip to main content
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()
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

Most browser operations are asynchronous. Always use await when calling browser methods.
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.
Always ensure the browser is properly closed using stop() or a context manager to avoid orphaned browser processes.
You can connect to an already-running Chrome instance by specifying both host and port parameters when creating the browser.

Build docs developers (and LLMs) love

Get started for freeTalk to us