Install & Compatibility
Where this runs
tested against v2.1.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.740s · 19.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.636s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisCluster
✓ from rediscluster import RedisCluster
✗ from rediscluster import RedisCluster
This quickstart demonstrates how to connect to a Redis Cluster using `redis-py-cluster`, set a key-value pair, and retrieve it. It highlights the use of `startup_nodes` for initial cluster discovery and `decode_responses=True` for handling string decoding in Python 3. For multi-key commands, ensure keys hash to the same slot, often achieved using Redis hash tags (e.g., `{user1}name`, `{user1}email`).
import os
from rediscluster import RedisCluster
# Configure startup nodes for the Redis Cluster
# In a real scenario, use actual hostnames/IPs and ports
# For local testing, ensure a Redis Cluster is running on these ports
startup_nodes = [
{"host": os.environ.get('REDIS_CLUSTER_HOST_1', '127.0.0.1'), "port": os.environ.get('REDIS_CLUSTER_PORT_1', '7000')},
# {"host": "127.0.0.1", "port": "7001"}, # Add more nodes as needed
]
try:
# Initialize RedisCluster client with decode_responses=True for Python 3 strings
rc = RedisCluster(startup_nodes=startup_nodes, decode_responses=True, skip_full_coverage_check=True)
# Test connection and basic operations
rc.set("mykey", "Hello, Redis Cluster!")
value = rc.get("mykey")
print(f"Retrieved value: {value}")
# Example of a multi-key operation (keys must hash to the same slot)
# This example might fail if 'mykey' and 'myotherkey' don't hash to the same slot.
# In a real cluster, you'd use Redis hash tags {key}. See documentation.
# For this quickstart, we'll stick to single key for simplicity.
# rc.mset({"mykey": "val1", "{mykey}other": "val2"})
# vals = rc.mget(["mykey", "{mykey}other"])
# print(f"Retrieved multiple values: {vals}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure a Redis Cluster is running and accessible at the specified startup nodes.")
print("For example, using Docker: docker run -p 7000:7000 -p 7001:7001 -p 7002:7002 -p 7003:7003 -p 7004:7004 -p 7005:7005 --name redis-cluster-node-1 redislabs/redismod")
print("Then manually create the cluster if not using a managed service.")
Debug
Known issues
breakingThe `redis-py` library (version 4.1.0 and later) now includes native support for Redis Cluster, effectively superseding `redis-py-cluster`. New projects or upgrades of `redis-py` should consider migrating to `redis.cluster.RedisCluster` for direct cluster support.fixFor new projects or when upgrading `redis-py` to 4.1.0+, use `from redis.cluster import RedisCluster` instead of `from rediscluster import RedisCluster`.
affects: All versions
breakingIn version 2.0.0, the main client class was renamed from `StrictRedisCluster` to `RedisCluster`. Code using the old class name will no longer work.fixUpdate all instantiations from `StrictRedisCluster(...)` to `RedisCluster(...)`.
affects: >=2.0.0
gotchaThe `redis-py-cluster` 2.x.x series requires `redis-py` versions strictly within `3.0.0 <= redis < 4.0.0`. Using `redis-py` versions outside this range can lead to compatibility issues or errors.fixEnsure your `redis` dependency is pinned to `redis>=3.0.0,<4.0.0` if using `redis-py-cluster` 2.x.x. Check the `redis-py-cluster` documentation for specific `redis-py` version requirements if using other major versions.
affects: All 2.x.x versions
deprecatedVersion 2.1.x is the last major release line to support Python 2.7. Future major versions (e.g., 3.0.x) will require Python 3.5+.fixMigrate to Python 3.5+ for continued support and future compatibility. For new projects, consider using `redis-py`'s native cluster support on Python 3.
affects: 2.1.x and earlier
gotchaIn Python 3, Redis responses are typically bytes. To receive Python strings (Unicode), you must instantiate the client with `decode_responses=True`.fixWhen creating `RedisCluster`, pass `decode_responses=True` as an argument: `rc = RedisCluster(startup_nodes=nodes, decode_responses=True)`.
affects: All versions on Python 3
gotchaIn version 2.1.3, the default `max_connection` in `ClusterBlockingConnectionPool` was changed to 50 to prevent issues with infinite loops in the queue mechanism.fixIf you rely on a specific connection pool size, explicitly set `max_connections` when initializing `ClusterBlockingConnectionPool` or `RedisCluster` if it uses this pool type.
affects: >=2.1.3
gotchaSupport for using read replicas for read commands within pipelines was improved in 2.1.3, but the release notes indicate this feature 'might be unstable to use as own risk'.fixExercise caution when using read replicas with pipelines. Test thoroughly in your environment and consider alternatives if stability issues arise.
affects: >=2.1.3
Upgrade
Version history
2.1.3latest on PyPI · released May 30, 2021
Audit
Dependencies
redisrequiredCore dependency for Redis client functionality.
hiredisoptionalOptional faster parser for Redis responses.