crewAIInc/crewAI · error · ImportError

Attempted to install 'tavily-python' but failed: {e}. Please

Error message

Attempted to install 'tavily-python' but failed: {e}. Please install it manually to use the TavilySearchTool.

What it means

TavilySearchTool tried to auto-install the missing 'tavily-python' package by shelling out to 'uv add tavily-python', but the subprocess exited non-zero (check=True raised CalledProcessError). The ImportError wraps the subprocess failure and asks you to install the package manually.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/tavily_search_tool.py:144

                import subprocess

                import click
            except ImportError as e:
                raise ImportError(
                    "The 'tavily-python' package is required. 'click' and 'subprocess' are also needed to assist with installation if the package is missing. "
                    "Please install 'tavily-python' manually (e.g., 'pip install tavily-python') and ensure 'click' and 'subprocess' are available."
                ) from e

            if click.confirm(
                "You are missing the 'tavily-python' package, which is required for TavilySearchTool. Would you like to install it?"
            ):
                try:
                    subprocess.run(["uv", "add", "tavily-python"], check=True)  # noqa: S607
                    raise ImportError(
                        "'tavily-python' has been installed. Please restart your Python application to use the TavilySearchTool."
                    )
                except subprocess.CalledProcessError as e:
                    raise ImportError(
                        f"Attempted to install 'tavily-python' but failed: {e}. "
                        f"Please install it manually to use the TavilySearchTool."
                    ) from e
            else:
                raise ImportError(
                    "The 'tavily-python' package is required to use the TavilySearchTool. "
                    "Please install it with: uv add tavily-python"
                )

    def _run(
        self,
        query: str,
    ) -> str:
        """Synchronously performs a search using the Tavily API.
        Content of each result is truncated to `max_content_length_per_result`.

        Args:
            query: The search query string.

View on GitHub (pinned to 754d7323be)

Solutions

Install manually with your actual package manager: pip install tavily-python (or uv add tavily-python after fixing the underlying uv error).
Check the wrapped CalledProcessError/stderr to see why uv failed (no network, lock conflict, no pyproject.toml).
If uv is missing, install uv (curl -LsSf https://astral.sh/uv/install.sh | sh) or skip uv and use pip.
Pre-install the dependency in your image/CI so the interactive path is never hit.

Example fix

# before
TavilySearchTool()  # prompts -> 'uv add tavily-python' fails -> ImportError

# after
# shell: pip install tavily-python  (or fix uv project: uv add tavily-python)
# then restart the app
TavilySearchTool(api_key='tvly-...')

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil

if not shutil.which('uv'):
    print('uv not on PATH - install deps with pip instead')

Try / catch

try:
    tool = TavilySearchTool(api_key=KEY)
except ImportError as e:
    if 'Attempted to install' in str(e):
        subprocess.run([sys.executable, '-m', 'pip', 'install', 'tavily-python'], check=True)
        sys.exit('Installed tavily-python - please restart the application')
    raise

Prevention

Pre-install tavily-python in Docker/CI so 'uv add' never runs at runtime.
Ensure uv is installed and the project has a pyproject.toml if you expect 'uv add' to work.
Check network/proxy access for PyPI in the deployment environment.

When it happens

Trigger: Answering 'y' to the install prompt when 'tavily-python' is missing AND uv is absent from PATH, uv cannot resolve the package (offline, proxy blocked, lockfile conflict), or the project is not a uv workspace so 'uv add' fails.

Common situations: Restricted CI/network environments without PyPI access; using pip-managed venvs where 'uv add' has no project to modify; uv lock conflicts from an outdated uv.lock; running as a user without write access to the environment.

Related errors

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