{"id":10,"library":"browserbase","title":"Browserbase Python SDK","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","language":"python","source_language":"en","source_url":"https://github.com/browserbase/sdk-python","tags":["browser","headless","playwright","scraping","agents","CDP","cloud"],"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":[{"reason":"HTTP transport for Browserbase REST API calls.","package":"httpx","optional":false},{"reason":"Required for actual browser interaction via CDP. Not bundled in browserbase package.","package":"playwright","optional":true}],"imports":[{"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.","wrong":"from browserbase import Browserbase\nbb = Browserbase(os.environ['BROWSERBASE_API_KEY'])\nresult = bb.load('https://example.com')","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)"}],"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."},"warnings":[{"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.","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.","severity":"breaking","affected_versions":"<1.0.0 (old python-sdk)"},{"fix":"Use Browserbase(api_key=os.environ['BROWSERBASE_API_KEY']).","message":"Old SDK constructor accepted API key as positional argument: Browserbase(os.environ['BROWSERBASE_API_KEY']). New SDK requires keyword argument: Browserbase(api_key=...).","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"pip install browserbase playwright && playwright install chromium","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.","severity":"gotcha","affected_versions":"all v1.x"},{"fix":"Always call browser.close() in a finally block, or use keep_alive=False (default) and set explicit timeout= in sessions.create().","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).","severity":"gotcha","affected_versions":"all"},{"fix":"Do not set viewport when using advancedStealth. The OS parameter ('windows', 'mac', 'linux') controls fingerprint signals.","message":"browser_settings.viewport is ignored when advancedStealth=True. Stealth mode overrides viewport to match the spoofed OS fingerprint.","severity":"gotcha","affected_versions":"all v1.x"},{"fix":"For AI-driven browser automation (act/observe/extract): pip install stagehand. For raw CDP sessions: pip install browserbase.","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.","severity":"gotcha","affected_versions":"all"}],"env_vars":{"optional":[],"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."}]},"last_verified":"2026-05-11T18:12:58.020Z","next_check":"2026-04-01T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install browserbase`","cause":"The 'browserbase' package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'browserbase'"},{"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)`).","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.","error":"AttributeError: 'SessionCreateResponse' object has no attribute 'load'"},{"error":"Invalid API key"},{"error":"Session creation failed"},{"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.","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.","error":"BrowserBase connection timeout"},{"fix":"Correct the import statement to use the `Browserbase` class: `from browserbase import 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'.","error":"ImportError: cannot import name 'Client' from 'browserbase'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-11","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.29,"mem_mb":15.4,"disk_size":"33.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.97,"mem_mb":15.4,"disk_size":"33M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":15.4,"disk_size":"168M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.73,"mem_mb":17.1,"disk_size":"36.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.45,"mem_mb":17.1,"disk_size":"36M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.59,"mem_mb":17.1,"disk_size":"171M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.03,"mem_mb":16.9,"disk_size":"27.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.06,"mem_mb":16.9,"disk_size":"27M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.93,"mem_mb":16.9,"disk_size":"163M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.75,"mem_mb":17.8,"disk_size":"27.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.81,"mem_mb":17.8,"disk_size":"27M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.79,"mem_mb":17.8,"disk_size":"162M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.22,"mem_mb":15.4,"disk_size":"32.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.07,"mem_mb":15.4,"disk_size":"32M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":15.4,"disk_size":"167M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-11","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}