BerriAI/litellm · error · ModuleNotFoundError

Please install litellm with `litellm[caching]` to use disk c

Error message

Please install litellm with `litellm[caching]` to use disk caching.

What it means

ModuleNotFoundError raised by DiskCache.__init__ when the 'diskcache' package is not installed. LiteLLM's disk cache backend is an optional dependency; constructing litellm.Cache(type='disk') (or s3-disk variants) imports diskcache lazily and converts the failure into an actionable install hint. The original ImportError is chained via `from e`.

Source

Thrown at litellm/caching/disk_cache.py:19

import json
from typing import TYPE_CHECKING, Any, Final

from .base_cache import BaseCache

if TYPE_CHECKING:
    from opentelemetry.trace import Span as _Span

    Span = _Span | Any
else:
    Span = Any


class DiskCache(BaseCache):
    def __init__(self, disk_cache_dir: str | None = None):
        try:
            import diskcache as dc
        except ModuleNotFoundError as e:
            raise ModuleNotFoundError("Please install litellm with `litellm[caching]` to use disk caching.") from e

        # if users don't provider one, use the default litellm cache
        if disk_cache_dir is None:
            self.disk_cache = dc.Cache(".litellm_cache")
        else:
            self.disk_cache = dc.Cache(disk_cache_dir)

    def set_cache(self, key, value, **kwargs):
        if "ttl" in kwargs:
            self.disk_cache.set(key, value, expire=kwargs["ttl"])
        else:
            self.disk_cache.set(key, value)

    async def async_set_cache(self, key, value, **kwargs):
        self.set_cache(key=key, value=value, **kwargs)

    async def async_set_cache_pipeline(self, cache_list, **kwargs):
        for cache_key, cache_value in cache_list:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Install the extra: pip install 'litellm[caching]' (or pip install diskcache directly).
2. Alternatively use a cache backend you already have, e.g. litellm.Cache(type="redis", host=...).
3. Pin the extra in requirements.txt/pyproject so deploys match local.

Example fix

# before
litellm.cache = litellm.Cache(type="disk")  # ModuleNotFoundError

# after (shell)
# pip install 'litellm[caching]'
litellm.cache = litellm.Cache(type="disk")

def ensure_disk_cache_available() -> None:
    try:
        import diskcache  # noqa: F401
    except ModuleNotFoundError as e:
        raise RuntimeError("Run: pip install 'litellm[caching]'") from e

def disk_cache_available() -> bool:
    try:
        import diskcache  # noqa: F401
        return True
    except ModuleNotFoundError:
        return False

try:
    litellm.cache = litellm.Cache(type="disk", disk_cache_dir="./.litellm_cache")
except ModuleNotFoundError as e:
    logger.warning("disk cache unavailable (%s); falling back to in-memory", e)
    litellm.cache = litellm.Cache(type="local")

When it happens

Trigger: Configuring litellm.cache = litellm.Cache(type="disk", disk_cache_dir=...) (or "s3-disk") in an environment where the diskcache extra is not installed, or type="disk" in proxy config cache block without the optional dependency.

Common situations: Fresh installs with plain pip install litellm (extras not included); Docker images trimmed of optional deps; upgrading LiteLLM and the optional extra name changed; CI environments diverging from local.

Related errors

• LLM client cache lazy import: unknown attribute {name!r}
• cache key is None
• Missing expected key in embedding response: {e}
• input must be a string or a list
• Missing botocore to use AWS SigV4 authentication. Run 'pip i

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