headroomlabs-ai/headroom · error · ImportError

ollama package required. Install with: pip install ollama

Error message

ollama package required. Install with: pip install ollama

What it means

Raised by BeforeAfterRunner._init_llm_client when llm_config.provider == 'ollama' but the ollama Python client is not importable. The eval runner only imports the SDK inside this branch, so an environment without 'pip install ollama' fails at the first ground-truth judge call. Everything else in the run (compression stats, proxy calls) can have succeeded before this fires.

Source

Thrown at headroom/evals/runners/before_after.py:123

                raise ImportError(
                    "anthropic package required. Install with: pip install anthropic"
                ) from e
        elif self.llm_config.provider == "openai":
            try:
                import openai

                return openai.OpenAI()
            except ImportError as e:
                raise ImportError(
                    "openai package required. Install with: pip install openai"
                ) from e
        elif self.llm_config.provider == "ollama":
            try:
                import ollama

                return ollama.Client()
            except ImportError as e:
                raise ImportError(
                    "ollama package required. Install with: pip install ollama"
                ) from e
        else:
            raise ValueError(f"Unknown provider: {self.llm_config.provider}")

    def _init_proxy_client(self) -> Any:
        """Initialize an OpenAI client pointing at the Headroom proxy."""
        import openai

        return openai.OpenAI(
            base_url=f"{self.llm_config.headroom_proxy_url}/v1",
            api_key=os.environ.get("OPENAI_API_KEY", ""),
        )

    def _call_llm_via_proxy(self, context: str, query: str) -> str:
        """Call LLM through Headroom proxy (full stack: compression + CCR)."""
        prompt = f"""Based on the following context, answer the question.

View on GitHub (pinned to 322425c43b)

Solutions

1. python -m pip install ollama.
2. Confirm an Ollama server is reachable (OLLAMA_HOST, default http://localhost:11434) and has pulled the judge model — otherwise you will trade this error for a connection error.
3. If ollama was installed into another env, re-run inside the correct venv (which python -> which pip).
4. Prefer installing the repo's eval extras so provider SDKs are pinned.

Example fix

# before
# provider="ollama" without the client package -> ImportError

# after
$ python -m pip install ollama
$ ollama pull llama3.1   # ensure judge model exists locally

import importlib.util, os, urllib.request

assert importlib.util.find_spec("ollama"), "pip install ollama"
# server check: a connection error is the *next* failure you'd hit
try:
    urllib.request.urlopen(os.environ.get("OLLAMA_HOST", "http://localhost:11434"), timeout=2)
except OSError:
    raise SystemExit("Ollama server not reachable")

try:
    runner.run()
except ImportError as e:
    if "ollama package required" in str(e):
        sys.exit("pip install ollama and start the Ollama server")
    raise

When it happens

Trigger: provider='ollama' in the LLM judge config while the ollama package is missing; or the package is installed but the Ollama server itself is not running (that produces a connection error later, not this one).

Common situations: Local LLM evaluation setups where the Ollama desktop app is installed but the pip client never was; remote-eval environments expecting an Ollama endpoint; switching a suite from openai to ollama without updating dependencies.

Related errors

• anthropic package required. Install with: pip install anthro
• openai package required. Install with: pip install openai
• Agno is required for this integration. Install with: pip ins
• httpx is required for Headroom Cloud mode: pip install httpx
• AutoGen is required for this integration. Install with: pip

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/561817bc9adc4697. Report an issue: GitHub.