redis-py

The Python interface to the Redis key-value store.

Installation | Usage | Advanced Topics | Contributing

---

How do I Redis?

Learn for free at Redis University

Try the Redis Cloud

Dive in developer tutorials

Join the Redis community

Work at Redis

Installation

Start a redis via docker (for Redis versions >= 8.0):

docker run -p 6379:6379 -it redis:latest

Start a redis via docker (for Redis versions < 8.0):

docker run -p 6379:6379 -it redis/redis-stack:latest

To install redis-py, simply:

$ pip install redis

For faster performance, install redis with hiredis support, this provides a compiled response parser, and for most cases requires zero code changes. By default, if hiredis >= 1.0 is available, redis-py will attempt to use it for response parsing.

$ pip install "redis[hiredis]"

Looking for a high-level library to handle object mapping? See redis-om-python!

Supported Redis Versions

The most recent version of this library supports Redis 7.2 and every later release, up to the latest stable Redis version. CI tests each of these Redis release lines.

The table below highlights version compatibility of the most-recent library versions and redis versions.

Library version	Supported redis versions
3.5.3	<= 6.2 Family of releases
>= 4.5.0	Version 5.0 to 7.0
>= 5.0.0	Version 5.0 to 7.4
>= 6.0.0	Version 7.2 to current

Supported Python Versions

redis-py supports every CPython version that has not reached end of life, and PyPy. requires-python in pyproject.toml states the minimum Python version for each release. If you are on an older Python version, use the last redis-py release that supports it:

Python version	Last supporting redis-py releases
3.7	5.0.x
3.8	6.1.x
3.9	7.0.x
3.10	8.1.x

Usage

Basic Example

>>> import redis
>>> r = redis.Redis(host='localhost', port=6379, db=0)
>>> r.set('foo', 'bar')
True
>>> r.get('foo')
b'bar'

The above code connects to localhost on port 6379, sets a value in Redis, and retrieves it. All responses are returned as bytes in Python, to receive decoded strings, set decode_responses=True. For this, and more connection options, see these examples.

RESP3 Support

redis-py supports RESP3 starting with version 5.0. Starting with redis-py 8.0, clients use RESP3 on the wire by default while preserving legacy RESP2-compatible Python response shapes for existing applications.

When protocol is left unset, a server or proxy that rejects HELLO with an unknown-command or NOPROTO error triggers a fallback to RESP2 and a warning. Authentication and other server errors still propagate. Automatic fallback is disabled when protocol=3 is explicit, client-side caching is configured, or maintenance notifications are explicitly enabled.

Automatic fallback adapts core command response callbacks only. Module commands (JSON, Search, TimeSeries, Bloom, and vector sets) still select their response parsers from the configured protocol and can return incorrect results after a fallback, including empty results from FT.SEARCH. When using these commands with a server or proxy that does not support HELLO, set protocol=2 explicitly when creating the client.

Set protocol=3 explicitly when your application should receive RESP3-specific response shapes or when you want the wire protocol choice to be visible in code. To force RESP2 on the wire, set protocol=2. To opt in to protocol-independent response shapes, set legacy_responses=False.

For new projects, we recommend opting out of legacy response compatibility by setting legacy_responses=False. This makes redis-py return unified Python response shapes for affected commands whether the connection uses RESP2 or RESP3. Existing applications can keep the default legacy-compatible behavior while they migrate response handling at their own pace.

>>> import redis
>>> r = redis.Redis(host='localhost', port=6379, db=0, legacy_responses=False)

See the unified responses migration guide for activation instructions and command-by-command response differences. For RESP3-specific behavior, see the RESP3 features guide.

Connection Pools

By default, redis-py uses a connection pool to manage connections. Each instance of a Redis class receives its own connection pool. You can however define your own redis.ConnectionPool.

This is the beginning of the README. Read the rest at the original. Read the full README ↗