{"id":2259,"library":"redis-py-cluster","title":"Redis-Py-Cluster","description":"redis-py-cluster is a Python client library designed for communicating with Redis Clusters, building upon the core functionality of the redis-py library. The current version is 2.1.3. While it was a primary solution for Redis Cluster connectivity, its development has seen an irregular cadence, with the last major release in May 2021, as cluster support has since been integrated directly into the `redis-py` library itself.","status":"maintenance","version":"2.1.3","language":"en","source_language":"en","source_url":"https://github.com/grokzen/redis-py-cluster","tags":["redis","cluster","database","distributed"],"install":[{"cmd":"pip install redis-py-cluster","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for Redis client functionality.","package":"redis","version_spec":">=3.0.0,<4.0.0"},{"reason":"Optional faster parser for Redis responses.","package":"hiredis","optional":true,"version_spec":">=0.2.0"}],"imports":[{"note":"The class `StrictRedisCluster` was renamed to `RedisCluster` in version 2.0.0.","wrong":"from rediscluster import StrictRedisCluster","symbol":"RedisCluster","correct":"from rediscluster import RedisCluster"},{"note":"Introduced in 2.1.1, `ClusterPipeline` is exposed for pipelined commands.","symbol":"ClusterPipeline","correct":"from rediscluster import ClusterPipeline"}],"quickstart":{"code":"import os\nfrom rediscluster import RedisCluster\n\n# Configure startup nodes for the Redis Cluster\n# In a real scenario, use actual hostnames/IPs and ports\n# For local testing, ensure a Redis Cluster is running on these ports\nstartup_nodes = [\n    {\"host\": os.environ.get('REDIS_CLUSTER_HOST_1', '127.0.0.1'), \"port\": os.environ.get('REDIS_CLUSTER_PORT_1', '7000')},\n    # {\"host\": \"127.0.0.1\", \"port\": \"7001\"}, # Add more nodes as needed\n]\n\ntry:\n    # Initialize RedisCluster client with decode_responses=True for Python 3 strings\n    rc = RedisCluster(startup_nodes=startup_nodes, decode_responses=True, skip_full_coverage_check=True)\n\n    # Test connection and basic operations\n    rc.set(\"mykey\", \"Hello, Redis Cluster!\")\n    value = rc.get(\"mykey\")\n    print(f\"Retrieved value: {value}\")\n\n    # Example of a multi-key operation (keys must hash to the same slot)\n    # This example might fail if 'mykey' and 'myotherkey' don't hash to the same slot.\n    # In a real cluster, you'd use Redis hash tags {key}. See documentation.\n    # For this quickstart, we'll stick to single key for simplicity.\n    # rc.mset({\"mykey\": \"val1\", \"{mykey}other\": \"val2\"})\n    # vals = rc.mget([\"mykey\", \"{mykey}other\"])\n    # print(f\"Retrieved multiple values: {vals}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure a Redis Cluster is running and accessible at the specified startup nodes.\")\n    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\")\n    print(\"Then manually create the cluster if not using a managed service.\")","lang":"python","description":"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`)."},"warnings":[{"fix":"For new projects or when upgrading `redis-py` to 4.1.0+, use `from redis.cluster import RedisCluster` instead of `from rediscluster import RedisCluster`.","message":"The `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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Update all instantiations from `StrictRedisCluster(...)` to `RedisCluster(...)`.","message":"In version 2.0.0, the main client class was renamed from `StrictRedisCluster` to `RedisCluster`. Code using the old class name will no longer work.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure 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.","message":"The `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.","severity":"gotcha","affected_versions":"All 2.x.x versions"},{"fix":"Migrate to Python 3.5+ for continued support and future compatibility. For new projects, consider using `redis-py`'s native cluster support on Python 3.","message":"Version 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+.","severity":"deprecated","affected_versions":"2.1.x and earlier"},{"fix":"When creating `RedisCluster`, pass `decode_responses=True` as an argument: `rc = RedisCluster(startup_nodes=nodes, decode_responses=True)`.","message":"In Python 3, Redis responses are typically bytes. To receive Python strings (Unicode), you must instantiate the client with `decode_responses=True`.","severity":"gotcha","affected_versions":"All versions on Python 3"},{"fix":"If you rely on a specific connection pool size, explicitly set `max_connections` when initializing `ClusterBlockingConnectionPool` or `RedisCluster` if it uses this pool type.","message":"In version 2.1.3, the default `max_connection` in `ClusterBlockingConnectionPool` was changed to 50 to prevent issues with infinite loops in the queue mechanism.","severity":"gotcha","affected_versions":">=2.1.3"},{"fix":"Exercise caution when using read replicas with pipelines. Test thoroughly in your environment and consider alternatives if stability issues arise.","message":"Support 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'.","severity":"gotcha","affected_versions":">=2.1.3"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}