Install & Compatibility
Where this runs
tested against v0.91.4 · 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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 1.597s · 34.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.2s · import 1.453s · 34MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from hyperbrowser import Hyperbrowser
✗ from hyper import HTTP20Connection
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.
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())
Debug
Known issues
gotchaIt 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.fixAlways wrap session interaction in a `try...finally` block and call `client.sessions.stop(session.id)` in the `finally` block.
affects: All versions
gotchaThe 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.fixEnsure all parameter names passed to Hyperbrowser SDK methods in Python adhere to `snake_case`.
affects: All versions
gotchaThe 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`.fixInstall the necessary browser automation library: `pip install playwright-core` (for Playwright) or `pip install puppeteer-core` (for Puppeteer/Pyppeteer).
affects: All versions
breakingThe `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.fixReview 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.
affects: 0.90.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hyperbrowser'
The `hyperbrowser` package is not installed in the current Python environment.
fixInstall the package using pip: `pip install hyperbrowser`.
AttributeError: 'Hyperbrowser' object has no attribute 'sessions'
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.
fixEnsure 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=...)
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.
fixEnsure 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'
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.
fixAdd 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`.
Upgrade
Version history
0.91.4latest on PyPI · released Jun 14, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.8 or newer, but less than 4.0.
playwright-coreoptionalRequired for interacting with Hyperbrowser sessions using Playwright. Choose either playwright-core or puppeteer-core.
puppeteer-coreoptionalRequired for interacting with Hyperbrowser sessions using Puppeteer (via Pyppeteer). Choose either playwright-core or puppeteer-core.
dotenvoptionalCommonly used for loading API keys from environment variables.
langchain-hyperbrowseroptionalFor integration with LangChain.