assafelovic/gpt-researcher · error · ImportError

Unable to import {pkg_kebab}. Please install with `pip insta

Error message

Unable to import {pkg_kebab}. Please install with `pip install -U {pkg_kebab}`

What it means

check_pkg() uses importlib.util.find_spec to verify a retriever's optional dependency is importable before the retriever is instantiated. If find_spec returns None, it raises ImportError with a pip install hint naming the kebab-cased package. This is GPT Researcher's guard for its pluggable retriever backends.

Source

Thrown at gpt_researcher/retrievers/utils.py:56

                    "step": step,
                    "content": content
                })
        except Exception as e:
            logger.error(f"Error streaming output: {e}")

def check_pkg(pkg: str) -> None:
    """
    Checks if a package is installed and raises an error if not.
    
    Args:
        pkg (str): The package name
    
    Raises:
        ImportError: If the package is not installed
    """
    if not importlib.util.find_spec(pkg):
        pkg_kebab = pkg.replace("_", "-")
        raise ImportError(
            f"Unable to import {pkg_kebab}. Please install with "
            f"`pip install -U {pkg_kebab}`"
        )

# Valid retrievers for fallback
VALID_RETRIEVERS = [
    "tavily",
    "groundroute",
    "custom",
    "duckduckgo",
    "searchapi",
    "serper",
    "serpapi",
    "google",
    "searx",
    "bing",
    "brave",
    "arxiv",

View on GitHub (pinned to 6f998577d5)

Solutions

Install the named package exactly as the message suggests: pip install -U <pkg-kebab> (e.g., pip install -U tavily-python).
Install the relevant optional extra, e.g., pip install -U gpt-researcher[tavily], to pull all needed deps at once.
Confirm you're in the same virtualenv/interpreter you think you are (which python; which pip) and reinstall there.
Switch to a retriever with no extra dependencies (e.g., 'duckduckgo') if you can't install packages.

Example fix

# before
# retrieval provider 'tavily' selected, tavily-python not installed
retriever = TavilySearch(query)  # ImportError: Unable to import tavily-python. ...

# after
# pip install -U tavily-python
retriever = TavilySearch(query)  # works

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

pkg = 'tavily-python'  # or the retriever's dependency
if importlib.util.find_spec(pkg.replace('-', '_')) is None:
    raise SystemExit(f'{pkg} is required: pip install -U {pkg}')

Type guard

def has_pkg(module_name: str) -> bool:
    return importlib.util.find_spec(module_name) is not None

Try / catch

try:
    retriever = make_retriever(provider)
except ImportError as e:
    print(f'Missing optional dependency: {e}')
    retriever = make_retriever('duckduckgo')  # dependency-free fallback

Prevention

Install optional extras for every retriever you plan to use (pip install gpt-researcher[extra]).
Pin optional dependencies in requirements.txt to avoid surprise missing modules.
Run a startup dependency audit that check_pkg-style validates each enabled provider.
Default to a dependency-free retriever like duckduckgo in minimal installs.

When it happens

Trigger: Selecting a retriever whose optional dependency isn't installed (e.g., 'tavily' without tavily-python, 'serpapi' without google-search-results, or any retriever package not in your env); __init__ calls check_pkg(pkg) and the ImportError fires immediately at construction time.

Common situations: Installing gpt-researcher without the optional extra for the chosen retriever; running in a different virtualenv/conda env than the one where the package was installed; renamed or yanked PyPI packages; mixing pip and system Python so find_spec can't see the installed package.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of assafelovic/gpt-researcher@6f998577d5 (2026-08-28). Data as JSON: /api/errors/0918125d30d9fb61. Report an issue: GitHub.