Environment:BerriAI Litellm Redis Cache Backend

Knowledge Sources	BerriAI/litellm Redis Configuration
Domains	Infrastructure, Caching
Last Updated	2026-02-15 16:00 GMT

Overview

Redis 7+ server environment for LiteLLM response caching, distributed rate limiting, and spend tracking buffering.

Description

This environment provides the Redis infrastructure required by LiteLLM's caching system, router distributed state, and proxy spend update buffering. It supports standalone Redis, Redis Cluster, Redis Sentinel, and GCP Memorystore with IAM authentication. The Redis connection is configured through environment variables and supports SSL/TLS, username/password auth, and advanced topologies.

Usage

Use this environment when enabling response caching (LiteLLMCacheType.redis), distributed rate limiting across multiple proxy instances, semantic caching (via RedisVL), or spend update buffering for the proxy server's database write path.

System Requirements

Category	Requirement	Notes
Software	Redis >= 7.0	LPOP with count parameter required (used for batch operations)
Network	TCP port 6379 (default)	Or custom port via REDIS_PORT
Memory	Depends on cache size	Recommend >= 256MB for production

Dependencies

Python Packages

`redis` >= 5.2.1
`redisvl` >= 0.4.1 (optional, for semantic caching)
`google-cloud-iam` >= 2.19.1 (optional, for GCP IAM auth)

Credentials

The following environment variables configure Redis connectivity:

`REDIS_URL`: Full Redis connection URL (e.g., `redis://user:pass@host:6379`). Takes priority over individual settings.
`REDIS_HOST`: Redis server hostname.
`REDIS_PORT`: Redis server port number.
`REDIS_PASSWORD`: Redis authentication password.
`REDIS_USERNAME`: Redis ACL username (Redis 6+).
`REDIS_SSL`: Set to "true" to enable TLS (uses `rediss://` protocol).
`REDIS_CLUSTER_NODES`: JSON array of cluster node addresses.
`REDIS_SENTINEL_NODES`: JSON array of sentinel node addresses.
`REDIS_SENTINEL_PASSWORD`: Password for Redis Sentinel.
`REDIS_SERVICE_NAME`: Sentinel service name for master discovery.
`REDIS_GCP_SERVICE_ACCOUNT`: GCP service account for IAM-based Redis auth.
`REDIS_GCP_SSL_CA_CERTS`: Path to CA certificate for GCP Memorystore SSL.

Quick Install

# Install LiteLLM with caching support
pip install litellm redis

# For semantic caching
pip install litellm redisvl

# Start Redis locally (Docker)
docker run -d --name redis -p 6379:6379 redis:7-alpine

Code Evidence

Redis URL resolution from `litellm/_redis.py:173-196`:

def get_redis_url_from_environment():
    if "REDIS_URL" in os.environ:
        return os.environ["REDIS_URL"]

    if "REDIS_HOST" not in os.environ or "REDIS_PORT" not in os.environ:
        raise ValueError(
            "Either 'REDIS_URL' or both 'REDIS_HOST' and 'REDIS_PORT' must be specified for Redis."
        )

    if "REDIS_SSL" in os.environ and os.environ["REDIS_SSL"].lower() == "true":
        redis_protocol = "rediss"
    else:
        redis_protocol = "redis"

Redis version assumption from `litellm/constants.py:313-315`:

DEFAULT_REDIS_MAJOR_VERSION = 7
# Using 7 as it's the modern version that supports LPOP with count parameter

Default socket timeout from `litellm/caching/redis_cache.py:99`:

socket_timeout: Optional[float] = 5.0  # default 5 second timeout

Common Errors

Error Message	Cause	Solution
`ValueError: Either 'REDIS_URL' or both 'REDIS_HOST' and 'REDIS_PORT' must be specified`	Missing Redis connection config	Set `REDIS_URL` or both `REDIS_HOST` and `REDIS_PORT` env vars
`ConnectionError: Error connecting to Redis`	Redis server unreachable	Verify Redis is running and accessible on the configured host/port
`google-cloud-iam is required for GCP IAM Redis authentication`	Missing GCP IAM package	`pip install google-cloud-iam`
`AuthenticationError: GCP IAM authentication failed`	Invalid GCP service account	Verify `REDIS_GCP_SERVICE_ACCOUNT` value and IAM permissions

Compatibility Notes

Redis Cluster: Set `REDIS_CLUSTER_NODES` as a JSON array. Automatically uses `RedisClusterCache` backend.
Redis Sentinel: Set `REDIS_SENTINEL_NODES` and `REDIS_SERVICE_NAME` for high availability.
GCP Memorystore: Use `REDIS_GCP_SERVICE_ACCOUNT` for IAM-based auth. Requires `google-cloud-iam` package.
os.environ/ prefix: Config values can reference env vars with `os.environ/VAR_NAME` syntax in YAML config files.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment