Install & Compatibility
Where this runs
tested against v3.23.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 1.164s · 32.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 1.092s · 139MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Stagehand
✓ from stagehand import Stagehand
✗ from stagehand.sync import Stagehand
AsyncStagehand
✓ from stagehand import AsyncStagehand
Client
✓ from stagehand import Client
This quickstart demonstrates how to initialize the Stagehand client, navigate to a URL, and perform AI-powered actions like clicking and extracting information using natural language instructions. It's configured for the Browserbase cloud environment, requiring `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`. For local execution, `env="LOCAL"` can be set in `StagehandConfig`, but a Chromium-based browser must be installed and accessible.
import os
from stagehand.sync import Stagehand
from stagehand import StagehandConfig
# Ensure BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are set in your environment
# For local mode, set env="LOCAL" and ensure a Chromium browser is installed.
api_key = os.environ.get('BROWSERBASE_API_KEY', 'your_browserbase_api_key_here')
project_id = os.environ.get('BROWSERBASE_PROJECT_ID', 'your_browserbase_project_id_here')
if not api_key or not project_id:
print("Warning: BROWSERBASE_API_KEY or BROWSERBASE_PROJECT_ID not found. \n"\
"Using placeholder values. For full functionality, set these environment variables.")
try:
# Initialize Stagehand client for Browserbase cloud environment
config = StagehandConfig(
env="BROWSERBASE",
api_key=api_key,
project_id=project_id
)
stagehand = Stagehand(config=config)
print("Stagehand client initialized.")
# Navigate to a page
print("Navigating to example.com...")
page = stagehand.context.pages()[0] # Get the default page
page.goto("https://www.example.com")
print("Navigation complete.")
# Use natural language to interact (act) and extract data
print("Performing an action: clicking a link...")
# This 'act' command will try to find a link and click it
# For a deterministic action on example.com, a more specific instruction might be needed.
# For demonstration, we'll try a generic act.
# In a real scenario, you'd specify something like "click the 'More information...' link"
# if it existed and was prominent.
try:
page.act("click the first link on the page")
print("Clicked the first link.")
except Exception as e:
print(f"Could not perform 'act' on a link: {e}")
print("Continuing with extraction.")
print("Extracting page heading...")
# Extract the main heading using natural language
heading = page.extract("the main heading on the page")
print(f"Extracted heading: {heading}")
# End the session
stagehand.close()
print("Stagehand session closed.")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure you have a valid Browserbase API key and project ID, or configure for local mode.")
Debug
Known issues
breakingSome minor versions have been marked as 'DO NOT USE' shortly after release (e.g., v3.19.4, v3.19.3). Always check the GitHub releases or changelog for the latest recommended version before upgrading to avoid known issues.fixRefer to the official GitHub releases for the latest stable version and avoid versions explicitly marked as 'DO NOT USE'.
affects: v3.19.3, v3.19.4
gotchaFor cloud execution via Browserbase, `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` environment variables are required for authentication. Without these, the client will default to local mode or fail to connect to the cloud service.fixSet `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` as environment variables, or pass them directly to `StagehandConfig` when initializing the client.
affects: All versions
gotchaWhen running Stagehand in 'LOCAL' environment mode, a Chromium-based browser (like Chrome or Chromium) must be installed on the machine where the script is executed. If Stagehand cannot automatically locate it, you might need to specify its path using the `CHROME_PATH` environment variable or `browser.launchOptions.executablePath` in the configuration.fixEnsure a compatible browser is installed. If needed, configure the `CHROME_PATH` environment variable or pass `localBrowserLaunchOptions` in `StagehandConfig`.
affects: All versions
gotchaThe library is actively developed and has a high release cadence, indicating rapid evolution. Features and APIs may change or be refined frequently as it is still considered an 'early release'.fixRegularly review the official documentation and changelog before major upgrades. Consider pinning minor versions in production environments to control updates.
affects: All versions
Upgrade
Version history
4.0.2latest on PyPI · released Aug 20, 2026
Audit
Dependencies
python>=3.9requiredRequired Python version.
playwrightrequiredUnderlying browser automation library for local execution.
httpxrequiredAsynchronous HTTP client for the SDK.
requestsrequiredSynchronous HTTP client for the SDK.
pydanticrequiredUsed for response modeling and data validation.
python-dotenvoptionalOptional for loading environment variables from .env files.