crewAIInc/crewAI · error · ImportError

`hyperbrowser` package not found, please run `pip install hy

Error message

`hyperbrowser` package not found, please run `pip install hyperbrowser`

What it means

ImportError raised in HyperbrowserLoadTool.__init__ when the 'hyperbrowser' SDK package cannot be imported, with the original ImportError chained. The tool needs the SDK to construct its client; unlike some other crewai-tools it does not offer an interactive install, it just names the pip command.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/hyperbrowser_load_tool/hyperbrowser_load_tool.py:58

                name="HYPERBROWSER_API_KEY",
                description="API key for Hyperbrowser services",
                required=False,
            ),
        ]
    )

    def __init__(self, api_key: str | None = None, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self.api_key = api_key or os.getenv("HYPERBROWSER_API_KEY")
        if not api_key:
            raise ValueError(
                "`api_key` is required, please set the `HYPERBROWSER_API_KEY` environment variable or pass it directly"
            )

        try:
            from hyperbrowser import Hyperbrowser  # type: ignore[import-untyped]
        except ImportError as e:
            raise ImportError(
                "`hyperbrowser` package not found, please run `pip install hyperbrowser`"
            ) from e

        if not self.api_key:
            raise ValueError(
                "HYPERBROWSER_API_KEY is not set. Please provide it either via the constructor with the `api_key` argument or by setting the HYPERBROWSER_API_KEY environment variable."
            )

        self.hyperbrowser = Hyperbrowser(api_key=self.api_key)

    @staticmethod
    def _prepare_params(params: dict[str, Any]) -> dict[str, Any]:
        """Prepare session and scrape options parameters."""
        try:
            from hyperbrowser.models.scrape import (  # type: ignore[import-untyped]
                ScrapeOptions,
            )
            from hyperbrowser.models.session import (  # type: ignore[import-untyped]

View on GitHub (pinned to 754d7323be)

Solutions

1. Run: pip install hyperbrowser.
2. Add hyperbrowser to your project dependencies for CI and teammates.
3. Verify: python -c "import hyperbrowser".

Example fix

# before: ImportError
# after: shell
#   pip install hyperbrowser
tool = HyperbrowserLoadTool(api_key=HB_KEY)

try:
    import hyperbrowser  # noqa: F401
except ImportError:
    raise SystemExit('pip install hyperbrowser')

try:
    tool = HyperbrowserLoadTool(api_key=KEY)
except ImportError as e:
    if 'hyperbrowser' in str(e):
        raise SystemExit('install hyperbrowser before use') from e
    raise

When it happens

Trigger: Instantiating HyperbrowserLoadTool (with a valid api_key) in an environment where 'hyperbrowser' is not installed or is broken (e.g. a partially installed dist, Python version incompatibility raising ImportError).

Common situations: crewai-tools installed without the hyperbrowser extra; fresh virtualenvs; CI images missing optional dependencies; Python upgrades breaking an installed SDK.

Related errors

• The 'e2b_code_interpreter' package is required for the E2B P
• You are missing the 'exa_py' package. Please install it to u
• `firecrawl-py` package not found, please run `uv add firecra
• `firecrawl-py` package not found, please run `uv add firecra
• `firecrawl-py` package not found, please run `uv add firecra

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