Install & Compatibility
Where this runs
tested against v1.18.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
10/18 runs
12/18 runs
py 3.11
10/18 runs
12/18 runs
py 3.12
10/18 runs
12/18 runs
py 3.13
10/18 runs
12/18 runs
py 3.9
10/18 runs
12/18 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Browserbase
✓ from browserbase import Browserbase
✗ from browserbase import Browserbase
AsyncBrowserbase
✓ from browserbase import AsyncBrowserbase
Client
✓ from browserbase import Client
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}")
Debug
Known issues
breakingv1.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.fixReplace 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.
affects: <1.0.0 (old python-sdk)
breakingOld SDK constructor accepted API key as positional argument: Browserbase(os.environ['BROWSERBASE_API_KEY']). New SDK requires keyword argument: Browserbase(api_key=...).fixUse Browserbase(api_key=os.environ['BROWSERBASE_API_KEY']).
affects: <1.0.0
gotchaThe 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.fixpip install browserbase playwright && playwright install chromium
affects: all v1.x
gotchaSessions 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).fixAlways call browser.close() in a finally block, or use keep_alive=False (default) and set explicit timeout= in sessions.create().
affects: all
gotchabrowser_settings.viewport is ignored when advancedStealth=True. Stealth mode overrides viewport to match the spoofed OS fingerprint.fixDo not set viewport when using advancedStealth. The OS parameter ('windows', 'mac', 'linux') controls fingerprint signals. affects: all v1.x
gotchaStagehand (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.fixFor AI-driven browser automation (act/observe/extract): pip install stagehand. For raw CDP sessions: pip install browserbase.
affects: all
Upgrade
Version history
1.18.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
httpxrequiredHTTP transport for Browserbase REST API calls.
playwrightoptionalRequired for actual browser interaction via CDP. Not bundled in browserbase package.