crewAIInc/crewAI · error · ImportError

Failed to install firecrawl-py package

Error message

Failed to install firecrawl-py package

What it means

Raised by FirecrawlCrawlWebsiteTool.__init__ when the user accepted the interactive install prompt ('uv add firecrawl-py') but the subprocess install failed (non-zero exit). The CalledProcessError is chained as the cause, so the real failure (network error, uv not on PATH, resolver conflict) is visible in the exception chain.

Solutions

  1. Install firecrawl-py manually and inspect the real error: pip install firecrawl-py (or uv add firecrawl-py) in your shell.
  2. If uv is missing, install it (curl -LsSf https://astral.sh/uv/install.sh | sh) or rely on pip instead — the prompt only tries uv.
  3. Check the chained CalledProcessError (__cause__) for the underlying reason (offline, version conflict) and fix that.

Example fix

# before: prompt accepted, uv install fails -> ImportError
# after: shell
#   pip install firecrawl-py
tool = FirecrawlCrawlWebsiteTool(api_key=FIRECRAWL_API_KEY)
Defensive patterns

Strategy: try-catch

Validate before calling

def firecrawl_available() -> bool:
    try:
        import firecrawl  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    tool = FirecrawlCrawlWebsiteTool(api_key=KEY)
except ImportError as e:
    print(f'install failed or declined ({e}); cause: {e.__cause__}')
    subprocess.run([sys.executable, '-m', 'pip', 'install', 'firecrawl-py'], check=True)
    tool = FirecrawlCrawlWebsiteTool(api_key=KEY)

Prevention

When it happens

Trigger: Answering 'y' to the install prompt in an environment where 'uv' is not installed, is an old version, or cannot resolve firecrawl-py (offline machine, locked-down registry, dependency conflict).

Common situations: Containers/CI images without uv on PATH; air-gapped or proxied networks blocking the package index; pip-only environments where uv was never installed.

Related errors

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

Appendix: source

Thrown at lib/crewai-tools/src/crewai_tools/tools/firecrawl_crawl_website_tool/firecrawl_crawl_website_tool.py:101

        try:
            from firecrawl import FirecrawlApp

            self._firecrawl = FirecrawlApp(api_key=self.api_key)
        except ImportError:
            import click

            if click.confirm(
                "You are missing the 'firecrawl-py' package. Would you like to install it?"
            ):
                import subprocess

                try:
                    subprocess.run(["uv", "add", "firecrawl-py"], check=True)  # noqa: S607
                    from firecrawl import FirecrawlApp

                    self._firecrawl = FirecrawlApp(api_key=self.api_key)
                except subprocess.CalledProcessError as e:
                    raise ImportError("Failed to install firecrawl-py package") from e
            else:
                raise ImportError(
                    "`firecrawl-py` package not found, please run `uv add firecrawl-py`"
                ) from None

    def _run(self, url: str) -> Any:
        if not self._firecrawl:
            raise RuntimeError("FirecrawlApp not properly initialized")

        url = validate_url(url)
        return self._firecrawl.crawl(url=url, poll_interval=2, **self.config)


try:
    from firecrawl import FirecrawlApp  # noqa: F401

    if not getattr(FirecrawlCrawlWebsiteTool, "_model_rebuilt", False):
        FirecrawlCrawlWebsiteTool.model_rebuild()

View on GitHub (pinned to 754d7323be)