Skip to main content
The Browser class is the root of the Zendriver hierarchy and represents the browser process. You typically create one Browser instance per automation session.

​
Creating a browser instance

You create browser instances using the asynchronous Browser.create() method, not the constructor: 
import asyncio
from zendriver import Browser

async def main():
    browser = await Browser.create()
    # Your automation code here
    await browser.stop()

asyncio.run(main())
Never instantiate Browser using Browser() directly. Always use await Browser.create() to properly initialize the browser.

​
Configuration options

The create() method accepts various configuration parameters: 
browser = await Browser.create(
    headless=True,
    user_data_dir="/path/to/profile",
    browser_executable_path="/path/to/chrome",
    browser="chrome",  # or "brave", "auto"
    sandbox=True,
    lang="en-US",
    user_agent="Custom User Agent"
)

​
Common parameters

​
headless
bool
default:"False"
Run browser in headless mode (no UI)
​
user_data_dir
PathLike
default:"auto"
Directory for browser profile data. Auto-generates temporary directory if not specified
​
browser_executable_path
PathLike
default:"auto"
Path to browser executable. Auto-detects if not specified
​
browser
str
default:"auto"
Browser type: "chrome", "brave", or "auto"
​
sandbox
bool
default:"True"
Enable browser sandbox. Automatically disabled when running as root
​
user_agent
str
default:"None"
Custom user agent string
Use the get() method to navigate to URLs:
browser.py
browser = await Browser.create()

# Navigate to URL
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)
The get() method:
  • Waits for DOM events to fire
  • Handles navigation timing automatically
  • Returns a Tab object for further interaction

​
Working with tabs

Access browser tabs through properties:
tabs.py
# Get the main tab (first opened)
main_tab = browser.main_tab

# Get all tabs
all_tabs = browser.tabs

# Iterate through tabs
for tab in browser.tabs:
    print(await tab.get_content())

​
Tab properties

​
main_tab
Tab | None
Returns the first tab launched with the browser
​
tabs
List[Tab]
Returns all current tabs (targets of type “page”)
​
targets
List[Connection]
Returns all targets including iframes, service workers, and background scripts

​
Managing browser lifecycle

​
Starting the browser

The browser starts automatically when you call create(), but you can also start it manually: 
browser = await Browser.create()
await browser.start()  # Usually not needed

​
Stopping the browser

Always stop the browser when done to clean up resources: 
await browser.stop()
Use context managers for automatic cleanup:
async with await Browser.create() as browser:
    await browser.get("https://example.com")
    # Browser automatically stops when context exits

​
Waiting

Use the wait() or sleep() methods to pause execution: 
# Wait for 2 seconds
await browser.wait(2)

# Alias for wait
await browser.sleep(1.5)

​
Managing cookies

Access cookies through the cookies property:
cookies.py
# Get all cookies
cookies = await browser.cookies.get_all()

# Get cookies in requests format
import_cookies = await browser.cookies.get_all(requests_cookie_format=True)

# Set cookies
from zendriver import cdp

await browser.cookies.set_all([
    cdp.network.CookieParam(
        name="session",
        value="abc123",
        domain=".example.com"
    )
])

# Save cookies to file
await browser.cookies.save(".session.dat")

# Load cookies from file
await browser.cookies.load(".session.dat")

# Clear all cookies
await browser.cookies.clear()

​
Granting permissions

Grant all browser permissions at once: 
await browser.grant_all_permissions()
This grants permissions for:
  • Audio/video capture
  • Geolocation
  • Notifications
  • Clipboard access
  • And many more

​
Window management

Tile multiple browser windows: 
# Tile all windows automatically
await browser.tile_windows()

# Tile specific tabs
await browser.tile_windows([tab1, tab2, tab3])

# Specify maximum columns
await browser.tile_windows(max_columns=3)

​
Advanced usage

​
Connecting to existing browser

Connect to a running browser instance: 
browser = await Browser.create(
    host="127.0.0.1",
    port=9222
)

​
Using custom configuration

Create a Config object for advanced settings: 
from zendriver import Config

config = Config(
    headless=True,
    expert=True,  # Enables advanced debugging features
    disable_webrtc=True,
    disable_webgl=True
)

browser = await Browser.create(config=config)

​
Target discovery

Automatically discover new tabs and windows: 
# Update targets manually
await browser.update_targets()

# Access all targets
for target in browser.targets:
    print(target.target_id, target.type_)

​
Browser properties

​
websocket_url
str
WebSocket debugger URL for the browser connection
​
connection
Connection | None
The active browser-level connection object
​
config
Config
Browser configuration object
​
stopped
bool
Whether the browser process has stopped

​
Best practices

Chromium processes can be stubborn. Always call await browser.stop() or use context managers to ensure proper cleanup.
Creating browser instances is expensive. Reuse the same browser and open multiple tabs instead of creating new browsers.
If running multiple browsers simultaneously, provide unique user_data_dir values to avoid conflicts.
Use await browser.wait() or await tab.sleep() between page navigations to allow the browser to breathe.

​
Error handling

import asyncio
from zendriver import Browser

async def main():
    browser = None
    try:
        browser = await Browser.create()
        tab = await browser.get("https://example.com")
        # Your automation code
    except FileNotFoundError:
        print("Browser executable not found")
    except Exception as e:
        print(f"Error: {e}")
    finally:
        if browser:
            await browser.stop()

asyncio.run(main())

​
Next steps

Tabs

Learn how to work with browser tabs

Elements

Interact with page elements

Configuration

Advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us