Python SDK

All the features and utilities for fast Python development with Browserbase.

If you’re working with Python, the official browserbase package is the easiest way to connect to and control headless browsers running on Browserbase.

Installation

pip install browserbase

Basic usage

Here’s an example using the Browserbase Python SDK to create and connect to a session with Playwright:

from playwright.sync_api import sync_playwright
from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

# Create a session on Browserbase
session = bb.sessions.create()

# Connect to the remote session
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(session.connect_url)
context = browser.contexts[0]
page = context.pages[0]

page.goto("https://news.ycombinator.com/")
page.close()
browser.close()
playwright.stop()

print(f"Session complete! View recording at https://browserbase.com/sessions/{session.id}")

Session configuration

Pass configuration options when creating a session to customize browser behavior.

All configuration options

session = bb.sessions.create(
    # Project ID (optional - inferred from API key if not provided)
    project_id="your-project-id",

    # Proxy configuration
    proxies=True,  # Use default proxy

    # Region where the session runs
    region="us-west-2",

    # Keep session alive after disconnection
    keep_alive=True,

    # Session timeout in seconds (60-21600)
    timeout=3600,

    # Extension ID (uploaded via Upload Extension API)
    extension_id="ext_abc123",

    # Browser settings
    browser_settings={
        # Toggle features
        "blockAds": True,
        "solveCaptchas": True,
        "recordSession": True,
        "logSession": True,
        "verified": True,

        # Operating system (only available with verified)
        # Controls user agent and environment signals
        "os": "windows",

        # Context for session persistence
        "context": {
            "id": "my-context-id",
            "persist": True,
        },

        # Viewport configuration (ignored when verified is enabled)
        "viewport": {
            "width": 1920,
            "height": 1080,
        },

        # Custom CAPTCHA selectors
        "captchaImageSelector": "#captcha-image",
        "captchaInputSelector": "#captcha-input",
    },

    # Custom metadata for the session
    user_metadata={
        "userId": "user_123",
        "taskName": "data-extraction-job",
    },
)

Proxy configuration

Configure proxies as a boolean or a list for more control:

# Using Browserbase managed proxy with geolocation
session = bb.sessions.create(
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {
                "country": "US",
                "state": "CA",
                "city": "San Francisco",
            },
        },
    ],
)

# Using external proxy
session = bb.sessions.create(
    proxies=[
        {
            "type": "external",
            "server": "http://proxy.example.com:8080",
            "username": "user",
            "password": "pass",
            "domainPattern": "*.example.com",
        },
    ],
)

# Multiple proxies with domain patterns
session = bb.sessions.create(
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {"country": "US"},
            "domainPattern": "*.google.com",
        },
        {
            "type": "external",
            "server": "http://proxy.example.com:8080",
            "domainPattern": "*.example.com",
        },
    ],
)

Common configuration examples

# Verified with proxy
session = bb.sessions.create(
    proxies=True,
    browser_settings={
        "verified": True,
        "os": "windows",
    },
)

# Long-running session with keep-alive
session = bb.sessions.create(
    timeout=21600,  # 6 hours
    keep_alive=True,
)

# Session with context persistence
session = bb.sessions.create(
    browser_settings={
        "context": {
            "id": "user-session-context",
            "persist": True,
        },
    },
)

# Custom viewport and ad blocking
session = bb.sessions.create(
    browser_settings={
        "viewport": {"width": 1440, "height": 900},
        "blockAds": True,
    },
)

# Mobile viewport
session = bb.sessions.create(
    browser_settings={
        "viewport": {"width": 390, "height": 844},
    },
)

# Session in specific region with metadata
session = bb.sessions.create(
    region="eu-central-1",
    user_metadata={
        "jobId": "job_456",
        "environment": "production",
    },
)

Examples

Quickstart examples using CAPTCHA solving, proxies, extensions, and more.

PyPI package

View the package on PyPI

SDK reference

View the complete SDK reference documentation