Browserbase Python SDK

1.4.0 · active · verified Sun Mar 01

Python SDK for Browserbase, a serverless headless browser platform. Provides remote browser sessions accessible via Playwright/Selenium CDP connections. Has undergone a complete SDK rewrite at v1.0.0 (October 2024) — the old high-level API (browserbase.load(), browserbase.screenshot()) is gone. Current SDK is a low-level Stainless-generated client focused on session lifecycle management.

Warnings

breaking v1.0.0 (October 2024) is a complete rewrite. The old python-sdk (GitHub: browserbase/python-sdk) is archived as deprecated. All old high-level methods — browserbase.load(), browserbase.screenshot() — no longer exist. Calling them on v1.x raises AttributeError.
Fix: Replace bb.load(url) with a full Playwright session: create session, connect_over_cdp(session.connect_url), use page.goto(). See docs.browserbase.com/reference/sdk/python.
breaking Old SDK constructor accepted API key as positional argument: Browserbase(os.environ['BROWSERBASE_API_KEY']). New SDK requires keyword argument: Browserbase(api_key=...).
Fix: Use Browserbase(api_key=os.environ['BROWSERBASE_API_KEY']).
gotcha The browserbase package only manages session lifecycle (create, list, stop). It does NOT include Playwright or Selenium. You must install playwright separately and call playwright install chromium before CDP connections work.
Fix: pip install browserbase playwright && playwright install chromium
gotcha Sessions are billed per second of runtime. Forgetting to close the browser (browser.close()) or not setting a timeout leaves sessions running and accumulates charges. Default timeout is 60 seconds but can be set up to 21600 (6 hours).
Fix: Always call browser.close() in a finally block, or use keep_alive=False (default) and set explicit timeout= in sessions.create().
gotcha browser_settings.viewport is ignored when advancedStealth=True. Stealth mode overrides viewport to match the spoofed OS fingerprint.
Fix: Do not set viewport when using advancedStealth. The OS parameter ('windows', 'mac', 'linux') controls fingerprint signals.
gotcha Stagehand (pip install stagehand) is a separate AI-native automation framework built on top of Browserbase. It is not part of the browserbase package. Tutorials mixing stagehand and browserbase imports are using two different packages.
Fix: For AI-driven browser automation (act/observe/extract): pip install stagehand. For raw CDP sessions: pip install browserbase.

Install

pip install browserbase Python (current SDK — v1.x, Stainless-generated)
pip install browserbase playwright && playwright install chromium Python with Playwright (most common usage)
pip install stagehand Stagehand Python — AI-native browser automation on top of Browserbase

Imports

Browserbase (current)

from browserbase import Browserbase
bb = Browserbase(api_key=os.environ['BROWSERBASE_API_KEY'])
session = bb.sessions.create(project_id=os.environ['BROWSERBASE_PROJECT_ID'])
browser.connect_over_cdp(session.connect_url)

Old high-level API (load(), screenshot()) is from the deprecated python-sdk (v0.x). Current SDK v1.x has no load() method — it only manages sessions.

Quickstart

Current v1.x SDK: create session, connect via CDP, use Playwright normally. All browser logic is standard Playwright — Browserbase just provides the remote infrastructure.

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

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

# Create a remote browser session
session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    browser_settings={
        "blockAds": True,
        "recordSession": True,
    }
)

# Connect via CDP and use Playwright normally
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session.connect_url)
    context = browser.contexts[0]
    page = context.pages[0]

    page.goto("https://news.ycombinator.com/")
    print(page.title())
    page.screenshot(path="screenshot.png")

    browser.close()

print(f"Replay: https://browserbase.com/sessions/{session.id}")

view raw JSON →