| single |
# redis-py
The Python interface to the Redis key-value store.
[CI]
[docs]
[MIT licensed]
[pypi]
[![pre-release]](https://github.com/redis/redis-py/releases)
[codecov]
[Installation] | [Usage] | [Advanced Topics] | [Contributing]
---------------------------------------------
## Python Notice
redis-py 4.3.x will be the last generation of redis-py to support python
3.6 as it has been [End of Life'd]. Async support was introduced in
redis-py 4.2.x thanks to [aioredis], which necessitates this change. We
will continue to maintain 3.6 support as long as possible - but the plan is
for redis-py version 4.4+ to officially remove 3.6.
---------------------------
## Installation
To install redis-py, simply:
``` bash
$ 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.
``` bash
$ pip install redis[hiredis]
```
Looking for a high-level library to handle object mapping? See
[redis-om-python]!
## Usage
### Basic Example
``` python
>>> 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].
### 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].
``` python
>>> 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
|