Browser

The root browser instance that manages tabs and processes

Overview

The Browser class represents the root browser process and manages all tabs, windows, and resources. There should typically be only one Browser instance per process.

Create a Browser instance using await Browser.create() or the start() function, not by calling Browser() directly.

Creation

import nodriver as uc

# Recommended: Use start() function
browser = await uc.start()

# Alternative: Use Browser.create()
from nodriver import Browser, Config

config = Config(headless=True)
browser = await Browser.create(config)

Properties

config · Config

The configuration object used to launch the browser.

connection · Connection

The websocket connection to the browser.

targets · List[Tab]

All current targets including tabs, iframes, workers, and background processes.

tabs · List[Tab]

Only the targets that are of type “page” (actual browser tabs).

main_tab · Tab

The first tab that was launched with the browser.

stopped · bool

Whether the browser process has stopped.

cookies · CookieJar

Cookie management interface for the browser.

websocket_url · str

The WebSocket debugger URL for the browser.

Methods

create()

Create a new Browser instance.

@classmethod
async def create(
    cls,
    config: Config = None,
    *,
    user_data_dir: PathLike = None,
    headless: bool = False,
    browser_executable_path: PathLike = None,
    browser_args: List[str] = None,
    sandbox: bool = True,
    host: str = None,
    port: int = None,
    **kwargs,
) -> Browser

config · Config · default: "None"

Configuration object. If not provided, a new Config is created from the other parameters.

See start() for details on other parameters.

get()

Navigate to a URL using the first available tab, or create a new tab/window.

async def get(
    self, 
    url: str = "chrome://welcome", 
    new_tab: bool = False, 
    new_window: bool = False
) -> Tab

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

The URL to navigate to.

new_tab · bool · default: "False"

Open URL in a new tab.

new_window · bool · default: "False"

Open URL in a new window.

Returns: The Tab instance.

Example:

browser = await uc.start()

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

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

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

wait()

Wait for a specified time while updating targets.

async def wait(self, time: Union[float, int] = 0.1)

time · float | int · default: "0.1"

Time to wait in seconds.

Example:

await browser.wait(2)  # Wait for 2 seconds

sleep()

Alias for wait(). Wait for a specified time.

await browser.sleep(1.5)  # Wait for 1.5 seconds

stop()

Stop the browser process.

def stop(self)

Example:

browser = await uc.start()
tab = await browser.get('https://example.com')
browser.stop()  # Clean shutdown

grant_all_permissions()

Grant all possible permissions to the browser.

async def grant_all_permissions(self)

Grants permissions for:

• accessibilityEvents
• audioCapture
• backgroundSync
• clipboardReadWrite
• displayCapture
• geolocation
• notifications
• videoCapture
• And many more…

Example:

browser = await uc.start()
await browser.grant_all_permissions()

tile_windows()

Arrange browser windows in a grid layout.

async def tile_windows(
    self, 
    windows=None, 
    max_columns: int = 0
) -> List[Tuple[int, int, int, int]]

windows · List[Tab] · default: "None"

Specific windows to tile. If None, tiles all tabs.

max_columns · int · default: "0"

Maximum number of columns. If 0, automatically calculated.

Returns: List of window positions as (left, top, width, height) tuples.

Example:

browser = await uc.start()

# Open multiple tabs
for url in ['https://example.com', 'https://example.org']:
    await browser.get(url, new_window=True)

# Arrange them in a grid
positions = await browser.tile_windows()

create_context()

Create a new browser context, useful for managing multiple sessions with different proxies.

async def create_context(
    self,
    url: str = "chrome://welcome",
    new_tab: bool = False,
    new_window: bool = True,
    dispose_on_detach: bool = True,
    proxy_server: str = None,
    proxy_bypass_list: List[str] = None,
    origins_with_universal_network_access: List[str] = None,
    proxy_ssl_context = None,
) -> Tab

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

Initial URL to navigate to.

proxy_server · str · default: "None"

Proxy server URL. Supports http, https, and socks5 with authentication:

• http://USERNAME:PASSWORD@SERVER:PORT
• socks5://USERNAME:PASSWORD@SERVER:PORT

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

List of hosts to bypass proxy.

Example:

browser = await uc.start()

# Create context with proxy
tab = await browser.create_context(
    url='https://example.com',
    proxy_server='socks5://user:[e-mail]:1080'
)

update_targets()

Update the list of available targets (tabs, iframes, workers).

async def update_targets(self)

Iteration

You can iterate over browser tabs:

browser = await uc.start()

# Open multiple tabs
await browser.get('https://example.com')
await browser.get('https://example.org', new_tab=True)

# Iterate over all tabs
for tab in browser:
    print(tab.url)
    
# Or use .tabs property
for tab in browser.tabs:
    print(tab.url)

Context Manager

Use BrowserContext for automatic cleanup:

from nodriver.core.browser import BrowserContext

async with BrowserContext() as browser:
    tab = await browser.get('https://example.com')
    # Browser is automatically cleaned up on exit

Examples

Basic browser control

import nodriver as uc

async def main():
    browser = await uc.start()
    
    # Navigate to a page
    tab = await browser.get('https://example.com')
    
    # Wait for page to load
    await browser.wait(2)
    
    # Get all tabs
    print(f"Open tabs: {len(browser.tabs)}")
    
    # Stop browser
    browser.stop()

uc.loop().run_until_complete(main())

Working with multiple tabs

import nodriver as uc

async def main():
    browser = await uc.start()
    
    # Open multiple sites
    urls = [
        'https://example.com',
        'https://example.org',
        'https://example.net'
    ]
    
    for url in urls:
        await browser.get(url, new_tab=True)
    
    # Tile all windows
    await browser.tile_windows()
    
    # Process each tab
    for i, tab in enumerate(browser.tabs):
        print(f"Tab {i}: {tab.url}")
        await tab.activate()
        await browser.wait(1)
    
    browser.stop()

uc.loop().run_until_complete(main())

See also

• Tab class - Control individual browser tabs
• Config class - Browser configuration options
• start() - Launch a browser instance