Skip to main content

redis-py

The Python interface to the Redis key-value store.

CI docs MIT licensed pypi pre-release codecov

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+. Note: redis-py 7.0.1 is the last version of redis-py that supports Python 3.9, as it has reached end of life. redis-py 7.1.0 supports Python 3.10+.


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 version 7.2, 7.4, 8.0 and 8.2.

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

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

To enable support for RESP3, ensure you have at least version 5.0 of the client, and change your connection object to include protocol=3

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

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
>>> import redis

>>> r = redis.Redis(host='localhost', port=6379, db=0)
>>> r.ft().create_index(
>>>     (TextField("name"), TextField("lastname")),
>>>     definition=IndexDefinition(prefix=["test:"]),
>>> )

>>> r.hset("test:1", "name", "James")
>>> r.hset("test:1", "lastname", "Brown")

>>> # Query with default DIALECT 2
>>> query = "@name: James Brown"
>>> q = Query(query)
>>> res = r.ft().search(q)

>>> # Query with explicit DIALECT 1
>>> query = "@name: James Brown"
>>> q = Query(query).dialect(1)
>>> res = r.ft().search(q)

You can find further details in the query dialect documentation.

Multi-database client (Active-Active)

The multi-database client allows your application to connect to multiple Redis databases, which are typically replicas of each other. It is designed to work with Redis Software and Redis Cloud Active-Active setups. The client continuously monitors database health, detects failures, and automatically fails over to the next healthy database using a configurable strategy. When the original database becomes healthy again, the client can automatically switch back to it.
This is useful when:

  1. You have more than one Redis deployment. This might include two independent Redis servers or two or more Redis databases replicated across multiple active-active Redis Enterprise clusters.
  2. You want your application to connect to one deployment at a time and to fail over to the next available deployment if the first deployment becomes unavailable.

For the complete failover configuration options and examples, see the Multi-database client docs.


Author

redis-py is developed and maintained by Redis Inc. It can be found here, or downloaded from pypi.

Special thanks to:

  • Andy McCurdy (sedrik@gmail.com) the original author of redis-py.
  • Ludovico Magnocavallo, author of the original Python Redis client, from which some of the socket code is still used.
  • Alexander Solovyov for ideas on the generic response callback system.
  • Paul Hubbard for initial packaging support.

Redis

Metadata

Release files for redis 7.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for redis 7.1.0
File Size Uploaded Provenance Actions
redis-7.1.0.tar.gz 4.8 MB Without provenance Details for redis-7.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for redis 7.1.0
File Interpreter ABI Platform Actions
redis-7.1.0-py3-none-any.whl Python 3 none any Details for redis-7.1.0-py3-none-any.whl

Total release size: 5.2 MB

Release files / redis-7.1.0.tar.gz

Download URL redis-7.1.0.tar.gz
Size 4.8 MB
Tags Source
SHA-256 checksum
How to use checksums
b1cc3cfa5a2cb9c2ab3ba700864fb0ad75617b41f01352ce5779dabf6d5f9c3c
BLAKE2b-256 checksum
How to use checksums
43c8983d5c6579a411d8a99bc5823cc5712768859b5ce2c8afe1a65b37832c81
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / redis-7.1.0-py3-none-any.whl

Download URL redis-7.1.0-py3-none-any.whl
Size 354.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23c52b208f92b56103e17c5d06bdc1a6c2c0b3106583985a76a18f83b265de2b
BLAKE2b-256 checksum
How to use checksums
89f08956f8a86b20d7bb9d6ac0187cf4cd54d8065bc9a1a09eb8011d4d326596
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for redis 7.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

7.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page