BerriAI/litellm · error · ImportError

Guardrail {self.guardrail_name or type(self).__name__} imple

Error message

Guardrail {self.guardrail_name or type(self).__name__} implements apply_guardrail, which needs the litellm proxy dependencies to run at the deployment level. Install them with: pip install 'litellm[proxy]'

What it means

A guardrail subclass overrides apply_guardrail(), so at deployment level the proxy must wrap it with litellm.proxy.utils.unified_guardrail. When that import fails, litellm knows the optional proxy dependencies are missing and raises ImportError telling you to install the 'proxy' extra. It is a packaging error, not a logic error in your guardrail.

Source

Thrown at litellm/integrations/custom_guardrail.py:640

            return False
        for meta_key in ("metadata", "litellm_metadata"):
            meta = data.get(meta_key)
            if isinstance(meta, dict):
                executed = meta.get(PRE_CALL_EXECUTED_GUARDRAILS_KEY)
                if isinstance(executed, list) and marker in executed:
                    return True
        return False

    def uses_apply_guardrail_interface(self) -> bool:
        return type(self).apply_guardrail is not CustomGuardrail.apply_guardrail

    def _deployment_pre_call_target(self) -> "CustomLogger":
        if not self.uses_apply_guardrail_interface():
            return self
        try:
            from litellm.proxy.utils import unified_guardrail
        except ImportError as e:
            raise ImportError(
                f"Guardrail {self.guardrail_name or type(self).__name__} implements apply_guardrail, which needs "
                "the litellm proxy dependencies to run at the deployment level. "
                "Install them with: pip install 'litellm[proxy]'"
            ) from e
        return unified_guardrail

    async def async_pre_call_deployment_hook(self, kwargs: dict[str, Any], call_type: CallTypes | None) -> dict | None:
        from litellm.proxy._types import UserAPIKeyAuth

        # should run guardrail
        litellm_guardrails: Final = kwargs.get("guardrails")
        if litellm_guardrails is None or not isinstance(litellm_guardrails, list):
            return kwargs

        if self._pre_call_hook_already_ran(kwargs):
            return kwargs

        if self.should_run_guardrail(data=kwargs, event_type=GuardrailEventHooks.pre_call) is not True:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Install the proxy extras: pip install 'litellm[proxy]'
2. If you run the official litellm proxy image, ensure your custom Dockerfile does not downgrade litellm to the base wheel
3. If apply_guardrail is not needed, remove the override so the guardrail uses hook-based methods and the proxy dependency is not required

Example fix

# before
pip install litellm

# after
pip install 'litellm[proxy]'

def proxy_deps_available() -> bool:
    try:
        import litellm.proxy.utils  # noqa: F401
        return True
    except ImportError:
        return False

if guardrail.uses_apply_guardrail_interface() and not proxy_deps_available():
    raise SystemExit("Install with: pip install 'litellm[proxy]'")

try:
    _ = guardrail._deployment_pre_call_target()
except ImportError as e:
    if "litellm[proxy]" in str(e):
        subprocess.check_call([pip, "install", "litellm[proxy]"])  # then restart
    raise

When it happens

Trigger: Using litellm installed as the slim/core package (pip install litellm without extras, or a lambda/docker image built from requirements listing bare litellm) and loading a guardrail that implements apply_guardrail via _deployment_pre_call_target(). The try-import of litellm.proxy.utils fails because fastapi & co. are absent.

Common situations: SDK-only installs later pointed at proxy-style guardrail configs; minimal Docker images that strip extras to reduce size; CI environments installing litellm from a lockfile pinned to the base wheel.

Related errors

• cryptography package is required for OCI authentication. Ple
• Missing botocore to use AWS SigV4 authentication. Run 'pip i
• NVIDIA Riva client is not installed. Install with `pip insta
• Please install litellm with `litellm[caching]` to use disk c
• streamable_http_client is not available. Please install mcp

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/da20b7294c3014be. Report an issue: GitHub.