{"id":"browserbase","title":"Browserbase Python SDK","library":"browserbase","description":"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.","status":"active","version":"1.4.0","install":[{"cmd":"pip install browserbase","lang":"bash","label":"Python (current SDK — v1.x, Stainless-generated)"},{"cmd":"pip install browserbase playwright && playwright install chromium","lang":"bash","label":"Python with Playwright (most common usage)"},{"cmd":"pip install stagehand","lang":"bash","label":"Stagehand Python — AI-native browser automation on top of Browserbase"}],"dependencies":[{"package":"httpx","reason":"HTTP transport for Browserbase REST API calls.","optional":false},{"package":"playwright","reason":"Required for actual browser interaction via CDP. Not bundled in browserbase package.","optional":true}],"imports":[{"symbol":"Browserbase (current)","correct":"from browserbase import Browserbase\nbb = Browserbase(api_key=os.environ['BROWSERBASE_API_KEY'])\nsession = bb.sessions.create(project_id=os.environ['BROWSERBASE_PROJECT_ID'])\nbrowser.connect_over_cdp(session.connect_url)","wrong":"from browserbase import Browserbase\nbb = Browserbase(os.environ['BROWSERBASE_API_KEY'])\nresult = bb.load('https://example.com')","note":"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":{"code":"import os\nfrom playwright.sync_api import sync_playwright\nfrom browserbase import Browserbase\n\nbb = Browserbase(api_key=os.environ[\"BROWSERBASE_API_KEY\"])\n\n# Create a remote browser session\nsession = bb.sessions.create(\n    project_id=os.environ[\"BROWSERBASE_PROJECT_ID\"],\n    browser_settings={\n        \"blockAds\": True,\n        \"recordSession\": True,\n    }\n)\n\n# Connect via CDP and use Playwright normally\nwith sync_playwright() as p:\n    browser = p.chromium.connect_over_cdp(session.connect_url)\n    context = browser.contexts[0]\n    page = context.pages[0]\n\n    page.goto(\"https://news.ycombinator.com/\")\n    print(page.title())\n    page.screenshot(path=\"screenshot.png\")\n\n    browser.close()\n\nprint(f\"Replay: https://browserbase.com/sessions/{session.id}\")","lang":"python","description":"Current v1.x SDK: create session, connect via CDP, use Playwright normally. All browser logic is standard Playwright — Browserbase just provides the remote infrastructure."},"env_vars":{"required":[{"name":"BROWSERBASE_API_KEY","note":"Required. Get from browserbase.com dashboard."},{"name":"BROWSERBASE_PROJECT_ID","note":"Required for session creation. Found in your Browserbase project settings."}],"optional":[]},"warnings":[{"severity":"breaking","message":"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.","affected_versions":"<1.0.0 (old python-sdk)","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."},{"severity":"breaking","message":"Old SDK constructor accepted API key as positional argument: Browserbase(os.environ['BROWSERBASE_API_KEY']). New SDK requires keyword argument: Browserbase(api_key=...).","affected_versions":"<1.0.0","fix":"Use Browserbase(api_key=os.environ['BROWSERBASE_API_KEY'])."},{"severity":"gotcha","message":"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.","affected_versions":"all v1.x","fix":"pip install browserbase playwright && playwright install chromium"},{"severity":"gotcha","message":"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).","affected_versions":"all","fix":"Always call browser.close() in a finally block, or use keep_alive=False (default) and set explicit timeout= in sessions.create()."},{"severity":"gotcha","message":"browser_settings.viewport is ignored when advancedStealth=True. Stealth mode overrides viewport to match the spoofed OS fingerprint.","affected_versions":"all v1.x","fix":"Do not set viewport when using advancedStealth. The OS parameter ('windows', 'mac', 'linux') controls fingerprint signals."},{"severity":"gotcha","message":"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.","affected_versions":"all","fix":"For AI-driven browser automation (act/observe/extract): pip install stagehand. For raw CDP sessions: pip install browserbase."}],"last_verified":"2026-03-01","next_check":"2026-04-01","source_url":"https://github.com/browserbase/sdk-python","language":"en","source_language":"en","tags":["browser","headless","playwright","scraping","agents","CDP","cloud"]}