redis-py
The Python interface to the Redis key-value store.
Installation | Usage | Advanced Topics | Contributing
Note: redis-py 5.0 is the last version of redis-py that supports Python 3.7, as it has reached end of life. redis-py 5.1 supports Python 3.8+.
Note: redis-py 6.1.0 is the last version of redis-py that supports Python 3.8, as it has reached end of life. redis-py 6.2.0 supports Python 3.9+.
How do I Redis?
Learn for free at Redis University
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 = 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 version 7.2, 7.4, 8.0, 8.2, 8.4, 8.6 and 8.8.
The table below highlights version compatibility of the most-recent library versions and redis versions.
| Library version | Supported redis versions |
|---|---|
| 3.5.3 | = 4.5.0 |
| >= 5.0.0 | Version 5.0 to 7.4 |
| >= 6.0.0 | Version 7.2 to current |
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.
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.
>>> pool = redis.ConnectionPool(host='localhost', port=6379, db=0)
>>> r = redis.Redis(connection_pool=pool)
Alternatively, you might want to look at Async connections, or Cluster connections, or even Async Cluster connections.
Redis Commands
There is built-in support for all of the out-of-the-box Redis commands. They are exposed using the raw Redis command names (HSET, HGETALL, etc.) except where a word (i.e. del) is reserved by the language. The complete set of commands can be found here, or the documentation.
Advanced Topics
The official Redis command documentation does a great job of explaining each command in detail. redis-py attempts to adhere to the official command syntax. There are a few exceptions:
MULTI/EXEC: These are implemented as part of the Pipeline class. The pipeline is wrapped with the MULTI and EXEC statements by default when it is executed, which can be disabled by specifying transaction=False. See more about Pipelines below.
SUBSCRIBE/LISTEN: Similar to pipelines, PubSub is implemented as a separate class as it places the underlying connection in a state where it can't execute non-pubsub commands. Calling the pubsub method from the Redis client will return a PubSub instance where you can subscribe to channels and listen for messages. You can only call PUBLISH from the Redis client (see this comment on issue #151 for details).
For more details, please see the documentation on advanced topics page.
Pipelines
The following is a basic example of a Redis pipeline, a method to optimize round-trip calls, by batching Redis commands, and receiving their results as a list.
>>> pipe = r.pipeline()
>>> pipe.set('foo', 5)
>>> pipe.set('bar', 18.5)
>>> pipe.set('blee', "hello world!")
>>> pipe.execute()
[True, True, True]
PubSub
The following example shows how to utilize Redis Pub/Sub to subscribe to specific channels.
>>> r = redis.Redis(...)
>>> p = r.pubsub()
>>> p.subscribe('my-first-channel', 'my-second-channel', ...)
>>> p.get_message()
{'pattern': None, 'type': 'subscribe', 'channel': b'my-second-channel', 'data': 1}
Redis’ search and query capabilities default dialect
Release 6.0.0 introduces a client-side default dialect for Redis’ search and query capabilities. By default, the client now overrides the server-side dialect with version 2, automatically appending DIALECT 2 to commands like FT.AGGREGATE and FT.SEARCH.
Important: Be aware that the query dialect may impact the results returned. If needed, you can revert to a different dialect version by configuring the client accordingly.
>>> from redis.commands.search.field import TextField
>>> from redis.commands.search.query import Query
>>> from redis.commands.search.index_definition import IndexDefinition
>>>