zylon-ai/private-gpt · error · ImportError

OpenAI LLM dependencies are not installed. Install with `uv

Error message

OpenAI LLM dependencies are not installed. Install with `uv sync --inexact --extra llm-openai`.

What it means

ImportError raised by the lazy loader in the OpenAI completions factory: importing PatchedOpenAILLM (which pulls in the openai package and llama-index OpenAI integration) failed, so the optional 'llm-openai' extra is not installed. The message tells you the exact uv command to install the missing extra.

Source

Thrown at private_gpt/components/llm/factories/completions/openai.py:17

from typing import Any, cast

from llama_index.core.llms import LLM

from private_gpt.components.llm.factories.base import LLMFactory
from private_gpt.components.llm.tokenizers.tokenizer_base import TokenizerBase
from private_gpt.settings.settings import LLMModelConfig, Settings
from private_gpt.utils.dependencies import format_missing_dependency_message


def _load_patched_openai() -> type[Any]:
    try:
        from private_gpt.components.llm.custom.openai import PatchedOpenAILLM

        return PatchedOpenAILLM
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "OpenAI LLM",
                extras="llm-openai",
            )
        ) from e


class OpenAICompletionsFactory(LLMFactory):
    """Chat Completions factory for the real OpenAI endpoint (api.openai.com)."""

    def __init__(self, settings: Settings):
        super().__init__(settings)
        self.openai_settings = settings.openai

    def _create_llm(
        self, model_config: LLMModelConfig, tokenizer: TokenizerBase | None = None
    ) -> tuple[LLM, str | None]:
        PatchedOpenAILLM = _load_patched_openai()

View on GitHub (pinned to 4a030776a3)

Solutions

Run `uv sync --inexact --extra llm-openai` as the message instructs.
If not using uv, install the openai/llama-index OpenAI packages named in the llm-openai extra (check pyproject.toml).
Rebuild your Docker/CI image with the extra included.

Example fix

# before: default sync only
uv sync

# after
uv sync --inexact --extra llm-openai

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:
    factory = registry.get_factory("openai")
except ImportError as e:
    if 'llm-openai' in str(e):
        raise SystemExit('Install extras: uv sync --inexact --extra llm-openai') from e
    raise

Prevention

Pin the full set of extras your modes need in deployment scripts/CI from day one.
Fail fast at startup: attempt to resolve every configured LLM mode before serving traffic.
Document required extras per mode in the project README so onboarding installs them.

When it happens

Trigger: Configuring llm mode to use the OpenAI (api.openai.com) completions backend without having installed the project's llm-openai optional dependency group.

Common situations: Fresh clone with a minimal sync (`uv sync` without extras); Docker images built with a slim dependency set; CI environments where only core deps are installed.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/750b92852df0ad0b. Report an issue: GitHub.