Browserbase Python SDK

raw JSON →
1.4.0 verified Mon May 11 auth: yes python install: verified quickstart: stale

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.

pip install browserbase

Common errors

error ModuleNotFoundError: No module named 'browserbase' ↓
cause The 'browserbase' package is not installed in your current Python environment.
fix
Install the package using pip: pip install browserbase
error AttributeError: 'SessionCreateResponse' object has no attribute 'load' ↓
cause The `browserbase.load()` method was part of the old high-level API (pre-v1.0.0) and was removed in the SDK rewrite. The new SDK focuses on lower-level session management.
fix
Instead of session.load(), use client.fetch.get(url='your_url') for simple page content retrieval, or establish a Playwright/CDP connection via session.connect() to interact with the browser session for complex automation (e.g., page = playwright.chromium.connect_over_cdp(session.connect_url)).
error Invalid API key ↓
error Session creation failed ↓
error BrowserBase connection timeout ↓
cause Your Browserbase API key is missing, incorrect, or your project ID is not set, leading to authentication failure or an inability to establish a connection to the Browserbase service.
fix
Ensure BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID environment variables are correctly set, or pass them explicitly during client instantiation: client = Browserbase(api_key='your_api_key', project_id='your_project_id'). Also, verify your account status and available credits on the Browserbase dashboard.
error ImportError: cannot import name 'Client' from 'browserbase' ↓
cause You are attempting to import a class named 'Client' which does not exist in the 'browserbase' package. The primary client class is named 'Browserbase'.
fix
Correct the import statement to use the Browserbase class: from browserbase import Browserbase

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 playwright && playwright install chromium
pip install stagehand

Install compatibility verified last tested: 2026-05-11

python os / libc variant status wheel install import disk
3.10 alpine (musl) browserbase - - 1.29s 33.0M
3.10 alpine (musl) browserbase - - - -
3.10 alpine (musl) stagehand - - - -
3.10 slim (glibc) browserbase - - 0.97s 33M
3.10 slim (glibc) browserbase - - 1.02s 168M
3.10 slim (glibc) stagehand - - - -
3.11 alpine (musl) browserbase - - 1.73s 36.1M
3.11 alpine (musl) browserbase - - - -
3.11 alpine (musl) stagehand - - - -
3.11 slim (glibc) browserbase - - 1.45s 36M
3.11 slim (glibc) browserbase - - 1.59s 171M
3.11 slim (glibc) stagehand - - - -
3.12 alpine (musl) browserbase - - 2.03s 27.6M
3.12 alpine (musl) browserbase - - - -
3.12 alpine (musl) stagehand - - - -
3.12 slim (glibc) browserbase - - 2.06s 27M
3.12 slim (glibc) browserbase - - 1.93s 163M
3.12 slim (glibc) stagehand - - - -
3.13 alpine (musl) browserbase - - 1.75s 27.2M
3.13 alpine (musl) browserbase - - - -
3.13 alpine (musl) stagehand - - - -
3.13 slim (glibc) browserbase - - 1.81s 27M
3.13 slim (glibc) browserbase - - 1.79s 162M
3.13 slim (glibc) stagehand - - - -
3.9 alpine (musl) browserbase - - 1.22s 32.3M
3.9 alpine (musl) browserbase - - - -
3.9 alpine (musl) stagehand - - - -
3.9 slim (glibc) browserbase - - 1.07s 32M
3.9 slim (glibc) browserbase - - 1.13s 167M
3.9 slim (glibc) stagehand - - - -

Imports

Quickstart stale last tested: 2026-05-11

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}")
last verified Mon May 11
next check Wed Apr 01