crewAIInc/crewAI · error · ImportError

`stagehand` package not found, please run `uv add stagehand`

Error message

`stagehand` package not found, please run `uv add stagehand`

What it means

StagehandTool checks at construction time (_check_required_credentials) that the stagehand Python package is importable; if not (and the tool is not in _testing mode) it raises ImportError with the install command `uv add stagehand`. The check uses a module-level _HAS_STAGEHAND flag rather than a prompt — this tool does not offer auto-install.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/stagehand_tool/stagehand_tool.py:241

        if wait_for_captcha_solves is not None:
            self.wait_for_captcha_solves = wait_for_captcha_solves
        if verbose is not None:
            self.verbose = verbose

        self._session_id = session_id

        if not self._testing:
            log_level = {1: "INFO", 2: "WARNING", 3: "DEBUG"}.get(self.verbose, "ERROR")
            configure_logging(
                level=log_level, remove_logger_name=True, quiet_dependencies=True
            )

        self._check_required_credentials()

    def _check_required_credentials(self) -> None:
        """Validate that required credentials are present."""
        if not self._testing and not _HAS_STAGEHAND:
            raise ImportError(
                "`stagehand` package not found, please run `uv add stagehand`"
            )

        if not self.api_key:
            raise ValueError("api_key is required (or set BROWSERBASE_API_KEY in env).")
        if not self.project_id:
            raise ValueError(
                "project_id is required (or set BROWSERBASE_PROJECT_ID in env)."
            )

    def __del__(self) -> None:
        """Ensure cleanup on deletion."""
        try:
            self.close()
        except Exception:  # noqa: S110
            pass

    def _get_model_api_key(self) -> str | None:

View on GitHub (pinned to 754d7323be)

Solutions

1. Install the package: uv add stagehand (or pip install stagehand).
2. Add stagehand to your project dependencies/Dockerfile.
3. If writing unit tests of your own orchestration (not the tool), construct the tool with _testing=True to skip dependency and credential checks.

Example fix

# terminal
# before: StagehandTool() -> ImportError

# after:
#   pip install stagehand
from crewai_tools import StagehandTool
tool = StagehandTool()

import importlib.util
if importlib.util.find_spec("stagehand") is None:
    raise RuntimeError("Run: pip install stagehand")

try:
    tool = StagehandTool()
except ImportError as e:
    if "stagehand" in str(e):
        subprocess.run(["pip", "install", "stagehand"], check=True)
        tool = StagehandTool()

When it happens

Trigger: Instantiating StagehandTool without the stagehand package installed; environments where pip install crewai-tools did not pull stagehand (it is an optional dependency). Testing mode (_testing=True) deliberately bypasses it.

Common situations: Optional-dependency setups where stagehand wasn't installed; fresh clones running tests/dev environments; Docker images built without the stagehand extra.

Related errors

• The 'e2b' package is required for E2B sandbox tools. Install
• `scrapfly-sdk` package not found, please run `uv add scrapfl
• `selenium` and `webdriver-manager` package not found, please
• `serpapi` package not found, please install with `uv add ser
• Failed to install singlestore package

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/792951f6f12a5647. Report an issue: GitHub.