Hyperbrowser Python SDK

Common errors

• ModuleNotFoundError: No module named 'hyperbrowser'

  cause The `hyperbrowser` package is not installed in the current Python environment.
  fix Install the package using pip: `pip install hyperbrowser`.

• AttributeError: 'Hyperbrowser' object has no attribute 'sessions'

  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.
  fix Ensure you have correctly initialized the client, e.g., `client = Hyperbrowser(api_key="...")` or `async with AsyncHyperbrowser(api_key="...") as client:`.

• hyper.common.exceptions.HTTPUpgrade: ('h2c', <socket.socket fd=...)

  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.
  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`.

• KeyError: 'ws_endpoint'

  cause This error occurs when attempting to access `session.ws_endpoint` (or other session attributes) on a `session` object that is `None` or an unexpected structure, typically because the `client.sessions.create()` call failed.
  fix Add error handling around `client.sessions.create()` to check if the session object is valid before attempting to access its attributes. The most common cause is an invalid `HYPERBROWSER_API_KEY`.

Warnings

• gotcha 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.
  Fix: Always wrap session interaction in a `try...finally` block and call `client.sessions.stop(session.id)` in the `finally` block.
• gotcha 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.
  Fix: Ensure all parameter names passed to Hyperbrowser SDK methods in Python adhere to `snake_case`.
• gotcha 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`.
  Fix: Install the necessary browser automation library: `pip install playwright-core` (for Playwright) or `pip install puppeteer-core` (for Puppeteer/Pyppeteer).
• breaking 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.
  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.

Install

• pip install hyperbrowser Install core library
• pip install "hyperbrowser[playwright]" # or "hyperbrowser[puppeteer]" or "hyperbrowser[langchain]" Install with optional dependencies for browser interaction or integrations

Imports

• Hyperbrowser

  from hyperbrowser import Hyperbrowser

  For the synchronous client.
• AsyncHyperbrowser

  from hyperbrowser import AsyncHyperbrowser

  For the asynchronous client.
• CreateSessionParams

  from hyperbrowser.models import CreateSessionParams

  Importing model schemas for session configuration, etc.
• Hyperbrowser
  wrong:

  from hyper import HTTP20Connection

  correct:

  from hyperbrowser import Hyperbrowser

  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.

Quickstart

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.

import asyncio
import os
from hyperbrowser import AsyncHyperbrowser
from puppeteer_core import connect # Or from playwright_core import connect_over_cdp

async def main():
    hyperbrowser_api_key = os.environ.get('HYPERBROWSER_API_KEY', '')
    if not hyperbrowser_api_key:
        print("Error: HYPERBROWSER_API_KEY environment variable not set.")
        print("Please get your API key from https://app.hyperbrowser.ai/dashboard and set it.")
        return

    async with AsyncHyperbrowser(api_key=hyperbrowser_api_key) as client:
        print("Creating Hyperbrowser session...")
        session = await client.sessions.create()
        print(f"Session created: {session.id}, WS Endpoint: {session.ws_endpoint}")

        try:
            # Connect to the remote browser using puppeteer_core (or playwright_core)
            browser = await connect(browserWSEndpoint=session.ws_endpoint, defaultViewport=None)
            page = (await browser.pages())[0]

            print("Navigating to example.com...")
            await page.goto("https://example.com")
            page_title = await page.title()
            print(f"Page title: {page_title}")

            await page.close()
            await browser.disconnect()
        except Exception as e:
            print(f"Error during browser interaction: {e}")
        finally:
            print(f"Stopping session {session.id}...")
            await client.sessions.stop(session.id)
            print("Session stopped.")

if __name__ == "__main__":
    asyncio.run(main())