{"id":8222,"library":"hyperbrowser","title":"Hyperbrowser Python SDK","description":"Hyperbrowser Python SDK is a client library for interacting with the Hyperbrowser platform, offering cloud-based headless browser automation. It enables developers to perform advanced web scraping, create AI-driven browser agents, and manage scalable browser sessions with built-in features like CAPTCHA solving, proxy management, and anti-bot detection. The library provides both synchronous and asynchronous clients for flexible integration, with frequent updates to its `0.90.x` series.","status":"active","version":"0.90.3","language":"en","source_language":"en","source_url":"https://github.com/hyperbrowserai/python-sdk","tags":["browser automation","sdk","ai","web scraping","headless browser","playwright","puppeteer","api client"],"install":[{"cmd":"pip install hyperbrowser","lang":"bash","label":"Install core library"},{"cmd":"pip install \"hyperbrowser[playwright]\" # or \"hyperbrowser[puppeteer]\" or \"hyperbrowser[langchain]\"","lang":"bash","label":"Install with optional dependencies for browser interaction or integrations"}],"dependencies":[{"reason":"Requires Python 3.8 or newer, but less than 4.0.","package":"python","optional":false},{"reason":"Required for interacting with Hyperbrowser sessions using Playwright. Choose either playwright-core or puppeteer-core.","package":"playwright-core","optional":true},{"reason":"Required for interacting with Hyperbrowser sessions using Puppeteer (via Pyppeteer). Choose either playwright-core or puppeteer-core.","package":"puppeteer-core","optional":true},{"reason":"Commonly used for loading API keys from environment variables.","package":"dotenv","optional":true},{"reason":"For integration with LangChain.","package":"langchain-hyperbrowser","optional":true}],"imports":[{"note":"For the synchronous client.","symbol":"Hyperbrowser","correct":"from hyperbrowser import Hyperbrowser"},{"note":"For the asynchronous client.","symbol":"AsyncHyperbrowser","correct":"from hyperbrowser import AsyncHyperbrowser"},{"note":"Importing model schemas for session configuration, etc.","symbol":"CreateSessionParams","correct":"from hyperbrowser.models import CreateSessionParams"},{"note":"The `hyper` library is a separate, unrelated HTTP/2 library and not the SDK for Hyperbrowser. Importing `hyper` components will lead to `ModuleNotFoundError` or `AttributeError` when trying to use Hyperbrowser SDK methods.","wrong":"from hyper import HTTP20Connection","symbol":"Hyperbrowser","correct":"from hyperbrowser import Hyperbrowser"}],"quickstart":{"code":"import asyncio\nimport os\nfrom hyperbrowser import AsyncHyperbrowser\nfrom puppeteer_core import connect # Or from playwright_core import connect_over_cdp\n\nasync def main():\n hyperbrowser_api_key = os.environ.get('HYPERBROWSER_API_KEY', '')\n if not hyperbrowser_api_key:\n print(\"Error: HYPERBROWSER_API_KEY environment variable not set.\")\n print(\"Please get your API key from https://app.hyperbrowser.ai/dashboard and set it.\")\n return\n\n async with AsyncHyperbrowser(api_key=hyperbrowser_api_key) as client:\n print(\"Creating Hyperbrowser session...\")\n session = await client.sessions.create()\n print(f\"Session created: {session.id}, WS Endpoint: {session.ws_endpoint}\")\n\n try:\n # Connect to the remote browser using puppeteer_core (or playwright_core)\n browser = await connect(browserWSEndpoint=session.ws_endpoint, defaultViewport=None)\n page = (await browser.pages())[0]\n\n print(\"Navigating to example.com...\")\n await page.goto(\"https://example.com\")\n page_title = await page.title()\n print(f\"Page title: {page_title}\")\n\n await page.close()\n await browser.disconnect()\n except Exception as e:\n print(f\"Error during browser interaction: {e}\")\n finally:\n print(f\"Stopping session {session.id}...\")\n await client.sessions.stop(session.id)\n print(\"Session stopped.\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to create an asynchronous Hyperbrowser session, connect to the remote browser using `puppeteer_core` (ensure it's installed via `pip install puppeteer-core`), navigate to a page, and then properly close the session. The `HYPERBROWSER_API_KEY` is retrieved from environment variables for secure authentication. You can also use `playwright-core` and `connect_over_cdp` instead of `puppeteer_core` and `connect` respectively."},"warnings":[{"fix":"Always wrap session interaction in a `try...finally` block and call `client.sessions.stop(session.id)` in the `finally` block.","message":"It is crucial to explicitly stop Hyperbrowser sessions using `client.sessions.stop(session.id)` in a `finally` block or similar cleanup logic. Failing to do so can lead to sessions running longer than intended, consuming resources, and potentially incurring unexpected charges, even with automatic timeouts.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all parameter names passed to Hyperbrowser SDK methods in Python adhere to `snake_case`.","message":"The Hyperbrowser SDK for Python uses `snake_case` for all session parameters (e.g., `use_proxy`, `solve_captchas`), while the Node.js/TypeScript SDK uses `camelCase` (e.g., `useProxy`, `solveCaptchas`). Using the incorrect casing in Python will result in `TypeError` or ignored parameters.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the necessary browser automation library: `pip install playwright-core` (for Playwright) or `pip install puppeteer-core` (for Puppeteer/Pyppeteer).","message":"The core `hyperbrowser` library does not bundle browser automation libraries like Playwright or Puppeteer. To interact with the remote browser session's WebSocket endpoint (e.g., `session.ws_endpoint`), you must separately install and use `playwright-core` or `puppeteer-core`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review usage of `FetchBrowserOptions` and `solve_captchas` parameter to ensure it conforms to the correct type, likely a boolean or a specific object structure as per the updated API documentation.","message":"The `0.90.0` release included a fix for an `incorrect type for FetchBrowserOptions.solve_captchas`. If your code used `FetchBrowserOptions` and explicitly set `solve_captchas` with a type that was previously accepted but is now corrected, it might lead to type validation errors or runtime issues.","severity":"breaking","affected_versions":"0.90.0 and later"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install hyperbrowser`.","cause":"The `hyperbrowser` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'hyperbrowser'"},{"fix":"Ensure you have correctly initialized the client, e.g., `client = Hyperbrowser(api_key=\"...\")` or `async with AsyncHyperbrowser(api_key=\"...\") as client:`.","cause":"This usually happens if the `Hyperbrowser` or `AsyncHyperbrowser` client is not correctly initialized or if you're trying to access `sessions` without creating an instance.","error":"AttributeError: 'Hyperbrowser' object has no attribute 'sessions'"},{"fix":"Ensure you have `pip install hyperbrowser` and are importing `from hyperbrowser import ...` not `from hyper import ...`. If `hyper` is installed and causing conflicts, consider uninstalling it if not needed for other parts of your project: `pip uninstall hyper`.","cause":"This error comes from the unrelated `hyper` library, which handles HTTP/2 connections. It indicates a confusion between the `hyper` library and the `hyperbrowser` SDK. You might have mistakenly imported `hyper` components or installed the wrong library.","error":"hyper.common.exceptions.HTTPUpgrade: ('h2c',